Skip to content

API Documentation

A Python library of interactive CLI elements you have been looking for

Class DefaultKeys

class DefaultKeys()

[view_source]

A map of default keybindings.

Attributes:

escape(List[Union[Tuple[int, ...], str]]): Keys that escape the current context. select(List[Union[Tuple[int, ...], str]]): Keys that trigger list element selection. confirm(List[Union[Tuple[int, ...], str]]): Keys that trigger list confirmation. backspace(List[Union[Tuple[int, ...], str]]): Keys that trigger deletion of the previous character. delete(List[Union[Tuple[int, ...], str]]): Keys that trigger deletion of the next character. down(List[Union[Tuple[int, ...], str]]): Keys that select the element below. up(List[Union[Tuple[int, ...], str]]): Keys that select the element above. left(List[Union[Tuple[int, ...], str]]): Keys that select the element to the left. right(List[Union[Tuple[int, ...], str]]): Keys that select the element to the right. home(List[Union[Tuple[int, ...], str]]): Keys that move to the beginning of the context. end(List[Union[Tuple[int, ...], str]]): Keys that move to the end of the context.

Class Config

class Config()

[view_source]

A map of default configuration

Attributes:

  • raise_on_interrupt(bool) - If True, functions will raise KeyboardInterrupt whenever one is encountered when waiting for input, otherwise, they will return some sane alternative to their usual return. For select, prompt and confirm this means None, while for select_multiple it means an empty list - []. Defaults to False.
  • raise_on_escape(bool) - If True, functions will raise Abort whenever the escape key is encountered when waiting for input, otherwise, they will return some sane alternative to their usual return. For select, prompt and confirm this means None, while for select_multiple it means an empty list - []. Defaults to False.
  • transient(bool) - If False, elements will remain displayed after their context has ended. Defaults to True.

prompt

def prompt(
        prompt: str,
        target_type: Type[TargetType] = str,
        validator: Callable[[TargetType], bool] = lambda input: True,
        secure: bool = False,
        raise_validation_fail: bool = True,
        raise_type_conversion_fail: bool = True,
        initial_value: Optional[str] = None,
        completion: Optional[Callable[[str], List[str]]] = None) -> TargetType

[view_source]

Function that prompts the user for written input

Arguments:

  • prompt str - The prompt that will be displayed
  • target_type Union[Type[T], Type[str]], optional - Type to convert the answer to. Defaults to str.
  • validator Callable[[Any], bool], optional - Optional function to validate the input. Defaults to lambda input: True.
  • secure bool, optional - If True, input will be hidden. Defaults to False.
  • raise_validation_fail bool, optional - If True, invalid inputs will raise rich.internals.ValidationError, else the error will be reported onto the console. Defaults to True.
  • raise_type_conversion_fail bool, optional - If True, invalid inputs will raise rich.internals.ConversionError, else the error will be reported onto the console. Defaults to True.
  • initial_value str, optional - If present, the value is placed in the prompt as the default value.

Raises:

  • ValidationError - Raised if validation with provided validator fails
  • ConversionError - Raised if the value cannot be converted to provided type
  • KeyboardInterrupt - Raised when keyboard interrupt is encountered and Config.raise_on_interrupt is True

Returns:

Union[T, str]: Returns a value formatted as provided type or string if no type is provided

select

def select(options: List[Union[str, T]],
           preprocessor: Callable[[T], str] = lambda val: str(val),
           cursor: str = '>',
           cursor_style: str = 'pink1',
           cursor_index: int = 0,
           return_index: bool = False,
           strict: bool = False,
           pagination: bool = False,
           page_size: Optional[int] = None) -> Union[int, Any, None]

[view_source]

A prompt that allows selecting one option from a list of options

Arguments:

  • options List[Union[str, T]] - A list of options to select from. If preprocessor is left as default (not passed), it needs to be a list of strings or objects with a __str__ method. Otherwise, you can pass a preprocessor to create a string representation of arbitrary data-structures.
  • preprocessor Callable[[T], str] - A callable that can be used to preprocess the list of options prior to printing. For example, if you passed a Person object with name attribute, preprocessor could be lambda person: person.name to just show the content of name attribute in the select dialog. Defaults to lambda val: val
  • cursor str, optional - Cursor that is going to appear in front of currently selected option. Defaults to '> '.
  • cursor_style str, optional - Rich friendly style for the cursor. Defaults to 'pink1'.
  • cursor_index int, optional - Option can be preselected based on its list index. Defaults to 0.
  • return_index bool, optional - If True, select will return the index of selected element in options. Defaults to False.
  • strict bool, optional - If empty options is provided and strict is False, None will be returned, if it's True, ValueError will be thrown. Defaults to False.
  • pagination bool, optional - If True, pagination will be used. Defaults to False.
  • page_size Optional[int], optional - Number of options to show on a single page if pagination is enabled. If None, the page size is derived automatically from the terminal height. Pagination is also enabled automatically when options exceed the terminal height. Defaults to None.

Raises:

  • ValueError - Thrown if no options are provided and strict is True
  • KeyboardInterrupt - Raised when keyboard interrupt is encountered and Config.raise_on_interrupt is True

Returns:

Union[int, str, None]: Selected value or the index of a selected option or None

select_multiple

def select_multiple(options: List[Union[str, T]],
                    preprocessor: Callable[[T], str] = lambda val: str(val),
                    tick_character: str = '✓',
                    tick_style: str = 'pink1',
                    cursor_style: str = 'pink1',
                    ticked_indices: Optional[List[int]] = None,
                    cursor_index: int = 0,
                    minimal_count: int = 0,
                    maximal_count: Optional[int] = None,
                    return_indices: bool = False,
                    strict: bool = False,
                    pagination: bool = False,
                    page_size: Optional[int] = None) -> List[Union[int, Any]]

[view_source]

A prompt that allows selecting multiple options from a list of options

Arguments:

  • options List[Union[str, T]] - A list of options to select from. If preprocessor is left as default (not passed), it needs to be a list of strings or objects with a __str__ method. Otherwise, you can pass a preprocessor to create a string representation of arbitrary data-structures.
  • preprocessor Callable[[T], str] - A callable that can be used to preprocess the list of options prior to printing. For example, if you passed a Person object with name attribute, preprocessor could be lambda person: person.name to just show the content of name attribute in the select_multiple dialog. Defaults to lambda val: val
  • tick_character str, optional - Character that will be used as a tick in a checkbox. Defaults to 'x'.
  • tick_style str, optional - Rich friendly style for the tick character. Defaults to 'pink1'.
  • cursor_style str, optional - Rich friendly style for the option when the cursor is currently on it. Defaults to 'pink1'.
  • ticked_indices Optional[List[int]], optional - Indices of options that are pre-ticked when the prompt appears. Defaults to None.
  • cursor_index int, optional - Index of the option cursor starts at. Defaults to 0.
  • minimal_count int, optional - Minimal count of options that need to be selected. Defaults to 0.
  • maximal_count Optional[int], optional - Maximal count of options that need to be selected. Defaults to None.
  • return_indices bool, optional - If True, select_multiple will return the indices of ticked elements in options. Defaults to False.
  • strict bool, optional - If empty options is provided and strict is False, None will be returned, if it's True, ValueError will be thrown. Defaults to False.
  • pagination bool, optional - If True, pagination will be used. Defaults to False.
  • page_size Optional[int], optional - Number of options to show on a single page if pagination is enabled. If None, the page size is derived automatically from the terminal height. Pagination is also enabled automatically when options exceed the terminal height. Defaults to None.

Raises:

  • KeyboardInterrupt - Raised when keyboard interrupt is encountered and Config.raise_on_interrupt is True

Returns:

Union[List[str], List[int]]: A list of selected values or indices of selected options

confirm

def confirm(question: str,
            yes_text: str = 'Yes',
            no_text: str = 'No',
            has_to_match_case: bool = False,
            enter_empty_confirms: bool = True,
            default_is_yes: bool = False,
            cursor: str = '>',
            cursor_style: str = 'pink1',
            char_prompt: bool = True) -> Optional[bool]

[view_source]

A prompt that asks a question and offers two responses

Arguments:

  • question str - Question to be asked
  • yes_text str, optional - Text of the positive response. Defaults to 'Yes'.
  • no_text str, optional - Text of the negative response. Defaults to 'No'.
  • has_to_match_case bool, optional - Check if typed response matches case. Defaults to False.
  • enter_empty_confirms bool, optional - No response is confirmation. Defaults to True.
  • default_is_yes bool, optional - Default is Yes. Defaults to False.
  • cursor str, optional - What character(s) to use as a cursor. Defaults to '> '.
  • cursor_style str, optional - Rich friendly style for the cursor. Defaults to 'pink1'.
  • char_prompt bool, optional - Print [Y/n] after the question. Defaults to True.

Raises:

  • KeyboardInterrupt - Raised when keyboard interrupt is encountered and Config.raise_on_interrupt is True

Returns:

Optional[bool]

Class Spinner

class Spinner()

[view_source]

__init__

def __init__(spinner_characters: List[str] = DOTS,
             text: str = 'Loading...',
             refresh_per_second: float = 10,
             transient: bool = True)

[view_source]

Creates a spinner which can be used to provide some user feedback during long processing

Arguments:

  • spinner_characters List[str] - List of strings that will be displayed in sequence by a spinner
  • text str - Static text that will be shown after the spinner. Defaults to Loading...
  • refresh_per_second float, optional - Number of refreshes the spinner will do a second, this will affect the fluidity of the "animation". Defaults to 10.
  • transient bool, optional - If the spinner will disappear after it's done, otherwise not. Defaults to True.

Raises:

  • ValueError - Raised when no spinner_characters are provided in

start

def start() -> None

[view_source]

Starts the spinner

stop

def stop() -> None

[view_source]

Stops the spinner