Parameters¶
Click Extra implements tools to manipulate your CLI’s parameters, options and arguments.
The cornerstone of these tools is the magical --show-params option, which is a X-ray scanner for your CLI’s parameters.
--show-params option¶
Click Extra provides a ready-to-use --show-params option, which is enabled by default.
It produces a comprehensive table of all the metadata about each of your CLI parameters, including: their normalized IDs, types, defaults and environment variables. And because it is dynamic, actual values and their sources are evaluated at runtime.
The default @command decorator come with the --show-params option, so you can call it right away:
from click_extra import command, option, echo
@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 --int-param1 3 --show-params
╭─────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬─────────────────────────────────────────┬──────────────────────────────────┬─────────────┬────────┬─────────┬──────────────────┬─────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────┬─────────────╮
│ ID │ Spec. │ Class │ Param type │ Python type │ Hidden │ Exposed │ Allowed in conf? │ Env. vars. │ Default │ Value │ Source │
├─────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────┼──────────────────────────────────┼─────────────┼────────┼─────────┼──────────────────┼─────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────┤
│ cli.color │ --color, --ansi / --no-color, --no-ansi │ click_extra.colorize.ColorOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_COLOR │ True │ True │ DEFAULT │
│ cli.config │ --config CONFIG_PATH │ click_extra.config.ConfigOption │ click.types.UnprocessedParamType │ str │ ✘ │ ✘ │ ✘ │ CLI_CONFIG │ '/home/runner/.config/cli/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,pyproject.toml}' │ '/home/runner/.config/cli/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,pyproject.toml}' │ DEFAULT │
│ cli.config │ --no-config │ click_extra.config.NoConfigOption │ click.types.UnprocessedParamType │ str │ ✘ │ ✘ │ ✘ │ CLI_CONFIG │ Sentinel.UNSET │ Sentinel.UNSET │ DEFAULT │
│ cli.help │ -h, --help │ click.core.Option │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ CLI_HELP │ False │ False │ DEFAULT │
│ cli.int_param1 │ --int-param1 INTEGER │ click_extra.parameters.Option │ click.types.IntParamType │ int │ ✘ │ ✓ │ ✓ │ CLI_INT_PARAM1 │ 10 │ '3' │ COMMANDLINE │
│ cli.int_param2 │ --int-param2 INTEGER │ click_extra.parameters.Option │ click.types.IntParamType │ int │ ✘ │ ✓ │ ✓ │ CLI_INT_PARAM2 │ 555 │ 555 │ DEFAULT │
│ cli.show_params │ --show-params │ click_extra.parameters.ShowParamsOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ CLI_SHOW_PARAMS │ False │ True │ COMMANDLINE │
│ cli.table_format │ --table-format [aligned|asciidoc|colon-grid|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|hjson|html|jira|json|json5|jsonc|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|toml|tsv|unsafehtml|vertical|xml|yaml|youtrack] │ click_extra.table.TableFormatOption │ click_extra.types.EnumChoice │ str │ ✘ │ ✘ │ ✓ │ CLI_TABLE_FORMAT │ 'rounded-outline' │ 'rounded-outline' │ DEFAULT │
│ cli.time │ --time / --no-time │ click_extra.timer.TimerOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_TIME │ False │ False │ DEFAULT │
│ cli.validate_config │ --validate-config FILE │ click_extra.config.ValidateConfigOption │ click.types.Path │ str │ ✘ │ ✘ │ ✓ │ CLI_VALIDATE_CONFIG │ Sentinel.UNSET │ Sentinel.UNSET │ DEFAULT │
│ cli.verbose │ -v, --verbose │ click_extra.logging.VerboseOption │ click.types.IntRange │ int │ ✘ │ ✘ │ ✓ │ CLI_VERBOSE │ 0 │ 0 │ DEFAULT │
│ cli.verbosity │ --verbosity LEVEL │ click_extra.logging.VerbosityOption │ click_extra.types.EnumChoice │ str │ ✘ │ ✘ │ ✓ │ CLI_VERBOSITY │ 'WARNING' │ 'WARNING' │ DEFAULT │
│ cli.version │ --version │ click_extra.version.ExtraVersionOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ CLI_VERSION │ False │ False │ DEFAULT │
╰─────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴─────────────────────────────────────────┴──────────────────────────────────┴─────────────┴────────┴─────────┴──────────────────┴─────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────┴─────────────╯
See in the rendered table above how --int-param1 is set to 3, because it was explicitly set on the command line. While --int-param2 still gets its value from its 555 default.
Hint
--show-params always displays all parameters, even those marked as not allowed in conf. In effect bypassing its own excluded_params argument. So you can still see the --help, --version, -C/--config and --show-params options in the table.
Table format¶
The default table produced by --show-params can be a bit overwhelming, so you can change its rendering with the --table-format option:
$ cli --table-format vertical --show-params
***************************[ 1. row ]***************************
ID | cli.color
Spec. | --color, --ansi / --no-color, --no-ansi
Class | click_extra.colorize.ColorOption
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_COLOR
Default | True
Value | True
Source | DEFAULT
***************************[ 2. row ]***************************
ID | cli.config
Spec. | --config CONFIG_PATH
Class | click_extra.config.ConfigOption
Param type | click.types.UnprocessedParamType
Python type | str
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✘
Env. vars. | CLI_CONFIG
Default | '/home/runner/.config/cli/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,pyproject.toml}'
Value | '/home/runner/.config/cli/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,pyproject.toml}'
Source | DEFAULT
***************************[ 3. row ]***************************
ID | cli.config
Spec. | --no-config
Class | click_extra.config.NoConfigOption
Param type | click.types.UnprocessedParamType
Python type | str
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✘
Env. vars. | CLI_CONFIG
Default | Sentinel.UNSET
Value | Sentinel.UNSET
Source | DEFAULT
***************************[ 4. row ]***************************
ID | cli.help
Spec. | -h, --help
Class | click.core.Option
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✘
Env. vars. | CLI_HELP
Default | False
Value | False
Source | DEFAULT
***************************[ 5. row ]***************************
ID | cli.int_param1
Spec. | --int-param1 INTEGER
Class | click_extra.parameters.Option
Param type | click.types.IntParamType
Python type | int
Hidden | ✘
Exposed | ✓
Allowed in conf? | ✓
Env. vars. | CLI_INT_PARAM1
Default | 10
Value | 10
Source | DEFAULT
***************************[ 6. row ]***************************
ID | cli.int_param2
Spec. | --int-param2 INTEGER
Class | click_extra.parameters.Option
Param type | click.types.IntParamType
Python type | int
Hidden | ✘
Exposed | ✓
Allowed in conf? | ✓
Env. vars. | CLI_INT_PARAM2
Default | 555
Value | 555
Source | DEFAULT
***************************[ 7. row ]***************************
ID | cli.show_params
Spec. | --show-params
Class | click_extra.parameters.ShowParamsOption
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✘
Env. vars. | CLI_SHOW_PARAMS
Default | False
Value | True
Source | COMMANDLINE
***************************[ 8. row ]***************************
ID | cli.table_format
Spec. | --table-format [aligned|asciidoc|colon-grid|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|hjson|html|jira|json|json5|jsonc|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|toml|tsv|unsafehtml|vertical|xml|yaml|youtrack]
Class | click_extra.table.TableFormatOption
Param type | click_extra.types.EnumChoice
Python type | str
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_TABLE_FORMAT
Default | 'rounded-outline'
Value | 'vertical'
Source | COMMANDLINE
***************************[ 9. row ]***************************
ID | cli.time
Spec. | --time / --no-time
Class | click_extra.timer.TimerOption
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_TIME
Default | False
Value | False
Source | DEFAULT
***************************[ 10. row ]***************************
ID | cli.validate_config
Spec. | --validate-config FILE
Class | click_extra.config.ValidateConfigOption
Param type | click.types.Path
Python type | str
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_VALIDATE_CONFIG
Default | Sentinel.UNSET
Value | Sentinel.UNSET
Source | DEFAULT
***************************[ 11. row ]***************************
ID | cli.verbose
Spec. | -v, --verbose
Class | click_extra.logging.VerboseOption
Param type | click.types.IntRange
Python type | int
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_VERBOSE
Default | 0
Value | 0
Source | DEFAULT
***************************[ 12. row ]***************************
ID | cli.verbosity
Spec. | --verbosity LEVEL
Class | click_extra.logging.VerbosityOption
Param type | click_extra.types.EnumChoice
Python type | str
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_VERBOSITY
Default | 'WARNING'
Value | 'WARNING'
Source | DEFAULT
***************************[ 13. row ]***************************
ID | cli.version
Spec. | --version
Class | click_extra.version.ExtraVersionOption
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✘
Env. vars. | CLI_VERSION
Default | False
Value | False
Source | DEFAULT
Caution
Because both options are eager, the order in which they are passed matters. --table-format must be passed before --show-params, otherwise it will have no effect.
Color highlighting¶
By default, the table produced by --show-params is colorized to highlight important bits. If you do not like colors, you can disable them with the --no-color option:
$ cli --no-color --show-params
╭─────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬─────────────────────────────────────────┬──────────────────────────────────┬─────────────┬────────┬─────────┬──────────────────┬─────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────┬─────────────╮
│ ID │ Spec. │ Class │ Param type │ Python type │ Hidden │ Exposed │ Allowed in conf? │ Env. vars. │ Default │ Value │ Source │
├─────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────┼──────────────────────────────────┼─────────────┼────────┼─────────┼──────────────────┼─────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────┤
│ cli.color │ --color, --ansi / --no-color, --no-ansi │ click_extra.colorize.ColorOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_COLOR │ True │ False │ COMMANDLINE │
│ cli.config │ --config CONFIG_PATH │ click_extra.config.ConfigOption │ click.types.UnprocessedParamType │ str │ ✘ │ ✘ │ ✘ │ CLI_CONFIG │ '/home/runner/.config/cli/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,pyproject.toml}' │ '/home/runner/.config/cli/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,pyproject.toml}' │ DEFAULT │
│ cli.config │ --no-config │ click_extra.config.NoConfigOption │ click.types.UnprocessedParamType │ str │ ✘ │ ✘ │ ✘ │ CLI_CONFIG │ Sentinel.UNSET │ Sentinel.UNSET │ DEFAULT │
│ cli.help │ -h, --help │ click.core.Option │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ CLI_HELP │ False │ False │ DEFAULT │
│ cli.int_param1 │ --int-param1 INTEGER │ click_extra.parameters.Option │ click.types.IntParamType │ int │ ✘ │ ✓ │ ✓ │ CLI_INT_PARAM1 │ 10 │ 10 │ DEFAULT │
│ cli.int_param2 │ --int-param2 INTEGER │ click_extra.parameters.Option │ click.types.IntParamType │ int │ ✘ │ ✓ │ ✓ │ CLI_INT_PARAM2 │ 555 │ 555 │ DEFAULT │
│ cli.show_params │ --show-params │ click_extra.parameters.ShowParamsOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ CLI_SHOW_PARAMS │ False │ True │ COMMANDLINE │
│ cli.table_format │ --table-format [aligned|asciidoc|colon-grid|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|hjson|html|jira|json|json5|jsonc|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|toml|tsv|unsafehtml|vertical|xml|yaml|youtrack] │ click_extra.table.TableFormatOption │ click_extra.types.EnumChoice │ str │ ✘ │ ✘ │ ✓ │ CLI_TABLE_FORMAT │ 'rounded-outline' │ 'rounded-outline' │ DEFAULT │
│ cli.time │ --time / --no-time │ click_extra.timer.TimerOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_TIME │ False │ False │ DEFAULT │
│ cli.validate_config │ --validate-config FILE │ click_extra.config.ValidateConfigOption │ click.types.Path │ str │ ✘ │ ✘ │ ✓ │ CLI_VALIDATE_CONFIG │ Sentinel.UNSET │ Sentinel.UNSET │ DEFAULT │
│ cli.verbose │ -v, --verbose │ click_extra.logging.VerboseOption │ click.types.IntRange │ int │ ✘ │ ✘ │ ✓ │ CLI_VERBOSE │ 0 │ 0 │ DEFAULT │
│ cli.verbosity │ --verbosity LEVEL │ click_extra.logging.VerbosityOption │ click_extra.types.EnumChoice │ str │ ✘ │ ✘ │ ✓ │ CLI_VERBOSITY │ 'WARNING' │ 'WARNING' │ DEFAULT │
│ cli.version │ --version │ click_extra.version.ExtraVersionOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ CLI_VERSION │ False │ False │ DEFAULT │
╰─────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴─────────────────────────────────────────┴──────────────────────────────────┴─────────────┴────────┴─────────┴──────────────────┴─────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────┴─────────────╯
Caution
Because both options are eager, the order in which they are passed matters. --no-color must be passed before --show-params, otherwise it will have no effect.
Introspecting parameters¶
If you need to dive deeper into parameters and their values, there is a lot of metadata available in the context. Here are some pointers:
from click import option, echo, pass_context
from click_extra import config_option, group
@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}")
Hint
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 @group and @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:
~/configuration.toml¶[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')}
Parameter structure¶
Todo
Write example and tutorial.
click_extra.parameters API¶
classDiagram
Argument <|-- Argument
ExtraOption <|-- ShowParamsOption
Option <|-- ExtraOption
Option <|-- Option
ParamStructure <|-- ShowParamsOption
_ParameterMixin <|-- Argument
_ParameterMixin <|-- Option
dict <|-- _LazyMetaDict
… py:module:: click_extra.parameters
Our own flavor of Option, Argument and parameters.
… py:function:: search_params(params, klass, include_subclasses=True, unique=True)
- module:
click_extra.parameters
Search a particular class of parameter in a list and return them.
- type params:
:sphinx_autodoc_typehints_type:
\:py\:class\:\~collections.abc.Iterable`\ \[:py:class:`~click.core.Parameter`]`- param params:
list of parameter instances to search in.
- type klass:
:sphinx_autodoc_typehints_type:
\:py\:class\:\type`\ \[:py:class:`~click.core.Parameter`]`- param klass:
the class of the parameters to look for.
- type include_subclasses:
:sphinx_autodoc_typehints_type:
\:py\:class\:\bool``- param include_subclasses:
if
True, includes in the results all parameters subclassing the providedklass. IfFalse, only matches parameters which are strictly instances ofklass. Defaults toTrue.- type unique:
:sphinx_autodoc_typehints_type:
\:py\:class\:\bool``- param unique:
if
True, raise an error if more than one parameter of the providedklassis found. Defaults toTrue.- rtype: