Core Module

Core classes / functions for Commands, including the metaclass used for Commands, and utilities for finding the primary top-level Command.

author:

Doug Skrypa

class cli_command_parser.core.CommandMeta(name: str, bases: Bases, namespace: dict[str, Any], *, choice: str = <object object>, choices: Choices = None, help: str = None, config: AnyConfig = None, **kwargs)[source]

Bases: ABCMeta, type

Parameters:

  • choice – SubCommand value to map to this command. If specified, this single choice value will override the default value that is based on the name of the class. Use None (and do not provide a value for choices) to prevent the class from being registered as a subcommand choice.

  • choices – SubCommand values to map to this command. Optionally, a mapping of {choice: help text} may be provided to customize the help text displayed for each choice. If specified, these choice values will override the default value that is based on the name of the class. It is possible, but not necessary, for values to be provided for both choice and this parameter.

  • prog – The name of the program (default: sys.argv[0] or the name of the module in which the top-level Command was defined in some cases)

  • usage – Usage message (default: auto-generated)

  • description – Description of what the program does

  • epilog – Text to follow parameter descriptions

  • help – Help text to be displayed as a SubCommand option. Ignored for top-level commands.

  • doc_name – Name to use in documentation (default: the stem of the file name containing the Command, or the specified prog value)

  • error_handler – The ErrorHandler to be used by Command.__call__ to wrap main(), or None to disable error handling.

  • add_help (bool) – Whether the –help / -h action_flag should be added

  • action_after_action_flags (bool) – Whether action_flag methods are allowed to be combined with a positional Action method in a given CLI invocation

  • multiple_action_flags (bool) – Whether multiple action_flag methods are allowed to run if they are all specified

  • ignore_unknown (bool) – Whether unknown arguments should be allowed (default: raise an exception when unknown arguments are encountered)

  • allow_missing (bool) – Whether missing required arguments should be allowed (default: raise an exception when required arguments are missing)

  • always_run_after_main (bool) – Whether Command._after_main_() should always be called, even if an exception was raised in Command.main()

classmethod config(cls: CommandAny, default: T = None) → CommandConfig | T[source]
classmethod parent(cls: CommandAny, include_abc: bool = True) → CommandCls | None[source]
Parameters:

  • cls – A Command class or object

  • include_abc – If True, the first Command parent class in the given Command’s mro will be returned, regardless of whether that class extends ABC or not. If False, then the first Command parent class that does NOT extend ABC will be returned.

Returns:

The given Command’s parent Command, or None if no parent was found (which may depend on include_abc).

classmethod params(cls: CommandAny) → CommandParameters[source]
classmethod meta(cls: CommandCls) → ProgramMetadata[source]
cli_command_parser.core.get_parent(cls: CommandAny, include_abc: bool = True) → CommandCls | None
Parameters:

  • cls – A Command class or object

  • include_abc – If True, the first Command parent class in the given Command’s mro will be returned, regardless of whether that class extends ABC or not. If False, then the first Command parent class that does NOT extend ABC will be returned.

Returns:

The given Command’s parent Command, or None if no parent was found (which may depend on include_abc).

cli_command_parser.core.get_config(cls: CommandAny, default: T = None) → CommandConfig | T
cli_command_parser.core.get_metadata(cls: CommandCls) → ProgramMetadata
cli_command_parser.core.get_params(cls: CommandAny) → CommandParameters
cli_command_parser.core.get_top_level_commands() → list[CommandCls][source]

Returns a list of Command subclasses that are inferred to be direct subclasses of Command.

This was implemented because Command.__subclasses__() does not release dead references to subclasses quickly enough for tests.