Reference

Type Aliases

columbo uses type aliases heavily to simplify the annotations for the functions provided by the library. The following table defines the aliases that are used.

Alias	Value
Answer	Union[bool, str]
Answers	Mapping[str, Answer]
Interaction	Union[Echo, Acknowledge, Question]
MutableAnswers	MutableMapping[str, Answer]
OptionList†	List[str]
Options	Union[List[str], Mapping[str, str]]
Possible*	Union[T, Literal[_Sentinel]]
ShouldAsk	Callable[[Answers], bool]
StaticOrDynamicValue	Union[V, Callable[[Answers], V]]
ValidationResponse	Union[ValidationSuccess, ValidationFailure]
Validator	Callable[[str, Answers], ValidationResponse]

Note

* Possible is a special construct used in copy() methods to indicate that a value was not provided. Possible, _Sentinel, & _NOT_GIVEN are not exposed by columbo, but are documented here for completeness.

† OptionList is deprecated in favor of Options. It will be removed in a future release.

Interactions

Acknowledge

Bases: Displayable

Display a message to the user and require the user to press ENTER to continue.

__init__(message, should_ask=None)

Initialize an instance.

Parameters:

Name	Type	Description	Default
message	StaticOrDynamicValue[str]	The message to be displayed to the user. If the value is callable, the argument passed in will be the answers that have been provided this far.	required
should_ask	Optional[ShouldAsk]	If None, the message is displayed to the user. Otherwise, the callable will be passed the answers that have been provided this far and should return True if the message should be displayed.	None

copy(*, message=_NOT_GIVEN, should_ask=_NOT_GIVEN)

Create a new instance like this one, potentially with different values.

Parameters:

Name	Type	Description	Default
message	Possible[StaticOrDynamicValue[str]]	The message to be displayed to the user. If the value is callable, the argument passed in will be the answers that have been provided this far.	_NOT_GIVEN
should_ask	Possible[Optional[ShouldAsk]]	If None, the message is displayed. Otherwise, the callable will be passed the answers that have been provided this far and should return True if the message should be displayed.	_NOT_GIVEN

Returns:

Type	Description
Acknowledge	A newly constructed instance with the given values in place of the values of this instance.

display(answers, no_user_input=False)

Display a message to the user and require the user to press ENTER to continue

Parameters:

Name	Type	Description	Default
answers	Answers	The answers that have been provided this far.	required
no_user_input	bool	If True the message will be displayed without waiting for the user to interact. Default: False	False

Raises:

Type	Description
ValueError	The value for message did not have the correct type.

BasicQuestion

Bases: Question[str]

A question with an arbitrary text answer.

__init__(name, message, default, cli_help=None, should_ask=None, validator=None, value_if_not_asked=None)

Initialize an instance.

Parameters:

Name	Type	Description	Default
name	str	The identifier that will be used as the key to access this question's answer.	required
message	StaticOrDynamicValue[str]	The message to be displayed to the user. If the value is callable, the argument passed in will be the answers that have been provided this far.	required
default	StaticOrDynamicValue[str]	The default answer to the question. If the value is callable, the argument passed in will be the answers that have been provided this far.	required
cli_help	Optional[str]	Optional help message to be displayed for command line interface.	None
should_ask	Optional[ShouldAsk]	If None, the question is asked. Otherwise, the callable will be passed the answers that have been provided this far and should return True if the question should be asked.	None
validator	Optional[Validator]	Callable that will validate the response given by the user. A ValidationSuccess object indicates success and a ValidationFailure object indicates failure.	None
value_if_not_asked	Optional[str]	If provided and if should_ask is being used, this value will be recorded as an answer if should_ask evaluates to False.	None

Raises:

Type	Description
ValueError	A value for value_if_not_asked was given without giving a value for should_ask.

ask(answers, no_user_input=False)

Prompt the user with this question.

Parameters:

Name	Type	Description	Default
answers	Answers	The answers that have been provided this far.	required
no_user_input	bool	If True the default value for the question will be used without waiting for the user to provide an answer. Default: False	False

Returns:

Type	Description
str	The answer to the question.

Raises:

Type	Description
ValueError	Default value did not satisfy the validator. Or the instance was misconfigured in some way.

copy(*, name=_NOT_GIVEN, message=_NOT_GIVEN, default=_NOT_GIVEN, cli_help=_NOT_GIVEN, should_ask=_NOT_GIVEN, validator=_NOT_GIVEN, value_if_not_asked=_NOT_GIVEN)

Create a new instance like this one, potentially with different values.

Parameters:

