CliSession

Defines UX state for a program, to ensure a consistent look and feel for its CLI.

UX state consists of a combination of CliColors and CliStrings. These are set by the constructor arguments upon creating an instance of this class, and can subsequently be accessed through the instance's read-only properties.

This class also provides a number of utility functions for command-line input and output. In order to maintain a consistent UX, these functions should be used for all CLI interactions that require anything beyond a simple print() statement.

Info - Prerequisite for the examples

All of the examples in this class reference a CliSession variable named cli, which may be created as follows:

Python Console Session

>>> from botstrap.internal import CliSession
>>> cli = CliSession(name="cli-demo")

To keep the examples focused and brief, the above definition is only explicitly written out once in this section. However, all of the examples will fail with a NameError if the cli variable is not defined.

__init__(name, colors=CliColors.default(), strings=CliStrings.default())

Parameters:

Name	Type	Description	Default
name	str	The name of the program. Will be displayed in some parts of the CLI, and may be used to fetch package metadata.	required
colors	CliColors	The colors to be used by the CLI.	CliColors.default()
strings	CliStrings	The strings to be used by the CLI.	CliStrings.default()

Defines UX state for a program, to ensure a consistent look and feel for its CLI.

UX state consists of a combination of CliColors and CliStrings. These are set by the constructor arguments upon creating an instance of this class, and can subsequently be accessed through the instance's read-only properties.

This class also provides a number of utility functions for command-line input and output. In order to maintain a consistent UX, these functions should be used for all CLI interactions that require anything beyond a simple print() statement.

Info - Prerequisite for the examples

All of the examples in this class reference a CliSession variable named cli, which may be created as follows:

Python Console Session

>>> from botstrap.internal import CliSession
>>> cli = CliSession(name="cli-demo")

To keep the examples focused and brief, the above definition is only explicitly written out once in this section. However, all of the examples will fail with a NameError if the cli variable is not defined.

name() -> str property

The name of the program that owns this CliSession.

colors() -> CliColors property

The CliColors used by this instance.

strings() -> CliStrings property

The CliStrings used by this instance.

confirm_or_exit(question: str) -> None

Exits the program if the user responds non-affirmatively to a prompt.

If the user responds affirmatively, this function will return without raising any errors, allowing program execution to continue normally.

Example - Deciding whether to continue or exit

Python Console Session

>>> cli.confirm_or_exit("Would you like to continue?")
Would you like to continue? If so, type "yes" or "y":

Parameters:

Name	Type	Description	Default
question	str	The first part of the prompt. Should be phrased as a question that can be meaningfully answered by a "yes" / "no" response.	required

Raises:

Type	Description
SystemExit	If the user responds non-affirmatively. Will be raised with exit code 0.

exit_process(reason: str = '', is_error: bool = True) -> None

Exits the program in a user-friendly manner.

By default, the provided reason will be colored either red or grey (depending on the value of is_error) when it is displayed in the console.

Example - Exiting with an error message

Python Console Session

>>> cli.exit_process("Just testing the 'exit_process()' function!")
Just testing the 'exit_process()' function! Exiting process.

Console Session

Process finished with exit code 0

Note: Depending on your shell settings, the text in the second code block (titled "Console Session") may or may not be displayed. This does not change the behavior of this function, which is unaffected by what gets printed after its process is terminated.

Parameters:

Name	Type	Description	Default
reason	str	A human-readable explanation for why the program is ending. If omitted, the program will exit silently.	''
is_error	bool	Whether the program is ending due to an error. Determines its exit code and the color of the displayed reason text.	True

Raises:

Type	Description
SystemExit	If is_error is True, this will be raised with exit code 1 to indicate an "abnormal" exit. Otherwise, it will be raised with exit code 0 to indicate a "successful" exit.

get_bool_input(question: str) -> bool

Returns a boolean value corresponding to the user's response to a prompt.

Example - Printing output based on user input

Python Console Session

>>> if cli.get_bool_input("Do you believe in life after love?"):
...     print("I can feel something inside me say...")
... else:
...     print("I really don't think you're strong enough, no!")
...
Do you believe in life after love? If so, type "yes" or "y": umm...
I really don't think you're strong enough, no!

Note: You might have to hit the "Enter" or "Return" key an additional time after pasting this example into the console, to force the interpreter to recognize the end of the if statement.

Parameters:

Name	Type	Description	Default
question	str	The first part of the prompt. Should be phrased as a question that can be meaningfully answered by a "yes" / "no" response.	required

Returns:

Type	Description
bool	True if the user responds affirmatively, otherwise False.

get_hidden_input(prompt: str, format_input: Callable[[str], str] | None = None) -> str

Returns the user's input without echoing. Prints a safe representation of it.

This function tries to provide a user-friendly experience without leaking the resulting input. If the descriptions in the "Parameters" section below are undesirable for your use case, consider using get_input() (with the keyword argument echo_input=False) instead of this function.

Example - Obtaining input that should be hidden

Python Console Session

>>> very_secure_password = cli.get_hidden_input("Enter your password")
Enter your password: *******
>>> print(very_secure_password)  # NEVER do this with a real password!
hunter2

Parameters:

Name	Type	Description	Default
prompt	str	A short human-readable prompt for the user. Will always be followed by a colon (:) and a single space, and will also be highlighted if colors are enabled.	required
format_input	Callable[[str], str] | None	A function that accepts the raw user input and returns a string that can be safely displayed on the screen. If omitted, the input will be shown as a sequence of asterisks (one * for each character in the original input).	None

Returns:

Type	Description
str	The user's response as a string, stripped of leading & trailing whitespace.

get_input(prompt: str, *, echo_input: bool = True) -> str

Returns the user's input, with the option to turn off echoing.

In this context, "echoing" is displaying the user's input on the screen as they type. For security reasons, it's undesirable when dealing with sensitive data.

This function does not do anything special to format its console output. If you require sensitive user input with more nuanced console output, consider using get_hidden_input() instead.

Example - Obtaining and echoing user input

Python Console Session

>>> print(cli.get_input("Baby shark,"))
Baby shark, doo doo doo
doo doo doo

Parameters:

Name	Type	Description	Default
prompt	str	A short human-readable prompt for the user. Will be followed by a single space.	required
echo_input	bool	Whether the user's input should be displayed on the screen. Set this to False for sensitive input.	True

Returns:

Type	Description
str	The user's response as a string, stripped of leading & trailing whitespace.

print_prefixed(message: str = '', is_error: bool = False, suppress_newline: bool = False) -> None

Prints a message prefixed by the program name, and optionally an error label.

Example - Printing program prefix labels

Python Console Session

>>> cli.print_prefixed("What does the fox say?")
cli-demo: What does the fox say?
>>> cli.print_prefixed("Ring-ding-ding-ding-dingeringeding!", is_error=True)
cli-demo: error: Ring-ding-ding-ding-dingeringeding!

Parameters:

Name	Type	Description	Default
message	str	A human-readable string to display. If omitted, only the prefix will be printed, followed by a space instead of the usual newline. This allows subsequent text to be printed on the same line (after the prefix).	''
is_error	bool	Whether an error label should be included in the prefix (after the program name).	False
suppress_newline	bool	Whether to end the printed message with a space instead of a newline, even if message is non-empty.	False