Base Module

Base classes and helpers for Parameters and Groups

author:

Doug Skrypa

class cli_command_parser.parameters.base.ParamBase(name: str = None, required: Bool = False, help: str = None, hide: Bool = False)

Bases: ABC

Base class for Parameter and ParamGroup.

Parameters:

• name – The name to use for this parameter. Defaults to the name assigned to this parameter.

• 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.

• help – A brief description of this parameter that will appear in --help text.

• hide – If True, this parameter will not be included in usage / help messages. Defaults to False.

missing_hint: str = None

Hint to provide if this param/group is missing

group: ParamGroup = None

The group this object is a member of, if any

command: CommandCls = None

The Command this object is a member of

required: Bool

Whether this param/group is required

help: str

The description for this param/group that will appear in --help text

hide: Bool

Whether this param/group should be hidden in --help text

property name: str

property formatter: ParamHelpFormatter

abstract property show_in_help: bool

format_usage(*args, **kwargs) → str

Convenience method for calling ParamHelpFormatter.format_usage()

format_help(*args, **kwargs) → str

Convenience method for calling ParamHelpFormatter.format_help()

class cli_command_parser.parameters.base.Parameter(action: str, *, help: str = None, hide: Bool = False, metavar: str = None, name: str = None, required: Bool = False, default: Any = <object object>, default_cb: DefaultFunc = None, cb_with_cmd: Bool = False, show_default: Bool = None, strict_default: Bool = False)

Bases: ParamBase, Generic[T_co], ABC

Base class for all other parameters. It is not meant to be used directly.

Custom parameter classes should generally extend BasePositional or BaseOption instead of this, otherwise additional handling may be necessary in the parser.

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.

• name – The name to use for this parameter. Defaults to the name assigned to this parameter.

• 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.

• metavar – The name to use as a placeholder for values in usage / help messages.

• help – A brief description of this parameter that will appear in --help text.

• 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.

• default_cb – A default callback function (or other callable) may be provided instead of a static default value (they cannot both be provided). If cb_with_cmd is False (the default), then it must be callable with no arguments, otherwise it must accept a single positional argument (the Command that contains this Parameter). Similar to when the default value would be used, it will only be called when no argument was provided. It is also possible to register a method in a Command to be the default callback.

• cb_with_cmd – Whether the provided default_cb should be called with the Command that contains this Parameter. Ignored if default_cb is not provided.

• show_default – Override the CommandConfig.show_defaults setting for this parameter to always or never include the default value in usage / help messages. Default: follow the show_defaults setting.

• hide – If True, this parameter will not be included in usage / help messages. Defaults to False.

nargs: Nargs

type: Callable[[str], T_co] | None = None

allow_leading_dash: AllowLeadingDash = 'numeric'

classmethod __init_subclass__(repr_attrs: Strings = None, actions: Collection[Type[ParamAction]] = None, **kwargs)

Parameters:

• repr_attrs – Additional attributes to include in the repr.

• actions – Collection of ParamAction classes that this type of Parameter supports

metavar: str = None

default = <object object>

default_cb: DefaultCallback | None = None

strict_default: Bool = False

show_default: Bool = None

property has_choices: bool

register_default_cb(method: Callable[[CommandObj], T_co]) → Callable[[CommandObj], T_co]

Intended to be used as a decorator to register a method in a Command to be used as the default callback for this Parameter. The method will only be called during parsing if no value was explicitly provided for this Parameter. The decorated method is returned unchanged, so it can still be called directly if necessary.

Parameters:

method – A method that does not accept any arguments (except self), and returns the value that should be used for this Parameter.

Returns:

The method, unchanged.

get_const(opt_str: OptStr = None)

get_env_const(value: str, env_var: str) → tuple[T_co, bool]

prepare_value(value: str, short_combo: Bool = False, pre_action: Bool = False) → T_co

validate(value: T_co | None, joined: Bool = False)

is_valid_arg(value: Any) → bool

result(command: CommandObj | None = None, missing_default: TD = <object object>) → T_co | TD | None

The final result / parsed value for this Parameter that is returned upon access as a descriptor.

property show_in_help: bool

class cli_command_parser.parameters.base.BasePositional(action: str, *, required: Bool = True, default: Any = <object object>, default_cb: DefaultFunc = None, **kwargs)

Bases: Parameter[T_co], ABC

Base class for Positional, SubCommand, Action, and any other parameters that are provided positionally, without prefixes. It is not meant to be used directly.

All positional parameters are required by default.

Custom positional parameter classes should extend this class to be treated the same as other positionals by the parser.

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.

• kwargs – Additional keyword arguments to pass to Parameter.

classmethod __init_subclass__(default_ok: bool = None, **kwargs)

Parameters:

• default_ok – Whether default values are supported for this Parameter type

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

class cli_command_parser.parameters.base.BaseOption(*option_strs: str, action: str, name_mode: Union[OptionNameMode, str, None] = <object object>, env_var: OptStrs = None, strict_env: bool = True, use_env_value: Bool = None, show_env_var: Bool = None, **kwargs)

Bases: Parameter[T_co], ABC

Base class for Option, Flag, Counter, and any other keyword-like parameters that have --long and -short prefixes before values.

Only the handling for processing long/short options and formatting usage of these parameters is provided in this class - it is not meant to be used directly.

Custom option classes should extend this class to be treated the same as other options by the parser.

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.

• name_mode – Override the configured option_name_mode for this Option/Flag/Counter/etc.

• env_var – A string or sequence (tuple, list, etc) of strings representing environment variables that should be searched for a value when no value was provided via CLI. If a value was provided via CLI, then these variables will not be checked. If multiple env variable names/keys were provided, then they will be checked in the order that they were provided. When enabled, values from env variables take precedence over the default value. When enabled and the Parameter is required, then either a CLI value or an env var value must be provided.

• 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 – For optional Parameters that support storing a constant (such as Flag), this option controls behavior when an BaseOption.env_var is used as the source of a value for this Parameter. If True, the parsed value will be stored as this Parameter’s value (it must be a valid value). If False (the default), then the parsed value will be used to determine whether the store/append const action should be taken as if it was specified as a CLI flag (e.g., --foo with no value).

• kwargs – Additional keyword arguments to pass to Parameter.

const = <object object>

option_strs: OptionStrings

strict_env: Bool

env_var: OptStrs = None

use_env_value: Bool

show_env_var: Bool = None

env_vars() → Iterator[str]

get_const(opt_str: OptStr = None)

class cli_command_parser.parameters.base.AllowLeadingDashProperty(default: AllowLeadingDash = AllowLeadingDash.NUMERIC)

Bases: object

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

name

default

class cli_command_parser.parameters.base.DefaultCallback(func: Callable[[CommandObj], T_co] | Callable[[], T_co], use_cmd: bool = False)

Bases: object

func

use_cmd

__call__(command: CommandObj | None) → T_co