click_extra package¶

… py:module:: click_extra

Expose package-wide elements.

… py:exception:: Abort

module:

click_extra

canonical:

click.exceptions.Abort

Bases: :py:class:RuntimeError

An internal signalling exception that signals Click to abort.

… py:class:: Argument(*args, help=None, **attrs)

module:

click_extra

canonical:

click_extra.parameters.Argument

Bases: :py:class:~click_extra.parameters._ParameterMixin, :py:class:~cloup._params.Argument

Wrap cloup.Argument, itself inheriting from click.Argument.

Inherits first from _ParameterMixin to allow future overrides of Click’s Parameter methods.

… py:exception:: BadArgumentUsage(message, ctx=None)

module:

click_extra

canonical:

click.exceptions.BadArgumentUsage

Bases: :py:class:~click.exceptions.UsageError

Raised if an argument is generally supplied but the use of the argument was incorrect. This is for instance raised if the number of values for an argument is not correct.

… versionadded:: 6.0

… py:exception:: BadOptionUsage(option_name, message, ctx=None)

module:

click_extra

canonical:

click.exceptions.BadOptionUsage

Bases: :py:class:~click.exceptions.UsageError

Raised if an option is generally supplied but the use of the option was incorrect. This is for instance raised if the number of arguments for an option is not correct.

… versionadded:: 4.0

type option_name:

:sphinx_autodoc_typehints_type:str

param option_name:: the name of the option being used incorrectly.

… py:exception:: BadParameter(message, ctx=None, param=None, param_hint=None)

module:

click_extra

canonical:

click.exceptions.BadParameter

Bases: :py:class:~click.exceptions.UsageError

An exception that formats out a standardized error message for a bad parameter. This is useful when thrown from a callback or type as Click will attach contextual information to it (for instance, which parameter it is).

… versionadded:: 2.0

type param:

:sphinx_autodoc_typehints_type:Parameter \| None

param param:

the parameter object that caused this error. This can be left out, and Click will attach this info itself if possible.

type param_hint:

:sphinx_autodoc_typehints_type:cabc.Sequence\[str\] \| str \| None

param param_hint:

a string that shows up as parameter name. This can be used as alternative to param in cases where custom validation should happen. If it is a string it’s used as such, if it’s a list then each item is quoted and separated.

… py:method:: BadParameter.format_message()

module:

click_extra

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\str``

… py:class:: Choice(choices, case_sensitive=True)

module:

click_extra

canonical:

click.types.Choice

Bases: :py:class:~click.types.ParamType, :py:class:~typing.Generic\ [:py:obj:~click.types.ParamTypeValue]

The choice type allows a value to be checked against a fixed set of supported values.

You may pass any iterable value which will be converted to a tuple and thus will only be iterated once.

The resulting value will always be one of the originally passed choices. See :meth:normalize_choice for more info on the mapping of strings to choices. See :ref:choice-opts for an example.

type case_sensitive:

:sphinx_autodoc_typehints_type:\:py\:class\:\bool``

param case_sensitive:

Set to false to make choices case insensitive. Defaults to true.

… versionchanged:: 8.2.0 Non-str choices are now supported. It can additionally be any iterable. Before you were not recommended to pass anything but a list or tuple.

… versionadded:: 8.2.0 Choice normalization can be overridden via :meth:normalize_choice.

… py:attribute:: Choice.name

module:

click_extra

type:

str

value:

‘choice’

the descriptive name of this type

… py:method:: Choice.to_info_dict()

module:

click_extra

Gather information that could be useful for a tool generating user-facing documentation.

Use :meth:click.Context.to_info_dict to traverse the entire CLI structure.

… versionadded:: 8.0

rtype:

:sphinx_autodoc_typehints_type:\:py\:class\:\dict`\ \[:py:class:`str`, :py:data:`~typing.Any`]`

… py:method:: Choice.normalize_choice(choice, ctx)

module:

Subpackages¶

click_extra.sphinx package

Submodules¶

click_extra.cli module¶

… py:module:: click_extra.cli

Click Extra CLI with pre-baking utilities.

click_extra.colorize module¶

… py:module:: click_extra.colorize

Helpers and utilities to apply ANSI coloring to terminal content.

… py:class:: HelpExtraTheme(invoked_command=, command_help=, heading=, constraint=, section_help=, col1=, col2=, alias=, alias_secondary=None, epilog=, critical=, error=, warning=, info=, debug=, option=, subcommand=, choice=, metavar=, bracket=, envvar=, default=, range_label=, required=, argument=, deprecated=, search=, success=, cross_ref_highlight=True, subheading=)

module:

click_extra.colorize

Bases: :py:class:~cloup.styling.HelpTheme

Extends cloup.HelpTheme with logging.levels and extra properties.

… py:method:: HelpExtraTheme.critical()

module:

click_extra.colorize

rtype:

:sphinx_autodoc_typehints_type:\:py\:class\:\~typing.TypeVar`\ \(``T``)`

… py:method:: HelpExtraTheme.error()

module:

click_extra.colorize

rtype:

:sphinx_autodoc_typehints_type:\:py\:class\:\~typing.TypeVar`\ \(``T``)`

… py:method:: HelpExtraTheme.warning()

module:

click_extra.colorize

rtype:

:sphinx_autodoc_typehints_type:\:py\:class\:\~typing.TypeVar`\ \(``T``)`

… py:method:: HelpExtraTheme.info()

module:

click_extra.colorize

rtype:

:sphinx_autodoc_typehints_type:\:py\:class\:\~typing.TypeVar`\ \(``T``)`

… py:method:: HelpExtraTheme.debug()

module:

click_extra.commands module¶

… py:module:: click_extra.commands

Wraps vanilla Click and Cloup commands with extra features.

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

… py:class:: ExtraContext(*args, meta=None, **kwargs)

module:

click_extra.commands

Bases: :py:class:~cloup._context.Context

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

Also defaults color to True for root contexts (i.e. without a parent), so help screens are always colorized — even when piped. Click’s own default is None (auto-detect via TTY), which strips colors in non-interactive contexts.

Parent-to-child color inheritance is handled by Click itself at Context.__init__ time, so no property override is needed.

