Click Extra

https://kdeldycke.github.io/click-extra/
Admin
Click Extra is an opinionated wrapper around Click that provides colorized help screens, themes,...
Tokens:1,309,798
Snippets:8,262
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Argfile configuration format example

Source: https://kdeldycke.github.io/click-extra/_modules/click_extra/config/option.html

Shows the plain-text argfile format used by load_argfile_config, with comments starting with a hash and one option per line.

```text
# Comments start with a hash sign.
--option-name some value
--flag
```

--------------------------------

### Define command with examples and show help

Source: https://kdeldycke.github.io/click-extra/commands.html

Define a Click Extra command with usage examples and view its generated help screen. The examples appear in the help output under an 'Examples:' section, and the command lines are emitted verbatim so they can be copied.

```python
from click_extra import command, echo, option


@command(
    examples=[
        ("Report the temperature in Fahrenheit", "forecast --units fahrenheit Oslo"),
        ("Report tomorrow's forecast", "forecast --day tomorrow Oslo"),
    ]
)
@option("--units", default="celsius", help="Temperature scale to display.")
def forecast(units):
    """Report the forecast for a city."""
    echo(f"Sunny, in {units}.")

```

```shell
$ forecast --help
Usage: forecast [OPTIONS]

  Report the forecast for a city.

Options:
  --units TEXT                 Temperature scale to display.  [default: celsius]
  -h, --help                   Show this message and exit.

Configuration options:
  --config LOCATION            Location of the configuration file. Supports
                               local path with glob patterns or remote URL.
                               [default: ~/.config/forecast/]
  --no-config                  Ignore all configuration files and only use
                               command line parameters and environment
                               variables.
  --validate-config LOCATION   Validate the configuration file and exit.
  --export-config FORMAT       Export the configuration in the selected format
                               to <stdout>, then exit.

Output options:
  --accessible                 Accessibility mode: disable colors and render
                               tables in a borderless, screen-reader-friendly
                               format.
  --color [auto|always|never]  Colorize the output. A bare --color is the same
                               as --color=always.  [default: auto]
  --no-color                   Disable colorization (alias of --color=never).
  --progress / --no-progress   Show progress indicators during long operations.
                               Disabled for non-interactive output (pipes, dumb
                               terminals, CI) and by --accessible.  [default:
                               progress]
  --theme [auto|dark|dracula|light|manpage|monokai|nord|solarized-dark]
                               Color theme used for help screens.  [default:
                               dark]
  --table-format FORMAT        Rendering style of tables.  [default: rounded-
                               outline]

Logging options:
  --verbosity LEVEL            Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
                               [default: WARNING]
  -v, --verbose                Increase the default WARNING verbosity by one
                               level for each additional repetition of the
                               option.  [default: 0]
  -q, --quiet                  Decrease the default WARNING verbosity by one
                               level for each additional repetition of the
                               option.  [default: 0]
  --debug                      Shorthand for --verbosity DEBUG.

Introspection options:
  --time / --no-time           Measure and print elapsed execution time.
                               [default: no-time]
  --params                     Show all CLI parameters, their provenance,
                               defaults and value, then exit.
  --tree                       Show the tree of nested subcommands and exit.
  --man                        Read the command's manual page and exit.
  --help-format [carapace|json|json-full|man|markdown|markdown-full]
                               Render the command in the given format and exit.
  --version                    Show the version and exit.

Examples:
  Report the temperature in Fahrenheit:
    $ forecast --units fahrenheit Oslo
  Report tomorrow's forecast:
    $ forecast --day tomorrow Oslo

```

--------------------------------

### Install all extras

Source: https://kdeldycke.github.io/click-extra/install.html

Installs all extras at once.

```shell
$ uv pip install click-extra[all]

```

--------------------------------

### ARGFILE configuration file example

Source: https://kdeldycke.github.io/click-extra/config-formats.html

Example ARGFILE configuration file. Each line is a command-line option, comments start with #, and both --option value and --option=value are supported. Boolean flags use --flag and --no-flag.

