Options Module

Optional Parameters

author:

Doug Skrypa

class cli_command_parser.parameters.options.Option(*option_strs: str, nargs: NargsValue = None, action: Literal['store', 'append'] = None, default: TD = <object object>, required: Bool = False, type: InputTypeFunc = None, choices: ChoicesType = None, allow_leading_dash: LeadingDash = None, **kwargs)[source]

Bases: BaseOption[T_co | TD]

A generic option that can be specified as --foo bar or by using other similar forms.

Parameters:

  • option_strs – The long and/or short option prefixes for this option. If no long prefixes are specified, then one will automatically be added based on the name assigned to this parameter.

  • nargs – The number of values that are expected/required when this parameter is specified. Defaults to + when action='append', and to 1 otherwise. See Nargs for more info.

  • 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 store when nargs=1, and to append otherwise. A single value will be stored when action='store', and a list of values will be stored when action='append'.

  • default – The default value for this parameter if it is not specified. Defaults to None if this parameter is not required; not used if it is required.

  • required – Whether this parameter is required or not. If it is required, then an exception will be raised if the user did not provide a value for this parameter. Defaults to False.

  • type – A callable (function, class, etc.) that accepts a single string argument, which should be called on every value for this parameter to transform the value. By default, no transformation is performed, and values will be strings. If not specified, but a type annotation is detected, then that annotation will be used as if it was provided here. When both are present, this argument takes precedence.

  • choices – A container that holds the specific values that users must pick from. By default, any value is allowed.

  • allow_leading_dash – Whether string values may begin with a dash (-). By default, if a value begins with a dash, it is only accepted if it appears to be a negative numeric value. Use True / always / AllowLeadingDash.ALWAYS to allow any value that begins with a dash (as long as it is not an option string for an Option/Flag/etc). To reject all values beginning with a dash, including numbers, use False / never / AllowLeadingDash.NEVER.

  • kwargs – Additional keyword arguments to pass to BaseOption.

allow_leading_dash: AllowLeadingDash

Custom value normalizer/validator for the allow_leading_dash property of Positional and Option classes.

class cli_command_parser.parameters.options.Flag(*option_strs: str, action: ~typing.Literal['store_const', 'append_const'] = 'store_const', default: ~cli_command_parser.parameters.options.TD = <object object>, default_cb=<object object>, const: ~cli_command_parser.parameters.options.TC = <object object>, type: ~typing.Callable[[str], ~cli_command_parser.typing.T_co] = None, **kwargs)[source]

Bases: BaseOption[TD | TC]

A (typically boolean) option that does not accept any values.

Parameters:

  • option_strs – The long and/or short option prefixes for this option. If no long prefixes are specified, then one will automatically be added based on the name assigned to this parameter.

  • 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 store_const, but accepts append_const to build a list of the specified constant.

  • default – The default value for this parameter if it is not specified. Defaults to False when const=True (the default), and to True when const=False. Defaults to None for any other constant.

  • const – The constant value to store/append when this parameter is specified. Defaults to True.

  • type – A callable (function, class, etc.) that accepts a single string argument and returns a boolean value, which should be called on environment variable values, if any are configured for this Flag via BaseOption.env_var. It should return a truthy value if any action should be taken (i.e., if the constant should be stored/appended), or a falsey value for no action to be taken. The default function handles parsing 1 / true / yes and similar as True, and 0 / false / no and similar as False. If use_env_value is True, then this function should return either the default or constant value instead.

  • strict_env – When True (the default), if an BaseOption.env_var is used as the source of a value for this parameter and that value is invalid, then parsing will fail. When False, invalid values from environment variables will be ignored (and a warning message will be logged).

  • use_env_value – If True, when an BaseOption.env_var is used as the source of a value for this Flag, the parsed value will be stored as this Flag’s value (it must match either the default or constant value). If False (the default), then the parsed value will be used to determine whether this Flag’s normal action should be taken as if it was specified via a CLI argument.

  • kwargs – Additional keyword arguments to pass to BaseOption.

nargs: Nargs = Nargs(0)
use_env_value: bool = False
static type(value: str) → bool
register_default_cb(method)[source]
get_env_const(value: str, env_var: str) → tuple[TC | TD, bool][source]
class cli_command_parser.parameters.options.TriFlag(*option_strs: str, consts: tuple[~cli_command_parser.parameters.options.TC, ~cli_command_parser.parameters.options.TA] = (True, False), alt_prefix: str = None, alt_long: str = None, alt_short: str = None, alt_help: str = None, action: ~typing.Literal['store_const', 'append_const'] = 'store_const', default: ~cli_command_parser.parameters.options.TD = <object object>, default_cb: ~typing.Callable[[], ~cli_command_parser.parameters.options.TD] = None, type: ~typing.Callable[[str], ~cli_command_parser.typing.T_co] = None, **kwargs)[source]

Bases: BaseOption[TD | TC | TA], ABC

A trinary / ternary Flag. While Flag only supports 1 constant when provided, with 1 default if not provided, this class accepts a pair of constants for the primary and alternate values to store, along with a separate default.

Parameters:

  • option_strs – The primary long and/or short option prefixes for this option. If no long prefixes are specified, then one will automatically be added based on the name assigned to this parameter.

  • consts – A 2-tuple containing the (primary, alternate) values to store. Defaults to (True, False).

  • alt_prefix – The prefix to add to the assigned name for the alternate long form. Ignored if alt_long is specified. Defaults to no if alt_long is not specified.

  • alt_long – The alternate long form to use.

  • alt_short – The alternate short form to use.

  • alt_help – The help text to display with the alternate option strings.

  • action – The action to take on individual parsed values. Only store_const (the default) is supported.

  • default – The default value to use if neither the primary or alternate options are provided. Defaults to None.

  • name_mode – Override the configured option_name_mode for this TriFlag.

  • type – A callable (function, class, etc.) that accepts a single string argument and returns a boolean value, which should be called on environment variable values, if any are configured for this TriFlag via BaseOption.env_var. It should return a truthy value if the primary constant should be stored, or a falsey value if the alternate constant should be stored. The default function handles parsing 1 / true / yes and similar as True, and 0 / false / no and similar as False. If use_env_value is True, then this function should return the primary or alternate constant or the default value instead.

  • strict_env – When True (the default), if an BaseOption.env_var is used as the source of a value for this parameter and that value is invalid, then parsing will fail. When False, invalid values from environment variables will be ignored (and a warning message will be logged).

  • use_env_value – If True, when an BaseOption.env_var is used as the source of a value for this TriFlag, the parsed value will be stored as this TriFlag’s value (it must match the primary or alternate constant, or the default value). If False (the default), then the parsed value will be used to determine whether this TriFlag’s normal action should be taken as if it was specified via a CLI argument.

  • kwargs – Additional keyword arguments to pass to BaseOption.

nargs: Nargs = Nargs(0)
use_env_value: bool = False
option_strs: TriFlagOptionStrings
consts: tuple[TC, TA]
alt_help: OptStr = None
static type(value: str) → bool
register_default_cb(method: CommandMethod) → CommandMethod[source]
get_const(opt_str: OptStr = None) → TC | TA[source]
get_env_const(value: str, env_var: str) → tuple[TC | TA | TD, bool][source]
class cli_command_parser.parameters.options.ActionFlag(*option_strs: str, order: int | float = 1, func: Callable = None, before_main: Bool = True, always_available: Bool = False, **kwargs)[source]

Bases: Flag

A Flag that triggers the execution of a function / method / other callable when specified.

Parameters:

  • option_strs – The long and/or short option prefixes for this option. If no long prefixes are specified, then one will automatically be added based on the name assigned to this parameter.

  • order – The priority / order in which this ActionFlag should be executed, relative to other ActionFlags, if others would also be executed. Two ActionFlags in a given Command may not have the same combination of before_main and order values. ActionFlags with lower order values are executed before those with higher values. The --help action is implemented as an ActionFlag with order=float('-inf').

  • func – The function to execute when this parameter is specified.

  • before_main – Whether this ActionFlag should be executed before the Command.main() method or after it.

  • always_available – Whether this ActionFlag should always be available to be called, even if parsing failed. Only allowed when before_main=True. The intended use case is for actions like --help text.

  • kwargs – Additional keyword arguments to pass to Flag.

property func[source]
__call__(func: Callable) → ActionFlag[source]

Allows use as a decorator on the method to be called. A given method can only be decorated with one ActionFlag.

If stacking Action and ActionFlag decorators, the Action decorator must be first (i.e., the ActionFlag decorator must be above the Action decorator).

cli_command_parser.parameters.options.action_flag

Alias for ActionFlag

cli_command_parser.parameters.options.before_main(*option_strs: str, order: int | float = 1, func: Callable = None, **kwargs) → ActionFlag[source]

An ActionFlag that will be executed before Command.main()

cli_command_parser.parameters.options.after_main(*option_strs: str, order: int | float = 1, func: Callable = None, **kwargs) → ActionFlag[source]

An ActionFlag that will be executed after Command.main()

cli_command_parser.parameters.options.help_action(self)[source]

The --help / -h action. Prints help text, then exits.

class cli_command_parser.parameters.options.Counter(*option_strs: str, action: str = 'count', init: int = 0, const: int = 1, default: int = <object object>, default_cb: ~typing.Callable[[], int] = None, required: bool = False, **kwargs)[source]

Bases: BaseOption[int]

A Flag-like option that counts the number of times it was specified. Supports an optional integer value to explicitly increase the stored value by that amount.

Parameters:

  • option_strs – The long and/or short option prefixes for this option. If no long prefixes are specified, then one will automatically be added based on the name assigned to this parameter.

  • action – The action to take on individual parsed values. Defaults to append, and no other actions are supported (unless this class is extended).

  • init – The initial value that will be incremented when this parameter is specified. Defaults to 0.

  • default – The default value for this parameter if it is not specified. Defaults to 0 unless this Parameter is required.

  • const – The value by which the stored value should increase whenever this parameter is specified. Defaults to 1. If a different const value is used, and if an explicit value is provided by a user, the user-provided value will be added verbatim - it will NOT be multiplied by const.

  • kwargs – Additional keyword arguments to pass to BaseOption.

type

alias of int

nargs: Nargs = Nargs('?')
init: int
register_default_cb(method: CommandMethod) → CommandMethod[source]
prepare_value(value: str | None, short_combo: bool = False, env_var: str = None) → int[source]
prepare_validation_value(value: str | None, short_combo: bool = False, env_var: str = None) → int
validate(value: Any, joined: Bool = False)[source]