… todo:: Propose addition of meta keyword upstream to Click.

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

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

… py:attribute:: ExtraContext.formatter_class

module:

click_extra.commands

Use our own formatter to colorize the help screen.

alias of :py:class:~click_extra.colorize.HelpExtraFormatter

… py:function:: default_extra_params()

module:

click_extra.commands

Default additional options added to @command and @group.

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

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

#. --time / --no-time … hint:: --time is placed at the top of all other eager options so all other options’ processing time can be measured. #. --config CONFIG_PATH … hint:: --config is at the top so it can have a direct influence on the default behavior and value of the other options. #. --no-config #. --validate-config CONFIG_PATH #. --color, --ansi / --no-color, --no-ansi #. --show-params #. --table-format FORMAT #. --verbosity LEVEL #. -v, --verbose #. --version #. -h, --help … attention:: This is the option produced by the @click.decorators.help_option <https://click.palletsprojects.com/en/stable/api/#click.help_option>_ decorator.

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

    That's because it's `going to be added by Click itself
    <https://github.com/pallets/click/blob/c9f7d9d/src/click/core.py#L966-L969>`_,
    at the end of the list of options. By letting Click handle this, we ensure
    that the help option will take into account the `help_option_names
    <https://click.palletsprojects.com/en/stable/documentation/#help-parameter-customization>`_
    setting.

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

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

This is probably something that has been `requested in issue #544
<https://github.com/kdeldycke/click-extra/issues/544>`_.

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\list`\ \[:py:class:`~click.core.Option`]`

… py:class:: ExtraCommand(*args, version_fields=None, config_schema=None, schema_strict=False, fallback_sections=(), included_params=None, extra_option_at_end=True, populate_auto_envvars=True, extra_keywords=None, excluded_keywords=None, **kwargs)

module:

click_extra.commands

Bases: :py:class:~click_extra.colorize.ExtraHelpColorsMixin, :py:class:~cloup._commands.Command

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

List of extra parameters:

type version_fields:

:sphinx_autodoc_typehints_type:\:py\:class\:\dict`\ \[:py:class:`str`, :py:data:`~typing.Any`] | :py:obj:`None``

param version_fields:

dictionary of ExtraVersionOption template field overrides forwarded to the version option. Accepts any field from ExtraVersionOption.template_fields (e.g. prog_name, version, git_branch). Lets you customize --version output from the command decorator without replacing the default params list.

type extra_keywords:

:sphinx_autodoc_typehints_type:\:py\:class\:\~click_extra.colorize.HelpKeywords` | :py:obj:`None``

param extra_keywords:

a HelpKeywords instance whose entries are merged into the auto-collected keyword set. Use this to inject additional strings for help screen highlighting.

type excluded_keywords:

:sphinx_autodoc_typehints_type:\:py\:class\:\~click_extra.colorize.HelpKeywords` | :py:obj:`None``

param excluded_keywords:

a HelpKeywords instance whose entries are removed from the auto-collected keyword set. Use this to suppress highlighting of specific strings.

type extra_option_at_end:

:sphinx_autodoc_typehints_type:\:py\:class\:\bool``

param extra_option_at_end:

reorders all parameters attached to the command <https://kdeldycke.github.io/click-extra/commands.html#option-order>_, by moving all instances of ExtraOption at the end of the parameter list. The original order of the options is preserved among themselves.

type populate_auto_envvars:

click_extra.config module¶

… py:module:: click_extra.config

Utilities to load parameters and options from a configuration file.

… hint:: Why config?

   That whole namespace is using the common ``config`` short-name to designate
   configuration files.

   Not ``conf``, not ``cfg``, not ``configuration``, not ``settings``. Just ``config``.

   A quick survey of existing practices, and poll to my friends informed me that
   ``config`` is more explicit and less likely to be misunderstood.

   After all, is there a chance for it to be misunderstood, in the context of a CLI,
   for something else? *Confirm*? *Conference*? *Conflict* *Confuse*?...

   So yes, ``config`` is good enough.

… todo:: Add a --dump-config or --export-config option to write down the current configuration (or a template) into a file or <stdout>.

   Help message would be: *you can use this option with other options or environment
   variables to have them set in the generated configuration*.

Dotted keys in configuration files (e.g. "subcommand.option": value) are automatically expanded into nested dicts before merging, so users can freely mix flat dot-notation and nested structures in any supported format.

… py:data:: VCS_DIRS

module:

click_extra.config

value:

(‘.git’, ‘.hg’, ‘.svn’, ‘.bzr’, ‘CVS’, ‘.darcs’)

VCS directory names used to identify version control system roots.

Includes:

.git — Git
.hg — Mercurial
.svn — Subversion
.bzr — Bazaar
CVS — CVS (note: uppercase, no leading dot)
.darcs — Darcs

… py:class:: ConfigFormat(*values)

module:

click_extra.config

Bases: :py:class:~enum.Enum

All configuration formats, associated to their support status.

The first element of the tuple is a sequence of file extensions associated to the format. Patterns are fed to wcmatch.glob for matching, and are influenced by the flags set on the ConfigOption instance.

The second element indicates whether the format is supported or not, depending on the availability of the required third-party packages. This evaluation is performed at runtime when this module is imported.

… caution:: The order is important for both format members and file patterns. It defines the priority order in which formats are tried when multiple candidate files are found.

… todo:: Add support for JWCC <https://nigeltao.github.io/blog/2021/json-with-commas-comments.html>_ / hujson <https://github.com/tailscale/hujson>_ format?

… py:attribute:: ConfigFormat.TOML

module:

click_extra.config

value:

((‘*.toml’,), True, ‘TOML’)

… py:attribute:: ConfigFormat.YAML

module:

click_extra.config

value:

((‘.yaml’, ‘.yml’), True, ‘YAML’)

… py:attribute:: ConfigFormat.JSON

module:

click_extra.config

value:

((‘*.json’,), True, ‘JSON’)

… py:attribute:: ConfigFormat.JSON5

module:

click_extra.config

value:

((‘*.json5’,), True, ‘JSON5’)

… py:attribute:: ConfigFormat.JSONC

module:

