gfw.common.cli.CLI#

class CLI(name='python /home/docs/checkouts/readthedocs.org/user_builds/gfw-common/envs/stable/lib/python3.12/site-packages/sphinx/__main__.py', description='', options=None, subcommands=None, run=<function CLI.<lambda>>, version='0.1.0', examples=(), formatter=<function default_formatter.<locals>.formatter>, logger_config=None, allow_unknown=False, use_underscore=False, **main_parser_kwargs)[source]#

Wrapper around argparse for building CLIs more easily.

Key Features:

  • Supports a single command or multiple subcommands CLI.

  • Common CLI options can be easily defined once and shared across subcommands.

  • Configuration resolution: CLI arguments > config file > command defaults.

  • Rich logging with optional plain-text fallback.

  • Optionally allows unrecognized CLI arguments for custom handling.

  • Provides builtin options to provide config file, disable rich logging, etc.

Parameters:

  • name (str) – The main command to be run on the command line (e.g., my-cli).

  • description (str) – A brief message describing what the CLI application does.

  • options (List[Option] | None) – A tuple of Option instances representing CLI arguments for the main command. These options are inherited by every subcommand, if any.

  • run (Callable[[...], Any]) – Callable to be run when no subcommands are defined.

  • subcommands (List[Command | Type[Command]] | None) – A list containing either Command instances or types. Each item represents a subcommand to be registered in the CLI. If a type is provided, it will be instantiated automatically. This allows flexibility in defining subcommands either by passing already created instances or by passing the command classes themselves.

  • version (str) – The version of the application.

  • examples (Tuple[str, ...]) – Example command-line usages shown in the help footer.

  • formatter (Callable[[...], HelpFormatter]) – Callable that returns a HelpFormatter for customizing help text.

  • logger_config (LoggerConfig | None) – LoggerConfig instance to control logging behavior.

  • allow_unknown (bool) – If True, unknown CLI arguments are allowed.

  • use_underscore (bool) – If True, converts hyphens in the option name to underscores (e.g., --log_file). If False (default), converts underscores to hyphens (e.g., --log-file). This controls the naming convention of the CLI argument.

  • **main_parser_kwargs (Any) – Extra arguments passed to ArgumentParser constructor of the main command.

Methods

builtin_options

Defines built-in CLI options used across commands.

execute

Parse arguments, load config, and execute the CLI command.

Attributes

common_parser

Constructs the common parser containing built-in CLI options.

main_parser

Constructs the main argument parser.

title

Returns the CLI program title with version.
classmethod builtin_options()[source]#

Defines built-in CLI options used across commands.

Return type:

list[Option]

property title: str#

Returns the CLI program title with version.

property common_parser: ArgumentParser#

Constructs the common parser containing built-in CLI options.

property main_parser: ArgumentParser#

Constructs the main argument parser.

execute(args=['-T', '-b', 'html', '-d', '_build/doctrees', '-D', 'language=en', '.', '/home/docs/checkouts/readthedocs.org/user_builds/gfw-common/checkouts/stable/_readthedocs//html'], **kwargs)[source]#

Parse arguments, load config, and execute the CLI command.

Parameters:

  • args (list[str]) – Command-line arguments (defaults to sys.argv[1:]).

  • **kwargs (Any) – Extra keyword arguments passed to the command’s run() method.

Returns:

  • Result of the executed command.

  • Configuration dictionary used for execution.

Return type:

Tuple