```plaintext
# Print more details.
--verbose

# Repeat the operation three times, in French.
--count 3
--language fr

# A list is fed one item per occurrence.
--my-list pip
--my-list npm

```

--------------------------------

### click-extra wrap --help

Source: https://kdeldycke.github.io/click-extra/cli.html

Shows the full help output for the `click-extra wrap` command, including its options and usage examples. Use it to understand how to run or introspect any Click CLI through Click Extra, with modes like `--params`, `--man`, `--tree`, and `--help-format`. The examples illustrate running a CLI, reading subcommand help, reporting parameter sources, and installing a shell-completion spec.

```shell
$ click-extra wrap --help
Usage: click-extra wrap [OPTIONS] SCRIPT [ARGS]...
Aliases: run

  Run, or introspect, any Click CLI through Click Extra.

  By default, runs SCRIPT with keyword highlighting and themed styling for its
  help screens. The target CLI is not modified.

  With --params, --man, --tree or --help-format, SCRIPT is loaded and described
  without being run. The first three answer a question a person is asking right
  now; --help-format renders the target as an artifact for a program or a build
  step. Extra arguments after SCRIPT navigate into nested subcommands; for
  --params, any trailing options are replayed against the resolved command so
  the parameter table reports their value and source.

  Resolution order for SCRIPT: installed console_scripts entry point, a local
  project directory (its entry point is read from pyproject.toml or setup.cfg),
  Python file path, module:function notation, or Python module name.

Options:
  --params                Show the parameters of the target CLI and exit,
                          without running it.
  --man                   Read the manual page of the target CLI and exit,
                          without running it.
  --tree                  Show the tree of nested subcommands of the target CLI
                          and exit, without running it.
  --help-format [carapace|json|json-full|man|markdown|markdown-full]
                          Render the target CLI in the given format and exit,
                          without running it.
  --output-dir DIRECTORY  With --help-format, write the rendering into this
                          directory instead of printing it. Created if missing.
  --install               With --help-format, write the rendering where its
                          consumer looks for it instead of printing it, and echo
                          the written path.
  --table-format FORMAT   With --params, the rendering style of the parameter
                          table. Falls back to the click-extra group's --table-
                          format when not set here.  [default: rounded-outline]
  --columns COLUMNS       Restrict and reorder table columns, SQL SELECT-style.
                          Comma-separated list of column IDs. Default: all
                          columns in canonical order.
  -h, --help              Show this message and exit.

Examples:

  Run a CLI with Click Extra's colored help:
    $ click-extra wrap -- my-cli --help
  Read the help of one of its subcommands:
    $ click-extra wrap -- my-cli pick --help
  Report what a subcommand accepts, and where each value comes from:
    $ click-extra wrap --params -- my-cli pick
  Write a shell-completion spec where its consumer looks for it:
    $ click-extra wrap --help-format carapace --install -- my-cli

```

--------------------------------

### Install man page or Carapace spec with click-extra wrap --install

Source: https://kdeldycke.github.io/click-extra/machine-readable.html

Install a man page or Carapace spec for a Click CLI. The wrapper writes to the consumer's expected location, honoring XDG_DATA_HOME and XDG_CONFIG_HOME. Use --output-dir DIR to write elsewhere; --install is refused for other formats.

```shell
$ click-extra wrap --help-format man --install -- flask
/home/me/.local/share/man/man1/flask.1
/home/me/.local/share/man/man1/flask-run.1
$ click-extra wrap --help-format carapace --install -- flask
/home/me/.config/carapace/specs/flask.yaml

```

--------------------------------

### Install click-extra demo CLI with pipx

Source: https://kdeldycke.github.io/click-extra/install.html

Installs the demo CLI globally using pipx.

```shell
$ pipx install click-extra
```

--------------------------------

### TOML configuration file for the dataclass schema example

Source: https://kdeldycke.github.io/click-extra/config-schema.html

Example TOML file at ~/.config/my-app/config.toml that sets values for the group and its greet subcommand. The key extra-categories is hyphenated and gets normalized to extra_categories in the dataclass.

```toml
[my-app]
verbose = true
extra-categories = ["docs", "tests"]
output-format = "json"

[my-app.greet]
name = "Alice"

```

--------------------------------

### format_examples(_ctx, _formatter)

Source: https://kdeldycke.github.io/click-extra/commands.html

Writes an 'Examples:' section listing the command's examples. Each entry renders its description and the command line indented behind a '$' prompt. Command lines go out verbatim to avoid wrapping.

```APIDOC
## format_examples(_ctx, _formatter)

### Description
Writes an `Examples:` section listing the command's `examples`. Each entry renders its description, then the command line it describes, indented behind a `$` prompt. A command declaring none writes nothing at all. The command lines go out verbatim rather than through `formatter.write_text()`.

### Parameters
- **ctx** (Context) - Required - The Click context.
- **formatter** (HelpFormatter) - Required - The formatter to write to.

### Return Type
`None`
```

--------------------------------

### Initialize environment with uv and install dbt-core and aws-sam-cli

Source: https://kdeldycke.github.io/click-extra/commands.html

Initializes a virtual environment with Click Extra, dbt-core, and aws-sam-cli installed. The ellipses indicate omitted output from the commands.

```shell
$ git clone https://github.com/kdeldycke/click-extra
(...)

$ cd click-extra
(...)

$ python -m pip install uv
(...)

$ uv venv
(...)

$ source .venv/bin/activate
(...)

$ uv sync --all-extras
(...)

$ uv pip install dbt-core
(...)

$ uv pip install aws-sam-cli
(...)

```

--------------------------------

### Get ansi-color lexer by name

Source: https://kdeldycke.github.io/click-extra/pygments.html

After Click Extra installation, the ansi-color lexer is available to Pygments. Use get_lexer_by_name to retrieve it.

```python
>>> from pygments.lexers import get_lexer_by_name
>>> get_lexer_by_name("ansi-color")
<pygments.lexers.AnsiColorLexer>

```

--------------------------------

### Context.meta example: storing and retrieving language state

Source: https://kdeldycke.github.io/click-extra/_modules/click/core.html

Shows how to store and retrieve shared state in the context's meta dictionary using unique dotted keys. The example defines a module-specific key and two functions that set and get a language value, defaulting to 'en_US'.

```python
LANG_KEY = f'{__name__}.lang'

def set_language(value):
    ctx = get_current_context()
    ctx.meta[LANG_KEY] = value

def get_language():
    return get_current_context().meta.get(LANG_KEY, 'en_US')
```

--------------------------------

### Install click-extra demo CLI with uv tool

Source: https://kdeldycke.github.io/click-extra/install.html

Installs the demo CLI system-wide using uv tool.

```shell
$ uv tool install click-extra
```

--------------------------------

### Module header and imports for click_extra.pytest

Source: https://kdeldycke.github.io/click-extra/_modules/click_extra/pytest.html

The module starts with a copyright notice and imports necessary dependencies, including pytest, click, cloup, and internal modules. It raises an ImportError with a custom message if pytest is not installed.

```python
# Copyright Kevin Deldycke <kevin@deldycke.com> and contributors.
#
# This program is Free Software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
"""Pytest fixtures and marks to help testing Click CLIs."""

from __future__ import annotations

from ._utils import missing_extra_message

try:
    import pytest
except ImportError as err:
    raise ImportError(missing_extra_message("pytest", subject="This module")) from err


import difflib
import os

import click
import cloup
from extra_platforms import is_windows

from .decorators import argument, command, group, option
from .envvar import temporary_env
from .testing import (
    CliRunner,
    RegexLineMismatch,
    regex_fullmatch_line_by_line,
)

TYPE_CHECKING = False
if TYPE_CHECKING:
    from collections.abc import Iterable
    from pathlib import Path
    from typing import Any

    from _pytest.mark import MarkDecorator
    from _pytest.mark.structures import ParameterSet
```

--------------------------------

### click-extra prebake --help

Source: https://kdeldycke.github.io/click-extra/cli.html

Displays the help for the `click-extra prebake` command, which pre-bakes build-time metadata into Python source files. Lists its subcommands: all, field, help, and version.

```console
$ click-extra prebake --help
Usage: click-extra prebake [OPTIONS] COMMAND [ARGS]...

  Pre-bake build-time metadata into Python source files.

Options:
  -h, --help  Show this message and exit.

Commands:
  all      Pre-bake `__version__`, all git fields and all build fields in one...
  field    Replace an empty dunder variable with a value.
  help     Show help for a command.
  version  Inject Git commit hash into `__version__`.

```

--------------------------------

### Install Carapace spec with --install

Source: https://kdeldycke.github.io/click-extra/carapace.html

Writes the spec to the Carapace specs directory (`$XDG_CONFIG_HOME/carapace/specs/`, loaded on startup) instead of printing it. `--install` works across formats; `--output-dir` writes elsewhere, and both are refused for renderings that nothing looks for.

```shell
$ uvx --from "click-extra[carapace]" --with flask click-extra wrap --help-format carapace --install -- flask
/home/me/.config/carapace/specs/flask.yaml

```

--------------------------------

### Argfile configuration file format

Source: https://kdeldycke.github.io/click-extra/config.html

Example of a plain-text argfile configuration file. Each line holds one command-line token, with options and values separated by spaces. Comments start with a hash sign, and flags can be listed without a value.

```plaintext
# Comments start with a hash sign.
--option-name some value
--flag

```

--------------------------------

### OperationTrail.operation() usage example

Source: https://kdeldycke.github.io/click-extra/_modules/click_extra/spinner.html

Use inside a concurrent batch to time a single operation: create the handle, run the work, then call mark() with the outcome. The trail records the elapsed time automatically because the handle captured its start time on creation.

```python
def fetch(feed):
    op = trail.operation()
    ok, message = pull(feed)
    op.mark(ok, message)
```

--------------------------------

### HelpFormatOption.__init__: configure --help-format

Source: https://kdeldycke.github.io/click-extra/_modules/click_extra/command_doc.html

Constructor for the HelpFormatOption class. Sets the default parameter declaration to `--help-format`, makes it eager and non-exposing, assigns the `print_help_format` callback, and restricts the value to a `click.Choice` of sorted `HELP_FORMATS`. The help text reads "Render the command in the given format and exit.".

```python
    def __init__(
        self,
        param_decls: tuple[str, ...] | None = None,
        expose_value: bool = False,
        is_eager: bool = True,
        help: str = _("Render the command in the given format and exit."),
        **kwargs,
    ) -> None:
        if not param_decls:
            param_decls = ("--help-format",)
        kwargs.setdefault("callback", self.print_help_format)
        kwargs.setdefault("type", click.Choice(sorted(HELP_FORMATS)))
        super().__init__(
            param_decls,
            expose_value=expose_value,
            is_eager=is_eager,
            help=help,
            **kwargs,
        )

```

--------------------------------

### Install pygments extra for highlighting

Source: https://kdeldycke.github.io/click-extra/snippets.html

Installs the pygments extra required for syntax highlighting. Use uv pip install with the extra specification.

```bash
$ uv pip install click-extra[pygments]
```

--------------------------------

### Inject custom keywords with extra_keywords and show help output

Source: https://kdeldycke.github.io/click-extra/colorize.html

Use `extra_keywords` to inject additional strings for highlighting, grouped by category in a `HelpKeywords` dataclass so each gets the appropriate style. The example injects `--profile` as a long option, and the help output shows that `--profile` is highlighted in the option description. The output also displays the full help screen with all default options.

```python
from click_extra import HelpKeywords, command, echo, option

@command(
    extra_keywords=HelpKeywords(long_options={"--profile"}),
)
@option("--output", help="Write to file. See --profile for timing.")
def build(output):
    """Build the project."""
    echo("Building...")
```

