API Reference¶

Prompts¶

Select a single choice from a vertical list.

Parameters:

message (str or rich.text.Text) – The message to display above the choices.
choices (iterable of T or Choice[T]) – The values to choose from. Each choice can be a raw value or an instance of Choice, which allows customization of labels and descriptions.
cursor_pointer (str, default "❯") – The string to use as the cursor pointer.
numbered (bool or None, default None) –
Whether to display numbered choices, also enabling digit shortcuts (1-9). If None, show numbers only when there are at most 9 choices and they all fit in the viewport.

Changed in version 0.2.0: Numbers were previously shown by default.
viewport_size (int or None, default None) –
The maximum number of choices visible at once, at least 3. If None, fit as many choices as the terminal height allows.

Added in version 0.2.0.
show_hint (bool, default True) – Whether to show a hint about how to select choices.
console (rich.console.Console, optional) – A Console instance. If None, use the global console.

Examples

>>> prompt = Select("Choose a color:", ["Red", "Green", "Blue"])
>>> color = prompt()

__call__(index: int = 0) → T¶

Run the prompt loop.

Parameters:: index (int, default 0) – The index of the choice to select by default.
Return type:: The value of the selected choice.

classmethod ask(message: str | Text, choices: Iterable[Choice[T] | T], *, index: int = 0, cursor_pointer: str = '❯', numbered: bool | None = None, viewport_size: int | None = None, show_hint: bool = True, console: Console | None = None) → T¶

Shortcut to construct and run a prompt loop and return the result.

Parameters:

message (str or rich.text.Text) – The message to display above the choices.
choices (iterable of T or Choice[T]) – The values to choose from. Each choice can be a raw value or an instance of Choice, which allows customization of labels and descriptions.
index (int, default 0) – The index of the choice to have the cursor start on.
cursor_pointer (str, default "❯") – The string to use as the cursor pointer.
numbered (bool or None, default None) –
Whether to display numbered choices, also enabling digit shortcuts (1-9). If None, show numbers only when there are at most 9 choices and they all fit in the viewport.

Changed in version 0.2.0: Numbers were previously shown by default.
viewport_size (int or None, default None) –
The maximum number of choices visible at once, at least 3. If None, fit as many choices as the terminal height allows.

Added in version 0.2.0.
show_hint (bool, default True) – Whether to show a hint about how to select choices.
console (rich.console.Console, optional) – A Console instance. If None, use the global console.

Return type:

The value of the selected choice.

Examples

>>> color = Select.ask("Choose a color:", ["Red", "Green", "Blue"])

pre_prompt() → None¶: Hook to display something before the prompt.

Select multiple choices from a vertical list.

Parameters:

message (str or rich.text.Text) – The message to display above the choices.
choices (iterable of T or Choice[T]) – The values to choose from. Each choice can be a raw value or an instance of Choice, which allows customization of labels and descriptions.
cursor_pointer (str, default "❯") – The string to use as the cursor pointer.
numbered (bool or None, default None) –
Whether to display numbered choices, also enabling digit shortcuts (1-9). If None, show numbers only when there are at most 9 choices and they all fit in the viewport.

Changed in version 0.2.0: Numbers were previously shown by default.
show_hint (bool, default True) – Whether to show a hint about how to select choices.
viewport_size (int or None, default None) –
The maximum number of choices visible at once, at least 3. If None, fit as many choices as the terminal height allows.

Added in version 0.2.0.
console (rich.console.Console, optional) – A Console instance. If None, use the global console.

Examples

>>> prompt = MultiSelect("Choose colors:", ["Red", "Green", "Blue"])
>>> colors = prompt()

__call__(index: int = 0, default: set[int] | None = None) → list[T]¶

Run the prompt loop.

Parameters:

index (int, default 0) – The index of the choice to have the cursor start on.
default (set of int, optional) – A set of indices of choices that should be selected by default.

Return type:

List of values of the selected choices.

Shortcut to construct and run a prompt loop and return the result.

Parameters:

message (str or rich.text.Text) – The message to display above the choices.
choices (iterable of T or Choice[T]) – The values to choose from. Each choice can be a raw value or an instance of Choice, which allows customization of labels and descriptions.
index (int, default 0) – The index of the choice to have the cursor start on.
default (set of int, optional) – A set of indices of choices that should be selected by default.
cursor_pointer (str, default "❯") – The string to use as the cursor pointer.
numbered (bool or None, default None) –
Whether to display numbered choices, also enabling digit shortcuts (1-9). If None, show numbers only when there are at most 9 choices and they all fit in the viewport.

Changed in version 0.2.0: Numbers were previously shown by default.
show_hint (bool, default True) – Whether to show a hint about how to select choices.
viewport_size (int or None, default None) –
The maximum number of choices visible at once, at least 3. If None, fit as many choices as the terminal height allows.

Added in version 0.2.0.
console (rich.console.Console, optional) – A Console instance. If None, use the global console.

Return type:

List of values of the selected choices.

Examples

>>> colors = MultiSelect.ask("Choose colors:", ["Red", "Green", "Blue"])

pre_prompt() → None¶: Hook to display something before the prompt.

class richer_prompt.Tabs(message: str | Text, choices: Iterable[Choice[T] | T], *, console: Console | None = None)¶

Select a single choice from a horizontal list.

Parameters:

message (str or rich.text.Text) – The message to display above the choices.
choices (iterable of T or Choice[T]) – The values to choose from. Each choice can be a raw value or an instance of Choice, which allows customization of labels and descriptions.
console (rich.console.Console, optional) – A Console instance. If None, use the global console.

Examples

>>> prompt = Tabs("Choose a color:", ["Red", "Green", "Blue"])
>>> color = prompt()

__call__(index: int = 0) → T¶

Run the prompt loop.

Parameters:: index (int, default 0) – The index of the choice to select by default.
Return type:: The value of the selected choice.

classmethod ask(message: str | Text, choices: Iterable[Choice[T] | T], *, index: int = 0, console: Console | None = None) → T¶

Shortcut to construct and run a prompt loop and return the result.

Parameters:

message (str or rich.text.Text) – The message to display above the choices.
choices (iterable of T or Choice[T]) – The values to choose from. Each choice can be a raw value or an instance of Choice, which allows customization of labels and descriptions.
index (int, default 0) – The index of the choice to have the cursor start on.
console (rich.console.Console, optional) – A Console instance. If None, use the global console.

Return type:

The value of the selected choice.

Examples

>>> color = Tabs.ask("Choose a color:", ["Red", "Green", "Blue"])

pre_prompt() → None¶: Hook to display something before the prompt.

class richer_prompt.Form(steps: dict[str, Select | MultiSelect], *, required: bool = True, show_hint: bool = True, console: Console | None = None)¶

Ask a sequence of choice prompts as a single, navigable form.

Added in version 0.3.0.

Steps are shown one at a time with a tab bar to move between them, followed by a review step to submit all answers at once. Choosing Cancel on the review step raises PromptCancelled.

By default every step must be answered before the form can be submitted, so the result always has one entry per step. Pass required=False to allow submitting a partial form, in which case only answered steps appear in the result.

Parameters:

steps (dict) – Steps to ask. The keys are the names in navigation tabs and in the return dict, while the values are the prompts to ask. Only Select and MultiSelect are supported.
required (bool, default True) – Whether every step must be answered before the form can be submitted. When False, the form may be submitted with unanswered steps, which are then omitted from the result.
console (rich.console.Console, optional) – A Console instance. If None, use the global console.

Examples

>>> Form(
...     {
...         "Protein": Select("Choose a protein:", ["Ham", "Chicken", "Tofu"]),
...         "Bread": Select("Choose a bread:", ["White", "Wheat", "Rye"]),
...         "Toppings": MultiSelect("Any toppings?", ["Lettuce", "Tomato", "Onion", "Pickles"]),
...     }
... )
>>> answers = form()

__call__(index: int = 0) → dict[str, Any]¶

Run the form loop.

Return type:: A dict of step name as keys and answer as value, for each answered step.

classmethod ask(steps: dict[str, Select | MultiSelect], *, show_hint: bool = True, required: bool = True, console: Console | None = None) → dict[str, Any]¶

Shortcut to construct, run a form and return the answers.

Parameters:

steps (dict of str to Select or MultiSelect) – The prompts to ask, keyed by the name used in the result.
required (bool, default True) – Whether every step must be answered before the form can be submitted. When False, unanswered steps are omitted from the result.
console (rich.console.Console, optional) – A Console instance. If None, use the global console.

Return type:

A dict of step name as keys and answer as value, for each answered step.

Examples

>>> answers = Form.ask(
...     {
...         "Protein": Select("Choose a protein:", ["Ham", "Chicken", "Tofu"]),
...         "Bread": Select("Choose a bread:", ["White", "Wheat", "Rye"]),
...         "Toppings": MultiSelect("Any toppings?", ["Lettuce", "Tomato", "Onion", "Pickles"]),
...     }
... )

pre_prompt() → None¶: Hook to display something before the prompt.

Choices¶

class richer_prompt.Choice(value: T, label: str = '', description: str = '', disabled: bool = False)¶

A selectable choice used by prompt classes.

Parameters:

value (T) – The choice value returned when selected.
label (str, optional) – The label to display for the choice. If not provided, the value is used as the label.
description (str, optional) – Additional text to describe the choice.
disabled (bool, default False) –
If True, the choice cannot be selected or toggled.

Added in version 0.3.0.

description: str¶

disabled: bool¶

property display: str¶: Get the display string for the choice.

label: str¶

value: T¶

Exceptions¶

exception richer_prompt.NotInteractiveError¶: Raised when a prompt is run without an interactive terminal.

exception richer_prompt.PromptCancelled¶

Raised when the user deliberately cancels a prompt.

Distinct from KeyboardInterrupt (Ctrl+C) so callers can tell a chosen cancellation apart from an interrupt.

Added in version 0.3.0.

Keys¶

Named keystrokes (arrows, Enter, Tab, Ctrl combos) carry a name such as “KEY_DOWN”, while printable keys carry none and are their own character. See blessed.keyboard.get_curses_keycodes() for the full list of names.

Added in version 0.2.0.

richer_prompt.keys.CTRL_C: Final = 'KEY_CTRL_C'¶: Ctrl+C; raises KeyboardInterrupt when read.

richer_prompt.keys.CTRL_D: Final = 'KEY_CTRL_D'¶: Ctrl+D; raises EOFError when read.

richer_prompt.keys.CTRL_Z: Final = 'KEY_CTRL_Z'¶: Ctrl+Z; treated as end-of-file on Windows.

richer_prompt.keys.DOWN: Final = 'KEY_DOWN'¶: Down arrow key.

richer_prompt.keys.END: Final = 'KEY_END'¶: End key.

richer_prompt.keys.ENTER: Final = 'KEY_ENTER'¶: Enter/Return key.

richer_prompt.keys.HOME: Final = 'KEY_HOME'¶: Home key.

richer_prompt.keys.LEFT: Final = 'KEY_LEFT'¶: Left arrow key.

richer_prompt.keys.RIGHT: Final = 'KEY_RIGHT'¶: Right arrow key.

richer_prompt.keys.SHIFT_TAB: Final = 'KEY_BTAB'¶: Shift+Tab (back-tab) key.

richer_prompt.keys.SPACE: Final = ' '¶: Space bar.

richer_prompt.keys.TAB: Final = 'KEY_TAB'¶: Tab key.

richer_prompt.keys.UP: Final = 'KEY_UP'¶: Up arrow key.

Testing¶

richer_prompt.testing.simulate_keys(*keys: str) → Iterator[None]¶

Simulate keyboard input for prompts run within the context block.

Prompts read the given keys in order instead of the real keyboard, so no interactive terminal is required.

Added in version 0.2.0.

Parameters:: *keys (str) – The keys to deliver, e.g. richer_prompt.keys.DOWN or plain characters. Control keys behave like the real keyboard: richer_prompt.keys.CTRL_C raises KeyboardInterrupt and richer_prompt.keys.CTRL_D raises EOFError.
Raises:: AssertionError – If a prompt is still waiting for input after all keys were delivered.

Examples

>>> from richer_prompt import keys, Select
>>> from richer_prompt.testing import simulate_keys
>>> with simulate_keys(keys.DOWN, keys.ENTER):
...     Select.ask("Choose a color:", ["Red", "Green", "Blue"])
'Green'