click_extra.decorators module¶

… py:module:: click_extra.decorators

Decorators for group, commands and options.

… py:function:: allow_missing_parenthesis(dec_factory)

module:

click_extra.decorators

Allow to use decorators with or without parenthesis.

As proposed in Cloup issue #127 <https://github.com/janluke/cloup/issues/127#issuecomment-1264704896>_.

… py:function:: decorator_factory(dec, *new_args, **new_defaults)

module:

click_extra.decorators

Clone decorator with a set of new defaults.

Used to create our own collection of decorators for our custom options, based on Cloup’s.

… attention:: The cls argument passed to the factory is used as the reference class from which the produced decorator’s cls argument must inherit.

The idea is to ensure that, for example, the `@command` decorator
re-implemented by Click Extra is always a subclass of `ExtraCommand`, even when
the user overrides the `cls` argument. That way it can always rely on the
additional properties and methods defined in the Click Extra framework, where we
have extended Cloup and Click so much that we want to prevent surprising side
effects.

… py:function:: command(*args, **kwargs)

module:

click_extra.decorators

Returns a new decorator instantiated with custom defaults.

These defaults values are merged with the user’s own arguments.

A special case is made for the params argument, to allow it to be callable. This limits the issue of the mutable options being shared between commands.

This decorator can be used with or without arguments.

… py:function:: group(*args, **kwargs)

module:

click_extra.decorators

Returns a new decorator instantiated with custom defaults.

These defaults values are merged with the user’s own arguments.

A special case is made for the params argument, to allow it to be callable. This limits the issue of the mutable options being shared between commands.

This decorator can be used with or without arguments.

… py:function:: option(*args, **kwargs)

module:

click_extra.decorators

Returns a new decorator instantiated with custom defaults.

These defaults values are merged with the user’s own arguments.

A special case is made for the params argument, to allow it to be callable. This limits the issue of the mutable options being shared between commands.

This decorator can be used with or without arguments.

… py:function:: argument(*args, **kwargs)

module:

click_extra.decorators

Returns a new decorator instantiated with custom defaults.

These defaults values are merged with the user’s own arguments.

A special case is made for the params argument, to allow it to be callable. This limits the issue of the mutable options being shared between commands.

This decorator can be used with or without arguments.

… py:function:: help_option(*args, **kwargs)

module:

click_extra.decorators

Returns a new decorator instantiated with custom defaults.

These defaults values are merged with the user’s own arguments.

A special case is made for the params argument, to allow it to be callable. This limits the issue of the mutable options being shared between commands.

This decorator can be used with or without arguments.

… py:function:: version_option(*args, **kwargs)

module:

click_extra.decorators

Returns a new decorator instantiated with custom defaults.

These defaults values are merged with the user’s own arguments.

A special case is made for the params argument, to allow it to be callable. This limits the issue of the mutable options being shared between commands.

This decorator can be used with or without arguments.

… py:function:: lazy_group(*args, **kwargs)

module:

click_extra.decorators

Returns a new decorator instantiated with custom defaults.

These defaults values are merged with the user’s own arguments.

A special case is made for the params argument, to allow it to be callable. This limits the issue of the mutable options being shared between commands.

This decorator can be used with or without arguments.

… py:function:: color_option(*args, **kwargs)

module:

click_extra.decorators

Returns a new decorator instantiated with custom defaults.

These defaults values are merged with the user’s own arguments.

A special case is made for the params argument, to allow it to be callable. This limits the issue of the mutable options being shared between commands.

This decorator can be used with or without arguments.

… py:function:: config_option(*args, **kwargs)

module:

click_extra.decorators

Returns a new decorator instantiated with custom defaults.

These defaults values are merged with the user’s own arguments.

A special case is made for the params argument, to allow it to be callable. This limits the issue of the mutable options being shared between commands.

This decorator can be used with or without arguments.

… py:function:: no_config_option(*args, **kwargs)

module:

click_extra.decorators

Returns a new decorator instantiated with custom defaults.

These defaults values are merged with the user’s own arguments.

A special case is made for the params argument, to allow it to be callable. This limits the issue of the mutable options being shared between commands.

This decorator can be used with or without arguments.

… py:function:: validate_config_option(*args, **kwargs)

module:

click_extra.decorators

Returns a new decorator instantiated with custom defaults.

These defaults values are merged with the user’s own arguments.

A special case is made for the params argument, to allow it to be callable. This limits the issue of the mutable options being shared between commands.

This decorator can be used with or without arguments.

… py:function:: show_params_option(*args, **kwargs)

module:

click_extra.decorators

Returns a new decorator instantiated with custom defaults.

These defaults values are merged with the user’s own arguments.

A special case is made for the params argument, to allow it to be callable. This limits the issue of the mutable options being shared between commands.

This decorator can be used with or without arguments.

… py:function:: table_format_option(*args, **kwargs)

module:

click_extra.decorators

Returns a new decorator instantiated with custom defaults.

These defaults values are merged with the user’s own arguments.

A special case is made for the params argument, to allow it to be callable. This limits the issue of the mutable options being shared between commands.

This decorator can be used with or without arguments.

… py:function:: telemetry_option(*args, **kwargs)

module:

click_extra.decorators

Returns a new decorator instantiated with custom defaults.

These defaults values are merged with the user’s own arguments.

A special case is made for the params argument, to allow it to be callable. This limits the issue of the mutable options being shared between commands.

This decorator can be used with or without arguments.

… py:function:: timer_option(*args, **kwargs)

module:

click_extra.decorators

Returns a new decorator instantiated with custom defaults.

These defaults values are merged with the user’s own arguments.

A special case is made for the params argument, to allow it to be callable. This limits the issue of the mutable options being shared between commands.

This decorator can be used with or without arguments.

… py:function:: verbose_option(*args, **kwargs)

module:

click_extra.decorators

Returns a new decorator instantiated with custom defaults.

These defaults values are merged with the user’s own arguments.

A special case is made for the params argument, to allow it to be callable. This limits the issue of the mutable options being shared between commands.

This decorator can be used with or without arguments.

… py:function:: verbosity_option(*args, **kwargs)

module:

click_extra.decorators