```shell
$ build --help
Usage: build [OPTIONS]

  Build the project.

Options:
  --output TEXT                Write to file. See --profile for timing.
  -h, --help                   Show this message and exit.

Configuration options:
  --config LOCATION            Location of the configuration file. Supports
                               local path with glob patterns or remote URL.
                               [default: ~/.config/build/]
  --no-config                  Ignore all configuration files and only use
                               command line parameters and environment
                               variables.
  --validate-config LOCATION   Validate the configuration file and exit.
  --export-config FORMAT       Export the configuration in the selected format
                               to <stdout>, then exit.

Output options:
  --accessible                 Accessibility mode: disable colors and render
                               tables in a borderless, screen-reader-friendly
                               format.
  --color [auto|always|never]  Colorize the output. A bare --color is the same
                               as --color=always.  [default: auto]
  --no-color                   Disable colorization (alias of --color=never).
  --progress / --no-progress   Show progress indicators during long operations.
                               Disabled for non-interactive output (pipes, dumb
                               terminals, CI) and by --accessible.  [default:
                               progress]
  --theme [auto|dark|dracula|light|manpage|monokai|nord|solarized-dark]
                               Color theme used for help screens.  [default:
                               dark]
  --table-format FORMAT        Rendering style of tables.  [default: rounded-
                               outline]

Logging options:
  --verbosity LEVEL            Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
                               [default: WARNING]
  -v, --verbose                Increase the default WARNING verbosity by one
                               level for each additional repetition of the
                               option.  [default: 0]
  -q, --quiet                  Decrease the default WARNING verbosity by one
                               level for each additional repetition of the
                               option.  [default: 0]
  --debug                      Shorthand for --verbosity DEBUG.

Introspection options:
  --time / --no-time           Measure and print elapsed execution time.
                               [default: no-time]
  --params                     Show all CLI parameters, their provenance,
                               defaults and value, then exit.
  --tree                       Show the tree of nested subcommands and exit.
  --man                        Read the command's manual page and exit.
  --help-format [carapace|json|json-full|man|markdown|markdown-full]
                               Render the command in the given format and exit.
  --version                    Show the version and exit.
```

--------------------------------

### TOML configuration file example

Source: https://kdeldycke.github.io/click-extra/config.html

Example TOML configuration file for the my-cli command. It sets int_param to 3 and includes extra keys that will be ignored.

```toml
[my-cli]
int_param = 3
random_stuff = "will be ignored"

[garbage]
dummy_flag = true

```

--------------------------------

### Install click-extra with Pygments extra

Source: https://kdeldycke.github.io/click-extra/pygments.html

Install the optional Pygments components using pip. This keeps the base install lean by only pulling in Pygments and its prerequisites when needed.

```bash
$ pip install click_extra[pygments]

```

--------------------------------

### Example help output showing highlighted keywords

Source: https://kdeldycke.github.io/click-extra/colorize.html

Shows the help output of a command with various options, including color and theme options. This is the baseline output before any keyword exclusions are applied.

