API Reference¶
console_utilities Module¶
-
console_utilities.
input_boolean
(prompt: str, default: Optional[bool] = False, error_message: Optional[str] = None, true_string: str = 'y', false_string: str = 'n') → bool¶ Allows the user to input a boolean.
Specifically, this function does the following:
- Prints the prompt
- Waits for the user to enter a value
- Checks the value is valid (i.e. equal to
true_string
orfalse_string
). - If valid, the corresponding boolean value is returned (i.e.
True
fortrue_string
andFalse
forfalse_string
). If not valid, the default value will be returned. If not valid and a default has not been provided, the error message is printed and the function loops until a valid value is entered.
Note that case is ignored.
Parameters: - prompt – Prompt message to print on waiting for input. If
None
, the default prompt will be used. - default – Specifies a default value to use on entering an invalid value (i.e. a value other than
true_string
orfalse_string
). IfTrue
, an invalid value will be consideredTrue
. IfFalse
, an invalid value will be consideredFalse
. IfNone
, the user must enter eithertrue_string
orfalse_string
. - error_message – Error message to print on entering an invalid value. If
None
, the default error message will be used. Ignored ifdefault
is notNone
. - true_string – The string used to represent
True
. - false_string – The string used to represent
False
.
Returns: The boolean value entered by the user.
-
console_utilities.
input_float
(prompt: Optional[str] = None, min_value: Optional[float] = None, max_value: Optional[float] = None, error_message: Optional[str] = None, include_min: bool = True, include_max: bool = False, default: Optional[float] = None) → float¶ Allows the user to input a float, possibly within a specified range.
Specifically, this function does the following:
- Prints the prompt
- Waits for the user to enter a value
- Checks the value is valid (i.e. is a valid float and in the specified range, if applicable).
- If valid, the value is returned. If not valid, the error message is printed and the function loops until a valid value is entered. Hence, this function should only ever return a valid value.
Parameters: - prompt – Prompt message to print on waiting for input. If
None
, the default prompt will be used. - min_value – Minimum value allowed. Inclusive if
include_min
isTrue
; exclusive otherwise. UseNone
if a minimum value is not required. - max_value – Maximum value allowed. Inclusive if
include_max
isTrue
; exclusive otherwise. UseNone
if a maximum value is not required. - error_message – Error message to print on entering an invalid value. If
None
, the default error message will be used. - include_min – Specifies whether the
min_value
is inclusive. UseTrue
for inclusive orFalse
for exclusive. - include_max – Specifies whether the
max_value
is inclusive. UseTrue
for inclusive orFalse
for exclusive. - default – Specifies a default value to return on entering an invalid value. If
None
, the function will loop until a valid value is entered.
Returns: The valid float value entered by the user.
-
console_utilities.
input_int
(prompt: Optional[str] = None, min_value: Optional[int] = None, max_value: Optional[int] = None, error_message: Optional[str] = None, include_max: bool = False, default: Optional[int] = None) → int¶ Allows the user to input an integer, possibly within a specified range.
Specifically, this function does the following:
- Prints the prompt
- Waits for the user to enter a value
- Checks the value is valid (i.e. is a valid integer and in the specified range, if applicable).
- If valid, the value is returned. If not valid, the error message is printed and the function loops until a valid value is entered. Hence, this function should only ever return a valid value.
Parameters: - prompt – Prompt message to print on waiting for input. If
None
, the default prompt will be used. - min_value – Minimum value allowed. Inclusive. Use
None
if a minimum value is not required. - max_value – Maximum value allowed. Inclusive if
include_max
isTrue
; exclusive otherwise. UseNone
if a maximum value is not required. - error_message – Error message to print on entering an invalid value. If
None
, the default error message will be used. - include_max – Specifies whether the
max_value
is inclusive. UseTrue
for inclusive orFalse
for exclusive. - default – Specifies a default value to return on entering an invalid value. If
None
, the function will loop until a valid value is entered.
Returns: The valid integer value entered by the user.
-
console_utilities.
input_multiple_int
(prompt: Optional[str] = None, min_value: Optional[int] = None, max_value: Optional[int] = None, error_message: Optional[str] = None, include_max: bool = False, default: Optional[List[int]] = None, separator: Optional[str] = None, allow_empty: bool = True) → List[int]¶ Allows the user to input multiple integers, optionally with each in a specified range.
Parameters: - prompt – Prompt message to print on waiting for input. If
None
, the default prompt will be used. - min_value – Minimum value allowed. Inclusive. Use
None
if a minimum value is not required. - max_value – Maximum value allowed. Inclusive if
include_max
isTrue
; exclusive otherwise. UseNone
if a maximum value is not required. - error_message – Error message to print on entering an invalid value. If
None
, the default error message will be used. - include_max – Specifies whether the
max_value
is inclusive. UseTrue
for inclusive orFalse
for exclusive. - default – Specifies a default value to return on entering an invalid value. If
None
, the function will loop until a valid value is entered. - separator – Specifies the separator string to use when splitting the input into multiple values. If
None
or an empty string, then whitespace will be used. - allow_empty – Specifies whether no values may be entered. If
True
, zero or more values may be entered; ifFalse
, one or more values may be entered.
Returns: The valid integer values entered by the user.
- prompt – Prompt message to print on waiting for input. If
-
console_utilities.
input_multiple_option_int
(options: List[str], prompt: Optional[str] = None, error_message: Optional[str] = None, separator: Optional[str] = None, allow_empty: bool = True) → List[int]¶ Allows the user to select multiple options from a list of options by entering the options’ indices.
Parameters: - options – List of option names. Example:
["Export to PDF", "Export to HTML"]
. - prompt – Prompt message to print on waiting for input. If
None
, the default prompt will be used. - error_message – Error message to print on entering an invalid value. If
None
, the default error message will be used. - separator – Specifies the separator string to use when splitting the input into multiple values. If
None
or an empty string, then whitespace will be used. - allow_empty – Specifies whether no values may be entered. If
True
, zero or more values may be entered; ifFalse
, one or more values may be entered.
Returns: The indices of the selected options.
- options – List of option names. Example:
-
console_utilities.
input_option_char
(options: List[str], chars: List[str], prompt: str = None, error_message: str = None, ignore_case: bool = True, default: Optional[str] = None) → str¶ Allows the user to select from a list of options by entering a character.
Specifically, this function does the following:
- Displays a list of option names with their associated characters
- Prints the prompt
- Waits for the user to enter a value
- Checks the value is valid (i.e. is a valid integer and in the specified range, if applicable).
- If valid, the value is returned; else, the error message is printed and this process is repeated until a valid value is entered. Hence, this function should only ever return a valid value.
options
andchars
are expected to be lists of the same length. Additionally,chars
must not contain duplicates, to avoid ambiguity. Ifignore_case
isTrue
then case is also ignored when checking for duplicates.Parameters: - options – List of option names. Example:
["Export to PDF", "Export to HTML"]
. - chars – List of characters to associate with each option. Example:
["p", "h"]
. - prompt – Prompt message to print on waiting for input. If
None
, the default prompt will be used. - error_message – Error message to print on entering an invalid value. If
None
, the default error message will be used. - ignore_case – Specifies whether case should be ignored. If
True
, this also means that the characters inchars
will be output in lower case to reduce confusion for the user. (To me, displaying some characters in upper case and some in lower case implies that case is not ignored.) - default – Specifies a default value to return on entering an invalid value. If
None
, the function will loop until a valid value is entered.
Returns: The character corresponding to the selected option.
Todo
- Replace the
options
andchars
lists with a single list of objects.
-
console_utilities.
input_option_int
(options: List[str], prompt: Optional[str] = None, error_message: Optional[str] = None) → int¶ Allows the user to select a single option from a list of options by entering the option’s index.
Specifically, this function does the following:
- Displays a list of option names with their indices
- Waits for the user to input an index (i.e. an integer between 0 and
len(options) - 1
) usinginput_option_int()
Parameters: - options – List of option names. Example:
["Export to PDF", "Export to HTML"]
. - prompt – Prompt message to print on waiting for input. If
None
, the default prompt will be used. - error_message – Error message to print on entering an invalid value. If
None
, the default error message will be used. - default – Specifies a default value to return on entering an invalid value. If
None
, the function will loop until a valid value is entered.
Returns: The index of the selected option.