Returns a new decorator instantiated with custom defaults.

These defaults values are merged with the user’s own arguments.

A special case is made for the params argument, to allow it to be callable. This limits the issue of the mutable options being shared between commands.

This decorator can be used with or without arguments.

click_extra.envvar module¶

… py:module:: click_extra.envvar

Implements environment variable utilities.

… seealso: Environment variables are a legacy mess: Let's dive deep into them <https://allvpv.org/haotic-journey-through-envvars/>_.

… py:function:: merge_envvar_ids(*envvar_ids)

module:

click_extra.envvar

Merge and deduplicate environment variables.

Multiple parameters are accepted and can be single strings or arbitrary-nested iterables of strings. None values are ignored.

Variable names are deduplicated while preserving their initial order.

… caution:: On Windows, environment variable names are case-insensitive <https://docs.python.org/3/library/os.html#os.environ>, so we normalize them to uppercase as the standard library does <https://github.com/python/cpython/blob/3.14/Lib/os.py#L770-L782>.

Returns a tuple of strings. The result is ready to be used as the envvar parameter for Click’s options or arguments.

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\tuple`\ \[:py:class:`str`, :py:data:`…<Ellipsis>`]`

… py:function:: clean_envvar_id(envvar_id)

module:

click_extra.envvar

Utility to produce a user-friendly environment variable name from a string.

Separates all contiguous alphanumeric string segments, eliminate empty strings, join them with an underscore and uppercase the result.

… attention:: We do not rely too much on this utility to try to reproduce the current behavior of Click, which is is not consistent regarding case-handling of environment variable <https://github.com/pallets/click/issues/2483>_.

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\str``

… py:function:: param_auto_envvar_id(param, ctx)

module:

click_extra.envvar

Compute the auto-generated environment variable of an option or argument.

Returns the auto envvar as it is exactly computed within Click’s internals, i.e. click.core.Parameter.resolve_envvar_value() and click.core.Option.resolve_envvar_value().

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\str` | :py:obj:`None``

… py:function:: param_envvar_ids(param, ctx)

module:

click_extra.envvar

Returns the deduplicated, ordered list of environment variables for an option or argument, including the auto-generated one.

The auto-generated environment variable is added at the end of the list, so that user-defined envvars takes precedence. This respects the current implementation of click.core.Option.resolve_envvar_value().

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\tuple`\ \[:py:class:`str`, :py:data:`…<Ellipsis>`]`

… py:function:: env_copy(extend=None)

module:

click_extra.envvar

Returns a copy of the current environment variables and eventually extend it.

Mimics Python's original implementation <https://github.com/python/cpython/blob/3.14/Lib/subprocess.py#L1907-L1908>_ by returning None if no extend content are provided.

Environment variables are expected to be a dict of str:str.

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\~collections.abc.Mapping`\ \[:py:class:`str`, :py:class:`str` | :py:obj:`None`] | :py:obj:`None``

click_extra.logging module¶

… py:module:: click_extra.logging

Logging utilities.

… py:class:: LogLevel(*values)

module:

click_extra.logging

Bases: :py:class:~enum.IntEnum

Mapping of :ref:canonical log level names <levels> to their integer level.

That’s our own version of logging._nameToLevel <https://github.com/python/cpython/blob/3.14/Lib/logging/__init__.py#L115-L124>_, but:

sorted from lowest to highest verbosity,
excludes the following levels:
- data:
  
  NOTSET <logging.NOTSET>, which is considered internal - WARN, which :meth:is obsolete <logging.Logger.warning> - FATAL, which shouldn't be used <https://github.com/python/cpython/issues/85013>_ and has been replaced by CRITICAL <https://github.com/python/cpython/blob/3.14/Lib/logging/__init__.py#L2150-L2154>_
  
  … py:attribute:: LogLevel.CRITICAL
  
  module:
  
  click_extra.logging
  
  value:
  
  50
  
  … py:attribute:: LogLevel.ERROR
  
  module:
  
  click_extra.logging
  
  value:
  
  40
  
  … py:attribute:: LogLevel.WARNING
  
  module:
  
  click_extra.logging
  
  value:

click_extra.parameters module¶

… py:module:: click_extra.parameters

Our own flavor of Option, Argument and parameters.

… py:function:: search_params(params, klass, include_subclasses=True, unique=True)

module:

click_extra.parameters

Search a particular class of parameter in a list and return them.

type params:

:sphinx_autodoc_typehints_type:\:py\:class\:\~collections.abc.Iterable`\ \[:py:class:`~click.core.Parameter`]`

param params:

list of parameter instances to search in.

type klass:

:sphinx_autodoc_typehints_type:\:py\:class\:\type`\ \[:py:class:`~click.core.Parameter`]`

param klass:

the class of the parameters to look for.

type include_subclasses:

:sphinx_autodoc_typehints_type:\:py\:class\:\bool``

param include_subclasses:

if True, includes in the results all parameters subclassing the provided klass. If False, only matches parameters which are strictly instances of klass. Defaults to True.

type unique:

:sphinx_autodoc_typehints_type:\:py\:class\:\bool``

param unique:

if True, raise an error if more than one parameter of the provided klass is found. Defaults to True.

rtype:

click_extra.pygments module¶

… py:module:: click_extra.pygments

Helpers and utilities to allow Pygments to parse and render ANSI codes.

… py:data:: DEFAULT_TOKEN_TYPE

module:

click_extra.pygments

value:

(‘Generic’, ‘Output’)

Default Pygments’ token type to render with ANSI support.

We defaults to Generic.Output tokens, as this is the token type used by all REPL- like and terminal lexers.

… py:class:: AnsiFilter(**options)

module:

click_extra.pygments

Bases: :py:class:~pygments.filter.Filter

Custom filter transforming a particular kind of token (Generic.Output by defaults) into ANSI tokens.

Initialize a AnsiColorLexer and configure the token_type to be colorized.

… todo::