```bash
$ export --help
Usage: export [OPTIONS]

  Export data.

Options:
  --format [json|text]         Use json or text.
  -h, --help                   Show this message and exit.

Configuration options:
  --config LOCATION            Location of the configuration file. Supports
                               local path with glob patterns or remote URL.
                               [default: ~/.config/export/]
  --no-config                  Ignore all configuration files and only use
                               command line parameters and environment
                               variables.
  --validate-config LOCATION   Validate the configuration file and exit.
  --export-config FORMAT       Export the configuration in the selected format
                               to <stdout>, then exit.

Output options:
  --accessible                 Accessibility mode: disable colors and render
                               tables in a borderless, screen-reader-friendly
                               format.
  --color [auto|always|never]  Colorize the output. A bare --color is the same
                               as --color=always.  [default: auto]
  --no-color                   Disable colorization (alias of --color=never).
  --progress / --no-progress   Show progress indicators during long operations.
                               Disabled for non-interactive output (pipes, dumb
                               terminals, CI) and by --accessible.  [default:
                               progress]
  --theme [auto|dark|dracula|light|manpage|monokai|nord|solarized-dark]
                               Color theme used for help screens.  [default:
                               dark]
  --table-format FORMAT        Rendering style of tables.  [default: rounded-
                               outline]

Logging options:
  --verbosity LEVEL            Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
                               [default: WARNING]
  -v, --verbose                Increase the default WARNING verbosity by one
                               level for each additional repetition of the
                               option.  [default: 0]
  -q, --quiet                  Decrease the default WARNING verbosity by one
                               level for each additional repetition of the
                               option.  [default: 0]
  --debug                      Shorthand for --verbosity DEBUG.

Introspection options:
  --time / --no-time           Measure and print elapsed execution time.
                               [default: no-time]
  --params                     Show all CLI parameters, their provenance,
                               defaults and value, then exit.
  --tree                       Show the tree of nested subcommands and exit.
  --man                        Read the command's manual page and exit.
  --help-format [carapace|json|json-full|man|markdown|markdown-full]
                               Render the command in the given format and exit.
  --version                    Show the version and exit.

```

--------------------------------

### click-extra prebake all --help

Source: https://kdeldycke.github.io/click-extra/cli.html

Shows the help for the `click-extra prebake all` subcommand, which pre-bakes all git and build fields in one pass. It scans target files for empty dunder placeholders, resolves values from Git state and build host, and appends the Git short hash to `.dev` versions. The `--module` option is auto-discovered from `[project.scripts]` if not provided.

```console
$ click-extra prebake all --help
Usage: click-extra prebake all [OPTIONS]

  Pre-bake `__version__`, all git fields and all build fields in one pass.

  Scans each target file for empty `__<field>__` dunder placeholders, resolves
  their values from the current Git state and build host, and injects them.

  Also appends the Git short hash to `.dev` versions in `__version__` (same as
  `prebake version`).

  Supported git fields:
      git_branch, git_long_hash, git_short_hash, git_date, git_tag

  Supported build fields:
      build_time, build_os, build_target, build_target_arch

  Additional computed fields (`__git_tag_sha__`, `__git_distance__`,
  `__git_dirty__`) are baked if their dunder placeholder exists and a git
  resolution is available. Fields without a placeholder in the source file
  are skipped silently.

Options:
  --module PATH  Path to __init__.py to modify. Auto-discovered from
                 [project.scripts] if not provided.
  -h, --help     Show this message and exit.

```

--------------------------------

### Install click-extra with pytest extra group

Source: https://kdeldycke.github.io/click-extra/pytest.html

Install the additional dependencies required for the click_extra.pytest helpers using uv pip install with the pytest extra group.

```bash
$ uv pip install click-extra[pytest]
```

--------------------------------

### documented command with examples

Source: https://kdeldycke.github.io/click-extra/_modules/tests/test_command_doc.html

Defines a command with two usage examples, a positional argument, and an option with a Choice type. The examples show how to report the forecast in Fahrenheit and the default forecast.

```python
@command(
    examples=[
        ("Report the forecast in Fahrenheit", "weather Oslo --units fahrenheit"),
        ("Report the default forecast", "weather Oslo"),
    ]
)
@argument("city", help="The city to report on.")
@option("--units", type=Choice(["celsius", "fahrenheit"]), help="Temperature scale.")
def documented(city, units):
    """Report the forecast for a CITY."""
```

--------------------------------

### click-extra prebake help --help

Source: https://kdeldycke.github.io/click-extra/cli.html

Shows the help for the `click-extra prebake help` subcommand, which displays help for a command. It accepts an optional COMMAND_PATH and a `--search` option to search all subcommands for matching options or descriptions.

```console
$ click-extra prebake help --help
Usage: click-extra prebake help [OPTIONS] [COMMAND_PATH]...

  Show help for a command.

Options:
  --search TEXT  Search all subcommands for matching options or descriptions.
  -h, --help     Show this message and exit.

```
Tokens:
Raw