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 │ 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.theme │ --theme [dark|dracula|light|monokai|nord|solarized_dark] │ click_extra.theme.ThemeOption │ click_extra.theme.ThemeChoice │ str │ ✘ │ ✘ │ ✓ │ CLI_THEME │ 'dark' │ 'dark' │ 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 │
╰─────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴─────────────────────────────────────────┴──────────────────────────────────┴─────────────┴────────┴─────────┴──────────────────┴─────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────┴─────────────╯
--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.
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.theme
Spec. | --theme [dark|dracula|light|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'
Value | 'dark'
Source | DEFAULT
***************************[ 10. 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
***************************[ 11. 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
***************************[ 12. 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
***************************[ 13. 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
***************************[ 14. 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.theme │ --theme [dark|dracula|light|monokai|nord|solarized_dark] │ click_extra.theme.ThemeOption │ click_extra.theme.ThemeChoice │ str │ ✘ │ ✘ │ ✓ │ CLI_THEME │ 'dark' │ 'dark' │ 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')}
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 the show-params subcommand:
$ click-extra 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 | ✘
Env. vars. |
Default | Sentinel.UNSET
***************************[ 2. row ]***************************
ID | run.debug
Spec. | --debug / --no-debug
Class | click.core.Option
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Env. vars. |
Default | False
***************************[ 3. row ]***************************
ID | run.debugger
Spec. | --debugger / --no-debugger
Class | click.core.Option
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Env. vars. |
Default | None
***************************[ 4. row ]***************************
ID | run.exclude_patterns
Spec. | --exclude-patterns PATH
Class | click.core.Option
Param type | flask.cli.SeparatedPathType
Python type | str
Hidden | ✘
Env. vars. |
Default | None
***************************[ 5. row ]***************************
ID | run.extra_files
Spec. | --extra-files PATH
Class | click.core.Option
Param type | flask.cli.SeparatedPathType
Python type | str
Hidden | ✘
Env. vars. |
Default | None
***************************[ 6. row ]***************************
ID | run.help
Spec. | --help
Class | click.core.Option
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Env. vars. |
Default | False
***************************[ 7. row ]***************************
ID | run.host
Spec. | -h, --host TEXT
Class | click.core.Option
Param type | click.types.StringParamType
Python type | str
Hidden | ✘
Env. vars. |
Default | '127.0.0.1'
***************************[ 8. row ]***************************
ID | run.key
Spec. | --key FILE
Class | click.core.Option
Param type | click.types.Path
Python type | str
Hidden | ✘
Env. vars. |
Default | Sentinel.UNSET
***************************[ 9. row ]***************************
ID | run.port
Spec. | -p, --port INTEGER
Class | click.core.Option
Param type | click.types.IntParamType
Python type | int
Hidden | ✘
Env. vars. |
Default | 5000
***************************[ 10. row ]***************************
ID | run.reload
Spec. | --reload / --no-reload
Class | click.core.Option
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Env. vars. |
Default | None
***************************[ 11. row ]***************************
ID | run.with_threads
Spec. | --with-threads / --without-threads
Class | click.core.Option
Param type | click.types.BoolParamType
Python type | bool
Hidden | ✘
Env. vars. |
Default | True
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.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.Does nothing in particular for now but provides a way to identify Click Extra’s own options with certainty.
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 inHelpExtraFormatter._style_bracket_fields(), which uses the structured data fromOption.get_help_extra()to identify each field by its label.
- class click_extra.parameters.ParamStructure(*args, excluded_params=None, included_params=None, **kwargs)[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
..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.
Items of
excluded_paramsare 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.included_paramsis the inverse: only the listed parameters will be allowed. Cannot be used together withexcluded_params.- 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:
- flatten_tree_dict(tree_dict, parent_key=None)[source]¶
Recursively traverse the tree-like
dictand produce a flatdictwhose 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: 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]¶
Format the common parameter table cells.
Returns a tuple of 8 cells in column order: ID, Spec., Class, Param type, Python type, Hidden, Env. vars., Default.
For structured formats (JSON, YAML, etc.), cells are native Python values. For visual formats, cells are themed strings matching help-screen styling.
- 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 = ('ID', 'Spec.', 'Class', 'Param type', 'Python type', 'Hidden', 'Exposed', 'Allowed in conf?', 'Env. vars.', 'Default', 'Value', 'Source')¶
Hard-coded list of table headers.
- print_params(ctx, param, value)[source]¶
Introspects current CLI and list its parameters and metadata.
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/ExtraGroupclasses, in which we are attaching aclick_extra.raw_argsmetadata entry to the context.- Return type: