Commands & groups

Drop-in replacement

The whole namespace of click_extra is a superset of both click and cloup namespaces. Click Extra’s main decorators, functions and classes extends and enhance Click and Cloup ones. Those left untouched by Click Extra are directly proxied to Cloup or Click.

This means if you want to upgrade an existing CLI to Click Extra, you can often replace imports of the click namespace by click_extra and it will work as expected.

Click and Cloup inheritance

At the module level, click_extra imports all elements from click.*, then all elements from the cloup.* namespace.

Which means all elements not redefined by Click Extra fallback to Cloup. And if Cloup itself does not redefine them, they fallback to Click.

For example:

• click_extra.echo is a direct alias to click.echo because neither Click Extra or Cloup re-implements an echo helper.

• @cloup.option_group is a specific feature of Cloup that is only implemented by it. It is not modified by Click Extra, and Click does not implement it. Still, @click_extra.option_group is a direct alias to Cloup’s one.

• @click_extra.timer is a new decorator only implemented by Click Extra. So it is not a proxy of anything.

• As for @click_extra.version_option, it is a re-implementation of @click.version_option, and so overrides it. If you want to use its original version, import it directly from click namespace.

Here is some of the main decorators of Click Extra and how they wraps and extends Cloup and Click ones:

Decorators from click_extra	Wrapped decorator	Base class
@command	@cloup.command	click_extra.ExtraCommand
@group	@cloup.group	click_extra.ExtraGroup
@lazy_group	@click_extra.group	click_extra.LazyGroup
@option	@cloup.option	click_extra.Option
@argument	@cloup.argument	click_extra.Argument
@version_option	@click_extra.option	click_extra.ExtraVersionOption
@color_option	@click_extra.option	click_extra.ColorOption
@config_option	@click_extra.option	click_extra.ConfigOption
@no_config_option	@click_extra.option	click_extra.NoConfigOption
@show_params_option	@click_extra.option	click_extra.ShowParamsOption
@table_format_option	@click_extra.option	click_extra.TableFormatOption
@telemetry_option	@click_extra.option	click_extra.TelemetryOption
@timer_option	@click_extra.option	click_extra.TimerOption
@verbose_option	@click_extra.option	click_extra.VerboseOption
@verbosity_option	@click_extra.option	click_extra.VerbosityOption
@option_group	@cloup.option_group	cloup.OptionGroup
@pass_context	@click.pass_context	-
@help_option	@click.help_option	-
…	…	…

Same for the main classes and functions, where some are re-implemented by Click Extra, and others are direct aliases to Cloup or Click ones:

Classes from click_extra	Alias to	Parent class
ExtraCommand	-	cloup.Command
ExtraGroup	-	cloup.Group
LazyGroup	-	click_extra.ExtraGroup
Option	-	cloup.Option
Argument	-	cloup.Argument
ExtraContext	-	cloup.Context
HelpFormatter	cloup.HelpFormatter
HelpExtraFormatter	-	cloup.HelpFormatter
HelpTheme	cloup.HelpThene
HelpExtraTheme	-	cloup.HelpThene
ExtraCliRunner	-	click.testing.CliRunner
ExtraVersionOption	-
Style	cloup.Style
echo	click.echo
ParameterSource	click.core.ParameterSource
UNSET	click._utils.UNSET
Choice	click.Choice
EnumChoice	-	click.Choice
…	…	…

Hint

You can inspect the implementation details in:

• click_extra.__init__

• cloup.__init__

• click.__init__

Default options

The @command and @group decorators are pre-configured with a set of default options.

Remove default options

You can remove all default options by resetting the params argument to None:

from click_extra import command

@command(params=None)
def bare_cli():
    pass

Which results in:

$ bare-cli --help
Usage: bare-cli [OPTIONS]

Options:
  -h, --help  Show this message and exit.

As you can see, all options are stripped out, but the colouring and formatting of the help message is preserved.

Change default options

To override the default options, you can provide the params= argument to the command. But note how we use classes instead of option decorators:

from click_extra import command, ConfigOption, VerbosityOption

@command(
    params=[
        ConfigOption(default="ex.yml"),
        VerbosityOption(default="DEBUG"),
    ]
)
def cli():
    pass

And now you get:

$ cli --help
Usage: cli [OPTIONS]

Options:
  --config CONFIG_PATH  Location of the configuration file. Supports local path
                        with glob patterns or remote URL.  [default: ex.yml]
  --verbosity LEVEL     Either CRITICAL, ERROR, WARNING, INFO, DEBUG.  [default:
                        DEBUG]
  -h, --help            Show this message and exit.

This let you replace the preset options by your own set, tweak their order and fine-tune their defaults.

Duplicate options

If you try to add option decorators to a command which already have them by default, you will end up with duplicate entries (as seen in issue #232):

from click_extra import command, version_option

@command
@version_option(version="0.1")
def cli():
    pass

See how the --version option gets duplicated at the end:

$ cli --help
Usage: cli [OPTIONS]

Options:
  --time / --no-time    Measure and print elapsed execution time.  [default: no-
                        time]
  --color, --ansi / --no-color, --no-ansi
                        Strip out all colors and all ANSI codes from output.
                        [default: color]
  --config CONFIG_PATH  Location of the configuration file. Supports local path
                        with glob patterns or remote URL.  [default: ~/.config/c
                        li/*.toml|*.yaml|*.yml|*.json|*.json5|*.jsonc|*.hjson|*.
                        ini|*.xml]
  --no-config           Ignore all configuration files and only use command line
                        parameters and environment variables.
  --show-params         Show all CLI parameters, their provenance, defaults and
                        value, then exit.
  --table-format [asciidoc|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|html|jira|latex|latex-booktabs|latex-longtable|latex-raw|mediawiki|mixed-grid|mixed-outline|moinmoin|orgtbl|outline|pipe|plain|presto|pretty|psql|rounded-grid|rounded-outline|rst|simple|simple-grid|simple-outline|textile|tsv|unsafehtml|vertical|youtrack]
                        Rendering style of tables.  [default: rounded-outline]
  --verbosity LEVEL     Either CRITICAL, ERROR, WARNING, INFO, DEBUG.  [default:
                        WARNING]
  -v, --verbose         Increase the default WARNING verbosity by one level for
                        each additional repetition of the option.  [default: 0]
  --version             Show the version and exit.
  --version             Show the version and exit.
  -h, --help            Show this message and exit.
/home/runner/work/click-extra/click-extra/.venv/lib/python3.12/site-packages/click/core.py:1213: UserWarning: The parameter --version is used more than once. Remove its duplicate as parameters should be unique.
  parser = self.make_parser(ctx)
/home/runner/work/click-extra/click-extra/.venv/lib/python3.12/site-packages/cloup/constraints/_support.py:183: UserWarning: The parameter --version is used more than once. Remove its duplicate as parameters should be unique.
  args = super().parse_args(ctx, args)  # type: ignore
/home/runner/work/click-extra/click-extra/click_extra/colorize.py:345: UserWarning: The parameter --version is used more than once. Remove its duplicate as parameters should be unique.
  metavars.update(command.collect_usage_pieces(ctx))
/home/runner/work/click-extra/click-extra/click_extra/colorize.py:452: UserWarning: The parameter --version is used more than once. Remove its duplicate as parameters should be unique.
  ) = self._collect_keywords(ctx)
/home/runner/work/click-extra/click-extra/.venv/lib/python3.12/site-packages/click/core.py:1022: UserWarning: The parameter --version is used more than once. Remove its duplicate as parameters should be unique.
  pieces = self.collect_usage_pieces(ctx)

This is by design: decorators are cumulative, to allow you to add your own options to the preset of @command and @group.

But notice the UserWarning log messages: The parameter --version is used more than once. Remove its duplicate as parameters should be unique.. As it is not a good practice to have duplicate options and you must avoid it. There’s also a non-zero chance for this situation to result in complete failure in a future Click release.

Finally, if the second --version option is placed right before the --help option, it is because Click is adding its own generated --help option at the end of the list.

Option order

Notice how the options above are ordered in the help message.

The default behavior of @command is to order options in the way they are provided to the params= argument of the decorator. Then adds to that list the additional option decorators positioned after the @command decorator.

After that, there is a final sorting step applied to options. This is done by the extra_option_at_end option, which is True by default.

Option’s defaults

Because Click Extra inherits from Click, you can override the defaults the same way Click allows you to. Here is a reminder on how to do it.

For example, the --verbosity option defaults to the WARNING level. Now we’d like to change this default to INFO.

If you manage your own --verbosity option, you can pass the default argument to its decorator like we did above:

import click
from click_extra import verbosity_option

@click.command
@verbosity_option(default="INFO")
def cli():
    pass

This also works in its class form:

import click
from click_extra import VerbosityOption

@click.command(params=[VerbosityOption(default="INFO")])
def cli():
    pass

With a @click_extra.command instead of @click.command, it is the same, you also have the alternative to pass a default_map via the context_settings:

import click_extra

@click_extra.command(context_settings={"default_map": {"verbosity": "INFO"}})
def cli():
    pass

Which results in [default: INFO] being featured in the help message:

$ cli --help
Usage: cli [OPTIONS]

Options:
  --time / --no-time    Measure and print elapsed execution time.  [default: no-
                        time]
  --color, --ansi / --no-color, --no-ansi
                        Strip out all colors and all ANSI codes from output.
                        [default: color]
  --config CONFIG_PATH  Location of the configuration file. Supports local path
                        with glob patterns or remote URL.  [default: ~/.config/c
                        li/*.toml|*.yaml|*.yml|*.json|*.json5|*.jsonc|*.hjson|*.
                        ini|*.xml]
  --no-config           Ignore all configuration files and only use command line
                        parameters and environment variables.
  --show-params         Show all CLI parameters, their provenance, defaults and
                        value, then exit.
  --table-format [asciidoc|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|html|jira|latex|latex-booktabs|latex-longtable|latex-raw|mediawiki|mixed-grid|mixed-outline|moinmoin|orgtbl|outline|pipe|plain|presto|pretty|psql|rounded-grid|rounded-outline|rst|simple|simple-grid|simple-outline|textile|tsv|unsafehtml|vertical|youtrack]
                        Rendering style of tables.  [default: rounded-outline]
  --verbosity LEVEL     Either CRITICAL, ERROR, WARNING, INFO, DEBUG.  [default:
                        INFO]
  -v, --verbose         Increase the default WARNING verbosity by one level for
                        each additional repetition of the option.  [default: 0]
  --version             Show the version and exit.
  -h, --help            Show this message and exit.

Tip

The advantage of the context_settings method we demonstrated above, is that it let you change the default of the --verbosity option provided by Click Extra, without having to touch the params argument.

Lazily loading subcommands

Click Extra provides a LazyGroup class and @lazy_group decorator to create command groups that only load their subcommands when they are invoked.

This implementation is based on the one provided in Click’s documentation, so refer to the Lazily loading subcommands section for more details.

Third-party commands composition

Click Extra is capable of composing with existing Click CLI in various situation.

Wrap other commands

Click allows you to build up a hierarchy of command and subcommands. Click Extra inherits this behavior, which means we are free to assemble multiple third-party subcommands into a top-level one.

For this example, let’s imagine you are working for an operation team that is relying daily on a couple of CLIs. Like dbt to manage your data workflows, and aws-sam-cli to deploy them in the cloud.

For some practical reasons, you’d like to wrap all these commands into a big one. This is how to do it.

Note

Here is how I initialized this example on my machine:

$ git clone https://github.com/kdeldycke/click-extra
(...)

$ cd click-extra
(...)

$ python -m pip install uv
(...)

$ uv venv
(...)

$ source .venv/bin/activate
(...)

$ uv sync --all-extras
(...)

$ uv pip install dbt-core
(...)

$ uv pip install aws-sam-cli
(...)

That way I had the latest Click Extra, dbt and aws-sam-cli installed in the same virtual environment:

$ uv run -- dbt --version
Core:
  - installed: 1.6.1
  - latest:    1.6.2 - Update available!

  Your version of dbt-core is out of date!
  You can find instructions for upgrading here:
  https://docs.getdbt.com/docs/installation

Plugins:

$ uv run -- sam --version
SAM CLI, version 1.97.0

Once you identified the entry points of each commands, you can easily wrap them into a top-level Click Extra CLI, here in a local script I called wrap.py:

wrap.py

import click_extra

from samcli.cli.main import cli as sam_cli
from dbt.cli.main import cli as dbt_cli


@click_extra.group
def main():
    pass


main.add_command(cmd=sam_cli, name="aws_sam")
main.add_command(cmd=dbt_cli, name="dbt")


if __name__ == "__main__":
    main()

And this simple script gets rendered into:

$ uv run -- python ./wrap.py
Usage: wrap.py [OPTIONS] COMMAND [ARGS]...

Options:
  --time / --no-time    Measure and print elapsed execution time.  [default: no-
                        time]
  --color, --ansi / --no-color, --no-ansi
                        Strip out all colors and all ANSI codes from output.
                        [default: color]
  --config CONFIG_PATH  Location of the configuration file. Supports glob
                        pattern of local path and remote URL.  [default:
                        ~/Library/Application
                        Support/wrap.py/*.{toml,yaml,yml,json,ini,xml}]
  --no-config           Ignore all configuration files and only use command line
                        parameters and environment variables.
  --show-params         Show all CLI parameters, their provenance, defaults and
                        value, then exit.
  --table-format [asciidoc|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|html|jira|latex|latex-booktabs|latex-longtable|latex-raw|mediawiki|mixed-grid|mixed-outline|moinmoin|orgtbl|outline|pipe|plain|presto|pretty|psql|rounded-grid|rounded-outline|rst|simple|simple-grid|simple-outline|textile|tsv|unsafehtml|vertical|youtrack]
                        Rendering style of tables.  [default: rounded-outline]
  --verbosity LEVEL     Either CRITICAL, ERROR, WARNING, INFO, DEBUG.  [default:
                        INFO]
  -v, --verbose         Increase the default WARNING verbosity by one level for
                        each additional repetition of the option.  [default: 0]
  --version             Show the version and exit.
  -h, --help            Show this message and exit.

Commands:
  aws_sam  AWS Serverless Application Model (SAM) CLI
  dbt      An ELT tool for managing your SQL transformations and data models.

Here you can see that the top-level CLI gets all the default options and behavior (including coloring) of @group. But it also made available the standalone aws_sam and dbt CLI as standard subcommands.

And they are perfectly functional as-is.

You can compare the output of the aws_sam subcommand with its original one:

aws_sam subcommand in wrap.py

$ uv run -- python ./wrap.py aws_sam --help
Usage: wrap.py aws_sam [OPTIONS] COMMAND [ARGS]...

  AWS Serverless Application Model (SAM) CLI

  The AWS Serverless Application Model Command Line Interface (AWS SAM CLI) is
  a command line tool that you can use with AWS SAM templates and supported
  third-party integrations to build and run your serverless applications.

  Learn more: https://docs.aws.amazon.com/serverless-application-model/

Commands:

  Learn:
    docs NEW!           Launch the AWS SAM CLI documentation in a browser.

  Create an App:
    init                Initialize an AWS SAM application.

  Develop your App:
    build               Build your AWS serverless function code.
    local               Run your AWS serverless function locally.
    validate            Validate an AWS SAM template.
    sync NEW!           Sync an AWS SAM project to AWS.
    remote NEW!         Invoke or send an event to cloud resources in your AWS
                        Cloudformation stack.

  Deploy your App:
    package             Package an AWS SAM application.
    deploy              Deploy an AWS SAM application.

  Monitor your App:
    logs                Fetch AWS Cloudwatch logs for AWS Lambda Functions or
                        Cloudwatch Log groups.
    traces              Fetch AWS X-Ray traces.

  And More:
    list NEW!           Fetch the state of your AWS serverless application.
    delete              Delete an AWS SAM application and the artifacts created
                        by sam deploy.
    pipeline            Manage the continuous delivery of your AWS serverless
                        application.
    publish             Publish a packaged AWS SAM template to AWS Serverless
                        Application Repository for easy sharing.

Options:

    --beta-features / --no-beta-features
                                    Enable/Disable beta features.
    --debug                         Turn on debug logging to print debug message
                                    generated by AWS SAM CLI and display
                                    timestamps.
    --version                       Show the version and exit.
    --info                          Show system and dependencies information.
    -h, --help                      Show this message and exit.

Examples:

    Get Started:        $wrap.py aws_sam init

Vanilla sam CLI

$ uv run -- sam --help
Usage: sam [OPTIONS] COMMAND [ARGS]...

  AWS Serverless Application Model (SAM) CLI

  The AWS Serverless Application Model Command Line Interface (AWS SAM CLI) is
  a command line tool that you can use with AWS SAM templates and supported
  third-party integrations to build and run your serverless applications.

  Learn more: https://docs.aws.amazon.com/serverless-application-model/

Commands:

  Learn:
    docs NEW!           Launch the AWS SAM CLI documentation in a browser.

  Create an App:
    init                Initialize an AWS SAM application.

  Develop your App:
    build               Build your AWS serverless function code.
    local               Run your AWS serverless function locally.
    validate            Validate an AWS SAM template.
    sync NEW!           Sync an AWS SAM project to AWS.
    remote NEW!         Invoke or send an event to cloud resources in your AWS
                        Cloudformation stack.

  Deploy your App:
    package             Package an AWS SAM application.
    deploy              Deploy an AWS SAM application.

  Monitor your App:
    logs                Fetch AWS Cloudwatch logs for AWS Lambda Functions or
                        Cloudwatch Log groups.
    traces              Fetch AWS X-Ray traces.

  And More:
    list NEW!           Fetch the state of your AWS serverless application.
    delete              Delete an AWS SAM application and the artifacts created
                        by sam deploy.
    pipeline            Manage the continuous delivery of your AWS serverless
                        application.
    publish             Publish a packaged AWS SAM template to AWS Serverless
                        Application Repository for easy sharing.

Options:

    --beta-features / --no-beta-features
                                    Enable/Disable beta features.
    --debug                         Turn on debug logging to print debug message
                                    generated by AWS SAM CLI and display
                                    timestamps.
    --version                       Show the version and exit.
    --info                          Show system and dependencies information.
    -h, --help                      Show this message and exit.

Examples:

    Get Started:        $sam init

Here is the highlighted differences to make them even more obvious:

@@ -1,5 +1,5 @@
-$ uv run -- python ./wrap.py aws_sam --help
-Usage: wrap.py aws_sam [OPTIONS] COMMAND [ARGS]...
+$ uv run -- sam --help
+Usage: sam [OPTIONS] COMMAND [ARGS]...

   AWS Serverless Application Model (SAM) CLI

@@ -56,4 +56,4 @@

 Examples:

-    Get Started:        $wrap.py aws_sam init
+    Get Started:        $sam init

Now that all commands are under the same umbrella, there is no limit to your imagination!

Caution

This might looks janky, but this franken-CLI might be a great way to solve practical problems in your situation.

You can augment them with your custom glue code. Or maybe mashing them up will simplify the re-distribution of these CLIs on your production machines. Or control their common dependencies. Or freeze their versions. Or hard-code some parameters. Or apply monkey-patches. Or chain these commands to create new kind of automation…

There is a miriad of possibilities. If you have some other examples in the same vein, please share them in an issue or even directly via a PR. I’d love to complement this documentation with creative use-cases.

click_extra.commands API

        classDiagram
  Command <|-- ExtraCommand
  Context <|-- ExtraContext
  ExtraCommand <|-- ExtraGroup
  ExtraGroup <|-- LazyGroup
  ExtraHelpColorsMixin <|-- ExtraCommand
  Group <|-- ExtraGroup
    

Wraps vanilla Click and Cloup commands with extra features.

Our flavor of commands, groups and context are all subclasses of their vanilla counterparts, but are pre-configured with good and common defaults. You can still leverage the mixins in here to build up your own custom variants.

class click_extra.commands.ExtraContext(*args, meta=None, **kwargs)

Bases: Context

Like cloup._context.Context, but with the ability to populate the context’s meta property at instantiation.

Also inherits color property from parent context. And sets it to True for parentless contexts at instantiatiom, so we can always have colorized output.

Todo

Propose addition of meta keyword upstream to Click.

Like parent’s context but with an extra meta keyword-argument.

Also force color property default to True if not provided by user and this context has no parent.

formatter_class

Use our own formatter to colorize the help screen.

alias of HelpExtraFormatter

property color: bool | None

Overrides Context.color to allow inheritance from parent context.

Returns the color setting of the parent context if it exists and the color is not set on the current context.

click_extra.commands.default_extra_params()

Default additional options added to @command and @group.

Caution

The order of options has been carefully crafted to handle subtle edge-cases and avoid leaky states in unittests.

You can still override this hard-coded order for easthetic reasons and it should be fine. Your end-users are unlikely to be affected by these sneaky bugs, as the CLI context is going to be naturraly reset after each invocation (which is not the case in unitests).

1. --time / --no-time

   Hint

   --time is placed at the top of all other eager options so all other options’ processing time can be measured.

2. --config CONFIG_PATH

   Hint

   --config is at the top so it can have a direct influence on the default behavior and value of the other options.

3. --no-config

4. --color, --ansi / --no-color, --no-ansi

5. --show-params

6. --table-format FORMAT

7. --verbosity LEVEL

8. -v, --verbose

9. --version

10. -h, --help

    Attention

    This is the option produced by the @click.decorators.help_option decorator.

    It is not explicitly referenced in the implementation of this function.

    That’s because it’s going to be added by Click itself, at the end of the list of options. By letting Click handle this, we ensure that the help option will take into account the help_option_names setting.

Important

Sensitivity to order still remains to be proven. With the code of Click Extra and its dependencies moving fast, there is a non-zero chance that all the options are now sound enough to be re-ordered in a more natural way.

Todo

For bullet-proof handling of edge-cases, we should probably add an indirection layer to have the processing order of options (the one below) different from the presentation order of options in the help screen.

This is probably something that has been requested in issue #544.

Return type:

list[Option]

class click_extra.commands.ExtraCommand(*args, version=None, extra_option_at_end=True, populate_auto_envvars=True, **kwargs)

Bases: ExtraHelpColorsMixin, Command

Like cloup.command, with sane defaults and extra help screen colorization.

List of extra parameters:

Parameters:

• version (str | None) – allows a version string to be set directly on the command. Will be passed to the first instance of ExtraVersionOption parameter attached to the command.

• extra_option_at_end (bool) – reorders all parameters attached to the command, by moving all instances of ExtraOption at the end of the parameter list. The original order of the options is preserved among themselves.

• populate_auto_envvars (bool) – forces all parameters to have their auto-generated environment variables registered. This address the shortcoming of click which only evaluates them dynamiccaly. By forcing their registration, the auto-generated environment variables gets displayed in the help screen, fixing click#2483 issue. On Windows, environment variable names are case-insensitive, so we normalize them to uppercase.

By default, these Click context settings are applied:

• auto_envvar_prefix = self.name (Click feature)

  Auto-generate environment variables for all options, using the command ID as prefix. The prefix is normalized to be uppercased and all non-alphanumerics replaced by underscores.

• help_option_names = ("--help", "-h") (Click feature)

  Allow help screen to be invoked with either –help or -h options.

• show_default = True (Click feature)

  Show all default values in help screen.

Additionally, these Cloup context settings are set:

• align_option_groups = False (Cloup feature)

  Aligns option groups in help screen.

• show_constraints = True (Cloup feature)

  Show all constraints in help screen.

• show_subcommand_aliases = True (Cloup feature)

  Show all subcommand aliases in help screen.

Click Extra also adds its own context_settings:

• show_choices = None (Click Extra feature)

  If set to True or False, will force that value on all options, so we can globally show or hide choices when prompting a user for input. Only makes sense for options whose prompt property is set.

  Defaults to None, which will leave all options untouched, and let them decide of their own show_choices setting.

• show_envvar = None (Click Extra feature)

  If set to True or False, will force that value on all options, so we can globally enable or disable the display of environment variables in help screen.

  Defaults to None, which will leave all options untouched, and let them decide of their own show_envvar setting. The rationale being that discoverability of environment variables is enabled by the --show-params option, which is active by default on extra commands. So there is no need to surcharge the help screen.

  This addresses the click#2313 issue.

To override these defaults, you can pass your own settings with the context_settings parameter:

@command(
    context_settings={
        "show_default": False,
        ...
    }
)

context_class

alias of ExtraContext

main(args=None, prog_name=None, **kwargs)

Pre-invocation step that is instantiating the context, then call invoke() within it.

Caution

During context instantiation, each option’s callbacks are called. These might break the execution flow (like --help or --version).

Sets the default CLI’s prog_name to the command’s name if not provided, instead of relying on Click’s auto-detection via the _detect_program_name() method. This is to avoid the CLI being called python -m <module_name>, which is not very user-friendly.

Return type:

Union[Any, NoReturn]

make_context(info_name, args, parent=None, **extra)

Intercept the call to the original click.core.Command.make_context so we can keep a copy of the raw, pre-parsed arguments provided to the CLI.

The result are passed to our own ExtraContext constructor which is able to initialize the context’s meta property under our own click_extra.raw_args entry. This will be used in ShowParamsOption.print_params() to print the table of parameters fed to the CLI.

See also

This workaround is being discussed upstream in click#1279.

Return type:

Any

invoke(ctx)

Main execution of the command, just after the context has been instantiated in main().

Return type:

Any

class click_extra.commands.ExtraGroup(*args, version=None, extra_option_at_end=True, populate_auto_envvars=True, **kwargs)

Bases: ExtraCommand, Group

Like cloup.Group, with sane defaults and extra help screen colorization.

List of extra parameters:

Parameters:

• version (str | None) – allows a version string to be set directly on the command. Will be passed to the first instance of ExtraVersionOption parameter attached to the command.

• extra_option_at_end (bool) –

  reorders all parameters attached to the command, by moving all instances of ExtraOption at the end of the parameter list. The original order of the options is preserved among themselves.

• populate_auto_envvars (bool) –

  forces all parameters to have their auto-generated environment variables registered. This address the shortcoming of click which only evaluates them dynamiccaly. By forcing their registration, the auto-generated environment variables gets displayed in the help screen, fixing click#2483 issue. On Windows, environment variable names are case-insensitive, so we normalize them to uppercase.

By default, these Click context settings are applied:

• auto_envvar_prefix = self.name (Click feature)

  Auto-generate environment variables for all options, using the command ID as prefix. The prefix is normalized to be uppercased and all non-alphanumerics replaced by underscores.

• help_option_names = ("--help", "-h") (Click feature)

  Allow help screen to be invoked with either –help or -h options.

• show_default = True (Click feature)

  Show all default values in help screen.

Additionally, these Cloup context settings are set:

• align_option_groups = False (Cloup feature)

  Aligns option groups in help screen.

• show_constraints = True (Cloup feature)

  Show all constraints in help screen.

• show_subcommand_aliases = True (Cloup feature)

  Show all subcommand aliases in help screen.

Click Extra also adds its own context_settings:

• show_choices = None (Click Extra feature)

  If set to True or False, will force that value on all options, so we can globally show or hide choices when prompting a user for input. Only makes sense for options whose prompt property is set.

  Defaults to None, which will leave all options untouched, and let them decide of their own show_choices setting.

• show_envvar = None (Click Extra feature)

  If set to True or False, will force that value on all options, so we can globally enable or disable the display of environment variables in help screen.

  Defaults to None, which will leave all options untouched, and let them decide of their own show_envvar setting. The rationale being that discoverability of environment variables is enabled by the --show-params option, which is active by default on extra commands. So there is no need to surcharge the help screen.

  This addresses the click#2313 issue.

To override these defaults, you can pass your own settings with the context_settings parameter:

@command(
    context_settings={
        "show_default": False,
        ...
    }
)

command_class

Makes commands of an ExtraGroup be instances of ExtraCommand.

That way all subcommands created from an ExtraGroup benefits from the same defaults and extra help screen colorization.

See: https://click.palletsprojects.com/en/stable/api/#click.Group.command_class

alias of ExtraCommand

group_class

Let ExtraGroup produce sub-groups that are also of ExtraGroup type.

See: https://click.palletsprojects.com/en/stable/api/#click.Group.group_class

alias of type

class click_extra.commands.LazyGroup(*args, lazy_subcommands=None, **kwargs)

Bases: ExtraGroup

An ExtraGroup that supports lazy loading of subcommands.

This implementation adds special handling for config_option to ensure configuration values are passed to lazily loaded commands correctly.

Hint

This implementation is based on the snippet from Click’s documentation: Defining the lazy group.

And has been adapted to work with Click Extra’s config_option in click_extra#1332 issue.

Initialize the LazyGroup.

Args:

*args: Positional arguments for the parent class. lazy_subcommands (dict, optional): Mapping of command names to import paths. **kwargs: Keyword arguments for the parent class.

Tip

lazy_subcommands is a map of the form:

{"<command-name>": "<module-name>.<command-object-name>"}

Example:

{"mycmd": "my_cli.commands.mycmd"}

list_commands(ctx)

List all commands, including lazy subcommands.

Returns the list of command names, including the lazy-loaded.

Return type:

list[str]

get_command(ctx, cmd_name)

Get a command by name, loading lazily if necessary.

Todo

Allow passing extra parameters to the self.lazy_subcommands so we can registered commands with custom settings like Cloup’s section or fallback_to_default_section:

• section: Optional[Section] = None,

• fallback_to_default_section: bool = True,

See: https://github.com/janluke/cloup/blob/master/cloup/_sections.py#L169

Return type:

Command | None