Parameters#

Click Extra provides a set of tools to help you manage parameters in your CLI.

Like the magical --show-params option, which is a X-ray scanner for your CLI’s parameters.

Parameter structure#

Todo

Write example and tutorial.

Introspecting parameters#

If for any reason you need to dive into parameters and their values, there is a lot of intermediate and metadata available in the context. Here are some pointers:

from click import option, echo, pass_context

from click_extra import config_option, extra_group

@extra_group
@option("--dummy-flag/--no-flag")
@option("--my-list", multiple=True)
@config_option
@pass_context
def my_cli(ctx, dummy_flag, my_list):
    echo(f"dummy_flag    is {dummy_flag!r}")
    echo(f"my_list       is {my_list!r}")
    echo(f"Raw parameters:            {ctx.meta.get('click_extra.raw_args', [])}")
    echo(f"Loaded, default values:    {ctx.default_map}")
    echo(f"Values passed to function: {ctx.params}")

@my_cli.command()
@option("--int-param", type=int, default=10)
def subcommand(int_param):
    echo(f"int_parameter is {int_param!r}")

Caution

The click_extra.raw_args metadata field in the context referenced above is not a standard feature from Click, but a helper introduced by Click Extra. It is only available with @extra_group and @extra_command decorators.

In the mean time, it is being discussed in the Click community at click#1279.

Todo

Propose the raw_args feature upstream to Click.

Now if we feed the following ~/configuration.toml configuration file:

[my-cli]
verbosity = "DEBUG"
dummy_flag = true
my_list = [ "item 1", "item #2", "Very Last Item!",]

[my-cli.subcommand]
int_param = 3

Here is what we get:

$ cli --config ~/configuration.toml default-command
dummy_flag    is True
my_list       is ('item 1', 'item #2', 'Very Last Item!')
Raw parameters:            ['--config', '~/configuration.toml', 'default-command']
Loaded, default values:    {'dummy_flag': True, 'my_list': ['pip', 'npm', 'gem'], 'verbosity': 'DEBUG', 'default-command': {'int_param': 3}}
Values passed to function: {'dummy_flag': True, 'my_list': ('pip', 'npm', 'gem')}

`--show-params` option#

Click Extra provides a ready-to-use --show-params option, which is enabled by default.

It produces a comprehensive table of your CLI parameters, normalized IDs, types and corresponding environment variables. And because it dynamiccaly print their default value, actual value and its source, it is a practical tool for users to introspect and debug the parameters of a CLI.

See how the default @extra_command decorator come with the default --show-params option and the result of its use:

from click_extra import extra_command, option, echo

@extra_command
@option("--int-param1", type=int, default=10)
@option("--int-param2", type=int, default=555)
def cli(int_param1, int_param2):
    echo(f"int_param1 is {int_param1!r}")
    echo(f"int_param2 is {int_param2!r}")

$ cli --verbosity Debug --int-param1 3 --show-params
debug: Set <Logger click_extra (DEBUG)> to DEBUG.
debug: Set <RootLogger root (DEBUG)> to DEBUG.
debug: click_extra.raw_args: ['--verbosity', 'Debug', '--int-param1', '3', '--show-params']
╭─────────────────┬─────────────────────────────────────────┬─────────────────────────────────────────┬─────────────────────────────┬─────────────┬────────┬─────────┬──────────────────┬─────────────────┬─────────────────────────────────────────────────────────┬─────────────────────────────────────────────────────────┬─────────────╮
│ ID              │ Class                                   │ Spec.                                   │ Param type                  │ Python type │ Hidden │ Exposed │ Allowed in conf? │ Env. vars.      │ Default                                                 │ Value                                                   │ Source      │
├─────────────────┼─────────────────────────────────────────┼─────────────────────────────────────────┼─────────────────────────────┼─────────────┼────────┼─────────┼──────────────────┼─────────────────┼─────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────┼─────────────┤
│ cli.color       │ click_extra.colorize.ColorOption        │ --color, --ansi / --no-color, --no-ansi │ click.types.BoolParamType   │ bool        │ ✘      │ ✘       │ ✓                │ CLI_COLOR       │ True                                                    │ True                                                    │ DEFAULT     │
│ cli.config      │ click_extra.config.ConfigOption         │ -C, --config CONFIG_PATH                │ click.types.StringParamType │ str         │ ✘      │ ✘       │ ✘                │ CLI_CONFIG      │ /home/runner/.config/cli/*.{toml,yaml,yml,json,ini,xml} │ /home/runner/.config/cli/*.{toml,yaml,yml,json,ini,xml} │ DEFAULT     │
│ cli.help        │ click_extra.colorize.HelpOption         │ -h, --help                              │ click.types.BoolParamType   │ bool        │ ✘      │ ✘       │ ✘                │ CLI_HELP        │ False                                                   │ False                                                   │ DEFAULT     │
│ cli.int_param1  │ cloup._params.Option                    │ --int-param1 INTEGER                    │ click.types.IntParamType    │ int         │ ✘      │ ✓       │ ✓                │ CLI_INT_PARAM1  │ 10                                                      │ 3                                                       │ COMMANDLINE │
│ cli.int_param2  │ cloup._params.Option                    │ --int-param2 INTEGER                    │ click.types.IntParamType    │ int         │ ✘      │ ✓       │ ✓                │ CLI_INT_PARAM2  │ 555                                                     │ 555                                                     │ DEFAULT     │
│ cli.show_params │ click_extra.parameters.ShowParamsOption │ --show-params                           │ click.types.BoolParamType   │ bool        │ ✘      │ ✘       │ ✘                │ CLI_SHOW_PARAMS │ False                                                   │ True                                                    │ COMMANDLINE │
│ cli.time        │ click_extra.timer.TimerOption           │ --time / --no-time                      │ click.types.BoolParamType   │ bool        │ ✘      │ ✘       │ ✓                │ CLI_TIME        │ False                                                   │ False                                                   │ DEFAULT     │
│ cli.verbosity   │ click_extra.logging.VerbosityOption     │ -v, --verbosity LEVEL                   │ click.types.Choice          │ str         │ ✘      │ ✘       │ ✓                │ CLI_VERBOSITY   │ WARNING                                                 │ Debug                                                   │ COMMANDLINE │
│ cli.version     │ click_extra.version.ExtraVersionOption  │ --version                               │ click.types.BoolParamType   │ bool        │ ✘      │ ✘       │ ✘                │ CLI_VERSION     │ False                                                   │ False                                                   │ DEFAULT     │
╰─────────────────┴─────────────────────────────────────────┴─────────────────────────────────────────┴─────────────────────────────┴─────────────┴────────┴─────────┴──────────────────┴─────────────────┴─────────────────────────────────────────────────────────┴─────────────────────────────────────────────────────────┴─────────────╯
debug: Reset <RootLogger root (DEBUG)> to WARNING.
debug: Reset <Logger click_extra (DEBUG)> to WARNING.

Note

Notice how --show-params is showing all parameters, even those provided to the excluded_params argument. You can still see the --help, --version, -C/--config and --show-params options in the table.

`click_extra.parameters` API#

classDiagram ExtraOption <|-- ShowParamsOption Option <|-- ExtraOption ParamStructure <|-- ShowParamsOption

Our own flavor of Option, Argument and parameters.

Also implements environment variable utilities.

click_extra.parameters.auto_envvar(param, ctx)[source]#

Compute the auto-generated environment variable of an option or argument.

Returns the auto envvar as it is exactly computed within Click’s internals, i.e. click.core.Parameter.resolve_envvar_value() and click.core.Option.resolve_envvar_value().

Return type:: str | None

click_extra.parameters.extend_envvars(envvars_1, envvars_2)[source]#

Utility to build environment variables value to be fed to options.

Variable names are deduplicated while preserving their initial order.

Returns a tuple of environment variable strings. The result is ready to be used as the envvar parameter for options or arguments.

Return type:: tuple[str, ...]

click_extra.parameters.normalize_envvar(envvar)[source]#

Utility to normalize an environment variable name.

The normalization process separates all contiguous alphanumeric string segments, eliminate empty strings, join them with an underscore and uppercase the result.

Return type:: str

click_extra.parameters.all_envvars(param, ctx, normalize=False)[source]#

Returns the deduplicated, ordered list of environment variables for an option or argument, including the auto-generated one.

The auto-generated environment variable is added at the end of the list, so that user-defined envvars takes precedence. This respects the current implementation of click.core.Option.resolve_envvar_value().

If normalize is True, the returned value is normalized. By default it is False to perfectly reproduce the current behavior of Click, which is subject to discussions.

Return type:: tuple[str, ...]

click_extra.parameters.search_params(params, klass, unique=True)[source]#

Search a particular class of parameter in a list and return them.

Parameters:

params (Iterable[Parameter]) – list of parameter instances to search in.
klass (type[Parameter]) – the class of the parameters to look for.
unique (bool) – if True, raise an error if more than one parameter of the provided klass is found.

Return type:

list[Parameter] | Parameter | None

class click_extra.parameters.ExtraOption(*args, group=None, **attrs)[source]#

Bases: Option

All new options implemented by click-extra inherits this class.

Does nothing in particular for now but provides a way to identify Click Extra’s own options with certainty.

Also contains Option-specific code that should be contributed upstream to Click.

static get_help_default(option, ctx)[source]#

Produce the string to be displayed in the help as option’s default. :rtype: str | None

Caution

This is a copy of Click’s default value rendering of the default

This code should be keep in sync with Click’s implementation.

Attention

This doesn’t work with our own --config option because we are also monkey-patching ConfigOption.get_help_record() to display the dynamic default value.

So the results of this method call is:

<bound method ConfigOption.default_pattern of <ConfigOption config>>

instead of the expected:

~/(...)/multiple_envvars.py/*.{toml,yaml,yml,json,ini,xml}

Todo

A better solution has been proposed upstream to Click: - https://github.com/pallets/click/issues/2516 - https://github.com/pallets/click/pull/2517

class click_extra.parameters.ParamStructure(*args, excluded_params=None, **kwargs)[source]#

Bases: object

Utilities to introspect CLI options and commands structure.

Structures are represented by a tree-like dict.

Access to a node is available using a serialized path string composed of the keys to descend to that node, separated by a dot ..

Todo

Evaluates the possibility of replacing all key-based access to the tree-like structure by a Box object, as it provides lots of utilities to merge its content.

Allow a list of paramerers to be blocked from the parameter structure.

If excluded_params is not provided, let the dynamic and cached self.excluded_params property to compute the default value on first use.

SEP: str = '.'#: Use a dot . as a separator between levels of the tree-like parameter structure.

DEFAULT_EXCLUDED_PARAMS: Iterable[str] = ('config', 'help', 'show_params', 'version')#

List of root parameters to exclude from configuration by default:

-C/--config option, which cannot be used to recursively load another configuration file.
--help, as it makes no sense to have the configurable file always forces a CLI to show the help and exit.
--show-params flag, which is like --help and stops the CLI execution.
--version, which is not a configurable option per-se.

static init_tree_dict(*path, leaf=None)[source]#

Utility method to recursively create a nested dict structure whose keys are provided by path list and at the end is populated by a copy of leaf.

Return type:: Any

static get_tree_value(tree_dict, *path)[source]#

Get in the tree_dict the value located at the path.

Return type:: Any | None

flatten_tree_dict(tree_dict, parent_key=None)[source]#

Recursively traverse the tree-like dict and produce a flat dict whose keys are path and values are the leaf’s content.

Return type:: dict[str, Any]

walk_params()[source]#

Generates an unfiltered list of all CLI parameters.

Everything is included, from top-level groups to subcommands, and from options to arguments.

Return type:: Iterator[tuple[tuple[str, ...], Parameter]]

Returns a 2-elements tuple:

the first being a tuple of keys leading to the parameter
the second being the parameter object itself

TYPE_MAP: dict[type[ParamType], type[str | int | float | bool | list]] = {<class 'click.types.StringParamType'>: <class 'str'>, <class 'click.types.IntParamType'>: <class 'int'>, <class 'click.types.FloatParamType'>: <class 'float'>, <class 'click.types.BoolParamType'>: <class 'bool'>, <class 'click.types.UUIDParameterType'>: <class 'str'>, <class 'click.types.UnprocessedParamType'>: <class 'str'>, <class 'click.types.File'>: <class 'str'>, <class 'click.types.Path'>: <class 'str'>, <class 'click.types.Choice'>: <class 'str'>, <class 'click.types.IntRange'>: <class 'int'>, <class 'click.types.FloatRange'>: <class 'float'>, <class 'click.types.DateTime'>: <class 'str'>, <class 'click.types.Tuple'>: <class 'list'>}#

Map Click types to their Python equivalent.

Keys are subclasses of click.types.ParamType. Values are expected to be simple builtins Python types.

This mapping can be seen as a reverse of the click.types.convert_type() method.

get_param_type(param)[source]#

Get the Python type of a Click parameter.

See the list of custom types provided by Click.

Return type:: type[str | int | float | bool | list]

property excluded_params: Iterable[str]#

List of parameter IDs to exclude from the parameter structure.

Elements of this list are expected to be the fully-qualified ID of the parameter, i.e. the dot-separated ID that is prefixed by the CLI name.

Caution

It is only called once to produce the list of default parameters to exclude, if the user did not provided its own list to the constructor.

It was not implemented in the constructor but made as a property, to allow for a just-in-time call to the current context. Without this trick we could not have fetched the CLI name.

build_param_trees()[source]#

Build all parameters tree structure in one go and cache them.

This removes parameters whose fully-qualified IDs are in the excluded_params blocklist.

Return type:: None

property params_template: dict[str, Any]#

Returns a tree-like dictionary whose keys shadows the CLI options and subcommands and values are None.

Perfect to serve as a template for configuration files.

property params_types: dict[str, Any]#

Returns a tree-like dictionary whose keys shadows the CLI options and subcommands and values are their expected Python type.

Perfect to parse configuration files and user-provided parameters.

property params_objects: dict[str, Any]#

Returns a tree-like dictionary whose keys shadows the CLI options and subcommands and values are parameter objects.

Perfect to parse configuration files and user-provided parameters.

class click_extra.parameters.ShowParamsOption(param_decls=None, is_flag=True, expose_value=False, is_eager=True, help='Show all CLI parameters, their provenance, defaults and value, then exit.', **kwargs)[source]#

Bases: ExtraOption, ParamStructure

A pre-configured option adding a --show-params option.

Between configuration files, default values and environment variables, it might be hard to guess under which set of parameters the CLI will be executed. This option print information about the parameters that will be fed to the CLI.

Allow a list of paramerers to be blocked from the parameter structure.

If excluded_params is not provided, let the dynamic and cached self.excluded_params property to compute the default value on first use.

default: t.Union[t.Any, t.Callable[[], t.Any]]#

type: types.ParamType#

is_flag: bool#

is_bool_flag: bool#

flag_value: t.Any#

name: t.Optional[str]#

opts: t.List[str]#

secondary_opts: t.List[str]#

TABLE_HEADERS = ('ID', 'Class', 'Spec.', 'Param type', 'Python type', 'Hidden', 'Exposed', 'Allowed in conf?', 'Env. vars.', 'Default', 'Value', 'Source')#: Hard-coded list of table headers.

print_params(ctx, param, value)[source]#: Introspects current CLI and list its parameters and metadata. :rtype: None

Important

Click doesn’t keep a list of all parsed arguments and their origin. So we need to emulate here what’s happening during CLI invocation.

Unfortunately we cannot even do that because the raw, pre-parsed arguments are not available anywhere within Click’s internals.

Our workaround consist in leveraging our custom ExtraCommand/ExtraGroup classes, in which we are attaching a click_extra.raw_args metadata entry to the context.

Parameters#

Parameter structure#

Introspecting parameters#

--show-params option#

click_extra.parameters API#

`--show-params` option#

`click_extra.parameters` API#