Name	Type	Description	Default
name	Possible[str]	The identifier that will be used as the key to access this question's answer.	_NOT_GIVEN
message	Possible[StaticOrDynamicValue[str]]	The message to be displayed to the user. If the value is callable, the argument passed in will be the answers that have been provided this far.	_NOT_GIVEN
default	Possible[StaticOrDynamicValue[str]]	The default answer to the question. If the value is callable, the argument passed in will be the answers that have been provided this far.	_NOT_GIVEN
cli_help	Possible[Optional[str]]	Optional help message to be displayed for command line interface.	_NOT_GIVEN
should_ask	Possible[Optional[ShouldAsk]]	If None, the question is asked. Otherwise, the callable will be passed the answers that have been provided this far and should return True if the question should be asked.	_NOT_GIVEN
validator	Possible[Optional[Validator]]	Callable that will validate the response given by the user. None indicates that validation was successful. Otherwise, a string containing details of the error that caused the validation failure.	_NOT_GIVEN
value_if_not_asked	Possible[Optional[str]]	If provided and if should_ask is being used, this value will be recorded as an answer if should_ask evaluates to False.	_NOT_GIVEN

Returns:

Type	Description
BasicQuestion	A newly constructed instance with the given values in place of the values of this instance.

validate(value, answers)

Validate the value (a new answer).

Parameters:

Name	Type	Description	Default
value	str	The identifier that will be used as the key to access this question's answer.	required
answers	Answers	The answers that have been provided this far.	required

Returns:

Type	Description
ValidationResponse	A ValidationFailure or ValidationSuccess object.

Raises:

Type	Description
ValueError	The value for validator was not a callable.

Choice

Bases: Question[str]

A question with a set of possible answers.

__init__(name, message, options, default, cli_help=None, should_ask=None, value_if_not_asked=None)

Initialize an instance.

Parameters:

Name	Type	Description	Default
name	str	The identifier that will be used as the key to access this question's answer.	required
message	StaticOrDynamicValue[str]	The message to be displayed to the user. If the value is callable, the argument passed in will be the answers that have been provided this far.	required
options	StaticOrDynamicValue[Options]	The set of possible answers to the question. If the value is callable, the argument passed in will be the answers that have been provided this far. If the value is a Mapping, the values of the mapping will be displayed to the user & the respective key will be the returned value.	required
default	StaticOrDynamicValue[str]	The default answer to the question. If the value is callable, the argument passed in will be the answers that have been provided this far.	required
cli_help	Optional[str]	Optional help message to be displayed for command line interface.	None
should_ask	Optional[ShouldAsk]	If None, the question is asked. Otherwise, the callable will be passed the answers that have been provided this far and should return True if the question should be asked.	None
value_if_not_asked	Optional[str]	If provided and if should_ask is being used, this value will be recorded as an answer if should_ask evaluates to False.	None

Raises:

Type	Description
ValueError	A value for value_if_not_asked was given without giving a value for should_ask. Or the given value for value_if_not_asked was not one of the options.

ask(answers, no_user_input=False)

Prompt the user with this question.

Parameters:

Name	Type	Description	Default
answers	Answers	The answers that have been provided this far.	required
no_user_input	bool	If True the default value for the question will be used without waiting for the user to provide an answer. Default: False	False

Returns:

Type	Description
str	The answer to the question.

Raises:

Type	Description
ValueError	The instance was misconfigured in some way.

copy(*, name=_NOT_GIVEN, message=_NOT_GIVEN, options=_NOT_GIVEN, default=_NOT_GIVEN, cli_help=_NOT_GIVEN, should_ask=_NOT_GIVEN, value_if_not_asked=_NOT_GIVEN)

Create a new instance like this one, potentially with different values.

Parameters:

Name	Type	Description	Default
name	Possible[str]	The identifier that will be used as the key to access this question's answer.	_NOT_GIVEN
message	Possible[StaticOrDynamicValue[str]]	The message to be displayed to the user. If the value is callable, the argument passed in will be the answers that have been provided this far.	_NOT_GIVEN
options	Possible[StaticOrDynamicValue[Options]]	The set of possible answers to the question. If the value is callable, the argument passed in will be the answers that have been provided this far.	_NOT_GIVEN
default	Possible[StaticOrDynamicValue[str]]	The default answer to the question. If the value is callable, the argument passed in will be the answers that have been provided this far.	_NOT_GIVEN
cli_help	Possible[Optional[str]]	Optional help message to be displayed for command line interface.	_NOT_GIVEN
should_ask	Possible[Optional[ShouldAsk]]	If None, the question is asked. Otherwise, the callable will be passed the answers that have been provided this far and should return True if the question should be asked.	_NOT_GIVEN
value_if_not_asked	Possible[Optional[str]]	If provided and if should_ask is being used, this value will be recorded as an answer if should_ask evaluates to False.	_NOT_GIVEN

Returns:

Type	Description
Choice	A newly constructed instance with the given values in place of the values of this instance.

validate(value, answers)

Validate the value (a new answer).

Parameters:

Name	Type	Description	Default
value	str	The identifier that will be used as the key to access this question's answer.	required
answers	Answers	The answers that have been provided this far.	required

Returns:

Type	Description
ValidationResponse	A ValidationFailure or ValidationSuccess object.

Raises:

Type	Description
ValueError	The value for options did not have the correct type.

Confirm

Bases: Question[bool]

A question with a yes or no answer.

__init__(name, message, default=False, cli_help=None, should_ask=None, value_if_not_asked=None)

Initialize an instance.

Parameters:

Name	Type	Description	Default
name	str	The identifier that will be used as the key to access this question's answer.	required
message	StaticOrDynamicValue[str]	The message to be displayed to the user. If the value is callable, the argument passed in will be the answers that have been provided this far.	required
default	StaticOrDynamicValue[bool]	The default answer to the question. If the value is callable, the argument passed in will be the answers that have been provided this far.	False
cli_help	Optional[str]	Optional help message to be displayed for command line interface.	None
should_ask	Optional[ShouldAsk]	If None, the question is asked. Otherwise, the callable will be passed the answers that have been provided this far and should return True if the question should be asked.	None
value_if_not_asked	Optional[bool]	If provided and if should_ask is being used, this value will be recorded as an answer if should_ask evaluates to False.	None

Raises:

Type	Description
ValueError	A value for value_if_not_asked was given without giving a value for should_ask or the value for value_if_not_asked is not a bool.

ask(answers, no_user_input=False)

Prompt the user with this question.

Parameters:

Name	Type	Description	Default
answers	Answers	The answers that have been provided this far.	required
no_user_input	bool	If True the default value for the question will be used without waiting for the user to provide an answer. Default: False	False

Returns:

Type	Description
bool	The answer to the question.

Raises:

Type	Description
ValueError	The instance was misconfigured in some way.

copy(*, name=_NOT_GIVEN, message=_NOT_GIVEN, default=_NOT_GIVEN, cli_help=_NOT_GIVEN, should_ask=_NOT_GIVEN, value_if_not_asked=_NOT_GIVEN)

Create a new instance like this one, potentially with different values.

Parameters:

Name	Type	Description	Default
name	Possible[str]	The identifier that will be used as the key to access this question's answer.	_NOT_GIVEN
message	Possible[StaticOrDynamicValue[str]]	The message to be displayed to the user. If the value is callable, the argument passed in will be the answers that have been provided this far.	_NOT_GIVEN
default	Possible[StaticOrDynamicValue[bool]]	The default answer to the question. If the value is callable, the argument passed in will be the answers that have been provided this far.	_NOT_GIVEN
cli_help	Possible[Optional[str]]	Optional help message to be displayed for command line interface.	_NOT_GIVEN
should_ask	Possible[Optional[ShouldAsk]]	If None, the question is asked. Otherwise, the callable will be passed the answers that have been provided this far and should return True if the question should be asked.	_NOT_GIVEN
value_if_not_asked	Possible[Optional[bool]]	If provided and if should_ask is being used, this value will be recorded as an answer if should_ask evaluates to False.	_NOT_GIVEN

Returns:

Type	Description
Confirm	A newly constructed instance with the given values in place of the values of this instance.

Echo

Bases: Displayable

Display a message to the user.

__init__(message, should_ask=None)

Initialize an instance.

Parameters:

Name	Type	Description	Default
message	StaticOrDynamicValue[str]	The message to be displayed to the user. If the value is callable, the argument passed in will be the answers that have been provided this far.	required
should_ask	Optional[ShouldAsk]	If None, the message is displayed to the user. Otherwise, the callable will be passed the answers that have been provided this far and should return True if the message should be displayed.	None

copy(*, message=_NOT_GIVEN, should_ask=_NOT_GIVEN)

Create a new instance like this one, potentially with different values.

Parameters:

Name	Type	Description	Default
message	Possible[StaticOrDynamicValue[str]]	The message to be displayed to the user. If the value is callable, the argument passed in will be the answers that have been provided this far.	_NOT_GIVEN
should_ask	Possible[Optional[ShouldAsk]]	If None, the message is displayed. Otherwise, the callable will be passed the answers that have been provided this far and should return True if the message should be displayed.	_NOT_GIVEN

Returns:

Type	Description
Echo	A newly constructed instance with the given values in place of the values of this instance.

display(answers, no_user_input=False)

Display a message to the user.

Parameters:

Name	Type	Description	Default
answers	Answers	The answers that have been provided this far.	required
no_user_input	bool	Has no effect because no user input is expected. Default: False	False

Raises:

Type	Description
ValueError	The value for message did not have the correct type.

Question

Bases: ABC, Generic[QuestionValue]

Base class for a prompt to the user that produces an answer.

__init__(name, message, cli_help=None, should_ask=None, value_if_not_asked=None)

Initialize an instance.

Parameters:

Name	Type	Description	Default
name	str	The identifier that will be used as the key to access this question's answer.	required
message	StaticOrDynamicValue[str]	The message to be displayed to the user. If the value is callable, the argument passed in will be the answers that have been provided this far.	required
cli_help	Optional[str]	Optional help message to be displayed for command line interface.	None
should_ask	Optional[ShouldAsk]	If None, the question is asked. Otherwise, the callable will be passed the answers that have been provided this far and should return True if the question should be asked.	None
value_if_not_asked	Optional[QuestionValue]	If provided and if should_ask is being used, this value will be recorded as an answer if should_ask evaluates to False.	None

Raises:

Type	Description
ValueError	A value for value_if_not_asked was given without giving a value for should_ask.

ask(answers, no_user_input=False) abstractmethod

Prompt the user with this question.

Parameters:

Name	Type	Description	Default
answers	Answers	The answers that have been provided this far.	required
no_user_input	bool	If True the default value for the question will be used without waiting for the user to provide an answer. Default: False	False

Returns:

Type	Description
Answer	The answer to the question.

should_ask(answers)

Should the user be asked this question.

Parameters:

Name	Type	Description	Default
answers	Answers	The answers that have been provided this far.	required

Returns:

Type	Description
bool	True if this questions should be asked

Raises:

Type	Description
ValueError	The value for should_ask did not have the correct type.

Functions

format_cli_help(interactions, parser_name=None)

Produce CLI help text for a given set of interactions.

Parameters:

Name	Type	Description	Default
interactions	Collection[Interaction]	Interactions that should be turned into CLI arguments.	required
parser_name	Optional[str]	Optional name to be used in help text. If omitted, the name of the process will be used.	None

Raises:

Type	Description
DuplicateQuestionNameException	One of the given questions attempted to reuse a name.
ValueError	One of the given Interactions was not a valid type.

get_answers(interactions, answers=None, no_user_input=False)

Iterates over collection of interactions, invoking interaction specific behavior.

Parameters:

Name	Type	Description	Default
interactions	Collection[Interaction]	Collection of interactions to present the user with.	required
answers	Optional[Answers]	An initial dictionary of answers to start from.	None
no_user_input	bool	If True the default value for the question will be used without waiting for the user to provide an answer. Default: False	False

Returns:

Type	Description
MutableAnswers	Dictionary of answers.

Raises:

Type	Description
DuplicateQuestionNameException	One of the given questions attempted to reuse a name. When a value is provided for answers, those are considered as well.
ValueError	One of the given Interactions was not a valid type or was misconfigured in some way.

parse_args(interactions, args=None, exit_on_error=True, answers=None, parser_name=None)

Parse command line argument for the given interactions.

Parameters:

Name	Type	Description	Default
interactions	Collection[Interaction]	Interactions that should be turned into CLI arguments.	required
args	Optional[Sequence[str]]	Arguments to parse. If None, sys.argv will be used.	None
exit_on_error	bool	If True, print the CLI usage and exit the application. Otherwise, raise an exception with the error information.	True
answers	Optional[Answers]	An initial dictionary of answers to start from.	None
parser_name	Optional[str]	Optional name to be used in error text. If omitted, the name of the process will be used.	None

Returns:

Type	Description
MutableAnswers	Answers based on the given arguments.

Raises:

Type	Description
SystemExit	A value passed to CLI argument was not valid and exit_on_error was True.
CliException	A value passed to CLI argument was not valid and exit_on_error was False.
DuplicateQuestionNameException	One of the given questions attempted to reuse a name. When a value is provided for answers, those are considered as well.
ValueError	One of the given Interactions was not a valid type or was misconfigured in some way.

Exceptions

CliException

Bases: ColumboException

An error occurred while processing command line arguments.

ColumboException

Bases: Exception

Base exception for exceptions raised by Columbo

DuplicateQuestionNameException

Bases: ColumboException

Multiple questions use the same name.