Config Module

Configuration options for Command behavior.

author:

Doug Skrypa

class cli_command_parser.config.ShowDefaults(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: FixedFlag

Options for showing (default: <default>) in --help text. Options can be combined, but ShowDefaults.NEVER will override all other options.

If TRUTHY / NON_EMPTY / ANY are combined, then the most permissive (rightmost / highest value) option will be used.

The MISSING option must be combined with one of TRUTHY / NON_EMPTY / ANY - using MISSING alone is equivalent to ShowDefaults.MISSING | ShowDefaults.NEVER, which will result in no default values being shown.

NEVER = 1

Never include the default value in help text

MISSING = 2

Only include the default value if default: is not already present

TRUTHY = 4

Only include the default value if it is treated as True in a boolean context

NON_EMPTY = 8

Only include the default value if it is not None or an empty container

ANY = 16

Any default value, regardless of truthiness, will be included

class cli_command_parser.config.OptionNameMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: FixedFlag

How the default long form that is added for Option/Flag/Counter/etc. Parameters should handle underscores/dashes.

Given a Parameter defined as foo_bar = Option(...), the default long form handling based on this setting would be:

UNDERSCORE:

--foo_bar - the attribute name is used verbatim.

DASH:

--foo-bar - any underscores present in the attribute name will be replaced with dashes (this is the default behavior).

BOTH:

Both --foo-bar and --foo_bar will be accepted, and both will be displayed in help text.

BOTH_UNDERSCORE:

Both --foo-bar and --foo_bar will be accepted, but only --foo_bar with be displayed in help text. This may be useful for compatibility purposes, and helps prevent help text from being too cluttered.

BOTH_DASH:

Both --foo-bar and --foo_bar will be accepted, but only --foo-bar with be displayed in help text. This may be useful for compatibility purposes, and helps prevent help text from being too cluttered.

NONE:

No long form option string will be added. At least one short form option string must be defined. Note that it is NOT necessary to use name_mode=None to prevent the automatic creation of long form option strings in general. If any long form option strings are explicitly provided for a given Parameter, then an automatic one will not be added, regardless of value for this configuration option.

If a long form is provided explicitly for a given optional Parameter, then this setting will be ignored.

The value may be specified to Commands as option_name_mode=<mode> or to Parameters as name_mode=<mode>, where <mode> is one of:

• '_' or '-' or '*' or '*_' or '*-' or '_*' or '-*' or None

• OptionNameMode.UNDERSCORE or OptionNameMode.DASH or OptionNameMode.BOTH or OptionNameMode.BOTH_UNDERSCORE or OptionNameMode.BOTH_DASH or OptionNameMode.NONE

• 'underscore' or 'dash' or 'both' or 'both_underscore' or 'both_dash' or 'none'

UNDERSCORE = 1

DASH = 2

BOTH = 3

BOTH_UNDERSCORE = 15

BOTH_DASH = 23

NONE = 32

class cli_command_parser.config.SubcommandAliasHelpMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: MissingMixin, Enum

Options for how subcommand aliases (alternate choices specified for a given Command class that is registered as a subcommand / subclass of another Command) should be displayed in help text.

If a given Command is defined without the choices= class keyword argument, or if the provided collection contained only one value, then this setting is ignored.

The output based on each supported option:

REPEAT:

Each alias will be on a separate line in the Subcommands: section, and each alias will repeat the description (if defined for the target Command) as if it was a separate subcommand

COMBINE:

All of the aliases will be combined on the same line in the Subcommands: section, with the values displayed in a way that is similar to the way that the choices= values for other Parameters are displayed.

ALIAS:

Each alias will be on a separate line in the Subcommands: section, but only the first choice/value will have the description (if defined for the target Command). Subsequent aliases’ descriptions will be replaced by Alias of: <first choice/alias value>.

REPEAT = 'repeat'

COMBINE = 'combine'

ALIAS = 'alias'

class cli_command_parser.config.AmbiguousComboMode(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: MissingMixin, Enum

Options for handling potentially ambiguous combinations of short forms of Option / Flag / etc. Parameters.

The behavior based on each supported option:

IGNORE:

Ignore potentially ambiguous combinations of short options entirely. Best effort parsing will be performed.

PERMISSIVE:

Allow multi-char short options that overlap with a single char one for exact matches, but reject any user input that combines multiple short options when the combination contains a sequence that could be interpreted as a multi-char short option.

STRICT:

Reject multi-char short options that overlap with a single char one before parsing, regardless of user input.

IGNORE = 'ignore'

PERMISSIVE = 'permissive'

STRICT = 'strict'

class cli_command_parser.config.AllowLeadingDash(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

How a given Parameter should handle values with a leading dash (-). Only configurable at the Parameter level, not the Command level.

The behavior based on each supported option:

NUMERIC:

Allow numeric values like -5 and -1.3, but reject values like -d.

ALWAYS:

Always allow values with a leading dash.

NEVER:

Never allow values with a leading dash.

NUMERIC = 'numeric'

ALWAYS = 'always'

NEVER = 'never'

class cli_command_parser.config.ConfigItem(default: DV, type: Callable[[...], CV] = None)

Bases: Generic[CV, DV]

A single configurable setting in the CommandConfig.

Parameters:

• default – Default config value to use if no explicit value is provided

• type – A class or other callable that will be called to validate/normalize provided values

default

type

name

class cli_command_parser.config.DynamicConfigItem(default: DV, type: Callable[[...], CV])

Bases: ConfigItem

cli_command_parser.config.config_item(default: DV)

class cli_command_parser.config.CommandConfig(parent: CommandConfig | None = None, read_only: bool = False, **kwargs)

Bases: object

Configuration options for Commands.

FIELDS = {'action_after_action_flags', 'add_help', 'allow_annotation_type', 'allow_backtrack', 'allow_missing', 'always_run_after_main', 'ambiguous_short_combos', 'choice_delim', 'cmd_alias_mode', 'command_formatter', 'error_handler', 'extended_epilog', 'group_tree_spacers', 'ignore_unknown', 'multiple_action_flags', 'option_name_mode', 'param_formatter', 'reject_ambiguous_pos_combos', 'show_defaults', 'show_docstring', 'show_env_vars', 'show_group_tree', 'show_group_type', 'show_inherited_descriptions', 'sort_choices', 'strict_usage_column_width', 'sub_cmd_doc_depth', 'usage_column_width', 'use_type_metavar', 'wrap_usage_str'}

error_handler: ErrorHandler | None

The ErrorHandler to be used by Command.__call__()

always_run_after_main: Bool

Whether Command._after_main_() should always be called, even if an exception was raised in Command.main() (similar to a finally block)

allow_annotation_type: Bool

Whether inferring Parameter types from type annotations should be enabled

multiple_action_flags: Bool

Whether multiple action_flag methods are allowed to run if they are all specified

action_after_action_flags: Bool

Whether action_flag methods are allowed to be combined with a positional Action method in a given CLI invocation

ignore_unknown: Bool

Whether unknown arguments should be ignored (default: raise an exception when unknown arguments are encountered)

allow_missing: Bool

Whether missing required arguments should be allowed (default: raise an exception when they are missing)

allow_backtrack: Bool

Whether backtracking is enabled for positionals following params with variable nargs

option_name_mode: OptionNameMode

How the default long form that is added for Option/Flag/Counter/etc. Parameters should handle underscores/dashes

reject_ambiguous_pos_combos: Bool

Whether ambiguous combinations of positional choices should result in an AmbiguousParseTree error

ambiguous_short_combos: AmbiguousComboMode

How potentially ambiguous combinations of short forms of Option/Flag/etc. Parameters should be handled

add_help: Bool

Whether the --help / -h action_flag should be added

use_type_metavar: Bool

Whether the metavar for Parameters that accept values should default to the name of the specified type (default: the name of the parameter)

show_defaults: ShowDefaults

Whether the default value for Parameters should be shown in help text, and related behavior

show_env_vars: Bool

Whether Parameters that support reading their values from env variables should include the var names in help text

cmd_alias_mode

How subcommand aliases should be displayed in help text.

sort_choices: Bool

Whether Parameter choices values and Action / Subcommand choices should be sorted

choice_delim: str

Delimiter to use between choices in usage / help text

show_group_tree: Bool

Whether there should be a visual indicator in help text for the parameters that are members of a given group

group_tree_spacers

The spacer characters to use at the beginning of each line when show_group_tree is True.

The default spacers:

Parameter Type	Character	Character Name
Mutually Exclusive	¦	BROKEN BAR
Mutually dependent	║	BOX DRAWINGS DOUBLE VERTICAL
Other	│	BOX DRAWINGS LIGHT VERTICAL

Parameters:

value – A 3-tuple (or other sequence with 3 items) of spacer strings to be used for (mutually exclusive, mutually dependent, other) group members, respectively.

Returns:

The validated and normalized value (or the default value if this property is accessed without providing explicit values)

show_group_type: Bool

Whether mutually exclusive / dependent groups should include that fact in their descriptions

command_formatter: Callable[[CommandType, CommandParameters], CommandHelpFormatter]

A callable that accepts 2 arguments, a Command class (not object) and a CommandParameters object, and returns a CommandHelpFormatter

param_formatter: Callable[[ParamOrGroup], ParamHelpFormatter]

A callable that accepts a Parameter or ParamGroup and returns a ParamHelpFormatter

extended_epilog: Bool

Whether the program version, author email, and documentation URL should be included in the help text epilog, if they were successfully detected

usage_column_width: int

Width (in characters) for the usage column in help text, after which the parameter descriptions begin.

strict_usage_column_width: bool

Whether the usage_column_width should be enforced for parameters with usage text parts that exceed it. By default, that setting only defines where the parameter descriptions begin.

wrap_usage_str

Wrap the basic usage line after the specified number of characters, or automatically based on terminal size if True is specified instead.

show_docstring: Bool

Whether the top level script’s docstring should be included in generated documentation

show_inherited_descriptions: Bool

Whether inherited descriptions should be included in subcommand sections of generated documentation

sub_cmd_doc_depth: int

Maximum subcommand depth to include in generated documentation (default: include all)

as_dict(full: Bool = True) → dict[str, Any]

Return a dict representing the configured options.