ยถ
ParametersClick 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 @extra_command
decorator come with the --show-params
option, so you can call it right away:
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 --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,ini,xml}' โ '/home/runner/.config/cli/*.{toml,yaml,yml,json,ini,xml}' โ 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 โ cloup._params.Option โ click.types.IntParamType โ int โ โ โ โ โ โ โ CLI_INT_PARAM1 โ 10 โ '3' โ COMMANDLINE โ
โ cli.int_param2 โ --int-param2 INTEGER โ cloup._params.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 [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] โ click_extra.table.TableFormatOption โ click.types.Choice โ 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.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.types.Choice โ str โ โ โ โ โ โ โ CLI_VERBOSITY โ <LogLevel.WARNING: 30> โ <LogLevel.WARNING: 30> โ 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 default of 555
.
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,ini,xml}'
Value | '/home/runner/.config/cli/*.{toml,yaml,yml,json,ini,xml}'
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 | cloup._params.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 | cloup._params.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 [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]
Class | click_extra.table.TableFormatOption
Param type | click.types.Choice
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.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
***************************[ 11. row ]***************************
ID | cli.verbosity
Spec. | --verbosity LEVEL
Class | click_extra.logging.VerbosityOption
Param type | click.types.Choice
Python type | str
Hidden | โ
Exposed | โ
Allowed in conf? | โ
Env. vars. | CLI_VERBOSITY
Default | <LogLevel.WARNING: 30>
Value | <LogLevel.WARNING: 30>
Source | DEFAULT
***************************[ 12. 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,ini,xml}' โ '/home/runner/.config/cli/*.{toml,yaml,yml,json,ini,xml}' โ 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 โ cloup._params.Option โ click.types.IntParamType โ int โ โ โ โ โ โ โ CLI_INT_PARAM1 โ 10 โ 10 โ DEFAULT โ
โ cli.int_param2 โ --int-param2 INTEGER โ cloup._params.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 [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] โ click_extra.table.TableFormatOption โ click.types.Choice โ 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.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.types.Choice โ str โ โ โ โ โ โ โ CLI_VERBOSITY โ <LogLevel.WARNING: 30> โ <LogLevel.WARNING: 30> โ 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, 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:
~/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 ExtraOption <|-- ShowParamsOption Option <|-- ExtraOption ParamStructure <|-- ShowParamsOption
Our own flavor of Option
, Argument
and parameters
.
- click_extra.parameters.search_params(params, klass, include_subclasses=True, 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.include_subclasses (
bool
) โ ifTrue
, includes in the results all parameters subclassing the providedklass
. IfFalse
, only matches parameters which are strictly instances ofklass
. Defaults toTrue
.unique (
bool
) โ ifTrue
, raise an error if more than one parameter of the providedklass
is found. Defaults toTrue
.
- Return type:
- 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.
- 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 cachedself.excluded_params
property to compute the default value on first use.- 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 ofleaf
.- Return type:
- static get_tree_value(tree_dict, *path)[source]ยถ
Get in the
tree_dict
the value located at thepath
.Raises
KeyError
if no item is found at the providedpath
.- Return type:
- flatten_tree_dict(tree_dict, parent_key=None)[source]ยถ
Recursively traverse the tree-like
dict
and produce a flatdict
whose keys are path and values are the leafโs content.
- 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.
- 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.BoolParamType'>: <class 'bool'>, <class 'click.types.Choice'>: <class 'str'>, <class 'click.types.DateTime'>: <class 'str'>, <class 'click.types.File'>: <class 'str'>, <class 'click.types.FloatParamType'>: <class 'float'>, <class 'click.types.FloatRange'>: <class 'float'>, <class 'click.types.IntParamType'>: <class 'int'>, <class 'click.types.IntRange'>: <class 'int'>, <class 'click.types.Path'>: <class 'str'>, <class 'click.types.StringParamType'>: <class 'str'>, <class 'click.types.Tuple'>: <class 'list'>, <class 'click.types.UUIDParameterType'>: <class 'str'>, <class 'click.types.UnprocessedParamType'>: <class 'str'>}ยถ 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.
- 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. Which is the dot-separated ID that is prefixed by the CLI name, featured in the first column of the table.
Defaults to:
--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.
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:
- 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.
- 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 cachedself.excluded_params
property to compute the default value on first use.- TABLE_HEADERS = ('ID', 'Spec.', 'Class', 'Param type', 'Python type', 'Hidden', 'Exposed', 'Allowed in conf?', 'Env. vars.', 'Default', 'Value', 'Source')ยถ
Hard-coded list of table headers.
- is_flag: boolยถ
- is_bool_flag: boolยถ
- flag_value: t.Anyยถ
- name: str | Noneยถ
- opts: list[str]ยถ
- secondary_opts: list[str]ยถ
- type: types.ParamTypeยถ
- print_params(ctx, param, value)[source]ยถ
Introspects current CLI and list its parameters and metadata.
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 aclick_extra.raw_args
metadata entry to the context.- Return type: