Skip to content

Latest commit

 

History

History
290 lines (200 loc) · 9.65 KB

APIDOC.md

File metadata and controls

290 lines (200 loc) · 9.65 KB

Table of Contents

__init__

spinners

Spinner Objects

class Spinner()

__init__

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

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

Arguments:

  • spinner_characters List[str] - List of characters 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

Starts the spinner

stop

def stop() -> None

Stops the spinner

_internals

beaupy

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

DefaultKeys Objects

class DefaultKeys()

A map of default keybindings.

Attributes:

  • interrupt(List[str]) - Keys that cause a keyboard interrupt.
  • select(List[str]) - Keys that trigger list element selection.
  • confirm(List[str]) - Keys that trigger list confirmation.
  • delete(List[str]) - Keys that trigger character deletion.
  • down(List[str]) - Keys that select the element below.
  • up(List[str]) - Keys that select the element above.

Config Objects

class Config()

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 (e.g.: None, [] ). Defaults to False.

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) -> TargetType

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.

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[Any],
           preprocessor: Callable[[Any], Any] = lambda val: val,
           cursor: str = '>',
           cursor_style: str = 'pink1',
           cursor_index: int = 0,
           return_index: bool = False,
           strict: bool = False) -> Union[Selection, None]

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

Arguments:

  • options List[Any] - A list of options to select from
  • preprocessor Callable[[Any], Any] - 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.

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[Any],
                    preprocessor: Callable[[Any], Any] = lambda val: 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) -> Selections

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

Arguments:

  • options List[Any] - A list of options to select from
  • preprocessor Callable[[Any], Any] - 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
  • 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.

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]

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]