prompt

The Prompt class supplies a number of methods which manage command-line input and validation.

class promptpy.prompt.Prompt(console: Console | None = None)[source]

Call methods of this class to prompt for and validate different types of data (characters, integers, etc.).

If you have a Rich Console instance already created, supply it to the constructor, otherwise one will be created.

Parameters:

console (Console) – Rich console instance, if one has been created (default=None)

choice(text: str, choices: list[str], default: str | None = None, commands: str = '', transform: Literal['upper', 'lower', 'casefold', 'none'] = 'none') → str[source]

Prompt for one of a list of predefined choices.

The choices are provided as a list of strings:

prompt = Prompt()
choices = ["ham", "eggs", "spam"]
choice = prompt.choice("Please choose your breakfast", choices, default="ham")
# Prompt is displayed as:
# Please choose your breakfast [ham]:
Parameters:

  • text (str) – Text prompt to display

  • choices (list[str]) – List of available choices

  • default (str) – Default option (default=None)

  • commands (str) – String of single-letter commands to accept (default=’’)

  • transform (str) – Transformation to apply to input before returning (default=’none’)

Returns:

Validated user input

Return type:

str

date(text: str, format: str, default: date | None = None, commands: str = '', transform: Literal['upper', 'lower', 'casefold', 'none'] = 'upper', accept_empty: bool = False) → date | str[source]

Prompt for a date

prompt = Prompt()
date = prompt.date('Enter a date (dd/mm/yyyy)', '%d/%m/%Y', default=datetime.date(2024, 1, 1))
# Prompt is displayed as:
# Enter a date (dd/mm/yyyy) [01/01/2024]:
Parameters:

  • text (str) – Prompt text

  • format (str) – Date format as per strptime()

  • default (datetime.date) – Default value (default=None)

  • commands (str) – String of single-letter commands to accept (default=’’)

  • transform (str) – Transformation to apply to command input before returning (default=’upper’)

  • accept_empty (bool) – Accept the empty string as a return value (default=False)

Returns:

The date or command entered at the prompt, or the default value if nothing was entered

Return type:

datetime.date | str

float(text: str, min: float | None = None, max: float | None = None, default: float | None = None, commands: str = '', transform: Literal['upper', 'lower', 'casefold', 'none'] = 'upper') → float | str[source]

Prompt for a float.

prompt = Prompt()
prompt.float('Pick a number', min=1.2, max=3.5, default=2.0)
# Prompt is displayed as:
# Pick a number (1.2-3.5) [2.0]:
Parameters:

  • text (str) – Prompt text

  • min (float) – Minimum accepted value (default=None)

  • max (float) – Maximum accepted value (default=None)

  • default (float) – Default value (default=None)

  • commands (str) – String of single-letter commands to accept (default=’’)

  • transform (str) – Transformation to apply to command input before returning (default=’upper’)

Returns:

The float or command entered at the prompt, or the default value if none was entered

Return type:

Union[float, str]

integer(text: str, min: int | None = None, max: int | None = None, default: int | None = None, commands: str = '', transform: Literal['upper', 'lower', 'casefold', 'none'] = 'upper') → int | str[source]

Prompt for an integer.

prompt = Prompt()
prompt.integer('Pick a number', min=1, max=10, default=7)
# Prompt is displayed as:
# Pick a number (1-10) [7]:
Parameters:

  • text (str) – Prompt text

  • min (int) – Minimum accepted value (default=None)

  • max (int) – Maximum accepted value (default=None)

  • default (int) – Default value (default=None)

  • commands (str) – String of single-letter commands to accept (default=’’)

  • transform (str) – Transformation to apply to command input before returning (default=’upper’)

Returns:

The integer or command entered at the prompt, or the default value if none was entered

Return type:

Union[int, str]

options(options: dict[str, str], default: str | None = None, transform: Literal['upper', 'lower', 'casefold', 'none'] = 'upper', multi_line: int = 5) → str[source]

Prompt for one of a list of command options.

Options are provided as a dict where the key is the character to enter to select the option and the value is a description of that option. The function creates a prompt to present the options to the user:

prompt = Prompt()
options = {
    's': 'to solve',
    'p': 'to play',
    'q': 'to quit',
}
choice = prompt.options(options, default='s')
# Prompt is displayed as:
# Enter S to solve, P to play, Q to quit [S]:

If the number of options is greater than or equal to``multi_line`` the options will be split across multiple lines:

prompt = Prompt()
options = {
    's': 'to solve',
    'p': 'to play',
    'q': 'to quit',
}
choice = prompt.options(options, default='s', multi_line=2)
# Prompt is displayed as:
# S to solve
# P to play
# Q to quit
# Enter choice [S]:
Parameters:

  • options (dict[str, str]) – Options to display

  • default (str) – Default option (default=None)

  • transform (str) – Transformation to apply to input before returning (default=’upper’)

  • multi_line (int) – Lowest number of options to split across multiple lines (default=5)

Returns:

Selected option, or default option if none is selected

Return type:

str

prompt(text: str, validators: list[Callable[[str], None]] | None = None, commands: str = '', transform: Literal['upper', 'lower', 'casefold', 'none'] = 'none', default: str = '') → str[source]

Display a command line prompt and return the user input.

The validators parameter takes an optional list of validators. This is any callable that takes a string as its single parameter and raises a ValidationError if the string is invalid according to its validation rules.

If any validation fails the user prompt will be redisplayed, preceded by the validation error message.

prompt accepts an optional string of case-insensitive single-letter commands. If any one of these characters is entered at the prompt it will be returned without any further validation being undertaken.

The transform parameter indicates how the input string should be transformed before returning. It can be one of:

  • ‘upper’: converted to upper case

  • ‘lower’: converted to lower case

  • ‘casefold`: applies str.casefold()

  • ‘none’: input string is returned as entered

If default is provided and the user input is empty, the value of default will be returned without any further validation.

Parameters:

  • text (str) – Text prompt to display

  • validators (list[Callable[[str], None]]) – Validators to test user input (default=None)

  • commands (str) – String of single-letter commands to accept (default=’’)

  • transform (str) – Transformation to apply to input before returning (default=’none’)

  • default (str) – Value to return if no user input is supplied (default=’’)

Returns:

Validated user input

Return type:

str

string_list(text: str, default: list[str] | None = None, transform: Literal['upper', 'lower', 'casefold', 'none'] = 'none') → list[str][source]

Prompt for a list of strings.

Presents user with a text prompt and an options default:

prompt = Prompt()
prompt.list("Words to exclude", default=["yes", "no")
# Prompt is displayed as:
# Words to exclude [yes, no]:

Words should be separated by a comma, and will be stored without leading or trailing whitespace.

Parameters:

  • text (str) – Prompt text

  • default (list[str]) – Default option (default=None)

  • transform (str) – Transformation to apply to input before returning (default=’none’)

Returns:

The words entered at the prompt

Return type:

list[str]

static transform_text(text: str, transform: Literal['upper', 'lower', 'casefold', 'none']) → str[source]

Apply a case transformation.

The transform parameter indicates how the text should be transformed. It can be one of:

  • ‘upper’: converted to upper case

  • ‘lower’: converted to lower case

  • ‘casefold`: applies str.casefold()

  • ‘none’: no transformation applied

Parameters:

  • text (str) – Text to transform

  • transform (str) – Transformation to apply

yes_no(text: str, default: str | None = None, transform: Literal['upper', 'lower', 'casefold', 'none'] = 'upper') → str[source]

Prompt for a yes/no response.

Presents user with a y/n option and an optional default:

prompt = Prompt()
choice = prompt.yes_no("Again", default="y")
# Prompt is displayed as:
# Again (Y/N)? [Y]:
Parameters:

  • text (str) – Prompt text

  • default (str) – Default option (default=None)

  • transform (str) – Transformation to apply to input before returning (default=’upper’)

Returns:

The letter entered at the prompt

Return type:

str