rbtools.utils.console¶

Utilities for working with console interactions.

Functions

rbtools.utils.console.get_input(prompt: str, require: bool = False, stderr: ~typing.TextIO = <_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, stdin: ~typing.TextIO = <_io.TextIOWrapper name='<stdin>' mode='r' encoding='utf-8'>) → str[source]¶

Ask the user for input.

Changed in version 3.1: stdout and stderr streams are now supported. This can now be used with a non-TTY input stream.

If stdin is not a TTY, this will read lines of input until it receives a valid answer.

Parameters:

• prompt (str) – The text to prompt the user with.

• require (bool, optional) – Whether to require a result. If True, this will keep prompting until a non-empty value is entered.

• stderr (io.TextIOWrapper or file, optional) –

  The error stream to use for the prompt.

  New in version 3.1.

• stdin (io.TextIOWrapper or file, optional) –

  The input stream to use.

  New in version 3.1.

Returns:

The entered user data.

Return type:

str

rbtools.utils.console.get_pass(prompt: str, require: bool = False, stderr: ~typing.TextIO = <_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, stdin: ~typing.TextIO = <_io.TextIOWrapper name='<stdin>' mode='r' encoding='utf-8'>) → str[source]¶

Ask the user for a password.

Changed in version 3.1: stdout and stderr streams are now supported. This can now be used with a non-TTY input stream.

If stdin is not a TTY, this will read lines of input until it receives a valid answer.

Parameters:

• prompt (str) – The text to prompt the user with.

• require (bool, optional) – Whether to require a result. If True, this will keep prompting until a non-empty value is entered.

• stderr (io.TextIOWrapper or file, optional) –

  The error stream to use for the prompt.

  New in version 3.1.

• stdin (io.TextIOWrapper or file, optional) –

  The input stream to use.

  New in version 3.1.

Returns:

The entered password.

Return type:

str

rbtools.utils.console.confirm(question: str, stderr: ~typing.TextIO = <_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, stdin: ~typing.TextIO = <_io.TextIOWrapper name='<stdin>' mode='r' encoding='utf-8'>) → bool[source]¶

Interactively prompt for a Yes/No answer.

This requires a Yes or a No answer. These are case-insensitive.

Valid Yes answers include: y, yes, t, true, on, 1.

Valid No answers include: n, no, f, false, off, 0.

If stdin is not a TTY, this will read lines of input until it receives a valid answer.

Changed in version 3.1: stdout and stderr streams are now supported. This can now be used with a non-TTY input stream.

Parameters:

• question (str) – The question to ask.

• stderr (io.TextIOWrapper or file, optional) –

  The error stream to use for the prompt.

  New in version 3.1.

• stdin (io.TextIOWrapper or file, optional) –

  The input stream to use.

  New in version 3.1.

Returns:

The confirmed value.

Return type:

bool

rbtools.utils.console.confirm_select(question: str, options_length: int, stderr: ~typing.TextIO = <_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, stdin: ~typing.TextIO = <_io.TextIOWrapper name='<stdin>' mode='r' encoding='utf-8'>) → int[source]¶

Interactively prompt for a specific answer from a list of options.

Accepted answers are integers starting from 1 until an integer n representing the nth of element within options.

If stdin is not a TTY, this will read lines of input until it receives a valid answer.

Changed in version 3.1: stdout and stderr streams are now supported. This can now be used with a non-TTY input stream.

Parameters:

• question (str) – The prompt to be displayed.

• options_length (int) – The number of available options that the user can choose a response from.

• stderr (io.TextIOWrapper or file, optional) –

  The error stream to use for the prompt.

  New in version 3.1.

• stdin (io.TextIOWrapper or file, optional) –

  The input stream to use.

  New in version 3.1.

Returns:

The user’s chosen response. If the user decides to cancel the prompt, None is returned.

Return type:

str

rbtools.utils.console.edit_file(filename: str) → str[source]¶

Run a user-configured editor to edit an existing file.

This will run a configured text editor (trying the VISUAL or EDITOR environment variables, falling back on vi) to request text for use in a commit message or some other purpose.

Parameters:

filename (str) – The file to edit.

Returns:

The resulting content.

Return type:

str

Raises:

rbcommons.utils.errors.EditorError – The configured editor could not be run, or it failed with an error.

rbtools.utils.console.edit_text(content: str = '', filename: Optional[str] = None) → str[source]¶

Run a user-configured editor to prompt for text.

This will run a configured text editor (trying the VISUAL or EDITOR environment variables, falling back on vi) to request text for use in a commit message or some other purpose.

Parameters:

• content (str, optional) – Existing content to edit.

• filename (str, optional) – The optional name of the temp file to edit. This can be used to help the editor provide a proper editing environment for the file.

Returns:

The resulting content.

Return type:

str

Raises:

rbcommons.utils.errors.EditorError – The configured editor could not be run, or it failed with an error.