Choice_Map Module

ChoiceMap Parameters

author:

Doug Skrypa

class cli_command_parser.parameters.choice_map.Choice(choice: str | None, target: ~cli_command_parser.parameters.choice_map.T = <object object>, help: str = None, local: bool = False)

Bases: Generic[T]

Used internally to store a value that can be provided as a choice for a parameter, and the target value / callable associated with that choice.

choice

target

help

local

format_usage() → str

format_help(lpad: int = 4, tw_offset: int = 0, prefix: str = '') → str

class cli_command_parser.parameters.choice_map.ChoiceMap(*, action: str = 'concatenate', title: str = None, description: str = None, **kwargs)

Bases: BasePositional[str], Generic[T]

Base class for SubCommand and Action. It is not meant to be used directly.

Allows choices to be defined and provided as a string that may contain spaces, without requiring users to escape or quote the string (i.e., as technically separate arguments). This allows for a more natural way to provide multi-word commands, without needing to jump through hoops to handle them.

Parameters:

• action – The action to take on individual parsed values. Actions must be defined as methods in classes that extend Parameter, and must be registered via parameter_action. Defaults to (and only supports) append. The nargs value is automatically calculated / maintained, based on the number of distinct words in the defined choices. While most parameters that use action='append' will return a list, the final value for ChoiceMap parameters will instead be a string of space-separated provided values.

• title – The title to use for help text sections containing the choices for this parameter. Default value depends on what is provided by subclasses.

• description – The description to be used in help text for this parameter.

• kwargs – Additional keyword arguments to pass to BasePositional.

nargs: Nargs = Nargs('+')

classmethod __init_subclass__(title: str = None, choice_validation_exc: Type[Exception] = None, **kwargs)

Parameters:

• title – Default title to use for help text sections containing the choices for this parameter.

• choice_validation_exc – The type of exception to raise when validating defined choices.

• kwargs – Additional keyword arguments to pass to Parameter.__init_subclass__().

title: OptStr

description: OptStr

choices: dict[str, Choice[T]]

register_default_cb(method)

property has_choices: bool

register_choice(choice: str, target: ~cli_command_parser.parameters.choice_map.T = <object object>, help: str = None)

validate(value: str, joined: bool | Any = False)

result(command: ~cli_command_parser.typing.CommandObj | None = None, missing_default: ~cli_command_parser.parameters.choice_map.TD = <object object>) → str | None | TD

target() → T

property show_in_help: bool

class cli_command_parser.parameters.choice_map.SubCommand(*, required: bool | Any = True, default_help: str = None, local_choices: Mapping[str, str] | Collection[str] | None = None, **kwargs)

Bases: ChoiceMap[CommandType | Type[CommandObj]]

Used to indicate the position where a choice that results in delegating execution of the program to a sub-command should be provided.

Sub Command classes are automatically registered as choices for a SubCommand parameter if they extend the Command that contains a SubCommand parameter instead of extending Command directly. When automatically registered, the choice will be the lower-case name of the sub command class. It is possible to register() sub commands explicitly to specify a different choice value.

property has_local_choices: bool

register_command(choice: str | None, command: CommandType | Type[CommandObj], help: str | None) → CommandType | Type[CommandObj]

register(command_or_choice: str | CommandType | Type[CommandObj] = None, *, choice: str = None, help: str = None) → Callable[[CommandType | Type[CommandObj]], CommandType | Type[CommandObj]]

Class decorator version of register_command(). Registers the wrapped Command as the subcommand class to be used for further parsing when the given choice is specified for this parameter.

This is only necessary for subcommands that do not extend their parent Command class. When extending a parent Command, it is automatically registered as a subcommand during Command subclass initialization.

Parameters:

• command_or_choice – When not called explicitly, this will be Command class that will be wrapped. When called to provide arguments, the choice value for the positional parameter that determines which subcommand was chosen may be provided here. Defaults to the name of the decorated class, converted from CamelCase to snake_case.

• choice – Keyword-only way to provide the choice value. May not be combined with a positional choice string value.

• help – (Keyword-only) The help text / description to be displayed for this choice

class cli_command_parser.parameters.choice_map.Action(*, action: str = 'concatenate', title: str = None, description: str = None, **kwargs)

Bases: ChoiceMap[MethodType]

Actions are similar to SubCommand parameters, but allow methods in Command classes to be registered as a callable to be executed based on a user’s choice instead of separate sub Commands.

Actions are better suited for use cases where all of the target functions accept the same arguments. If target functions require different / additional parameters, then using a SubCommand with separate sub Command classes may make more sense.

register_action(choice: str | None, method: MethodType, help: str = None, default: bool | Any = False) → MethodType

register(method_or_choice: str | MethodType = None, *, choice: str = None, help: str = None, default: bool | Any = False) → MethodType | Callable[[MethodType], MethodType]

Decorator that registers the wrapped method to be called when the given choice is specified for this parameter. Methods may also be registered by decorating them with the instantiated Action parameter directly - doing so calls this method.

This decorator may be used with or without arguments. When no arguments are needed, it does not need to be explicitly called.

Parameters:

• method_or_choice – When not called explicitly, this will be the method that will be wrapped. When called to provide arguments, the choice value may be provided as a positional argument here. Defaults to the name of the decorated method.

• choice – Keyword-only way to provide the choice value. May not be combined with a positional choice string value.

• help – (Keyword-only) The help text / description to be displayed for this choice

• default – (Keyword-only) If true, this method will be registered as the default action to take when no other choice is specified. When marking a method as the default, if you want it to also be available as an explicit choice, then a choice value must be specified.

Returns:

The original method, unchanged. When called explicitly, a partial method will be returned first, which will automatically be called by the interpreter with the method to be decorated, and that call will return the original method.

__call__(method_or_choice: str | MethodType = None, *, choice: str = None, help: str = None, default: bool | Any = False) → MethodType | Callable[[MethodType], MethodType]

Decorator that registers the wrapped method to be called when the given choice is specified for this parameter. Methods may also be registered by decorating them with the instantiated Action parameter directly - doing so calls this method.

This decorator may be used with or without arguments. When no arguments are needed, it does not need to be explicitly called.

Parameters:

• method_or_choice – When not called explicitly, this will be the method that will be wrapped. When called to provide arguments, the choice value may be provided as a positional argument here. Defaults to the name of the decorated method.

• choice – Keyword-only way to provide the choice value. May not be combined with a positional choice string value.

• help – (Keyword-only) The help text / description to be displayed for this choice

• default – (Keyword-only) If true, this method will be registered as the default action to take when no other choice is specified. When marking a method as the default, if you want it to also be available as an explicit choice, then a choice value must be specified.

Returns:

The original method, unchanged. When called explicitly, a partial method will be returned first, which will automatically be called by the interpreter with the method to be decorated, and that call will return the original method.