Allow multiple ``token_type`` to be configured for colorization (if
traditions are changed on Pygments' side).

… py:method:: AnsiFilter.filter(lexer, stream)

module:

click_extra.pygments

Transform each token of token_type type into a stream of ANSI tokens.

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\~collections.abc.Iterator`\ \[:py:class:`tuple`\ \[:py:class:`~pygments.token._TokenType`, :py:class:`str`]]`

… py:class:: AnsiSessionLexer(name, bases, dct)

module:

click_extra.pygments

Bases: :py:class:~pygments.lexer.LexerMeta

Custom metaclass used as a class factory to derive an ANSI variant of default shell session lexers.

Setup class properties’ defaults for new ANSI-capable lexers.

Adds an ANSI prefix to the lexer’s name.
Replaces all aliases IDs from the parent lexer with variants prefixed with ansi-.

… py:class:: AnsiLexerFiltersMixin(*args, **kwargs)

module:

click_extra.pygments

Bases: :py:class:~pygments.lexer.Lexer

Adds a TokenMergeFilter and AnsiOutputFilter to the list of filters.

The session lexers we inherits from are parsing the code block line by line so they can differentiate inputs and outputs. Each output line ends up encapsulated into a Generic.Output token. We apply the TokenMergeFilter filter to reduce noise and have each contiguous output lines part of the same single token.

Then we apply our custom AnsiOutputFilter to transform any Generic.Output monoblocks into ANSI tokens.

… py:function:: collect_session_lexers()

module:

click_extra.pygments

Retrieve all lexers producing shell-like sessions in Pygments.

This function contain a manually-maintained list of lexers, to which we dynamiccaly adds lexers inheriting from ShellSessionBaseLexer.

… hint::

To help maintain this list, there is `a test that will fail
<https://github.com/kdeldycke/click-extra/blob/main/tests/test_pygments.py>`_
if a new REPL/terminal-like lexer is added to Pygments but not referenced here.

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\~collections.abc.Iterator`\ \[:py:class:`type`\ \[:py:class:`~pygments.lexer.Lexer`]]`

… py:data:: lexer_map

module:

click_extra.pygments

value:

{<class ‘pygments.lexers.algebra.GAPConsoleLexer’>: <class ‘pygments.lexer.AnsiGAPConsoleLexer’>, <class ‘pygments.lexers.dylan.DylanConsoleLexer’>: <class ‘pygments.lexer.AnsiDylanConsoleLexer’>, <class ‘pygments.lexers.erlang.ElixirConsoleLexer’>: <class ‘pygments.lexer.AnsiElixirConsoleLexer’>, <class ‘pygments.lexers.erlang.ErlangShellLexer’>: <class ‘pygments.lexer.AnsiErlangShellLexer’>, <class ‘pygments.lexers.julia.JuliaConsoleLexer’>: <class ‘pygments.lexer.AnsiJuliaConsoleLexer’>, <class ‘pygments.lexers.matlab.MatlabSessionLexer’>: <class ‘pygments.lexer.AnsiMatlabSessionLexer’>, <class ‘pygments.lexers.php.PsyshConsoleLexer’>: <class ‘pygments.lexer.AnsiPsyshConsoleLexer’>, <class ‘pygments.lexers.python.PythonConsoleLexer’>: <class ‘pygments.lexer.AnsiPythonConsoleLexer’>, <class ‘pygments.lexers.r.RConsoleLexer’>: <class ‘pygments.lexer.AnsiRConsoleLexer’>, <class ‘pygments.lexers.ruby.RubyConsoleLexer’>: <class ‘pygments.lexer.AnsiRubyConsoleLexer’>, <class ‘pygments.lexers.shell.BashSessionLexer’>: <class ‘pygments.lexer.AnsiBashSessionLexer’>, <class ‘pygments.lexers.shell.MSDOSSessionLexer’>: <class ‘pygments.lexer.AnsiMSDOSSessionLexer’>, <class ‘pygments.lexers.shell.PowerShellSessionLexer’>: <class ‘pygments.lexer.AnsiPowerShellSessionLexer’>, <class ‘pygments.lexers.shell.TcshSessionLexer’>: <class ‘pygments.lexer.AnsiTcshSessionLexer’>, <class ‘pygments.lexers.special.OutputLexer’>: <class ‘pygments.lexer.AnsiOutputLexer’>, <class ‘pygments.lexers.sql.PostgresConsoleLexer’>: <class ‘pygments.lexer.AnsiPostgresConsoleLexer’>, <class ‘pygments.lexers.sql.SqliteConsoleLexer’>: <class ‘pygments.lexer.AnsiSqliteConsoleLexer’>}

Map original lexer to their ANSI variant.

… py:class:: AnsiHtmlFormatter(**kwargs)

module:

click_extra.pygments

Bases: :py:class:~pygments_ansi_color.ExtendedColorHtmlFormatterMixin, :py:class:~pygments.formatters.html.HtmlFormatter

Extend standard Pygments’ HtmlFormatter.

Adds support for ANSI 256 colors <https://github.com/chriskuehl/pygments-ansi-color#optional-enable-256-color-support>_.

Intercept the style argument to augment it with ANSI colors support.

Creates a new style instance that inherits from the one provided by the user, but updates its styles attribute to add ANSI colors support from pygments_ansi_color.

… py:attribute:: AnsiHtmlFormatter.name

module:

click_extra.pygments

value:

‘ANSI HTML’

Full name for the formatter, in human-readable form.

… py:attribute:: AnsiHtmlFormatter.aliases

module:

click_extra.pygments

type:

~typing.ClassVar[list[str]]

value:

[‘ansi-html’]

A list of short, unique identifiers that can be used to lookup the formatter from a list, e.g. using :func:.get_formatter_by_name().

click_extra.pytest module¶

… py:module:: click_extra.pytest

Pytest fixtures and marks to help testing Click CLIs.

… py:function:: extra_runner()

module:

click_extra.pytest

Runner fixture for click.testing.ExtraCliRunner.

… py:function:: invoke(extra_runner)

module:

click_extra.pytest

Invoke fixture shorthand for click.testing.ExtraCliRunner.invoke.

… py:function:: command_decorators(no_commands=False, no_groups=False, no_click=False, no_cloup=False, no_extra=False, with_parenthesis=True, with_types=False)

module:

click_extra.pytest

Returns collection of Pytest parameters to test all command-like decorators.

Returns:

click.command
click.command()
cloup.command
cloup.command()
click_extra.command
click_extra.command()
click.group
click.group()
cloup.group
cloup.group()
click_extra.group
click_extra.group()

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\tuple`\ \[:py:class:`~_pytest.mark.structures.ParameterSet`, :py:data:`…<Ellipsis>`]`

… py:function:: option_decorators(no_options=False, no_arguments=False, no_click=False, no_cloup=False, no_extra=False, with_parenthesis=True, with_types=False)

module:

click_extra.pytest

Returns collection of Pytest parameters to test all parameter-like decorators.

Returns:

click.option
click.option()
cloup.option
cloup.option()
click_extra.option
click_extra.option()
click.argument
click.argument()
cloup.argument
cloup.argument()
click_extra.argument
click_extra.argument()

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\tuple`\ \[:py:class:`~_pytest.mark.structures.ParameterSet`, :py:data:`…<Ellipsis>`]`

… py:function:: create_config(tmp_path)

module:

click_extra.pytest

A generic fixture to produce a temporary configuration file.

… py:function:: assert_output_regex(request)

module:

click_extra.pytest

An assert-like utility for Pytest to compare CLI output against the regex.

Designed for the regexes defined above.

click_extra.table module¶

… py:module:: click_extra.table

Collection of table rendering utilities.

… py:class:: TableFormat(*values)

module:

click_extra.table

Bases: :py:class:~enum.Enum

Enumeration of supported table formats.

Hard-coded to be in alphabetical order. Content of this enum is checked in unit tests.

… warning:: The youtrack format is missing in action from any official JetBrains documentation. It will be removed in python-tabulate v0.11 <https://github.com/astanin/python-tabulate/issues/375>_.

… py:attribute:: TableFormat.ALIGNED

module:

click_extra.table

value:

‘aligned’

… py:attribute:: TableFormat.ASCIIDOC

module:

click_extra.table

value:

‘asciidoc’

… py:attribute:: TableFormat.COLON_GRID

module:

click_extra.table

value:

‘colon-grid’

… py:attribute:: TableFormat.CSV

module:

click_extra.table

value:

‘csv’

… py:attribute:: TableFormat.CSV_EXCEL

module:

click_extra.telemetry module¶

… py:module:: click_extra.telemetry

Telemetry utilities.

… py:class:: TelemetryOption(param_decls=None, default=False, expose_value=False, envvar=None, show_envvar=True, help=‘Collect telemetry and usage data.’, **kwargs)

module:

click_extra.telemetry

Bases: :py:class:~click_extra.parameters.ExtraOption

A pre-configured --telemetry/--no-telemetry option flag.

Respects the proposed DO_NOT_TRACK environment variable <https://consoledonottrack.com>_ as a unified standard to opt-out of telemetry for TUI/console apps.

The DO_NOT_TRACK convention takes precedence over the user-defined environment variables and the auto-generated values.

… seealso::

- A `knowledge base of telemetry disabling configuration options
  <https://github.com/beatcracker/toptout>`_.

- And another `list of environment variable to disable telemetry in desktop apps
  <https://telemetry.timseverien.com/opt-out/>`_.

… py:method:: TelemetryOption.save_telemetry(ctx, param, value)

module:

click_extra.telemetry

Save the option value in the context, in ctx.telemetry.

rtype:

sphinx_autodoc_typehints_type:: \:py\:obj\:\None``

click_extra.testing module¶

… py:module:: click_extra.testing

CLI testing and simulation of their execution.

… py:data:: PROMPT

module:

click_extra.testing

value:

‘$ ’

Prompt used to simulate the CLI execution.

… hint:: Use ASCII characters to avoid issues with Windows terminals.

… py:data:: INDENT

module:

click_extra.testing

value:

’ ’

Constants for rendering of CLI execution.

… py:function:: args_cleanup(*args)

module:

click_extra.testing

Flatten recursive iterables, remove all None, and cast each element to strings.

Helps serialize :py:class:pathlib.Path and other objects.

It also allows for nested iterables and None values as CLI arguments for convenience. We just need to flatten and filters them out.

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\tuple`\ \[:py:class:`str`, :py:data:`…<Ellipsis>`]`

… py:function:: format_cli_prompt(cmd_args, extra_env=None)

module:

click_extra.testing

Simulate the console prompt used to invoke the CLI.

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\str``

… py:function:: render_cli_run(args, result, env=None)

module:

click_extra.testing

Generates the full simulation of CLI execution, including output.

Mostly used to print debug traces to user or in test results.

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\str``

… py:function:: print_cli_run(args, result, env=None)

module:

click_extra.testing

Prints the full simulation of CLI execution, including output.

rtype:

sphinx_autodoc_typehints_type:: \:py\:obj\:\None``

… py:data:: INVOKE_ARGS

module:

click_extra.testing

value:

{‘args’, ‘catch_exceptions’, ‘cli’, ‘color’, ‘env’, ‘input’, ‘self’}

Parameter IDs of click.testing.CliRunner.invoke().

We need to collect them to help us identify which extra parameters passed to invoke() collides with its original signature.

… warning:: This has been reported upstream to Click project <https://github.com/pallets/click/issues/2110>_ but has been rejected and not considered an issue worth fixing.

… py:class:: ExtraResult(runner, stdout_bytes, stderr_bytes, output_bytes, return_value, exit_code, exception, exc_info=None)

module:

click_extra.testing

Bases: :py:class:~click.testing.Result

A Result subclass with automatic traceback formatting.

Enhances __repr__ so that pytest assertion failures show the full traceback instead of just the exception type.

… py:property:: ExtraResult.formatted_exception

module:

click_extra.testing

type:

str | None

Full formatted traceback, or None if no exception occurred.

… py:class:: ExtraCliRunner(charset=‘utf-8’, env=None, echo_stdin=False, catch_exceptions=True)

module:

click_extra.testing

Bases: :py:class:~click.testing.CliRunner

Augment :class:click.testing.CliRunner with extra features and bug fixes.

… py:attribute:: ExtraCliRunner.force_color

module:

click_extra.testing

type:

bool

value:

False

Global class attribute to override the color parameter in invoke.

… py:method:: ExtraCliRunner.invoke(cli, *args, input=None, env=None, catch_exceptions=True, color=None, **extra)

module:

click_extra.testing

Same as click.testing.CliRunner.invoke() with extra features.

The first positional parameter is the CLI to invoke. The remaining positional parameters of the function are the CLI arguments. All other parameters are required to be named.
The CLI arguments can be nested iterables of arbitrary depth. This is useful for argument composition of test cases with @pytest.mark.parametrize <https://docs.pytest.org/en/stable/example/parametrize.html>_.
Allow forcing of the color property at the class-level via force_color attribute.
Adds a special case in the form of color="forced" parameter, which allows colored output to be kept, while forcing the initialization of Context.color = True. This is not allowed in current implementation <https://github.com/pallets/click/issues/2110>_ of click.testing.CliRunner.invoke() because of colliding parameters.
Strips all ANSI codes from results if color was explicirely set to False.
Always prints a simulation of the CLI execution as the user would see it in its terminal. Including colors.
Pretty-prints a formatted exception traceback if the command fails.

type cli:

:sphinx_autodoc_typehints_type:\:py\:class\:\~click.core.Command``

param cli:

CLI to invoke.

param *args:

can be nested iterables composed of str, :py:class:pathlib.Path objects and None values. The nested structure will be flattened and None values will be filtered out. Then all elements will be casted to str. See :func:args_cleanup for details.

type input:

:sphinx_autodoc_typehints_type:\:py\:class\:\str` | :py:class:`bytes` | :py:class:`~typing.IO` | :py:obj:`None``

param input:

click_extra.timer module¶

… py:module:: click_extra.timer

Command execution time measurement.

… py:class:: TimerOption(param_decls=None, default=False, expose_value=False, is_eager=True, help=‘Measure and print elapsed execution time.’, **kwargs)

module:

click_extra.timer

Bases: :py:class:~click_extra.parameters.ExtraOption

A pre-configured option that is adding a --time/--no-time flag to print elapsed time at the end of CLI execution.

The start time is made available in the context in ctx.meta["click_extra.start_time"].

… py:method:: TimerOption.print_timer()

module:

click_extra.timer

Compute and print elapsed execution time.

rtype:

:sphinx_autodoc_typehints_type:\:py\:obj\:\None``

… py:method:: TimerOption.register_timer_on_close(ctx, param, value)

module:

click_extra.timer

Callback setting up all timer’s machinery.

Computes and print the execution time at the end of the CLI, if option has been activated.

rtype:

sphinx_autodoc_typehints_type:: \:py\:obj\:\None``

click_extra.types module¶

… py:module:: click_extra.types

… py:class:: ChoiceSource(*values)

module:

click_extra.types

Bases: :py:class:~enum.Enum

Source of choices for EnumChoice.

… py:attribute:: ChoiceSource.KEY

module:

click_extra.types

value:

‘key’

… py:attribute:: ChoiceSource.NAME

module:

click_extra.types

value:

‘name’

… py:attribute:: ChoiceSource.VALUE

module:

click_extra.types

value:

‘value’

… py:attribute:: ChoiceSource.STR

module:

click_extra.types

value:: ‘str’

… py:class:: EnumChoice(choices, case_sensitive=False, choice_source=ChoiceSource.STR, show_aliases=False)

module:

click_extra.types

Bases: :py:class:~click.types.Choice

Choice type for Enum.

Allows to select which part of the members to use as choice strings, by setting the choice_source parameter to one of:

ChoiceSource.KEY or ChoiceSource.NAME to use the key (i.e. the name property),
ChoiceSource.VALUE to use the value,
ChoiceSource.STR to use the str() string representation, or
A custom callable that takes an Enum member and returns a string.

Default to ChoiceSource.STR, which makes you to only have to define the __str__() method on your Enum to produce beautiful choice strings.

Same as click.Choice, but takes an Enum as choices.

Also defaults to case-insensitive matching.

… py:attribute:: EnumChoice.choices

module:

click_extra.types

type:

tuple[str, …]

The strings available as choice.

… hint:: Contrary to the parent Choice class, we store choices directly as strings, not the Enum members themselves. That way there is no surprises when displaying them to the user.

   This trick bypass ``Enum``-specific code path in the Click library. Because,
   after all, a terminal environment only deals with strings: arguments,
   parameters, parsing, help messages, environment variables, etc.

… py:method:: EnumChoice.get_choice_string(member)

module:

click_extra.types

Derivate the choice string from the given Enum’s member.

rtype:

:sphinx_autodoc_typehints_type:\:py\:class\:\str``

… py:method:: EnumChoice.normalize_choice(choice, ctx)

module:

click_extra.types

Expand the parent’s normalize_choice() to accept Enum members as input.

Parent method expects a string, but here we allow passing Enum members too.

rtype:

:sphinx_autodoc_typehints_type:\:py\:class\:\str``

… py:method:: EnumChoice.convert(value, param, ctx)

module:

click_extra.types

Convert the input value to the corresponding Enum member.

The parent’s convert() is going to return the choice string, which we then map back to the corresponding Enum member.

rtype:

sphinx_autodoc_typehints_type:

click_extra.version module¶

… py:module:: click_extra.version

Gather CLI metadata and print them.

Pre-baking is inspired by shadow-rs <https://github.com/baoyachi/shadow-rs>_, which injects build-time constants (BRANCH, SHORT_COMMIT, COMMIT_HASH, COMMIT_DATE, TAG, …) into Rust binaries at compile time.

… todo:: shadow-rs also provides constants not yet covered here: BUILD_TIME, BUILD_TIME_2822, BUILD_TIME_3339, BUILD_OS, BUILD_TARGET, BUILD_TARGET_ARCH. Some overlap with data already in {env_info} (Python version, OS, architecture). Others like BUILD_TIME could be added as new template fields.

… py:data:: GIT_FIELDS

module:

click_extra.version

type:

dict[str, tuple[str, …]]

value:

{‘git_branch’: (‘rev-parse’, ‘–abbrev-ref’, ‘HEAD’), ‘git_date’: (‘show’, ‘-s’, ‘–format=%ci’, ‘HEAD’), ‘git_long_hash’: (‘rev-parse’, ‘HEAD’), ‘git_short_hash’: (‘rev-parse’, ‘–short’, ‘HEAD’), ‘git_tag’: (‘describe’, ‘–tags’, ‘–exact-match’, ‘HEAD’)}

Git fields that can be pre-baked, mapped to their git subcommand args.

git_tag_sha is excluded because its resolution depends on git_tag (it runs git rev-list -1 <tag>), so it cannot be expressed as a static argument tuple.

… py:function:: run_git(*args, cwd=None)

module:

click_extra.version

Run a git command and return its stripped output, or None.

cwd defaults to the current working directory when not provided.

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\str` | :py:obj:`None``

… py:function:: prebake_version(file_path, local_version)

module:

click_extra.version

Pre-bake a __version__ string with a PEP 440 local version identifier <https://peps.python.org/pep-0440/#local-version-identifiers>_.

Reads file_path, finds the __version__ assignment via

mod:

ast, and — if the version contains .dev and does not already contain + — appends +<local_version>.

This is the compile-time complement to the runtime

attr:

ExtraVersionOption.version property: Nuitka/PyInstaller binaries cannot run git at runtime, so the hash must be baked into __version__ in the source file before compilation.

Returns the new version string on success, or None if no change was made (release version, already pre-baked, or no __version__ found).

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\str` | :py:obj:`None``

… py:function:: prebake_dunder(file_path, name, value)

module:

click_extra.version

Replace an empty dunder variable’s value in a Python source file.

Reads file_path, finds a top-level name = "" assignment via

mod:

ast, and — if the current value is an empty string — replaces it with value.

Placeholders must use empty strings (__field__ = "", not None). The AST matcher only recognizes string literals, and the empty string serves as a falsy sentinel that stays type-consistent with baked values (always str).

This is the generic counterpart to :func:prebake_version: where prebake_version appends a PEP 440 local identifier to __version__, this function does a full replacement of any dunder variable that starts empty. Typical use case: injecting a release commit SHA into __git_tag_sha__ = "" at build time.

Returns the new value on success, or None if no change was made (variable not found, or already has a non-empty value).

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\str` | :py:obj:`None``

… py:function:: discover_package_init_files()

module:

click_extra.version

Discover __init__.py files from [project.scripts].

Reads the pyproject.toml in the current working directory, extracts [project.scripts] entry points, and returns the unique __init__.py paths for each top-level package.

Only returns paths that exist on disk. Returns an empty list if pyproject.toml is missing or has no [project.scripts].

rtype:

sphinx_autodoc_typehints_type:: \:py\:class\:\list`\ \[:py:class:`~pathlib.Path`]`

… py:class:: ExtraVersionOption(param_decls=None, message=None, module=None, module_name=None, module_file=None, module_version=None, package_name=None, package_version=None, exec_name=None, version=None, git_repo_path=None, git_branch=None, git_long_hash=None, git_short_hash=None, git_date=None, git_tag=None, git_tag_sha=None, prog_name=None, env_info=None, message_style=None, module_style=None, module_name_style=Style(fg=‘bright_white’, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, text_transform=None, _style_kwargs=None), module_file_style=None, module_version_style=Style(fg=‘green’, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, text_transform=None, _style_kwargs=None), package_name_style=Style(fg=‘bright_white’, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, text_transform=None, _style_kwargs=None), package_version_style=Style(fg=‘green’, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, text_transform=None, _style_kwargs=None), exec_name_style=Style(fg=‘bright_white’, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, text_transform=None, _style_kwargs=None), version_style=Style(fg=‘green’, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, text_transform=None, _style_kwargs=None), git_repo_path_style=Style(fg=‘bright_black’, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, text_transform=None, _style_kwargs=None), git_branch_style=Style(fg=‘cyan’, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, text_transform=None, _style_kwargs=None), git_long_hash_style=Style(fg=‘yellow’, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, text_transform=None, _style_kwargs=None), git_short_hash_style=Style(fg=‘yellow’, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, text_transform=None, _style_kwargs=None), git_date_style=Style(fg=‘bright_black’, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, text_transform=None, _style_kwargs=None), git_tag_style=Style(fg=‘cyan’, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, text_transform=None, _style_kwargs=None), git_tag_sha_style=Style(fg=‘yellow’, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, text_transform=None, _style_kwargs=None), prog_name_style=Style(fg=‘bright_white’, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, text_transform=None, _style_kwargs=None), env_info_style=Style(fg=‘bright_black’, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, text_transform=None, _style_kwargs=None), is_flag=True, expose_value=False, is_eager=True, help=‘Show the version and exit.’, **kwargs)

module:

click_extra.version

Bases: :py:class:~click_extra.parameters.ExtraOption

Gather CLI metadata and prints a colored version string.

… note:: This started as a copy of the standard @click.version_option() decorator <https://github.com/pallets/click/blob/cdab890/src/click/decorators.py#L421-L524>_, but is no longer a drop-in replacement. Hence the Extra prefix.

This address the following Click issues:

- `click#2324 <https://github.com/pallets/click/issues/2324>`_,
  to allow its use with the declarative ``params=`` argument.

- `click#2331 <https://github.com/pallets/click/issues/2331>`_,
  by distinguishing the module from the package.

- `click#1756 <https://github.com/pallets/click/issues/1756>`_,
  by allowing path and Python version.

Preconfigured as a --version option flag.

type message:

:sphinx_autodoc_typehints_type:\:py\:class\:\str` | :py:obj:`None``

param message:

the message template to print, in format string syntax <https://docs.python.org/3/library/string.html#format-string-syntax>_. Defaults to {prog_name}, version {version}.

type module:

:sphinx_autodoc_typehints_type:\:py\:class\:\str` | :py:obj:`None``

param module:

forces the value of {module}.

type module_name:

:sphinx_autodoc_typehints_type:\:py\:class\:\str` | :py:obj:`None``

param module_name:

forces the value of {module_name}.

type module_file:

:sphinx_autodoc_typehints_type:\:py\:class\:\str` | :py:obj:`None``

param module_file:

forces the value of {module_file}.

type module_version: