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 adds a --show-params flag to every @command and @group. It dumps a colorized table of every parameter, its current value, where that value came from, the resolved environment variable, and the default:
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 │ Is flag │ Flag value │ Is bool flag │ Multiple │ Nargs │ Prompt │ Confirmation prompt │ Value │ Source │
├─────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼────────────────────────────────────────────────┼───────────────────────────────────┼─────────────┼────────┼─────────┼──────────────────┼─────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────┼────────────────────┼──────────────┼──────────┼───────┼────────┼─────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────┤
│ cli.accessible │ --accessible │ click_extra.accessibility.AccessibleOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_ACCESSIBLE │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ cli.color │ --color [auto|always|never] │ click_extra.color.ColorOption │ click_extra.color.ColorWhenChoice │ str │ ✘ │ ✘ │ ✓ │ CLI_COLOR │ 'auto' │ ✘ │ 'always' │ ✘ │ ✘ │ 1 │ │ ✘ │ 'auto' │ DEFAULT │
│ cli.config │ --config CONFIG_PATH │ click_extra.config.option.ConfigOption │ click.types.UnprocessedParamType │ str │ ✘ │ ✘ │ ✘ │ CLI_CONFIG │ '/home/runner/.config/cli/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,pyproject.toml}' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ '/home/runner/.config/cli/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,pyproject.toml}' │ DEFAULT │
│ cli.config │ --no-config │ click_extra.config.option.NoConfigOption │ click.types.UnprocessedParamType │ str │ ✘ │ ✘ │ ✘ │ CLI_CONFIG │ None │ ✓ │ Sentinel.NO_CONFIG │ ✘ │ ✘ │ 1 │ │ ✘ │ None │ DEFAULT │
│ cli.help │ -h, --help │ click.core.Option │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ CLI_HELP │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ cli.int_param1 │ --int-param1 INTEGER │ click_extra.parameters.Option │ click.types.IntParamType │ int │ ✘ │ ✓ │ ✓ │ CLI_INT_PARAM1 │ 10 │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ '3' │ COMMANDLINE │
│ cli.int_param2 │ --int-param2 INTEGER │ click_extra.parameters.Option │ click.types.IntParamType │ int │ ✘ │ ✓ │ ✓ │ CLI_INT_PARAM2 │ 555 │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 555 │ DEFAULT │
│ cli.man │ --man │ click_extra.man_page.ManOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_MAN │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ cli.no_color │ --no-color │ click_extra.color.NoColorOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_NO_COLOR │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ cli.progress │ --progress / --no-progress │ click_extra.spinner.ProgressOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_PROGRESS │ True │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ True │ DEFAULT │
│ cli.quiet │ -q, --quiet │ click_extra.logging.QuietOption │ click.types.IntRange │ int │ ✘ │ ✘ │ ✓ │ CLI_QUIET │ 0 │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 0 │ DEFAULT │
│ cli.show_params │ --show-params │ click_extra.parameters.ShowParamsOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ CLI_SHOW_PARAMS │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ 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' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 'rounded-outline' │ DEFAULT │
│ cli.theme │ --theme [dark|dracula|light|manpage|monokai|nord|solarized_dark] │ click_extra.theme.ThemeOption │ click_extra.theme.ThemeChoice │ str │ ✘ │ ✘ │ ✓ │ CLI_THEME │ 'dark' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 'dark' │ DEFAULT │
│ cli.time │ --time / --no-time │ click_extra.execution.TimerOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_TIME │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ cli.validate_config │ --validate-config FILE │ click_extra.config.option.ValidateConfigOption │ click.types.Path │ str │ ✘ │ ✘ │ ✓ │ CLI_VALIDATE_CONFIG │ None │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ None │ DEFAULT │
│ cli.verbose │ -v, --verbose │ click_extra.logging.VerboseOption │ click.types.IntRange │ int │ ✘ │ ✘ │ ✓ │ CLI_VERBOSE │ 0 │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 0 │ DEFAULT │
│ cli.verbosity │ --verbosity LEVEL │ click_extra.logging.VerbosityOption │ click_extra.types.EnumChoice │ str │ ✘ │ ✘ │ ✓ │ CLI_VERBOSITY │ 'WARNING' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 'WARNING' │ DEFAULT │
│ cli.version │ --version │ click_extra.version.VersionOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ CLI_VERSION │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
╰─────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────────┴───────────────────────────────────┴─────────────┴────────┴─────────┴──────────────────┴─────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────┴─────────┴────────────────────┴──────────────┴──────────┴───────┴────────┴─────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────┴─────────────╯
--int-param1 shows 3 because it was passed on the command line. --int-param2 falls back to its 555 default. The --show-params option produces this table dynamically: every value is re-evaluated at invocation time from the current argv, environment, and config files.
Tip
Every command built with @command or @group captures the pre-parsed argv slice on ctx.meta as RAW_ARGS, which --show-params itself relies on to re-parse the original arguments. See the available keys table to read it from your own callbacks.
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.
Available columns¶
Each row in the table mirrors a single click.Parameter instance. The columns map to its public attributes (plus a handful of Click Extra-specific fields). The table below is auto-generated at build time from ShowParamsOption.TABLE_HEADERS: edit the ColumnSpec.description entries in click_extra/parameters.py to update it.
Column |
Description |
|---|---|
|
Fully-qualified parameter path ( |
|
Option/argument specification string (like |
|
Fully-qualified class of the parameter: a subclass of |
|
Click value converter class: a subclass of |
|
Python built-in type the parsed value resolves to: |
|
Reflects |
|
Reflects |
|
Click Extra-specific: whether the parameter is reachable from a configuration file. Controlled by |
|
Environment variables read for this parameter: the explicit |
|
Default value returned by |
|
Reflects |
|
Reflects |
|
Reflects |
|
Reflects |
|
Reflects |
|
Reflects |
|
Reflects |
|
Current value of the parameter at invocation time, computed by |
|
Provenance of the resolved value: a |
Columns selection¶
Add Click Extra’s columns_option to your CLI so users can pick which columns --show-params emits, in the order they want, SQL SELECT-style:
$ cli-with-columns --no-color --columns id,is_flag,default,value --show-params
╭──────────────────────────────────┬─────────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ID │ Is flag │ Default │ Value │
├──────────────────────────────────┼─────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ cli-with-columns.accessible │ ✓ │ False │ False │
│ cli-with-columns.color │ ✘ │ 'auto' │ 'auto' │
│ cli-with-columns.columns │ ✘ │ () │ 'id,is_flag,default,value' │
│ cli-with-columns.config │ ✘ │ '/home/runner/.config/cli-with-columns/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,pyproject.toml}' │ '/home/runner/.config/cli-with-columns/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,pyproject.toml}' │
│ cli-with-columns.config │ ✓ │ None │ None │
│ cli-with-columns.help │ ✓ │ False │ False │
│ cli-with-columns.int_param1 │ ✘ │ 10 │ 10 │
│ cli-with-columns.int_param2 │ ✘ │ 555 │ 555 │
│ cli-with-columns.man │ ✓ │ False │ False │
│ cli-with-columns.no_color │ ✓ │ False │ True │
│ cli-with-columns.progress │ ✓ │ True │ True │
│ cli-with-columns.quiet │ ✘ │ 0 │ 0 │
│ cli-with-columns.show_params │ ✓ │ False │ True │
│ cli-with-columns.table_format │ ✘ │ 'rounded-outline' │ 'rounded-outline' │
│ cli-with-columns.theme │ ✘ │ 'dark' │ 'dark' │
│ cli-with-columns.time │ ✓ │ False │ False │
│ cli-with-columns.validate_config │ ✘ │ None │ None │
│ cli-with-columns.verbose │ ✘ │ 0 │ 0 │
│ cli-with-columns.verbosity │ ✘ │ 'WARNING' │ 'WARNING' │
│ cli-with-columns.version │ ✓ │ False │ False │
╰──────────────────────────────────┴─────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Unknown IDs raise a BadParameter listing the valid ones (--columns is built on top of the generic MultiChoice type, which does the validation at parse time). The standalone click-extra wrap --show-params exposes the same option for inspecting third-party CLIs.
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.accessible
Spec. | --accessible
Class | click_extra.accessibility.AccessibleOption
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_ACCESSIBLE
Default | False
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | False
Source | DEFAULT
***************************[ 2. row ]***************************
ID | cli.color
Spec. | --color [auto|always|never]
Class | click_extra.color.ColorOption
Param type | click_extra.color.ColorWhenChoice
Python type | str
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_COLOR
Default | 'auto'
Is flag | ✘
Flag value | 'always'
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | 'auto'
Source | DEFAULT
***************************[ 3. row ]***************************
ID | cli.config
Spec. | --config CONFIG_PATH
Class | click_extra.config.option.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}'
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | '/home/runner/.config/cli/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,pyproject.toml}'
Source | DEFAULT
***************************[ 4. row ]***************************
ID | cli.config
Spec. | --no-config
Class | click_extra.config.option.NoConfigOption
Param type | click.types.UnprocessedParamType
Python type | str
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✘
Env. vars. | CLI_CONFIG
Default | None
Is flag | ✓
Flag value | Sentinel.NO_CONFIG
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source | DEFAULT
***************************[ 5. 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
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | False
Source | DEFAULT
***************************[ 6. 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
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | 10
Source | DEFAULT
***************************[ 7. 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
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | 555
Source | DEFAULT
***************************[ 8. row ]***************************
ID | cli.man
Spec. | --man
Class | click_extra.man_page.ManOption
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_MAN
Default | False
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | False
Source | DEFAULT
***************************[ 9. row ]***************************
ID | cli.no_color
Spec. | --no-color
Class | click_extra.color.NoColorOption
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_NO_COLOR
Default | False
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | False
Source | DEFAULT
***************************[ 10. row ]***************************
ID | cli.progress
Spec. | --progress / --no-progress
Class | click_extra.spinner.ProgressOption
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_PROGRESS
Default | True
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | True
Source | DEFAULT
***************************[ 11. row ]***************************
ID | cli.quiet
Spec. | -q, --quiet
Class | click_extra.logging.QuietOption
Param type | click.types.IntRange
Python type | int
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_QUIET
Default | 0
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | 0
Source | DEFAULT
***************************[ 12. 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
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | True
Source | COMMANDLINE
***************************[ 13. 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'
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | 'vertical'
Source | COMMANDLINE
***************************[ 14. row ]***************************
ID | cli.theme
Spec. | --theme [dark|dracula|light|manpage|monokai|nord|solarized_dark]
Class | click_extra.theme.ThemeOption
Param type | click_extra.theme.ThemeChoice
Python type | str
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_THEME
Default | 'dark'
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | 'dark'
Source | DEFAULT
***************************[ 15. row ]***************************
ID | cli.time
Spec. | --time / --no-time
Class | click_extra.execution.TimerOption
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_TIME
Default | False
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | False
Source | DEFAULT
***************************[ 16. row ]***************************
ID | cli.validate_config
Spec. | --validate-config FILE
Class | click_extra.config.option.ValidateConfigOption
Param type | click.types.Path
Python type | str
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✓
Env. vars. | CLI_VALIDATE_CONFIG
Default | None
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source | DEFAULT
***************************[ 17. 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
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | 0
Source | DEFAULT
***************************[ 18. 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'
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | 'WARNING'
Source | DEFAULT
***************************[ 19. row ]***************************
ID | cli.version
Spec. | --version
Class | click_extra.version.VersionOption
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Allowed in conf? | ✘
Env. vars. | CLI_VERSION
Default | False
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
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 │ Is flag │ Flag value │ Is bool flag │ Multiple │ Nargs │ Prompt │ Confirmation prompt │ Value │ Source │
├─────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼────────────────────────────────────────────────┼───────────────────────────────────┼─────────────┼────────┼─────────┼──────────────────┼─────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────┼────────────────────┼──────────────┼──────────┼───────┼────────┼─────────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────┤
│ cli.accessible │ --accessible │ click_extra.accessibility.AccessibleOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_ACCESSIBLE │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ cli.color │ --color [auto|always|never] │ click_extra.color.ColorOption │ click_extra.color.ColorWhenChoice │ str │ ✘ │ ✘ │ ✓ │ CLI_COLOR │ 'auto' │ ✘ │ 'always' │ ✘ │ ✘ │ 1 │ │ ✘ │ 'auto' │ DEFAULT │
│ cli.config │ --config CONFIG_PATH │ click_extra.config.option.ConfigOption │ click.types.UnprocessedParamType │ str │ ✘ │ ✘ │ ✘ │ CLI_CONFIG │ '/home/runner/.config/cli/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,pyproject.toml}' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ '/home/runner/.config/cli/{*.toml,*.yaml,*.yml,*.json,*.json5,*.jsonc,*.hjson,*.ini,*.xml,pyproject.toml}' │ DEFAULT │
│ cli.config │ --no-config │ click_extra.config.option.NoConfigOption │ click.types.UnprocessedParamType │ str │ ✘ │ ✘ │ ✘ │ CLI_CONFIG │ None │ ✓ │ Sentinel.NO_CONFIG │ ✘ │ ✘ │ 1 │ │ ✘ │ None │ DEFAULT │
│ cli.help │ -h, --help │ click.core.Option │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ CLI_HELP │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ cli.int_param1 │ --int-param1 INTEGER │ click_extra.parameters.Option │ click.types.IntParamType │ int │ ✘ │ ✓ │ ✓ │ CLI_INT_PARAM1 │ 10 │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 10 │ DEFAULT │
│ cli.int_param2 │ --int-param2 INTEGER │ click_extra.parameters.Option │ click.types.IntParamType │ int │ ✘ │ ✓ │ ✓ │ CLI_INT_PARAM2 │ 555 │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 555 │ DEFAULT │
│ cli.man │ --man │ click_extra.man_page.ManOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_MAN │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ cli.no_color │ --no-color │ click_extra.color.NoColorOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_NO_COLOR │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ True │ COMMANDLINE │
│ cli.progress │ --progress / --no-progress │ click_extra.spinner.ProgressOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_PROGRESS │ True │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ True │ DEFAULT │
│ cli.quiet │ -q, --quiet │ click_extra.logging.QuietOption │ click.types.IntRange │ int │ ✘ │ ✘ │ ✓ │ CLI_QUIET │ 0 │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 0 │ DEFAULT │
│ cli.show_params │ --show-params │ click_extra.parameters.ShowParamsOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ CLI_SHOW_PARAMS │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ 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' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 'rounded-outline' │ DEFAULT │
│ cli.theme │ --theme [dark|dracula|light|manpage|monokai|nord|solarized_dark] │ click_extra.theme.ThemeOption │ click_extra.theme.ThemeChoice │ str │ ✘ │ ✘ │ ✓ │ CLI_THEME │ 'dark' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 'dark' │ DEFAULT │
│ cli.time │ --time / --no-time │ click_extra.execution.TimerOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✓ │ CLI_TIME │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ False │ DEFAULT │
│ cli.validate_config │ --validate-config FILE │ click_extra.config.option.ValidateConfigOption │ click.types.Path │ str │ ✘ │ ✘ │ ✓ │ CLI_VALIDATE_CONFIG │ None │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ None │ DEFAULT │
│ cli.verbose │ -v, --verbose │ click_extra.logging.VerboseOption │ click.types.IntRange │ int │ ✘ │ ✘ │ ✓ │ CLI_VERBOSE │ 0 │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 0 │ DEFAULT │
│ cli.verbosity │ --verbosity LEVEL │ click_extra.logging.VerbosityOption │ click_extra.types.EnumChoice │ str │ ✘ │ ✘ │ ✓ │ CLI_VERBOSITY │ 'WARNING' │ ✘ │ │ ✘ │ ✘ │ 1 │ │ ✘ │ 'WARNING' │ DEFAULT │
│ cli.version │ --version │ click_extra.version.VersionOption │ click.types.BoolParamType │ bool │ ✘ │ ✘ │ ✘ │ CLI_VERSION │ False │ ✓ │ True │ ✓ │ ✘ │ 1 │ │ ✘ │ 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.
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')}
Introspecting external CLIs¶
The --show-params option works on your own Click Extra CLIs. To inspect a third-party CLI that doesn’t use Click Extra, use wrap --show-params, which loads the target and prints the same table without running it:
$ wrap --show-params --table-format vertical flask run
***************************[ 1. row ]***************************
ID | run.cert
Spec. | --cert PATH
Class | click.core.Option
Param type | flask.cli.CertParamType
Python type | str
Hidden | ✘
Exposed | ✓
Env. vars. | FLASK_RUN_CERT
Default | None
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
***************************[ 2. row ]***************************
ID | run.debug
Spec. | --debug / --no-debug
Class | click.core.Option
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Env. vars. | FLASK_RUN_DEBUG
Default | False
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
***************************[ 3. row ]***************************
ID | run.debugger
Spec. | --debugger / --no-debugger
Class | click.core.Option
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✓
Env. vars. | FLASK_RUN_DEBUGGER
Default | None
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
***************************[ 4. row ]***************************
ID | run.exclude_patterns
Spec. | --exclude-patterns PATH
Class | click.core.Option
Param type | flask.cli.SeparatedPathType
Python type | str
Hidden | ✘
Exposed | ✓
Env. vars. | FLASK_RUN_EXCLUDE_PATTERNS
Default | None
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
***************************[ 5. row ]***************************
ID | run.extra_files
Spec. | --extra-files PATH
Class | click.core.Option
Param type | flask.cli.SeparatedPathType
Python type | str
Hidden | ✘
Exposed | ✓
Env. vars. | FLASK_RUN_EXTRA_FILES
Default | None
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
***************************[ 6. row ]***************************
ID | run.help
Spec. | --help
Class | click.core.Option
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✘
Env. vars. | FLASK_RUN_HELP
Default | False
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
***************************[ 7. row ]***************************
ID | run.host
Spec. | -h, --host TEXT
Class | click.core.Option
Param type | click.types.StringParamType
Python type | str
Hidden | ✘
Exposed | ✓
Env. vars. | FLASK_RUN_HOST
Default | '127.0.0.1'
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
***************************[ 8. row ]***************************
ID | run.key
Spec. | --key FILE
Class | click.core.Option
Param type | click.types.Path
Python type | str
Hidden | ✘
Exposed | ✘
Env. vars. | FLASK_RUN_KEY
Default | None
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
***************************[ 9. row ]***************************
ID | run.port
Spec. | -p, --port INTEGER
Class | click.core.Option
Param type | click.types.IntParamType
Python type | int
Hidden | ✘
Exposed | ✓
Env. vars. | FLASK_RUN_PORT
Default | 5000
Is flag | ✘
Flag value |
Is bool flag | ✘
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
***************************[ 10. row ]***************************
ID | run.reload
Spec. | --reload / --no-reload
Class | click.core.Option
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✓
Env. vars. | FLASK_RUN_RELOAD
Default | None
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
***************************[ 11. row ]***************************
ID | run.with_threads
Spec. | --with-threads / --without-threads
Class | click.core.Option
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Exposed | ✓
Env. vars. | FLASK_RUN_WITH_THREADS
Default | True
Is flag | ✓
Flag value | True
Is bool flag | ✓
Multiple | ✘
Nargs | 1
Prompt |
Confirmation prompt | ✘
Value | None
Source |
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
Our own flavor of Option, Argument and parameters.
- click_extra.parameters.PARAM_PATH_SEP = '.'¶
Separator joining the keys of a parameter’s fully-qualified path (
cli.subcommand.param).
- 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 providedklassis found. Defaults toTrue.
- Return type:
- class click_extra.parameters.Argument(*args, help=None, **attrs)[source]¶
Bases:
_ParameterMixin,ArgumentWrap
cloup.Argument, itself inheriting fromclick.Argument.Inherits first from
_ParameterMixinto allow future overrides of Click’sParametermethods.
- class click_extra.parameters.Option(*args, group=None, **attrs)[source]¶
Bases:
_ParameterMixin,OptionWrap
cloup.Option, itself inheriting fromclick.Option.Inherits first from
_ParameterMixinto allow future overrides of Click’sParametermethods.
- class click_extra.parameters.ExtraOption(*args, group=None, **attrs)[source]¶
Bases:
OptionDedicated to option implemented by
click-extraitself.Provides a way to identify Click Extra’s own options with certainty, and restores the pre-Click-8.4.0 contract that eager callbacks can introspect their own parameter source from within their own callback.
Note
This is the one click-extra class that deliberately keeps the
Extraprefix. The8.0.0cleanup dropped it everywhere else (ExtraCommandbecameCommand,ExtraContextbecameContext, and so on), shadowing the matching Cloup or Click class. Here the plainOptionname is already taken by the user-facing enhanced wrapper this class subclasses, so the prefix is not legacy baggage but a real distinction:ExtraOptionmarks click-extra’s own built-in options. That marker is load-bearing, sinceCommandsorts parameters withisinstance(param, ExtraOption)to push the built-in options to the end.Note
Bracket fields (envvar, default, range, required) cannot be pre-styled in
get_help_record()because Click’s text wrapper splits lines after the record is returned, which would break ANSI codes that span wrapped boundaries. Styling is instead applied post-wrapping inHelpFormatter._style_bracket_fields(), which uses the structured data fromOption.get_help_extra()to identify each field by its label.Note
Built-in option subclasses share a common shape: their
__init__defaultsparam_declsto the option’s canonical flags and wires an eager callback viakwargs.setdefault("callback", self.<callback>). Every callback name encodes its role with a verb prefix. The common roles are:set_<key>publishes a resolved value toctx.meta(set_color,set_no_color,set_theme,set_telemetry,set_progress,set_accessible,set_zero_exit, the verbosity options’set_level);init_<system>additionally installs actxhelper or records a snapshot (init_timer,init_formatter,init_columns,init_sort);validate_<thing>coerces and validates the raw input (validate_jobs,validate_config);print_*renders output and exits (print_man,print_params,print_and_exit).
A few options own a richer operation and name it with its own verb rather than forcing one of the above.
ConfigOptionwiresload_confto read, parse, and merge a configuration file, andNoConfigOptionwirescheck_sibling_config_optionto assert that a sibling--configoption exists.- handle_parse_result(ctx, opts, args)[source]¶
Record the parameter source before delegating to the base implementation.
Warning
Click
8.4.0(PR pallets/click#3404) reorderedParameter.handle_parse_resultsoctx.set_parameter_sourceruns afterprocess_value. Eager callbacks that introspect their own provenance viactx.get_parameter_source(self.name)therefore readNoneinstead of the actual source.ColorOption,ConfigOption, andShowParamsOptionall rely on this introspection to decide whether an env var should override the default (--color), whether the--configpath was user-supplied, and what to render in theSourcecolumn of--show-params.Click
8.4.1restored the pre-8.4.0contract upstream (PR pallets/click#3484), so this override only matters for Click8.4.0itself, which sits inside click-extra’s supported>= 8.3.1range. Pre-recording the source here for eager options keeps that contract on every supported Click.super().handle_parse_resultre-records the same value at the canonical time, so the slot arbitration logic introduced by #3404 is unaffected:slot_emptyis computed fromctx.params, not from_parameter_source.consume_valueruns twice as a side effect: once here and once insuper. Both calls are pure for click-extra’s existing eager flag-style options (no env var side effects, no prompt). Should a future eager subclass need prompt behavior, this override would need to cache the result instead.The pre-record is skipped when the slot already carries a source from an earlier option sharing the same
name(Click’s feature-switch pattern), so the arbitration logic insuperstill sees the originalexisting_sourcerather than a stale rewrite from this option.
- class click_extra.parameters.ParamStructure[source]¶
Bases:
objectUtilities 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
..- excluded_params: frozenset[str]¶
Fully-qualified IDs of the parameters to block from the structure.
Set by subclasses:
ShowParamsOptionfreezes an empty set, whileConfigOptionresolves a dynamic default (or the user-provided list) within the active context. The two filters are mutually exclusive, a constraint each subclass enforces in its own constructor.
- included_params: frozenset[str] | None¶
Allowlist of parameter IDs, mutually exclusive with
excluded_params.Nonedisables the allowlist. It is resolved intoexcluded_paramsbybuild_param_trees(), once every parameter ID is known.
- static init_tree_dict(*path, leaf=None)[source]¶
Utility method to recursively create a nested dict structure whose keys are provided by
pathlist and at the end is populated by a copy ofleaf.- Return type:
- static get_tree_value(tree_dict, *path)[source]¶
Get in the
tree_dictthe value located at thepath.Raises
KeyErrorif no item is found at the providedpath.- Return type:
- walk_params()[source]¶
Generate an unfiltered list of all CLI parameters.
Everything is included, from top-level groups to subcommands, and from options to arguments.
- Yields a 2-element tuple:
a tuple of keys leading to the parameter;
the parameter object itself.
Thin adapter over
walk_command_params(): it resolves the root CLI from the active context and drops the per-parameter context that the free function also yields.
- TYPE_MAP: ClassVar[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.
- static get_param_type(param)[source]¶
Get the Python type of a Click parameter.
Returns
strfor unrecognised custom types, since command-line parameters are strings by default.See the list of custom types provided by Click.
- build_param_trees()[source]¶
Build the parameters tree structure and cache it.
This removes parameters whose fully-qualified IDs are in the
excluded_paramsblocklist.If
included_paramswas provided, it is resolved intoexcluded_paramshere, where all parameter IDs are available.- Return type:
- click_extra.parameters.get_param_spec(param, ctx)[source]¶
Extract the option-spec string (like
-v, --verbose) from a parameter.Temporarily unhides hidden options so their help record can be produced.
Note
The
hiddenproperty is only supported byOption, notArgument.Todo
Submit a PR to Click to separate production of param spec and help record. That way we can always produce the param spec even if the parameter is hidden. See: https://github.com/kdeldycke/click-extra/issues/689
- click_extra.parameters.format_param_row(param, ctx, path, is_structured)[source]¶
Compute the structural table cells for a Click parameter.
Returns a
dict[column_id, cell]covering every column that can be derived from the parameter object alone (no runtime invocation state or config-file context). Specifically:id,spec,class,param_type,python_type,hidden,exposed,envvars,default,is_flag,flag_value,is_bool_flag,multiple,nargs,prompt, andconfirmation_prompt.Attributes only defined on
click.Option(hidden,is_flag,flag_value,is_bool_flag,prompt,confirmation_prompt) yieldNoneforclick.Argumentparameters: empty cell in visual formats,nullin structured ones.For structured formats (JSON, YAML, etc.), values are native Python types. For visual formats, values are themed strings matching help-screen styling.
The remaining table columns (
allowed_in_conf,value,source) require live context and are filled in byrender_params_table().
- click_extra.parameters.walk_command_params(cmd, ctx, parent_keys=())[source]¶
Walk the parameter tree of a Click command and all its subcommands.
Yields
(path_keys, param, owning_ctx)for every parameter found on cmd and, recursively, on each subcommand. Each subcommand is walked under its own freshly-built child context, so context-sensitive metadata (notably the auto-generated environment variable, which derives fromContext.auto_envvar_prefix) is computed at the correct nesting level rather than inherited from the root.A subcommand whose name collides with a sibling parameter at the same level is skipped: a single fully-qualified path cannot address both an option and a subcommand at once.
- click_extra.parameters.render_params_table(subject_ctx, *, default_columns=None)[source]¶
Introspect
subject_ctx.commandand print its parameter metadata table.Walks the command and any nested subcommands, emitting one row per parameter. The table format and column selection are read from
subject_ctx.meta(seeTABLE_FORMATandCOLUMNS); when neither is set, a sibling--table-format/--columnsoption on the command is consulted, then the default_columns fallback, then the canonical order.When
subject_ctx.metacarries pre-parsedRAW_ARGS, thevalueandsourcecolumns are resolved by replaying those arguments against the command parser; otherwise they fall back to the parameter defaults.This is the shared rendering core behind both
ShowParamsOption.print_params()(introspecting the live CLI) and theclick-extra wrap --show-paramspath (introspecting a foreign target). The caller is responsible for exiting the context afterwards.Important
Click does not keep the raw, pre-parsed arguments around, so values and their provenance cannot be read back directly. The workaround replays
RAW_ARGS(captured on the context byCommand/Group) through the command parser, callingconsume_value()rather thanhandle_parse_result()so eager callbacks are not re-triggered.- Return type:
- 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,ParamStructureA pre-configured option adding a
--show-paramsoption.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.
- TABLE_HEADERS: ClassVar[tuple[_ColumnSpec, ...]] = (ColumnSpec(id='id', label='ID', description='Fully-qualified parameter path (`cli.subcommand.param-name`) derived from the [`click.Command`](https://click.palletsprojects.com/en/stable/api/#click.Command) tree. Doubles as the key used to address the parameter from a configuration file.'), ColumnSpec(id='spec', label='Spec.', description='Option/argument specification string (like `-v, --verbose`) extracted from [`click.Parameter.get_help_record()`](https://click.palletsprojects.com/en/stable/api/#click.Parameter.get_help_record).'), ColumnSpec(id='class', label='Class', description="Fully-qualified class of the parameter: a subclass of [`click.Option`](https://click.palletsprojects.com/en/stable/api/#click.Option), [`click.Argument`](https://click.palletsprojects.com/en/stable/api/#click.Argument), [`cloup.Option`](https://cloup.readthedocs.io/en/stable/autoapi/cloup/index.html#cloup.Option), or one of Click Extra's own wrappers ([`click_extra.parameters.Option`](#click_extra.parameters.Option), [`click_extra.parameters.Argument`](#click_extra.parameters.Argument), [`click_extra.parameters.ExtraOption`](#click_extra.parameters.ExtraOption))."), ColumnSpec(id='param_type', label='Param type', description='Click value converter class: a subclass of [`click.ParamType`](https://click.palletsprojects.com/en/stable/api/#click.ParamType) like [`click.IntRange`](https://click.palletsprojects.com/en/stable/api/#click.IntRange), [`click.Choice`](https://click.palletsprojects.com/en/stable/api/#click.Choice), or a Click Extra type.'), ColumnSpec(id='python_type', label='Python type', description='Python built-in type the parsed value resolves to: [`str`](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), [`int`](https://docs.python.org/3/library/functions.html#int), [`float`](https://docs.python.org/3/library/functions.html#float), [`bool`](https://docs.python.org/3/library/functions.html#bool), or [`list`](https://docs.python.org/3/library/stdtypes.html#list). Computed by [`ParamStructure.get_param_type()`](#click_extra.parameters.ParamStructure.get_param_type) from the Click `Param type`.'), ColumnSpec(id='hidden', label='Hidden', description="Reflects [`click.Option`'s `hidden`](https://click.palletsprojects.com/en/stable/api/#click.Option) constructor argument: the option is omitted from `--help` output. Empty for [`click.Argument`](https://click.palletsprojects.com/en/stable/api/#click.Argument), which does not support hiding."), ColumnSpec(id='exposed', label='Exposed', description="Reflects [`click.Parameter`'s `expose_value`](https://click.palletsprojects.com/en/stable/api/#click.Parameter) constructor argument: whether the parsed value is forwarded to the command callback. Eager options like `--show-params` and `--help` typically run a callback and exit, so they are not exposed."), ColumnSpec(id='allowed_in_conf', label='Allowed in conf?', description='Click Extra-specific: whether the parameter is reachable from a configuration file. Controlled by [`ParamStructure.excluded_params`](#click_extra.parameters.ParamStructure.excluded_params) and [`included_params`](#click_extra.parameters.ParamStructure.included_params). Empty when the CLI has no [`--config` option](config.md).'), ColumnSpec(id='envvars', label='Env. vars.', description="Environment variables read for this parameter: the explicit [`click.Parameter`'s `envvar`](https://click.palletsprojects.com/en/stable/api/#click.Parameter) plus the auto-resolved IDs documented in [Environment variables](envvar.md)."), ColumnSpec(id='default', label='Default', description='Default value returned by [`click.Parameter.get_default()`](https://click.palletsprojects.com/en/stable/api/#click.Parameter.get_default), rendered as its Python `repr()`.'), ColumnSpec(id='is_flag', label='Is flag', description="Reflects [`click.Option`'s `is_flag`](https://click.palletsprojects.com/en/stable/api/#click.Option): whether the option behaves as a flag (no value taken from the command line). Empty for [`click.Argument`](https://click.palletsprojects.com/en/stable/api/#click.Argument)."), ColumnSpec(id='flag_value', label='Flag value', description="Reflects [`click.Option`'s `flag_value`](https://click.palletsprojects.com/en/stable/api/#click.Option): the Python value substituted for the option when its flag is used. Defaults to `True` for boolean flags, can be any value for flag-value style options (like `@option('--upper', 'transform', flag_value='upper')`)."), ColumnSpec(id='is_bool_flag', label='Is bool flag', description='Reflects `click.Option.is_bool_flag` (set internally by Click when `flag_value` is `True` or `False`): the option is a *true* boolean flag, as opposed to a flag-value style option.'), ColumnSpec(id='multiple', label='Multiple', description="Reflects [`click.Parameter`'s `multiple`](https://click.palletsprojects.com/en/stable/api/#click.Parameter): the parameter can be repeated on the command line, collecting values into a tuple."), ColumnSpec(id='nargs', label='Nargs', description="Reflects [`click.Parameter`'s `nargs`](https://click.palletsprojects.com/en/stable/api/#click.Parameter): the number of CLI tokens the parameter consumes. `1` is the default; `-1` denotes a variadic argument."), ColumnSpec(id='prompt', label='Prompt', description="Reflects [`click.Option`'s `prompt`](https://click.palletsprojects.com/en/stable/api/#click.Option): the text shown to the user when the option is not provided on the command line. Empty when no prompt is configured."), ColumnSpec(id='confirmation_prompt', label='Confirmation prompt', description="Reflects [`click.Option`'s `confirmation_prompt`](https://click.palletsprojects.com/en/stable/api/#click.Option): whether the user is asked to enter the value twice for confirmation."), ColumnSpec(id='value', label='Value', description='Current value of the parameter at invocation time, computed by [`click.Parameter.consume_value()`](https://click.palletsprojects.com/en/stable/api/#click.Parameter) from the merged sources (CLI, environment, config file, default).'), ColumnSpec(id='source', label='Source', description='Provenance of the resolved value: a [`click.core.ParameterSource`](https://click.palletsprojects.com/en/stable/api/#click.core.ParameterSource) enum member such as `COMMANDLINE`, `ENVIRONMENT`, `DEFAULT_MAP`, or `DEFAULT`.'))¶
Rich column registry for the
--show-paramstable.Each entry is a
click_extra.table.ColumnSpeccarrying the column’s stableid(used by--columnsand as structured-format key), its displaylabel, and a MyST/Markdowndescriptionconsumed by the documentation’s auto-generated Available columns section. Iteration yields columns in canonical display order.
- classmethod column_labels()[source]¶
Return just the display labels of
TABLE_HEADERS(in order).
- classmethod column_ids()[source]¶
Return just the stable IDs of
TABLE_HEADERS(in order).
- classmethod find_column(column_id)[source]¶
Return the
ColumnSpecmatchingcolumn_id.Raises
KeyErrorif no column has this ID; callers should convert the error into aclick.UsageErrorwhen surfaced to a user.
- classmethod render_doc_table()[source]¶
Render
TABLE_HEADERSas a Markdown table for documentation.Used by the
show_params_columns_tableMyST substitution indocs/conf.pyto feed the Available columns section ofdocs/parameters.md: editing a description here automatically rebuilds the docs table on the nextsphinx-build.- Return type:
- excluded_params¶
Deactivates the blocking of any parameter.
- included_params¶
No allowlist filter; show all parameters.
- print_params(ctx, param, value)[source]¶
Introspect the current CLI and print its parameter metadata table.
Thin wrapper over
render_params_table(), the shared rendering core also drivingclick-extra wrap --show-paramsfor foreign CLIs. The live invocation context carries everything the core needs: the capturedRAW_ARGS(attached byCommand/Group) for value and source resolution, plus any sibling--table-format/--columnsoptions.- Return type: