API Reference¶

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.Choice(value: T, label: str = '', description: str = '')¶

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.

description: str¶

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

label: str¶

value: T¶

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

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'

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.

richer_prompt.keys.vim_motion(key: str) → str¶: Translate a vim motion key to its arrow-key token, if it is one.