click_extra package ¶

list_sections(ctx, include_default_section=True)[source]¶

Return the list of all sections in the “correct order”.

If include_default_section=True and the default section is non-empty, it will be included at the end of the list.

Return type:: List[Section]

format_subcommand_name(ctx, name, cmd)[source]¶

Used to format the name of the subcommands. This method is useful when you combine this extension with other click extensions that override format_commands(). Most of these, like click-default-group, just add something to the name of the subcommands, which is exactly what this method allows you to do without overriding bigger methods.

Return type:: str

make_commands_help_section(ctx, section)[source]¶

Return type:: HelpSection | None

must_align_sections(ctx, default=True)[source]¶

Return type:: bool

format_commands(ctx, formatter)[source]¶

Return type:: None

class click_extra.ShowParamsOption(param_decls=None, is_flag=True, expose_value=False, is_eager=True, help='Show all CLI parameters, their provenance, defaults and value, then exit.', **kwargs)[source]¶

Bases: ExtraOption, ParamStructure

A pre-configured option adding a --params option.

Between configuration files, default values and environment variables, it might be hard to guess under which set of parameters the CLI will be executed. This option print information about the parameters that will be fed to the CLI.

Note

The flag is named --params, not --show-params. It names the view it prints, matching the neighbouring bare-noun informational flags (--help, --version, --man, --tree), none of which carry a show- verb prefix. The class and @show_params_option decorator keep their historical names: the class is named for what it does (show the parameters), while the flag and the parameter’s ID use the bare noun.

TABLE_HEADERS: ClassVar[tuple[_ColumnSpec, ...]] = (ColumnSpec(id='id', label='ID', description='Fully-qualified parameter path (`cli.subcommand.param_name`) derived from the [`click.Command`](https://click.palletsprojects.com/en/stable/api/#click.Command) tree. Doubles as the key used to address the parameter from a configuration file, which also accepts the kebab-case spelling of the last segment.', max_width=None, optional=False), ColumnSpec(id='spec', label='Spec.', description='Option/argument specification string (like `-v, --verbose`) extracted from [`click.Parameter.get_help_record()`](https://click.palletsprojects.com/en/stable/api/#click.Parameter).', max_width=None, optional=False), ColumnSpec(id='help', label='Help', description="The parameter's own help text, as written by the CLI author. Opt-in: it is the only column carrying free-form prose, so it stays out of the default table and is selected by ID (`--columns id,spec,help`). Structured formats are its main audience: it turns a `--params` dump into a self-describing inventory a tool or an agent can read without also parsing the rendered `--help` screen.", max_width=None, optional=True), ColumnSpec(id='class', label='Class', description="Fully-qualified class of the parameter: a subclass of [`click.Option`](https://click.palletsprojects.com/en/stable/api/#click.Option), [`click.Argument`](https://click.palletsprojects.com/en/stable/api/#click.Argument), [`cloup.Option`](https://cloup.readthedocs.io/en/stable/autoapi/cloup/index.html#cloup.Option), or one of Click Extra's own wrappers ([`click_extra.parameters.Option`](#click_extra.parameters.Option), [`click_extra.parameters.Argument`](#click_extra.parameters.Argument), [`click_extra.parameters.ExtraOption`](#click_extra.parameters.ExtraOption)).", max_width=None, optional=False), ColumnSpec(id='param_type', label='Param type', description='Click value converter class: a subclass of [`click.ParamType`](https://click.palletsprojects.com/en/stable/api/#click.ParamType) like [`click.IntRange`](https://click.palletsprojects.com/en/stable/api/#click.IntRange), [`click.Choice`](https://click.palletsprojects.com/en/stable/api/#click.Choice), or a Click Extra type.', max_width=None, optional=False), ColumnSpec(id='python_type', label='Python type', description='Python built-in type the parsed value resolves to: [`str`](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), [`int`](https://docs.python.org/3/library/functions.html#int), [`float`](https://docs.python.org/3/library/functions.html#float), [`bool`](https://docs.python.org/3/library/functions.html#bool), or [`list`](https://docs.python.org/3/library/stdtypes.html#list). Computed by [`ParamStructure.get_param_type()`](#click_extra.parameters.ParamStructure.get_param_type) from the Click `Param type`.', max_width=None, optional=False), ColumnSpec(id='hidden', label='Hidden', description="Reflects [`click.Option`'s `hidden`](https://click.palletsprojects.com/en/stable/api/#click.Option) constructor argument: the option is omitted from `--help` output. Empty for [`click.Argument`](https://click.palletsprojects.com/en/stable/api/#click.Argument), which does not support hiding.", max_width=None, optional=False), ColumnSpec(id='exposed', label='Exposed', description="Reflects [`click.Parameter`'s `expose_value`](https://click.palletsprojects.com/en/stable/api/#click.Parameter) constructor argument: whether the parsed value is forwarded to the command callback. Eager options like `--params` and `--help` typically run a callback and exit, so they are not exposed.", max_width=None, optional=False), ColumnSpec(id='allowed_in_conf', label='Allowed in conf?', description='Click Extra-specific: whether the parameter is reachable from a configuration file. Controlled by [`ParamStructure.excluded_params`](#click_extra.parameters.ParamStructure.excluded_params) and [`included_params`](#click_extra.parameters.ParamStructure.included_params). Empty when the CLI has no [`--config` option](config.md).', max_width=None, optional=False), ColumnSpec(id='envvars', label='Env. vars.', description="Environment variables read for this parameter: the explicit [`click.Parameter`'s `envvar`](https://click.palletsprojects.com/en/stable/api/#click.Parameter) plus the auto-resolved IDs documented in [Environment variables](envvar.md).", max_width=None, optional=False), ColumnSpec(id='default', label='Default', description='Default value returned by [`click.Parameter.get_default()`](https://click.palletsprojects.com/en/stable/api/#click.Parameter.get_default), rendered as its Python `repr()`.', max_width=None, optional=False), ColumnSpec(id='is_flag', label='Is flag', description="Reflects [`click.Option`'s `is_flag`](https://click.palletsprojects.com/en/stable/api/#click.Option): whether the option behaves as a flag (no value taken from the command line). Empty for [`click.Argument`](https://click.palletsprojects.com/en/stable/api/#click.Argument).", max_width=None, optional=False), ColumnSpec(id='flag_value', label='Flag value', description="Reflects [`click.Option`'s `flag_value`](https://click.palletsprojects.com/en/stable/api/#click.Option): the Python value substituted for the option when its flag is used. Defaults to `True` for boolean flags, can be any value for flag-value style options (like `@option('--upper', 'transform', flag_value='upper')`).", max_width=None, optional=False), ColumnSpec(id='is_bool_flag', label='Is bool flag', description='Reflects `click.Option.is_bool_flag` (set internally by Click when `flag_value` is `True` or `False`): the option is a *true* boolean flag, as opposed to a flag-value style option.', max_width=None, optional=False), ColumnSpec(id='multiple', label='Multiple', description="Reflects [`click.Parameter`'s `multiple`](https://click.palletsprojects.com/en/stable/api/#click.Parameter): the parameter can be repeated on the command line, collecting values into a tuple.", max_width=None, optional=False), ColumnSpec(id='nargs', label='Nargs', description="Reflects [`click.Parameter`'s `nargs`](https://click.palletsprojects.com/en/stable/api/#click.Parameter): the number of CLI tokens the parameter consumes. `1` is the default; `-1` denotes a variadic argument.", max_width=None, optional=False), ColumnSpec(id='prompt', label='Prompt', description="Reflects [`click.Option`'s `prompt`](https://click.palletsprojects.com/en/stable/api/#click.Option): the text shown to the user when the option is not provided on the command line. Empty when no prompt is configured.", max_width=None, optional=False), ColumnSpec(id='confirmation_prompt', label='Confirmation prompt', description="Reflects [`click.Option`'s `confirmation_prompt`](https://click.palletsprojects.com/en/stable/api/#click.Option): whether the user is asked to enter the value twice for confirmation.", max_width=None, optional=False), ColumnSpec(id='value', label='Value', description='Current value of the parameter at invocation time, computed by [`click.Parameter.consume_value()`](https://click.palletsprojects.com/en/stable/api/#click.Parameter) from the merged sources (CLI, environment, config file, default).', max_width=None, optional=False), ColumnSpec(id='source', label='Source', description='Provenance of the resolved value: a [`click.core.ParameterSource`](https://click.palletsprojects.com/en/stable/api/#click.core.ParameterSource) enum member such as `COMMANDLINE`, `ENVIRONMENT`, `DEFAULT_MAP`, or `DEFAULT`.', max_width=None, optional=False), ColumnSpec(id='config_file', label='Config file', description='The configuration file the effective value was loaded from, when `Source` reports `DEFAULT_MAP`. With [`cascade=True`](config.md#cascading-configuration-files) several files are layered and this column names the one that won the parameter; with a single loaded file, every config-sourced parameter names that file. Empty for every other source and when no configuration file was loaded. Opt-in, like `help`: paths are wide and stay redundant with `Source` until several files take part.', max_width=None, optional=True))¶

Rich column registry for the --params table.

Each entry is a click_extra.table.ColumnSpec carrying the column’s stable id (used by --columns and as structured-format key), its display label, and a MyST/Markdown description consumed by the documentation’s auto-generated Available columns section. Iteration yields columns in canonical display order.

classmethod column_labels()[source]¶

Return just the display labels of TABLE_HEADERS (in order).

Return type:: tuple[str, ...]

classmethod column_ids()[source]¶

Return just the stable IDs of TABLE_HEADERS (in order).

Return type:: tuple[str, ...]

classmethod default_columns()[source]¶

Return the columns rendered when --columns asks for no projection.

Every column but the optional ones, which stay addressable by ID and out of the way until named.

Return type:: tuple[_ColumnSpec, …]

classmethod default_column_ids()[source]¶

Return the stable IDs of default_columns() (in order).

Return type:: tuple[str, ...]

classmethod default_column_labels()[source]¶

Return the display labels of default_columns() (in order).

Return type:: tuple[str, ...]

classmethod find_column(column_id)[source]¶

Return the ColumnSpec matching column_id.

Raises KeyError if no column has this ID; callers should convert the error into a click.UsageError when surfaced to a user.

classmethod render_doc_table()[source]¶

Render TABLE_HEADERS as a Markdown table for documentation.

Used by the show_params_columns_table MyST substitution in docs/conf.py to feed the Available columns section of docs/parameters.md: editing a description here automatically rebuilds the docs table on the next sphinx-build.

Return type:: str

excluded_params¶: Deactivates the blocking of any parameter.

included_params¶: No allowlist filter; show all parameters.

print_params(ctx, param, value)[source]¶

Introspect the current CLI and print its parameter metadata table.

Thin wrapper over render_params_table(), the shared rendering core also driving click-extra wrap --params for foreign CLIs. The live invocation context carries everything the core needs: the captured RAW_ARGS (attached by Command/Group) for value and source resolution, plus any sibling --table-format / --columns options.

Return type:: None

exception click_extra.SkippedTest[source]¶

Bases: Exception

Raised when a test case should be skipped.

class click_extra.SortByOption(*header_defs, param_decls=None, columns=None, default=None, expose_value=False, cell_key=None, help='Sort table by this column. Repeat to set priority.', **kwargs)[source]¶

Bases: ExtraOption

A --sort-by option whose choices are derived from column definitions.

Stores the selected column IDs in ctx.meta[click_extra.context.SORT_BY] and publishes the derived row sort key in ctx.meta[click_extra.context.TABLE_SORT_KEY], which ctx.print_table picks up so that table output is automatically sorted, without changing its (table_data, headers) call contract. The option accepts multiple=True, so users can repeat --sort-by to define a multi-column sort priority.

Column definitions may be ColumnSpec instances or raw (label, column_id) tuples, passed positionally or via the columns= keyword. Passing a ColumnSpec registry via columns= lets the same tuple drive both ColumnsOption (--columns) and --sort-by, so the two options stay in sync from a single source of truth.

COLUMNS = (
    ColumnSpec("package_id", "Package ID"),
    ColumnSpec("package_name", "Name"),
    ColumnSpec("manager_id", "Manager"),
)


@command
@table_format_option
@columns_option(columns=COLUMNS)
@sort_by_option(columns=COLUMNS)
@pass_context
def my_cmd(ctx):
    ctx.print_table(rows, [col.label for col in COLUMNS])

Definitions may instead be bare column ID strings, declaring a field vocabulary untied to any single table layout. This fits a --sort-by declared once on a group whose subcommands render heterogeneous tables: no sort key is published since no layout is known up front. The selection is resolved per table by print_table(), from the column IDs its headers carry — each table sorts by the selected fields it knows (remaining columns breaking ties left to right) and keeps its original row order when it knows none.

@group
@sort_by_option("package_id", "package_name", "manager_id")
def my_cli():
    pass


@my_cli.command
def installed():
    print_table(rows, [("Package ID", "package_id"), ("Manager", "manager_id")])


@my_cli.command
def managers():
    print_table(rows, [("Manager", "manager_id"), ("Path", None)])

field_vocabulary¶

Whether definitions are bare column IDs, untied to any table layout.

In this mode init_sort() only publishes the selection on the context: the sort is resolved per table at print_table() time.

init_sort(ctx, param, sort_columns)[source]¶

Publish the row sort key on the context’s shared meta.

Builds the sort key from this option’s column definitions and the selected sort_columns, then stores it under ctx.meta[click_extra.context.TABLE_SORT_KEY], where ctx.print_table picks it up. The call contract is the same sorted or not: ctx.print_table(table_data, headers).

In field-vocabulary mode no table layout is known at declaration time, so no key is published: only the selection lands on the context (ctx.meta is shared with every subcommand), resolved per table by print_table() from the column IDs its headers carry.

Return type:: None

class click_extra.Spinner(label='', *, frames=None, spinner=None, reverse=False, interval=None, delay=0.0, style=None, timer=False, stream=None, enabled=None, hide_cursor=True, beep=False)[source]¶

Bases: object

A thread-animated, indeterminate progress spinner usable as a context manager.

The animation runs on a background daemon thread, leaving the calling thread free to block on the actual work. Entering the context (or calling start()) begins the animation; leaving it (or calling stop()) halts the thread and erases the spinner line so it never lingers above the next output.

Note

A single Spinner instance drives one animation at a time. mpm and similar tools run their subprocesses sequentially, so one shared instance whose label is reassigned between steps is enough; for concurrent work, use one instance per thread.

Configure (but do not start) the spinner.

Parameters:

label (str | Callable[..., Any]) – text shown after the spinner glyph. As a special case, a bare @Spinner decorator passes the wrapped function here instead; it is detected and the label defaults to empty.
frames (Sequence[str] | None) – the animation frames, cycled in order. Defaults to SPINNER_FRAMES, or the spinner preset’s frames when given.
spinner (SpinnerPreset | None) – a SpinnerPreset from the SPINNERS catalog (spinner=SPINNERS["moon"]), supplying both frames and a tuned interval. An explicit frames or interval still overrides it.
reverse (bool) – cycle the frames backwards, spinning the animation the other way. Set it when the rotation runs counter to what you expect; it composes with any custom frames.
interval (float | None) – seconds between two frames. Defaults to 0.1, or the spinner preset’s interval when given.
delay (float) – seconds to wait before drawing the first frame. A non-zero delay keeps the spinner silent for calls that finish quickly, so it only surfaces once an operation is genuinely slow.
style (Style | None) – a Style applied to the spinner glyph, label and timer (Style(fg="cyan", bold=True)). Color is decoupled from animation: --no-color / NO_COLOR strip it while the spinner keeps spinning (see ProgressOption).
timer (bool | Callable[[float], str]) – append the elapsed wall-clock time to the spinner, and to any final ok() / fail() line. True uses format_duration() for the default compact format (2.3s, 1:05, then 1:02:03). Pass a callable (seconds: float) -> str to format the duration yourself, like timer=lambda s: f"{s / 60:.0f}m" for whole minutes.
stream (IO[str] | None) – where to draw; defaults to sys.stderr so the spinner never mixes into stdout data.
enabled (bool | None) – force the spinner on or off. None (the default) auto-detects, animating only when stream is a TTY.
hide_cursor (bool) – hide the text cursor while spinning and restore it on stop.
beep (bool) – ring the terminal bell once when the spinner stops. It fires only when the spinner was active, so a disabled or redirected spinner stays silent.

Raises:

ValueError – if style carries a color or attribute that cannot be rendered.

label: str¶

Text drawn after the spinner glyph.

Reassign it at any time while the spinner runs to reflect the current step; the animation thread reads it afresh on every frame.

property elapsed_time: float¶

Seconds elapsed since start(), frozen once stop() is called.

Returns 0.0 before the spinner has started.

property shown: bool¶

Whether the spinner has drawn at least one frame to its stream.

True only once an animation frame was actually rendered. It stays False for a disabled spinner (off a TTY, on a TERM=dumb terminal, or with enabled=False) and for a call that finishes within delay, before the first frame. Reset by start().

Use it to gate output that should mirror the spinner’s visibility. ok() and fail() write their line unconditionally, so an outcome is still recorded in a pipe or log; guard them with shown when you only want the finisher on screen after a spinner the user actually saw:

with Spinner("Baking bread") as spinner:
    bake()
    if spinner.shown:
        spinner.ok()

start()[source]¶

Begin animating on a background thread, unless the spinner is disabled.

A disabled spinner (non-TTY stream, or enabled=False) returns at once without spawning a thread or emitting anything (but still records the start time, so a later ok() / fail() can report a duration).

Return type:: None

stop()[source]¶

Halt the animation and erase the spinner line.

Idempotent and safe to call when the spinner never started. Restores the cursor and clears the line only if the animation actually drew to the terminal.

Return type:: None

echo(message='')[source]¶

Print message on its own line above the running spinner.

Click’s click.progressbar() and a bare print both fight the animation: a frame drawn between the cursor returns and the text mangles the line. echo() takes the same draw lock as the animation thread, erases the in-progress frame, writes message followed by a newline, and lets the next tick redraw the spinner underneath. It is safe to call from another thread while the spinner runs.

Output goes to the spinner’s own stream (stderr by default), so results written to stdout never need it. When the spinner is not animating (disabled, or a non-TTY stream), it degrades to a plain write of message with no control codes.

Return type:: None

ok(symbol=None, *, style=None)[source]¶

Stop the spinner and leave a persistent success line on screen.

Where stop() erases the spinner, ok() replaces the final frame with symbol followed by the current label (and the elapsed time when timer is set), then keeps that line. symbol defaults to the themed success glyph OK_GLYPH (✓), painted with the active theme’s success slot unless style overrides it. Color is stripped under --no-color / NO_COLOR; the glyph stays.

Return type:: None

fail(symbol=None, *, style=None)[source]¶

Stop the spinner and leave a persistent failure line on screen.

The failure counterpart of ok(), defaulting to KO_GLYPH (✘) painted with the active theme’s error slot.

Return type:: None

class click_extra.SpinnerPreset(frames: tuple[str, ...], interval: float)[source]¶

Bases: NamedTuple

A named spinner animation: its frames and the interval they look best at.

The SPINNERS catalog is ported from cli-spinners, with intervals converted from milliseconds to seconds. Pass one to Spinner via its spinner argument.

Create new instance of SpinnerPreset(frames, interval)

frames: tuple[str, ...]¶: The animation frames, cycled in order.

interval: float¶: Seconds between two frames, tuned per spinner upstream.

class click_extra.StreamHandler(stream=None)[source]¶

Bases: StreamHandler

A handler to output logs to the console.

Wraps logging.StreamHandler, but use click.echo() to support color printing.

Only <stderr> or <stdout> are allowed as output stream.

If stream is not specified, <stderr> is used by default

Initialize the handler.

If stream is not specified, sys.stderr is used.

property stream: IO[Any]¶

The stream to which logs are written.

A proxy of the parent logging.StreamHandler’s stream attribute.

Redefined here to enforce checks on the stream value.

emit(record)[source]¶

Use click.echo() to print to the console.

Cooperates with any live terminal line currently drawing on the same stream (a Spinner, or an OperationTrail progress bar): the record is then printed through its echo, which erases the in-progress render first, so a log line emitted mid-draw lands on its own line instead of garbling the indicator (and vice versa).

The color tri-state is resolved through invocation_color() rather than left to click.echo()’s own context lookup: a record emitted from a background thread (a subprocess stream reader, a fan-out worker) has no reachable Click context, and would otherwise ignore --no-color and keep its ANSI codes on a TTY.

Return type:: None

class click_extra.Style(fg=None, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, text_transform=None)[source]¶

Bases: Style

cloup.Style with extra ergonomics.

See the module docstring for the full list of additions. The runtime contract (calling the instance to apply styling, equality, hashing, with_()) is otherwise identical to cloup.Style.

fg: str | tuple[int, int, int] | int | None = None¶: Foreground color: named ANSI string, #rrggbb hex, RGB tuple, or palette index.

bg: str | tuple[int, int, int] | int | None = None¶: Background color: named ANSI string, #rrggbb hex, RGB tuple, or palette index.

cascade(base)[source]¶

Return a copy with None fields filled in from base.

The instance’s own non-None values always win: cascade only fills gaps. Useful for theme inheritance: derived.cascade(parent) keeps derived’s overrides and inherits the rest from parent.

Return type:: Style

to_dict()[source]¶

Serialize to a plain dict with only the set fields.

RGB tuples are emitted as #rrggbb strings so the result round-trips through TOML/JSON/YAML untouched. Pair with from_dict() to rebuild a Style.

Return type:: dict[str, Any]

classmethod from_dict(data)[source]¶

Build a Style from the plain dict produced by to_dict().

Validates that every key in data names a known Style field and raises TypeError otherwise. Pair with to_dict() to round-trip through TOML/JSON/YAML.

Return type:: Style

to_css()[source]¶

Render the style as a semicolon-separated CSS declaration list.

Style(fg="#f1fa8c", bold=True).to_css() returns "color: #f1fa8c; font-weight: bold". Suitable for inline style="..." attributes on HTML spans.

Return type:: str

classmethod from_ansi(escape)[source]¶

Parse one or more consecutive ANSI SGR escapes into a Style.

Supports the standard 8/16-color codes (30–37, 40–47, 90–97, 100–107), the 38;5;n / 48;5;n 256-color extension, and the 38;2;r;g;b / 48;2;r;g;b 24-bit extension. Reset codes (the full 0 reset, its parameter-less \x1b[m form included, and selective resets like 22, 39 or 49) are ignored, so parsing the full output of a style call (trailing reset included) recovers that style. Multiple back-to-back escapes (as click emits when combining colors with attributes: \x1b[31m\x1b[1m) are merged into a single Style.

To tokenize a string mixing text and escapes, with resets honored, see split_ansi().

Return type:: Style

contrast_ratio(other)[source]¶

Return the WCAG 2.x contrast ratio between this fg and other’s fg.

Result is in [1, 21]: 1 = identical colors (no contrast), 21 = maximum contrast (black on white). WCAG AA requires 4.5+ for normal text, 3.0+ for large text; AAA wants 7.0+ and 4.5+ respectively.

Return type:: float

class click_extra.TableFormat(*values)[source]¶

Bases: 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.

ALIGNED = 'aligned'¶

ASCIIDOC = 'asciidoc'¶

COLON_GRID = 'colon-grid'¶

CSV = 'csv'¶

CSV_EXCEL = 'csv-excel'¶

CSV_EXCEL_TAB = 'csv-excel-tab'¶

CSV_UNIX = 'csv-unix'¶

DOUBLE_GRID = 'double-grid'¶

DOUBLE_OUTLINE = 'double-outline'¶

FANCY_GRID = 'fancy-grid'¶

FANCY_OUTLINE = 'fancy-outline'¶

GITHUB = 'github'¶

GRID = 'grid'¶

HEAVY_GRID = 'heavy-grid'¶

HEAVY_OUTLINE = 'heavy-outline'¶

HJSON = 'hjson'¶

HTML = 'html'¶

JIRA = 'jira'¶

JSON = 'json'¶

JSON5 = 'json5'¶

JSONC = 'jsonc'¶

LATEX = 'latex'¶

LATEX_BOOKTABS = 'latex-booktabs'¶

LATEX_LONGTABLE = 'latex-longtable'¶

LATEX_RAW = 'latex-raw'¶

MEDIAWIKI = 'mediawiki'¶

MIXED_GRID = 'mixed-grid'¶

MIXED_OUTLINE = 'mixed-outline'¶

MOINMOIN = 'moinmoin'¶

ORGTBL = 'orgtbl'¶

OUTLINE = 'outline'¶

PIPE = 'pipe'¶

PLAIN = 'plain'¶

PRESTO = 'presto'¶

PRETTY = 'pretty'¶

PSQL = 'psql'¶

ROUNDED_GRID = 'rounded-grid'¶

ROUNDED_OUTLINE = 'rounded-outline'¶

RST = 'rst'¶

SIMPLE = 'simple'¶

SIMPLE_GRID = 'simple-grid'¶

SIMPLE_OUTLINE = 'simple-outline'¶

TEXTILE = 'textile'¶

TOML = 'toml'¶

TSV = 'tsv'¶

UNSAFEHTML = 'unsafehtml'¶

VERTICAL = 'vertical'¶

XML = 'xml'¶

YAML = 'yaml'¶

YOUTRACK = 'youtrack'¶

property is_markup: bool¶

Whether this format is a markup rendering.

ANSI codes never reach a markup rendering raw: they are either translated to the format’s native styling (see supports_styling) or stripped from cell values. Forcing --color on the command line preserves them as-is in the markup formats without styling support.

property supports_styling: bool¶

Whether ANSI codes are translated to this format’s native styling.

See STYLED_FORMATS for the registry, and the rationale behind each excluded markup format.

property is_wrappable: bool¶

Whether this format renders a cell wrapped onto several lines.

See WRAPPABLE_FORMATS for the registry, and the rationale behind each excluded format.

class click_extra.TableFormatOption(param_decls=None, type=EnumChoice('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'), default=TableFormat.ROUNDED_OUTLINE, expose_value=False, is_eager=True, help='Rendering style of tables.', **kwargs)[source]¶

Bases: ExtraOption

A pre-configured option that is adding a --table-format flag to select the rendering style of a table.

The selected table format ID is made available in the context in ctx.meta[click_extra.context.TABLE_FORMAT], where the render_table() and print_table() context methods pick it up as their default format. ctx.meta is shared along the context chain, so declaring this option on a group makes the selected format reach every subcommand:

ctx.render_table(table_data, headers, **kwargs): renders and returns the table as a string,
ctx.print_table(table_data, headers, **kwargs): renders and prints the table to the console.

Where:

table_data is a 2-dimensional iterable of iterables for rows and cells values,
headers is a list of string to be used as column headers,
**kwargs are any extra keyword arguments supported by the underlying table formatting function.

init_formatter(ctx, param, table_format)[source]¶

Save the resolved table_format in the context’s shared meta.

The render_table() and print_table() context methods read it back at call time.

Return type:: None

class click_extra.TelemetryOption(param_decls=None, default=False, expose_value=False, envvar=None, show_envvar=True, help='Collect telemetry and usage data.', **kwargs)[source]¶

Bases: ExtraOption

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

Respects the proposed DO_NOT_TRACK environment variable as a unified standard to opt-out of telemetry for TUI/console apps: a truthy DO_NOT_TRACK forces telemetry off, overriding the user-defined environment variables, the auto-generated values, and configuration files. Only an explicit --telemetry on the command line outranks it.

The resolved value is stored in ctx.meta[click_extra.context.TELEMETRY], aligning with every other Click Extra option’s per-invocation context-meta storage pattern.

See also

set_telemetry(ctx, param, value)[source]¶

Reconcile the flag with DO_NOT_TRACK and store the result on ctx.meta.

An explicit --telemetry/--no-telemetry on the command line wins. Otherwise a truthy DO_NOT_TRACK (bare presence, or any value not parseable as false, in the permissive spirit of the color environment variables) forces telemetry off. Read via click_extra.context.get(ctx, click_extra.context.TELEMETRY).

Note

DO_NOT_TRACK is read here rather than wired through the option’s envvar: Click’s environment plumbing feeds the raw value straight to the boolean flag, so DO_NOT_TRACK=1 would enable telemetry, inverting the convention. Reading it manually keeps the opt-out meaning, mirroring how ColorOption reads NO_COLOR and friends.

Return type:: None

class click_extra.ThemeOption(param_decls=None, default='dark', is_eager=True, expose_value=False, query_background=False, help='Color theme used for help screens.', **kwargs)[source]¶

Bases: ExtraOption

A pre-configured option that adds --theme to select the help-screen palette.

Accepts any name registered in theme_registry or in the per-invocation overrides loaded by ConfigOption from [tool.<cli>.themes.<name>]. Validation goes through ThemeChoice, which reads the live registry at parse time, so config-defined themes appear as valid choices and in the --help metavar without any further wiring.

The resolved HelpTheme lands on the Click context under click_extra.context.THEME and applies for the duration of the current invocation only.

A user who never passes the flag can still pick a palette by exporting THEME_ENVVAR (CLICK_EXTRA_THEME), which is honored by every Click Extra CLI at once. See set_theme() for how it ranks against the flag, the <CLI>_THEME variable and the configuration file.

The reserved value AUTO_THEME (--theme=auto) is also accepted on every CLI: it resolves the palette from the terminal background via resolve_auto_theme() instead of naming a registered theme. Background detection reads environment variables by default; pass query_background=True to additionally allow the live OSC 11 terminal query (query_osc_background()), which is opt-in because it reads stdin.

set_theme(ctx, param, value)[source]¶

Resolve the chosen theme name and store it on the Click context.

ThemeChoice has already validated value against the live registry (or accepted the AUTO_THEME directive) by the time this fires. A plain palette name is looked up unconditionally; auto is resolved from the terminal background via resolve_auto_theme(), leaving ctx.meta untouched when no palette can be resolved so get_current_theme() keeps its default.

Before that, THEME_ENVVAR is consulted when the value still comes from the option’s own default, which yields the precedence: --theme > <CLI>_THEME > configuration file > CLICK_EXTRA_THEME > built-in default. The global variable therefore only names the palette of the CLIs nothing else has an opinion about.

Note

The variable is read here rather than wired through the option’s envvar. Click resolves an explicit envvar before the auto-generated <CLI>_THEME, which would let the machine-wide preference outrank the CLI-specific one, and would list both names in the --params table, making the combined string the widest cell of its column. This mirrors how AccessibleOption reads ACCESSIBLE and ColorOption reads NO_COLOR.

An unparsable palette name is a warning, not an error: a typo in a shell profile would otherwise break every Click Extra CLI on the machine at once, including the ones needed to fix it.

Return type:: None

class click_extra.TimerOption(param_decls=None, default=False, expose_value=False, is_eager=True, help='Measure and print elapsed execution time.', **kwargs)[source]¶

Bases: 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.context.START_TIME].

print_timer()[source]¶

Compute and print elapsed execution time.

Always prints, even when a sibling eager option (--version, --params, --show-config…) short-circuited the command body via ctx.exit(). That makes --time a usable probe for the cost of Click Extra’s own machinery (option parsing, config loading, eager callbacks), not just user command bodies.

Return type:: None

init_timer(ctx, param, value)[source]¶

Set up the execution-timer machinery for the current invocation.

Captures time.perf_counter() as the start time, stores it on ctx.meta under click_extra.context.START_TIME, and queues print_timer() as a context-close callback so the elapsed duration is printed even when a sibling eager option (--version, --params…) short-circuits the command body.

Return type:: None

class click_extra.TreeOption(param_decls=None, is_flag=True, expose_value=False, is_eager=True, help='Show the tree of nested subcommands and exit.', **kwargs)[source]¶

Bases: ExtraOption

A pre-configured --tree flag that prints the hierarchy of nested subcommands and exits.

Eager and value-less, like ManOption. Part of the default option set injected by default_params(), so every @command and @group exposes it. Use @tree_option to add it to a plain Click CLI.

Note

The flag is named --tree, not --show-tree or --commands.

Rendering a hierarchy as a tree is conventionally named tree across ecosystems: eza --tree, lsblk --tree, poetry show --tree, cargo tree, pstree(1) and tree(1) itself (ps --forest being the lone dissenter). --commands would suggest the flat listing --help already provides.

The bare noun also lines up with the neighbouring --man, --version and --help informational flags; --params is the historical outlier, not the pattern. A flag was preferred over a registered tree subcommand, which could collide with the user’s own command namespace.

print_tree(ctx, param, value)[source]¶: Render and print the invoked command’s subcommand tree, then exit.

class click_extra.Tuple(types)[source]¶

Bases: CompositeParamType[tuple[Any, …]]

The default behavior of Click is to apply a type on a value directly. This works well in most cases, except for when nargs is set to a fixed count and different types should be used for different items. In this case the Tuple type can be used. This type can only be used if nargs is set to a fixed number.

For more information see Multi Value Options as Tuples.

This can be selected by using a Python tuple literal as a type.

Parameters:: types (Sequence[type[Any] | ParamType[Any]]) – a list of types that should be used for the tuple items.

types: Sequence[ParamType[Any]]¶

to_info_dict()[source]¶

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

Use click.Context.to_info_dict() to traverse the entire CLI structure.

Added in version 8.0.

Return type:: TupleInfoDict

property name: str¶

property arity: int¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

convert(value, param, ctx)[source]¶

Convert the value to the correct type. This is not called if the value is None (the missing value).

This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.

The param and ctx arguments may be None in certain situations, such as when converting prompt input.

If the value cannot be converted, call fail() with a descriptive message.

Parameters:

value (t.Any) – The value to convert.
param (Parameter | None) – The parameter that is using this type to convert its value. May be None.
ctx (Context | None) – The current context that arrived at this value. May be None.

Return type:

tuple[t.Any, …]

exception click_extra.UsageError(message, ctx=None)[source]¶

Bases: ClickException

An internal exception that signals a usage error. This typically aborts any further handling.

Parameters:

message (str) – the error message to display.
ctx (Context | None) – optionally the context that caused this error. Click will fill in the context automatically in some situations.

exit_code: t.ClassVar[int] = 2¶: The exit code for this exception.

ctx: Context | None¶

cmd: t.Final[Command | None]¶

show(file=None)[source]¶

Return type:: None

class click_extra.ValidateConfigOption(param_decls=None, type=<click.types.Path object>, is_eager=True, expose_value=False, help='Validate the configuration file and exit.', **kwargs)[source]¶

Bases: ExtraOption

A pre-configured option adding --validate-config CONFIG_PATH.

Loads the config file at the given path, validates it against the CLI’s parameter structure in strict mode, reports results, and exits.

validate_config(ctx, param, value)[source]¶

Load, parse, and validate the configuration file, then exit.

Validation runs three checks in order, every one of them under the same ValidationError shape so the reported path is always rooted at the configuration file:

CLI-parameter strict check on the non-opaque part of the document.
Schema processing, if a config_schema is configured: catches type errors and unknown keys inside the dataclass-described section.
Each registered ConfigValidator runs against its declared opaque sub-tree.

Every detected error is emitted before exiting, so a single --validate-config run surfaces the full list of fixes the user needs to apply.

Return type:: None

exception click_extra.ValidationError(path, message, code=None)[source]¶

Bases: Exception

Raised when a configuration file fails validation.

A single, structured exception type that uniformly carries the dotted path of the offending key, a human-readable message, and an optional code for programmatic handling. Used by click-extra’s built-in strict-mode check and by every user-registered ConfigValidator, so downstream apps and --validate-config see the same error shape regardless of who detected the problem.

Parameters:

path (str) – Dotted path to the offending key, relative to the configuration file root (like "my-cli.managers.winget.cli_searchpath"). An empty string means the error applies to the document as a whole.
message (str) – Human-readable description of the failure. Should be a single sentence, no trailing punctuation, no path repeated.
code (str | None) – Optional machine-readable error code (like "unknown_field") for callers that want to dispatch on error type without parsing the message string.

class click_extra.ValidationReport(schema_instance, opaque_subtrees, errors, merged_conf=None)[source]¶

Bases: object

Outcome of one pass through run_config_validation().

Bundles everything a caller needs after validating a parsed configuration document: the typed schema instance, the extracted opaque sub-trees, the template-filtered config ready for default_map, and every error detected across all validation stages.

Note

The report holds references to the parsed sub-trees, not copies, so building it is cheap regardless of document size.

schema_instance: Any | None¶

Typed object produced by the configured schema callable.

None when no schema is configured, or when the schema stage raised (in which case the failure is recorded in errors).

opaque_subtrees: dict[str, dict[str, Any]]¶: Extracted extension sub-trees, keyed by dotted path relative to the app section. Only paths actually present in the document appear here, so callers can re-route them to per-path validators or stash them on ctx.meta.

errors: tuple[ValidationError, ...]¶

Every ValidationError detected, in stage order (unknown CLI-flag keys first, then schema errors, then validator failures). Empty on success.

With collect_all=False this holds at most one error: the first failure short-circuits the remaining stages.

merged_conf: dict[str, Any] | None = None¶

The CLI-flag-bound configuration merged onto params_template: the payload _install_default_map() layers into the context’s default_map.

None when params_template was None (no strict check) or the strict check raised. Read it only on a successful report: it is the same value merge_default_map() would recompute, so reusing it avoids a second normalize/strip/merge pass.

property ok: bool¶: True when no error was detected.

class click_extra.VerboseOption(param_decls=None, **kwargs)[source]¶

Bases: _CounterOption

--verbose/-v option to raise the log level of _VerbosityOption by one step per repetition.

Each -v raises the verbosity by one LogLevel step. The option can be repeated, so -vv (or -v -v) raises it by two steps.

The base level the counter starts from is sourced from VerbosityOption.default. So with --verbosity’s default left at WARNING:

-v raises the level to INFO,
-vv raises the level to DEBUG,
any further repetition is clamped at the loudest level, so -vvvvv for example resolves to DEBUG.

-v shares a single signed counter with QuietOption’s -q, so the two cancel out: -v -q leaves the level unchanged. See _VerbosityOption.resolve_level for the full reconciliation rule with --verbosity.

Set up a verbosity-altering option.

Parameters:: default_logger – If a logging.Logger object is provided, that’s the instance to which we will set the level to. If the parameter is a string and is found in the global registry, we will use it as the logger’s ID. Otherwise, we will create a new logger with new_logger() Default to the global root logger.

class click_extra.VerbosityOption(param_decls=None, default_logger='root', default=LogLevel.WARNING, metavar='LEVEL', type=EnumChoice('CRITICAL', 'ERROR', 'WARNING', 'INFO', 'DEBUG'), help='Either CRITICAL, ERROR, WARNING, INFO, DEBUG.', **kwargs)[source]¶

Bases: _VerbosityOption

--verbosity LEVEL option to set the log level of _VerbosityOption.

Set up a verbosity-altering option.

Parameters:: default_logger (Logger | str) – If a logging.Logger object is provided, that’s the instance to which we will set the level to. If the parameter is a string and is found in the global registry, we will use it as the logger’s ID. Otherwise, we will create a new logger with new_logger() Default to the global root logger.

set_level(ctx, param, value)[source]¶

Record the --verbosity value, then reconcile.

The value passed to --verbosity is saved in ctx.meta[click_extra.context.VERBOSITY].

Return type:: None

class click_extra.VersionOption(param_decls=None, message=None, fields=None, styles=None, message_style=None, screen=None, is_flag=True, expose_value=False, is_eager=True, help='Show the version and exit.', **kwargs)[source]¶

Bases: ExtraOption

Gather CLI metadata and prints a colored version string.

Note

This started as a copy of the standard @click.version_option() decorator, but is no longer a drop-in replacement. Hence the Extra prefix.

This address the following Click issues:

click#2324, to allow its use with the declarative params= argument.
click#2331, by distinguishing the module from the package.
click#1756, by allowing path and Python version.

Preconfigured as a --version option flag.

Parameters:

message (str | None) – the message template to print, in format string syntax. Defaults to {prog_name}, version {version}.
fields (Mapping[str, Any] | None) – mapping of template field name to a forced value, overriding the value auto-computed for that field. Keys must be members of template_fields (for example {"version": "1.2.3"}).
styles (Mapping[str, Callable[[str], str] | None] | None) – mapping of template field name to its Style, merged over default_styles. Pass None as a value to clear a field’s default style. Keys must be members of template_fields.
message_style (Callable[[str], str] | None) – fallback style for the message literals and for any field that has no style of its own.
screen (VersionScreen | None) – a VersionScreen to draw instead of the one-line message, whenever the terminal can take it. Left unset, --version behaves exactly as it always has.

template_fields: tuple[str, ...] = ('module', 'module_name', 'module_file', 'module_version', 'package_name', 'package_version', 'author', 'license', 'exec_name', 'version', 'git_repo_path', 'git_branch', 'git_long_hash', 'git_short_hash', 'git_date', 'git_tag', 'git_tag_sha', 'git_distance', 'git_dirty', 'prog_name', 'env_info')¶: List of field IDs recognized by the message template.

default_styles: ClassVar[dict[str, IStyle]] = {'env_info': Style(fg='bright_black'), 'exec_name': <function theme_slot.<locals>.apply>, 'git_branch': Style(fg='cyan'), 'git_date': Style(fg='bright_black'), 'git_dirty': Style(fg='red'), 'git_distance': <function theme_slot.<locals>.apply>, 'git_long_hash': Style(fg='yellow'), 'git_repo_path': Style(fg='bright_black'), 'git_short_hash': Style(fg='yellow'), 'git_tag': Style(fg='cyan'), 'git_tag_sha': Style(fg='yellow'), 'module_name': <function theme_slot.<locals>.apply>, 'module_version': <function theme_slot.<locals>.apply>, 'package_name': <function theme_slot.<locals>.apply>, 'package_version': <function theme_slot.<locals>.apply>, 'prog_name': <function theme_slot.<locals>.apply>, 'version': <function theme_slot.<locals>.apply>}¶

Default style for each template field.

Fields absent from this mapping render with no style of their own and fall back to message_style (or no color when that is unset). User-provided styles are merged over these defaults.

The name and version fields defer to the active palette through theme_slot() rather than naming a color. Both slots render exactly what the literals they replaced did under the dark default — invoked_command is bright white bold, success is green — so nothing moves for a CLI that never touches --theme, while one that does finally gets a version message to match.

message: str = '{prog_name}, version {version}'¶: Default message template used to render the version string.

static cli_frame()[source]¶

Returns the frame in which the CLI is implemented.

Inspects the execution stack frames to find the package in which the user’s CLI is implemented.

Returns the frame itself.

Return type:: FrameType

property module: ModuleType[source]¶: Returns the module in which the CLI resides.

property module_name: str[source]¶: Returns the full module name or __main__.

property module_file: str | None[source]¶: Returns the module’s file full path.

property module_version: str | None[source]¶: Returns the string found in the local __version__ variable.

Hint

__version__ is an old pattern from early Python packaging. It is not a standard variable and is not defined in the packaging PEPs.

You should prefer using the package_version property below instead, which uses the standard library importlib.metadata API.

We’re still supporting it for backward compatibility with existing codebases, as Click removed it in version 8.2.0.

property package_name: str | None[source]¶: Returns the package name.

property package_version: str | None[source]¶

Returns the package version if installed.

Resolved from the distribution name (see _distribution_name) via importlib.metadata.version(). Returns None if the package is not installed or cannot be resolved.

property author: str | None[source]¶

Returns the package author(s) from its core metadata.

Delegates to resolve_author(): prefers the Author field, then the Maintainer field, then the display name parsed out of the Author-email / Maintainer-email fields (Name <email>). Returns None if no author can be determined.

property license: str | None[source]¶

Returns the package license from its core metadata.

Delegates to resolve_license(): prefers the SPDX License-Expression field, falls back to the human-readable name of the first License :: trove classifier, then to the free-form License field. Returns None if no license can be determined.

property exec_name: str[source]¶

User-friendly name of the executed CLI.

Returns the module name. But if the later is __main__, returns the package name.

If not packaged, the CLI is assumed to be a simple standalone script, and the returned name is the script’s file name (including its extension).

property version: str | None[source]¶

Return the version of the CLI.

Returns the module version if a __version__ variable is set alongside the CLI in its module.

Else returns the package version if the CLI is implemented in a package, using importlib.metadata.version().

For development versions (containing .dev), automatically appends the Git short hash as a PEP 440 local version identifier, producing versions like 1.2.3.dev0+abc1234. This helps identify the exact commit a dev build was produced from. If Git is unavailable, the plain dev version is returned.

Versions that already contain a + (a pre-baked local version identifier, typically set at build time by CI pipelines) are returned as-is to avoid producing invalid double-suffixed versions like 1.2.3.dev0+abc1234+xyz5678.

property git_repo_path: Path | None[source]¶: Find the Git repository root directory.

property git_branch: str | None[source]¶

Returns the current Git branch name.

Checks for a pre-baked __git_branch__ dunder first, then git rev-parse --abbrev-ref HEAD, then .git_archival.json.

property git_long_hash: str | None[source]¶

Returns the full Git commit hash.

Checks for a pre-baked __git_long_hash__ dunder first, then git rev-parse HEAD, then .git_archival.json.

property git_short_hash: str | None[source]¶

Returns the short Git commit hash.

Checks for a pre-baked __git_short_hash__ dunder first, then git rev-parse --short HEAD, then .git_archival.json (where it is derived from the first 7 characters of the full hash).

Hint

The short hash is usually the first 7 characters of the full hash, but this is not guaranteed to be the case.

But it is at least guaranteed to be unique within the repository, and a minimum of 4 characters.

property git_date: str | None[source]¶

Returns the commit date in ISO format: YYYY-MM-DD HH:MM:SS +ZZZZ.

Checks for a pre-baked __git_date__ dunder first, then git show -s --format=%ci HEAD, then .git_archival.json (whose node-date is strict ISO 8601, like 2021-01-01T12:00:00+00:00).

property git_tag: str | None[source]¶

Returns the Git tag pointing at HEAD, if any.

Checks for a pre-baked __git_tag__ dunder first, then git describe --tags --exact-match HEAD, then .git_archival.json.

Returns None if HEAD is not at a tagged commit.

property git_tag_sha: str | None[source]¶

Returns the commit SHA that the current tag points at.

Checks for a pre-baked __git_tag_sha__ dunder first, then git rev-list -1 on the tag returned by git_tag, then .git_archival.json. Returns None if HEAD is not at a tag.

property git_distance: str | None[source]¶

Number of commits since the most recent tag, or None.

Checks for a pre-baked __git_distance__ dunder first, then parses git describe --tags --long, then falls back to .git_archival.json. None when no tag is reachable or Git is unavailable.

property git_dirty: str | None[source]¶

Work-tree state: "dirty", "clean" or None.

Checks for a pre-baked __git_dirty__ dunder first, then runs git status --porcelain. None when not in a Git repository or Git is unavailable. There is no .git_archival.json fallback: an archive has no work tree, so its state is unknowable.

property prog_name: str | None¶

Return the name of the CLI, from Click’s point of view.

Get the info_name of the root command.

Note

Unlike its siblings, this field is resolved on every access instead of being cached on the instance: it is the one template field whose value legitimately varies between invocations of the same option instance sharing a process. multicall dispatch relies on that, running one CLI under many names in sequence, and a prog_name passed to main() varies it without any multicall at all. A cached value would pin the first name seen forever.

property env_info: dict[str, Any][source]¶

Various environment info.

Returns the data produced by boltons.ecoutils.get_profile().

field_style(field_id=None)[source]¶

Style painting the field_id segment of a rendered message.

A field carrying no style of its own falls back to message_style, and one left unset by the caller too renders bare. Call with no field_id for the style of the template’s literal segments, which is message_style alone.

Return type:: Callable[[str], str]

colored_template(template=None)[source]¶

Insert ANSI styles to a message template.

Accepts a custom template as parameter, otherwise uses the default message defined on the Option instance.

This step is necessary because we need to linearize the template to apply the ANSI codes on the string segments. This is a consequence of the nature of ANSI, directives which cannot be encapsulated within another (unlike markup tags like HTML).

Return type:: str

render_message(template=None)[source]¶

Render the version string from the provided template.

Accepts a custom template as parameter, otherwise uses the default self.colored_template() produced by the instance.

A CLI carrying a VersionScreen gets that drawn instead, whenever three conditions hold. Failing any one of them falls back to the plain template unchanged, which is a deliberate guarantee rather than a default: that form is the one every machine reader parses.

Color reaches the output. Not because a mark needs it — a good one survives having its escapes stripped — but because it is the one lever a caller already has. A redirected --version, or one run under --no-color or NO_COLOR, is asking for something parseable.
The terminal is wide enough to seat the facts beside the mark without wrapping them.
Accessible mode is off. A mark read out character by character is noise to a screen reader, so --accessible keeps the plain message.

Return type:: str

print_debug_message()[source]¶

Render in debug logs all template fields in color.

A field resolving to a nested structure is dumped as indented JSON under its own label, instead of the single-line repr a template would produce for it. Only :env_info: is built that way today, and it alone accounts for two thirds of this listing: a thousand characters on one line is what a bug report carries otherwise. Upstream reads its profile the same way, through boltons.ecoutils.get_profile_json(indent=True).

Return type:: None

print_and_exit(ctx, param, value)[source]¶

Print the version string and exits.

Also stores all version string elements in the Context’s meta dict.

Return type:: None

class click_extra.ZeroExitOption(param_decls=None, default=False, expose_value=False, is_flag=True, help='Always exit with a status code of 0, even when problems are found.', **kwargs)[source]¶

Bases: ExtraOption

A pre-configured -0/--zero-exit option flag.

Follows the convention popularized by linters and static analysers, which exit with a non-zero code whenever they report findings so that automation can gate on it. Setting this flag flips that behavior: the CLI returns 0 as long as it ran to completion, reserving non-zero codes for actual execution failures.

The resolved value is stored in ctx.meta[click_extra.context.ZERO_EXIT], aligning with every other Click Extra option’s per-invocation context-meta storage pattern.

Warning

This option is a placeholder: it does not alter the CLI’s exit code by itself. Downstream code must read ctx.meta[click_extra.context.ZERO_EXIT] and act on it.

set_zero_exit(ctx, param, value)[source]¶

Store the resolved zero-exit flag on the context’s meta dict.

Read via click_extra.context.get(ctx, click_extra.context.ZERO_EXIT).

Return type:: None

click_extra.accessible_option(param_decls: Sequence[str] | None = None, is_flag=True, default=False, is_eager=True, expose_value=False, help='Accessibility mode: disable colors and render tables in a borderless, screen-reader-friendly format.', **kwargs)¶

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.ansi_to_html(text)[source]¶

Translate ANSI styling in text to inline-styled HTML  tags.

\x1b[34mSummer\x1b[0m becomes Summer. The spans are self-contained (no stylesheet needed) and also valid in markups accepting inline HTML, like MediaWiki.

Return type:: str

click_extra.ansi_to_jira(text)[source]¶

Translate ANSI styling in text to Jira wiki markup.

\x1b[34;1mSummer\x1b[0m becomes {color:blue}*Summer*{color}.

Return type:: str

click_extra.ansi_to_latex(text)[source]¶

Translate ANSI styling in text to LaTeX macros.

\x1b[34;1mSummer\x1b[0m becomes \textcolor{blue}{\textbf{Summer}}. The colored macros require \usepackage{xcolor} in the document preamble.

Return type:: str

click_extra.ansi_to_textile(text)[source]¶

Translate ANSI styling in text to Textile spans.

\x1b[34;1mSummer\x1b[0m becomes %{color: blue; font-weight: bold}Summer%.

Return type:: str

click_extra.args_cleanup(*args)[source]¶

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

Helps serialize 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.

Return type:: tuple[str, ...]

click_extra.argument(*args, help=None, **attrs)¶

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.basicConfig(*, filename=None, filemode='a', format='{levelname}: {message}', datefmt=None, style='{', level=None, stream=None, handlers=None, force=False, encoding=None, errors='backslashreplace', stream_handler_class=<class 'click_extra.logging.StreamHandler'>, file_handler_class=<class 'logging.FileHandler'>, formatter_class=<class 'click_extra.logging.Formatter'>)[source]¶

Configure the global root logger.

This function is a wrapper around Python standard library’s logging.basicConfig(), but with additional parameters and tweaked defaults.

It sets up the global root logger, and optionally adds a file or stream handler to it.

Differences in default values:

Argument	`basicConfig()` default	`logging.basicConfig()` default
`style`	`{`	`%`
`format`	`{levelname}: {message}`	`%(levelname)s:%(name)s:%(message)s`

This function takes the same parameters as logging.basicConfig(), but require them to be all passed as explicit keywords arguments.

Parameters:

filename (str | None) – Specifies that a logging.FileHandler be created, using the specified filename, rather than an StreamHandler.
filemode (str) –
If filename is specified, open the file in this mode.

Defaults to a.
format (str | None) –
Use the specified format string for the handler.

Defaults to {levelname}: {message}.
datefmt (str | None) – Use the specified date/time format, as accepted by time.strftime().
style (Literal['%', '{', '$']) –
If format is specified, use this style for the format string:
- % for printf-style,
- { for str.format(),
- $ for string.Template.
Defaults to {.
level (int | str | None) – Set the root logger level to the specified level.
stream (IO[Any] | None) – Use the specified stream to initialize the StreamHandler. Note that this argument is incompatible with filename - if both are present, a ValueError is raised.
handlers (Iterable[Handler] | None) – If specified, this should be an iterable of already created handlers to add to the root logger. Any handlers which don’t already have a formatter set will be assigned the default formatter created in this function. Note that this argument is incompatible with filename or stream - if both are present, a ValueError is raised.
force (bool) – If this argument is specified as True, any existing handlers attached to the root logger are removed and closed, before carrying out the configuration as specified by the other arguments.
encoding (str | None) – Name of the encoding used to decode or encode the file. To be specified along with filename, and passed to logging.FileHandler for opening the output file.
errors (str | None) – Optional string that specifies how encoding and decoding errors are to be handled by the logging.FileHandler. Defaults to backslashreplace. Note that if None is specified, it will be passed as such to open().

Return type:

Important

Always keep the signature of this function, the default values of its parameters and its documentation in sync with the one from Python’s standard library.

These new arguments are available for better configurability:

Parameters:

stream_handler_class (type[Handler]) – A logging.Handler class that will be used in logging.basicConfig() to create a default stream-based handler. Defaults to StreamHandler.
file_handler_class (type[Handler]) – A logging.Handler class that will be used in logging.basicConfig() to create a default file-based handler. Defaults to logging.FileHandler.
formatter_class (type[Formatter]) – A logging.Formatter class of the formatter that will be used in logging.basicConfig() to setup the default formatter. Defaults to Formatter.

Note

I don’t like the camel-cased name of this function and would have called it basic_config(), but it’s kept this way for consistency with Python’s standard library logging.basicConfig().

click_extra.cases_from_data(data)[source]¶

Build CLITestCase instances from already-parsed suite data.

The in-memory counterpart to parse_test_suite() (which parses a string) and load_test_suite() (which reads a file): feed it a suite that is already a Python object, such as the native cases mappings declared in a [tool.<cli>.test-suite] config section.

A suite is a list of case mappings, each keyed by CLITestCase directive names. Formats with no bare top-level array (TOML) carry that list under a top-level cases key, so a mapping is unwrapped here.

Raises:

ValueError – the suite is empty, a mapping suite omits cases, or a case uses unknown directives.
TypeError – the suite is not a list, or a case is not a mapping.

Return type:

click_extra.clear()[source]¶

Drop-in for click.clear() that becomes a no-op under --accessible.

Clearing the screen wipes the scrollback a screen reader relies on and carries no meaning in a linear stream, so accessibility mode skips it entirely. Outside accessibility mode (or with no active context) it defers to click.clear(), which already no-ops when stdout is not a terminal.

Return type:: None

click_extra.color_option(param_decls: Sequence[str] | None = None, is_flag=False, flag_value='always', default='auto', is_eager=True, expose_value=False, help='Colorize the output. A bare --color is the same as --color=always.', **kwargs)¶

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.column_sort_key(header_defs, sort_columns=None, cell_key=None)[source]¶

Build a row sort key from the sort_columns a table actually carries.

header_defs describes the rendered columns: ColumnSpec instances or (label, column_id) tuples, with column_id=None for columns that cannot be sorted on. The requested sort_columns the table carries drive the comparison first, de-duplicated and in request order; the remaining columns follow in their natural left-to-right order for tie-breaking.

Returns None when the table carries none of the requested columns, signalling that rows should keep their original order. This is what lets one --sort-by selection apply across subcommands rendering heterogeneous tables: each table sorts by the requested fields it knows, and a table knowing none of them is left untouched.

Return type:: Callable[[Sequence[str | None]], tuple] | None

click_extra.columns_option(param_decls: Sequence[str] | None = None, columns: Sequence[ColumnSpec] | None = None, type=None, default: Sequence[str] | None = (), expose_value: bool = False, is_eager: bool = True, help: str = 'Restrict and reorder table columns, SQL SELECT-style. Comma-separated list of column IDs. Default: all columns in canonical order.', **kwargs)¶

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.command(*args, **kwargs)¶

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.config_option(param_decls: Sequence[str] | None = None, metavar='CONFIG_PATH', type=UNPROCESSED, help='Location of the configuration file. Supports local path with glob patterns or remote URL.', is_eager: bool = True, expose_value: bool = False, file_format_patterns: dict[ConfigFormat, Sequence[str] | str] | Iterable[ConfigFormat] | ConfigFormat | None = None, file_pattern_flags: int = 4104, roaming: bool = True, force_posix: bool = False, search_pattern_flags: int = 285504, search_parents: bool = False, stop_at: Path | str | Literal[Sentinel.VCS] | None = Sentinel.VCS, cascade: bool = False, excluded_params: Iterable[str] | None = None, included_params: Iterable[str] | None = None, strict: bool = False, config_schema: type | Callable[[dict[str, Any]], Any] | None = None, schema_strict: bool = False, fallback_sections: Sequence[str] = (), config_validators: Sequence[ConfigValidator] = (), **kwargs)¶

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.config_table_to_flags(table)[source]¶

Translate a mapping of configuration keys into long-form CLI flags.

For tools whose command-line options mirror their configuration keys but which cannot read the table themselves (no --config support, no native config file). Follows the conventional mapping:

key = True → --key
key = "value" (or a number) → --key=value
key = ["a", "b"] → --key=a --key=b (one flag per item)
key = False is skipped: there is no universal --no-<key> form.

Keys keep their spelling, so hyphenated keys map straight onto long options, and flags follow the mapping’s iteration order.

Parameters:: table (Mapping[str, Any]) – The configuration keys and values, like a parsed [tool.X] section.
Return type:: list[str]
Returns:: The equivalent list of --flag / --flag=value arguments.

click_extra.confirm(text, default=False, abort=False, prompt_suffix=': ', show_default=True, err=False)[source]¶

Prompts for confirmation (yes/no question).

If the user aborts the input by sending a interrupt signal this function will catch it and raise a Abort exception.

Parameters:

text (str) – the question to ask.
default (bool | None) – The default value to use when no input is given. If None, repeat until input is given.
abort (bool) – if this is set to True a negative answer aborts the exception by raising Abort.
prompt_suffix (str) – a suffix that should be added to the prompt.
show_default (bool) – shows or hides the default value in the prompt.
err (bool) – if set to true the file defaults to stderr instead of stdout, the same as with echo.

Changed in version 8.3.1: A space is no longer appended to the prompt.

Changed in version 8.0: Repeat until input is given if default is None.

Added in version 4.0: Added the err parameter.

Return type:: bool

click_extra.confirmation_option(*param_decls, **kwargs)[source]¶

Add a --yes option which shows a prompt before continuing if not passed. If the prompt is declined, the program will exit.

Parameters:

param_decls (str) – One or more option names. Defaults to the single value "--yes".
kwargs (Any) – Extra arguments are passed to option().

Return type:

Callable[[TypeVar(FC, bound= _AnyCallable | Command)], TypeVar(FC, bound= _AnyCallable | Command)]

click_extra.constrained_params(constr, *param_adders)[source]¶

Return a decorator that adds the given parameters and applies a constraint to them. Equivalent to:

@param_adders[0]
...
@param_adders[-1]
@constraint(constr, <param names>)

This decorator saves you to manually (re)type the parameter names. It can also be used inside @option_group.

Instead of using this decorator, you can also call the constraint itself:

@constr(*param_adders)

but remember that:

Python 3.9 is the first that allows arbitrary expressions on the right of @;
using a long conditional/composite constraint as decorator may be less readable.

In these cases, you may consider using @constrained_params.

Added in version 0.9.0.

Parameters:

constr (Constraint) – an instance of Constraint
param_adders (Callable[[Callable[..., Any]], Callable[..., Any]]) – function decorators, each attaching a single parameter to the decorated function.

Return type:

Callable[[TypeVar(F, bound= Callable[..., Any])], TypeVar(F, bound= Callable[..., Any])]

click_extra.constraint(constr, params)[source]¶

Register a constraint on a list of parameters specified by (destination) name (e.g. the default name of --input-file is input_file).

Return type:: Callable[[TypeVar(F, bound= Callable[..., Any])], TypeVar(F, bound= Callable[..., Any])]

click_extra.convert_apidoc_rst_to_myst(content)[source]¶

Convert sphinx-apidoc RST to MyST markdown with {eval-rst} blocks.

Parameters:: content (str) – RST content produced by sphinx-apidoc.
Return type:: str
Returns:: Equivalent MyST markdown.

click_extra.convert_directory(directory)[source]¶

Convert all Python files in a directory from reST to MyST docstrings.

Parameters:: directory (Path) – Directory to process recursively.
Return type:: list[Path]
Returns:: List of files that were modified.

click_extra.convert_file(filepath)[source]¶

Apply all conversions to a single Python file.

Returns True if the file was modified.

Return type:: bool

click_extra.convert_rst_files_in_directory(directory)[source]¶

Convert sphinx-apidoc RST files to MyST markdown in the given directory.

For each .rst file containing .. automodule:: directives:

If a .md file with the same stem exists, delete the .rst (the existing markdown takes precedence).
Otherwise, convert the RST content to MyST and write a .md file, then delete the .rst.

Parameters:: directory (Path) – Directory to scan for .rst files.
Return type:: list[Path]
Returns:: List of newly created .md file paths.

click_extra.convert_source(source)[source]¶

Convert reST markup to MyST in a Python module’s docstrings and comments.

Docstrings get the full pipeline, in an order that matters: inline constructs (cross-references, links, inline code) run before directives so that directive bodies are already converted when they are dedented into fences. Comments get the inline conversions only, except consecutive full-line #: comments, whose directives are also converted through convert_comment_blocks(). Everything outside docstrings and comments passes through byte-for-byte.

Return type:: str

click_extra.detect_source_package(pyproject_path=None)[source]¶

Locate the project’s single source package from its script entry points.

Reads [project.scripts] from pyproject.toml and derives the top-level package of each entry point target ("pkg.cli:main" gives pkg), so the convert-to-myst command can run bare from a project root.

Parameters:: pyproject_path (Path | None) – Path of the pyproject.toml to inspect. Defaults to the one in the current working directory.
Return type:: Path
Returns:: Path of the single detected package directory.
Raises:: ValueError – When pyproject.toml is missing, declares no script entry point, or several distinct packages are detected.

click_extra.dir_path(*, path_type=<class 'pathlib.Path'>, exists=False, readable=True, writable=False, executable=False, resolve_path=False, allow_dash=False)[source]¶

Shortcut for click.Path with file_okay=False, path_type=pathlib.Path.

Return type:: Path

click_extra.echo(message=None, file=None, nl=True, err=False, color=None)[source]¶

Print a message and newline to stdout or a file. This should be used instead of print() because it provides better support for different data, files, and environments.

Compared to print(), this does the following:

Ensures that the output encoding is not misconfigured on Linux.
Supports Unicode in the Windows console.
Supports writing to binary outputs, and supports writing bytes to text outputs.
Supports colors and styles on Windows.
Removes ANSI color and style codes if the output does not look like an interactive terminal.
Always flushes the output.

Parameters:

message (object) – The string or bytes to output. Other objects are converted to strings.
file (IO[Any] | None) – The file to write to. Defaults to stdout.
err (bool) – Write to stderr instead of stdout.
nl (bool) – Print a newline after the message. Enabled by default.
color (bool | None) – Force showing or hiding colors and other styles. By default Click will remove color if the output does not look like an interactive terminal.

Changed in version 6.0: Support Unicode output on the Windows console. Click does not modify sys.stdout, so sys.stdout.write() and print() will still not support Unicode.

Changed in version 4.0: Added the color parameter.

Added in version 3.0: Added the err parameter.

Changed in version 2.0: Support colors on Windows if colorama is installed.

Return type:: None

click_extra.echo_via_pager(text_or_generator, color=None)[source]¶

Drop-in for click.echo_via_pager() that streams plainly under –accessible.

A pager is a full-screen, cursor-driven TUI: it traps output behind its own keybindings, hostile to a screen reader consuming a linear stream. Under --accessible the text is written straight to stdout via click.echo() instead. Outside accessibility mode (or with no active context) it defers to click.echo_via_pager(), which already falls back to a plain write when stdout is not a terminal.

The argument is normalized exactly as click.echo_via_pager() does (a generator function is called, a string is emitted as-is, anything else is iterated), so the two behave identically on their inputs.

Return type:: None

click_extra.edit(text=None, editor=None, env=None, require_save=True, extension='.txt', filename=None)[source]¶

Edits the given text in the defined editor. If an editor is given (should be the full path to the executable but the regular operating system search path is used for finding the executable) it overrides the detected editor. Optionally, some environment variables can be used. If the editor is closed without changes, None is returned. In case a file is edited directly the return value is always None and require_save and extension are ignored.

Overloads:

text (bytes | bytearray), editor (str | None), env (cabc.Mapping[str, str] | None), require_save (bool), extension (str) → bytes | None
text (str), editor (str | None), env (cabc.Mapping[str, str] | None), require_save (bool), extension (str) → str | None
text (None), editor (str | None), env (cabc.Mapping[str, str] | None), require_save (bool), extension (str), filename (str | cabc.Iterable[str] | None) → None

If the editor cannot be opened a UsageError is raised.

Note for Windows: to simplify cross-platform usage, the newlines are automatically converted from POSIX to Windows and vice versa. As such, the message here will have \n as newline markers.

Parameters:

text (str | bytes | bytearray | None) – the text to edit.
editor (str | None) – optionally the editor to use. Defaults to automatic detection.
env (Mapping[str, str] | None) – environment variables to forward to the editor.
require_save (bool) – if this is true, then not saving in the editor will make the return value become None.
extension (str) – the extension to tell the editor about. This defaults to .txt but changing this might change syntax highlighting.
filename (str | Iterable[str] | None) – if provided it will edit this file instead of the provided text contents. It will not use a temporary file as an indirection in that case. If the editor supports editing multiple files at once, a sequence of files may be passed as well. Invoke click.file once per file instead if multiple files cannot be managed at once or editing the files serially is desired.

Changed in version 8.2.0: filename now accepts any Iterable[str] in addition to a str if the editor supports editing multiple files at once.

click_extra.export_config_option(param_decls: Sequence[str] | None = None, type: click.ParamType | Any = None, metavar: str = 'FORMAT', is_eager: bool = True, expose_value: bool = False, help: str = 'Export the configuration in the selected format to <stdout>, then exit.', **kwargs: Any)¶

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.field_docstrings(cls)[source]¶

Extract attribute docstrings from a class body, keyed by field name.

Attribute docstrings are string literals immediately following an annotated assignment in a class body (the PEP 257 convention used by Sphinx’s autodoc). Python discards them at runtime, so they are recovered by parsing the class source with ast. Each docstring is cleaned up with inspect.cleandoc(), preserving paragraph breaks.

Caution

Returns an empty mapping when the class source is unavailable, as for classes defined in an exec-ed code block (an interactive session, or the body of a click:source Sphinx directive). Import the schema from a real module to get its docstrings documented.

Return type:: dict[str, str]

click_extra.file_path(*, path_type=<class 'pathlib.Path'>, exists=False, readable=True, writable=False, executable=False, resolve_path=False, allow_dash=False)[source]¶

Shortcut for click.Path with dir_okay=False, path_type=pathlib.Path.

Return type:: Path

click_extra.flatten_config_keys(conf, sep='_', opaque_keys=frozenset({}), _prefix='')[source]¶

Flatten nested dicts into a single level by joining keys with a separator.

Useful for mapping nested configuration structures (like TOML sub-tables) to flat Python dataclass fields. After normalization with normalize_config_keys, the flattened keys match dataclass field names directly:

>>> from click_extra.config import (
...     flatten_config_keys,
...     normalize_config_keys,
... )
>>> raw = {"dependency-graph": {"all-groups": True, "output": "deps.mmd"}}
>>> flatten_config_keys(normalize_config_keys(raw))
{'dependency_graph_all_groups': True, 'dependency_graph_output': 'deps.mmd'}

Parameters:

conf (dict[str, Any]) – Nested dictionary to flatten.
sep (str) – Separator used to join parent and child keys. Defaults to "_" which produces valid Python identifiers when combined with normalize_config_keys.
opaque_keys (frozenset[str]) – Fully-qualified key names where flattening stops. When the accumulated key matches an entry in this set, the dict value is kept as-is instead of being recursively flattened. This is useful for fields typed as dict[str, X] where the dict keys are data (like GitHub Actions matrix axis names), not config structure.
_prefix (str) – Internal parameter for tracking the accumulated key path during recursion. Callers should not set this.

Return type:

dict[str, Any]

click_extra.format_cli_prompt(cmd_args, extra_env=None, theme=None, prompt=None)[source]¶

Render the shell prompt simulating a CLI invocation, for logs and dry-runs.

Prefixes PROMPT to any extra_env assignments and the command line. Each token family is styled with the theme slot (get_current_theme()) it holds elsewhere in a CLI’s output, so the line reads like the help screens do:

the prompt sigil with bracket, the structural-token style;
each environment assignment as envvar name, plain =, default value;
the program’s binary name with invoked_command, its directory plain (see highlight_bin_name());
the -/-- flags with option; other arguments stay plain.

Useful to print a copy-pasteable command trace in debug logs, dry-runs and test output.

Parameters:

cmd_args (Iterable[str]) – the command line to render.
extra_env (Mapping[str, str | None] | None) – environment assignments to prefix it with.
theme (HelpTheme | None) – palette to style the line with. Defaults to the theme the current invocation runs under, which is what a CLI printing its own trace wants. A caller drawing the line onto a surface of its own choosing (a light capture, say) passes the one that surface can show.
prompt (str | None) – sigil to draw before the command, when the shell being pictured is not the one running. A capture mimicking a Windows terminal passes PS C:\>; None keeps PROMPT, which is this platform’s.

Return type:

Returns:

the styled prompt line.

click_extra.format_duration(duration)[source]¶

Render an elapsed duration compactly: 2.3s, 1:05, then 1:02:03.

Below a minute the duration reads as one-decimal seconds (2.3s). From a minute up it switches to a clock layout, growing an hours field only once it reaches an hour: 1:05 under an hour, 1:02:03 at or above.

The reverse direction, parsing a human-written duration back into a timedelta, lives in click_extra.types (see Duration).

Parameters:: duration (float | timedelta) – The elapsed time, as a number of seconds or a timedelta.
Return type:: str
Returns:: The compact rendering described above.

click_extra.format_filename(filename, shorten=False)[source]¶

Format a filename as a string for display. Ensures the filename can be displayed by replacing any invalid bytes or surrogate escapes in the name with the replacement character �.

Invalid bytes or surrogate escapes will raise an error when written to a stream with errors="strict". This will typically happen with stdout when the locale is something like en_GB.UTF-8.

Many scenarios are safe to write surrogates though, due to PEP 538 and PEP 540, including:

Writing to stderr, which uses errors="backslashreplace".
The system has LANG=C.UTF-8, C, or POSIX. Python opens stdout and stderr with errors="surrogateescape".
None of LANG/LC_* are set. Python assumes LANG=C.UTF-8.
Python is started in UTF-8 mode with PYTHONUTF8=1 or -X utf8. Python opens stdout and stderr with errors="surrogateescape".

Parameters:

filename (str | bytes | PathLike[str] | PathLike[bytes]) – formats a filename for UI display. This will also convert the filename into unicode without failing.
shorten (bool) – this optionally shortens the filename to strip of the path that leads up to it.

Return type:

click_extra.format_from_mime(mime_type, formats=None)[source]¶

Return the configuration format a media type designates.

The counterpart of format_from_path() for a configuration fetched over HTTP, whose URL often carries no usable file extension: the Content-Type header is then the only thing typing the payload. The media type is matched against each format’s mime_types, so application/toml resolves to TOML and text/yaml to YAML. formats restricts and orders the candidates (the first match wins); it defaults to every ConfigFormat.

Parameters are stripped, so a raw application/yaml; charset=utf-8 header value can be passed as-is, and matching is case-insensitive.

Note

A RFC 6839 structured syntax suffix is honored, so the application/vnd.acme.settings+json a private API answers with resolves to JSON. An exact match wins over a suffix.

Returns None for a media type no format claims, which covers the generic text/plain and application/octet-stream a server falls back to for an extension it does not recognize.

Return type:: ConfigFormat | None

click_extra.format_from_path(path, formats=None)[source]¶

Return the configuration format whose patterns match a file name.

The name is matched against each format’s patterns, so app.toml resolves to TOML and app.yml to YAML. formats restricts and orders the candidates (the first match wins); it defaults to every ConfigFormat.

Return type:: ConfigFormat | None

click_extra.format_manpage(roff, width=None)[source]¶

Typeset roff into readable terminal text, or None if nothing can.

Tries each entry of MAN_FORMATTERS in turn and returns the output of the first that succeeds. Returns None when none of them is installed, which the caller is expected to degrade on rather than fail: a CLI that cannot find a typesetter is a CLI running somewhere that never had man pages to begin with (Windows, a slim container), and that is no reason for --man to error.

Parameters:

roff (str) – the man page source, as CommandDoc.to_roff() renders it.
width (int | None) – line length in columns. Defaults to the terminal’s own, so the result matches what man would have produced in the same window.

Return type:

str | None

click_extra.format_param_row(param, ctx, path, is_structured)[source]¶

Compute the structural table cells for a Click parameter.

Returns a dict[column_id, cell] covering every column that can be derived from the parameter object alone (no runtime invocation state or config-file context). Specifically: id, spec, class, param_type, python_type, hidden, exposed, envvars, default, is_flag, flag_value, is_bool_flag, multiple, nargs, prompt, and confirmation_prompt.

Attributes only defined on click.Option (hidden, is_flag, flag_value, is_bool_flag, prompt, confirmation_prompt) yield None for click.Argument parameters: empty cell in visual formats, null in structured ones.

For structured formats (JSON, YAML, etc.), values are native Python types. For visual formats, values are themed strings matching help-screen styling.

The remaining table columns (allowed_in_conf, value, source, config_file) require live context and are filled in by render_params_table().

Return type:: dict[str, Any]

click_extra.format_size(size, *, units='iec', precision=1)[source]¶

Render a byte count as a compact, human-readable string.

Parameters:

size (float) – The number of bytes. A negative value keeps a leading -.
units (Literal['iec', 'si', 'jedec']) – The unit system to render in, one of _UNIT_SYSTEMS: iec (the default) for binary powers with the unambiguous KiB/MiB symbols, si for decimal powers with kB/MB, or jedec for binary powers with the customary but imprecise KB/MB.
precision (int) – Number of fractional digits for every unit above bytes. A byte count is always rendered as a whole number.

Return type:

Returns:

The size followed by a space and its unit, like 1.5 KiB. The integer part is grouped with thousands separators.

Raises:

ValueError – If units is not a known unit system.

click_extra.get_app_dir(app_name, roaming=True, force_posix=False)[source]¶

Returns the config folder for the application. The default behavior is to return whatever is most appropriate for the operating system.

To give you an idea, for an app called "Foo Bar", something like the following folders could be returned:

Mac OS X:: ~/Library/Application Support/Foo Bar
Mac OS X (POSIX):: ~/.foo-bar
Unix:: ~/.config/foo-bar
Unix (POSIX):: ~/.foo-bar
Windows (roaming):: C:\Users\<user>\AppData\Roaming\Foo Bar
Windows (not roaming):: C:\Users\<user>\AppData\Local\Foo Bar

Added in version 2.0.

Parameters:

app_name (str) – the application name. This should be properly capitalized and can contain whitespace.
roaming (bool) – controls if the folder should be roaming or not on Windows. Has no effect otherwise.
force_posix (bool) – if this is set to True then on any POSIX system the folder will be stored in the home folder with a leading dot instead of the XDG config home or darwin’s application support folder.

Return type:

click_extra.get_binary_stream(name)[source]¶

Returns a system stream for byte processing.

Parameters:: name (Literal['stdin', 'stdout', 'stderr']) – the name of the stream to open. Valid names are 'stdin', 'stdout' and 'stderr'
Return type:: BinaryIO

click_extra.get_current_context(silent=False)[source]¶

Equivalent to click.get_current_context() but casts the returned click.Context object to cloup.Context (which is safe when using cloup commands classes and decorators).

Overloads:

→ Context
silent (bool) → Optional[Context]

click_extra.get_current_theme()[source]¶

Return the theme active for the current CLI invocation.

Resolution order:

The theme stored on the active Click context under click_extra.context.THEME (set by ThemeOption from --theme).
The process-wide fallback returned by get_default_theme() (the dark default, or whatever patch_click() set at process start).

Falling back through the active context (instead of reading a module attribute) keeps --theme scoped to the invocation that received it, so a second invocation in the same process starts from the default again.

Return type:: HelpTheme

click_extra.get_default_theme()[source]¶

Return the process-wide fallback theme.

Read by get_current_theme() when no Click context is active or when the active context has no theme set. The default is the built-in dark palette; patch_click() overrides it via set_default_theme() for the duration of a patched session.

Resolved through a function rather than a module attribute so callers always observe the current value: capturing default_theme as a default function parameter (the previous pattern) would freeze whatever was set at import time.

Return type:: HelpTheme

click_extra.get_pager_file(color=None)[source]¶

Context manager.

Yields a writable file-like object which can be used as an output pager.

Added in version 8.4.0.

Parameters:: color (bool | None) – controls if the pager supports ANSI colors or not. The default is autodetection.
Return type:: ContextManager[TextIO, bool | None]

click_extra.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 hidden property is only supported by Option, not Argument.

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

Return type:: str | None

click_extra.get_text_stream(name, encoding=None, errors='strict')[source]¶

Returns a system stream for text processing. This usually returns a wrapped stream around a binary stream returned from get_binary_stream() but it also can take shortcuts for already correctly configured streams.

Parameters:

name (Literal['stdin', 'stdout', 'stderr']) – the name of the stream to open. Valid names are 'stdin', 'stdout' and 'stderr'
encoding (str | None) – overrides the detected default encoding.
errors (str | None) – overrides the default error mode.

Return type:

TextIO

click_extra.get_tool_config(ctx=None)[source]¶

Retrieve the typed tool configuration from the context.

Returns the object stored under click_extra.context.TOOL_CONFIG by ConfigOption when a config_schema is set, or None if no schema was configured or no configuration was loaded.

Parameters:: ctx (Context | None) – Click context. Defaults to the current context.
Return type:: Any

click_extra.getchar(echo=False)[source]¶

Fetches a single character from the terminal and returns it. This will always return a unicode character and under certain rare circumstances this might return more than one character. The situations which more than one character is returned is when for whatever reason multiple characters end up in the terminal buffer or standard input was not actually a terminal.

Note that this will always read from the terminal, even if something is piped into the standard input.

Note for Windows: in rare cases when typing non-ASCII characters, this function might wait for a second character and then return both at once. This is because certain Unicode characters look like special-key markers.

Added in version 2.0.

Parameters:: echo (bool) – if set to True, the character read will also show up on the terminal. The default is to not show it.
Return type:: str

click_extra.group(*args, **kwargs)¶

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.help_format_option(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)¶

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.help_option(*args, **kwargs)¶

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.highlight_bin_name(program, theme=None)[source]¶

Style the binary’s own name inside program, leaving its directory plain.

/opt/homebrew/bin/mas renders with only mas in the active theme’s invoked_command style, so the part of the path the eye scans for stands out from the noise of its location. A bare name (no separator) is styled whole. Both POSIX and Windows separators are recognized, whichever comes last.

Parameters:

program (str) – the command, path and all.
theme (HelpTheme | None) – palette to style with. Defaults to the theme the current invocation runs under, see format_cli_prompt().

Return type:

Returns:

the styled command.

click_extra.install_interrupt_handler(ctx)[source]¶

Make the first Ctrl+C terminate in-flight subprocesses, then abort as usual.

Installs a SIGINT handler for the duration of the CLI run that calls terminate_live_processes() before re-raising KeyboardInterrupt (exactly what Python’s default handler raises). The abort then proceeds normally, but a concurrent fan-out no longer hangs on surviving children. The previous handler is restored when ctx closes.

Must run in the main thread: signal.signal() refuses to install a handler from any other, so a non-main-thread caller (embedded use, some tests) is a no-op that keeps the default Ctrl+C behavior.

A signal handler is required here rather than a try/except KeyboardInterrupt around the fan-out: Python delivers Ctrl+C only to the main thread, so worker threads never see the interrupt, and the exception unwinds through the executor’s blocking shutdown(wait=True) teardown before any except in the caller could run. The children must be killed at signal-delivery time, ahead of that teardown.

Return type:: None

click_extra.install_manpages(command, prog_name=None, **overrides)[source]¶

Write the command tree’s man pages where man can find them.

Targets $XDG_DATA_HOME/man/man1 when that variable is set, else MAN_INSTALL_DIR. Returns the written paths.

The environment is read here rather than at import time, so a caller that sets XDG_DATA_HOME for one invocation (a test, a packaging script staging into a build root) is honored. This mirrors install_carapace_spec(), whose spec directory resolves the same way.

Return type:: list[Path]

click_extra.is_stdout(path)[source]¶

Return True when path is the stdout sentinel -.

Guards against accidentally creating a file literally named - in the current directory.

Return type:: bool

click_extra.jobs_option(param_decls: Sequence[str] | None = None, default='auto', expose_value=False, show_default=True, type=<click_extra.execution.JobCount object>, help="Number of parallel jobs. Accepts an integer, 'auto' (the host's logical CPUs minus one) or 'max' (all logical CPUs). 0 runs sequentially.", **kwargs)¶

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.last_param(params, klass)[source]¶

Return the last parameter of exactly klass in params, or None.

Unlike search_params(), this matches the exact klass (no subclasses) and tolerates duplicates: when an option is declared more than once (like an explicit @verbosity_option stacked on a Click Extra command that already ships one), Click keeps the last occurrence, so this mirrors that here instead of erroring out on the ambiguity.

Parameters:

params (Iterable[Parameter]) – the command’s parameter list to scan.
klass (type[Parameter]) – the exact parameter class to look for.

Return type:

Parameter | None

click_extra.launch(url, wait=False, locate=False)[source]¶

This function launches the given URL (or filename) in the default viewer application for this file type. If this is an executable, it might launch the executable in a new session. The return value is the exit code of the launched application. Usually, 0 indicates success.

Examples:

click.launch('https://click.palletsprojects.com/')
click.launch('/my/downloaded/file', locate=True)

Added in version 2.0.

Parameters:

url (str) – URL or filename of the thing to launch.
wait (bool) – Wait for the program to exit before returning. This only works if the launched program blocks. In particular, xdg-open on Linux does not block.
locate (bool) – if this is set to True then instead of launching the application associated with the URL it will attempt to launch a file manager with the file located. This might have weird effects if the URL does not point to the filesystem.

Return type:

int

click_extra.lazy_group(*args, **kwargs)¶

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.load_test_suite(path)[source]¶

Read a test suite file and parse it by the format of its extension.

The format is resolved from path’s name over the list-capable SUITE_FORMATS (so suite.toml parses as TOML, suite.yaml as YAML). Reading and format detection are delegated to click_extra.config.formats.read_file().

Raises:

ValueError – the file extension matches no suite format.
ImportError – the matched format’s optional parser is not installed.

Return type:

click_extra.make_pass_decorator(object_type, ensure=False)[source]¶

Given an object type this creates a decorator that will work similar to pass_obj() but instead of passing the object of the current context, it will find the innermost context of type object_type().

This generates a decorator that works roughly like this:

from functools import update_wrapper

def decorator(f):
    @pass_context
    def new_func(ctx, *args, **kwargs):
        obj = ctx.find_object(object_type)
        return ctx.invoke(f, obj, *args, **kwargs)
    return update_wrapper(new_func, f)
return decorator

Parameters:

object_type (type[T]) – the type of the object to pass.
ensure (bool) – if set to True, a new object will be created and remembered on the context if it’s not there yet.

Return type:

t.Callable[[t.Callable[te.Concatenate[T, P], R]], t.Callable[P, R]]

click_extra.make_schema_callable(schema, *, strict=False, normalize=True, warn_unknown=False)[source]¶

Wrap a schema type into a callable that accepts a raw config dict.

Dataclass types (detected via dataclasses.is_dataclass) are auto-wrapped: keys are normalized (hyphens to underscores), nested dicts are flattened, and the result is filtered to known fields before instantiation. Three schema-aware features refine this process:
1. Type-aware flattening. Fields typed as dict[str, X] are treated as opaque: flatten_config_keys stops at their boundary so the dict value is kept intact.
2. Field metadata. Dataclass fields may carry click_extra.config_path (a dotted TOML path like "test-matrix.replace") and click_extra.normalize_keys (False to skip key normalization on the extracted value). Fields with an explicit path are extracted from the raw config before normalization and flattening.
3. Nested dataclass support. Fields whose resolved type is itself a dataclass are recursively processed with the same logic.
Any other callable is returned as-is. The caller is responsible for key normalization if needed.
None returns None.

Parameters:

strict (bool) – If True, raise ValueError when the config contains keys that do not match any dataclass field (after normalization and flattening).
warn_unknown (bool) – If True (and strict is False), log a warning naming those same unknown keys instead of silently dropping them. Meant for configs whose section is schema-only (no CLI parameter is merged from it, i.e. included_params=()), where any unrecognized key can only be a typo. Applies recursively to nested dataclasses.
normalize (bool) – If False, skip normalize_config_keys on the remaining config dict. Used internally when recursing into nested dataclasses whose parent opted out of normalization via click_extra.normalize_keys = False.

Return type:

Callable[[dict[str, Any]], Any] | None

click_extra.man_option(param_decls: tuple[str, ...] | None = None, is_flag: bool = True, expose_value: bool = False, is_eager: bool = True, help: str = "Read the command's manual page and exit.", **kwargs)¶

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.multicall_group(*args, **kwargs)¶

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.new_logger(name='root', *, propagate=False, force=True, **kwargs)[source]¶

Setup a logger in the style of Click Extra.

By default, this helper will:

Fetch the logger registered under the name parameter, or creates a new one with that name if it doesn’t exist,
Set the logger’s propagate attribute to False,
Force removal of any existing handlers and formatters attached to the logger,
Attach a new StreamHandler with Formatter,
Return the logger object.

This function is a wrapper around basicConfig() and takes the same keywords arguments.

Parameters:

name (str) – ID of the logger to setup. If None, Python’s root logger will be used. If a logger with the provided name is not found in the global registry, a new logger with that name will be created.
propagate (bool) – Sets the logger’s propagate attribute. Defaults to False.
force (bool) – Same as the force parameter from logging.basicConfig() and basicConfig(). Defaults to True.
kwargs – Any other keyword parameters supported by logging.basicConfig() and basicConfig().

Return type:

Logger

click_extra.no_color_option(param_decls: Sequence[str] | None = None, is_flag=True, default=False, is_eager=True, expose_value=False, help='Disable colorization (alias of --color=never).', **kwargs)¶

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.no_config_option(param_decls: Sequence[str] | None = None, type=UNPROCESSED, help='Ignore all configuration files and only use command line parameters and environment variables.', is_flag=True, flag_value=Sentinel.NO_CONFIG, is_eager=True, expose_value=False, **kwargs)¶

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.normalize_config_keys(conf, opaque_keys=frozenset({}), _prefix='')[source]¶

Normalize configuration keys to valid Python identifiers.

Recursively replaces hyphens with underscores in all dict keys, using the same str.replace("-", "_") transform that Click applies internally when deriving parameter names from option declarations (--foo-bar becomes foo_bar). Click does not expose this as a public function, so we replicate the one-liner here.

Handles the convention mismatch between configuration formats (TOML, YAML, JSON all commonly use kebab-case) and Python identifiers. Works with all configuration formats supported by ConfigOption.

Parameters:

opaque_keys (frozenset[str]) – Fully-qualified key names (using "_" as separator) where recursion stops. The key itself is still normalized, but its dict value is kept as-is. Used in tandem with flatten_config_keys’s opaque_keys to protect data dicts (like GitHub Actions matrix axes) from normalization.
_prefix (str) – Internal parameter for tracking the accumulated key path during recursion. Callers should not set this.

Todo

Propose upstream to Click to extract the inline name.replace("-", "_") into a private _normalize_param_name helper, so downstream projects like Click Extra can reuse it instead of duplicating the transform.

Return type:: dict[str, Any]

click_extra.open_file(filename, mode='r', encoding=None, errors='strict', lazy=False, atomic=False)[source]¶

Open a file, with extra behavior to handle '-' to indicate a standard stream, lazy open on write, and atomic write. Similar to the behavior of the File param type.

If '-' is given to open stdout or stdin, the stream is wrapped so that using it in a context manager will not close it. This makes it possible to use the function without accidentally closing a standard stream:

with open_file(filename) as f:
    ...

Parameters:

filename (str | PathLike[str]) – The name or Path of the file to open, or '-' for stdin/stdout.
mode (str) – The mode in which to open the file.
encoding (str | None) – The encoding to decode or encode a file opened in text mode.
errors (str | None) – The error handling mode.
lazy (bool) – Wait to open the file until it is accessed. For read mode, the file is temporarily opened to raise access errors early, then closed until it is read again.
atomic (bool) – Write to a temporary file and replace the given file on close.

Added in version 3.0.

Return type:: IO[Any]

click_extra.option(*args, group=None, **attrs)¶

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.option_group(title, *args, **kwargs)[source]¶

Return a decorator that annotates a function with an option group.

Overloads:

title (str), help (str), options (Decorator), constraint (Optional[Constraint]), hidden (bool) → Callable[[F], F]
title (str), options (Decorator), help (Optional[str]), constraint (Optional[Constraint]), hidden (bool) → Callable[[F], F]

The help argument is an optional description and can be provided either as keyword argument or as 2nd positional argument after the name of the group:

# help as keyword argument
@option_group(name, *options, help=None, ...)

# help as 2nd positional argument
@option_group(name, help, *options, ...)

Changed in version 0.9.0: in order to support the decorator cloup.constrained_params(), @option_group now allows each input decorators to add multiple options.

Parameters:

title (str) – title of the help section describing the option group.
help – an optional description shown below the name; can be provided as keyword argument or 2nd positional argument.
options – an arbitrary number of decorators like click.option, which attach one or multiple options to the decorated command function.
constraint – an optional instance of Constraint (see Constraints for more info); a description of the constraint will be shown between squared brackets aside the option group title (or below it if too long).
hidden – if True, the option group and all its options are hidden from the help page (all contained options will have their hidden attribute set to True).

click_extra.parse_content(fmt, content)[source]¶

Parse content with a single stateless format.

INI is excluded: it needs the CLI parameter structure for type coercion and is handled by ConfigOption.load_ini_config. ARGFILE is excluded for the same reason: it maps command-line tokens to the CLI’s parameters and is handled by ConfigOption.load_argfile_config. SQLITE is excluded too: it is a binary format, read from its file path by ConfigOption.load_sqlite_config instead of a text payload.

PLIST parses here from its XML variant, the only one expressible as a text payload; the binary variant is read from its file path by ConfigOption.load_plist_config.

Note

Optional third-party parsers are imported lazily, at the point of use, rather than at module load. Only enabled formats reach this function (disabled ones are filtered out of ConfigOption.file_format_patterns), so the import always resolves for the formats actually parsed here.

Return type:: Any

click_extra.parse_duration(value, *, now=None)[source]¶

Parse a friendly, ISO 8601 or RFC 3339 duration into a timedelta.

The soft, library-friendly counterpart of the Duration parameter type: it accepts the same three input shapes but returns None instead of raising when value matches none of them, so it suits classifying values read from files or other machine sources. Unlike Duration, it does not collapse a zero duration to None: parse_duration("0") is timedelta(0), letting callers tell a zero duration from an unparsable value. None is returned only for an empty value, a future timestamp, or a value matching no known form.

Parameters:

value (Any) – The duration to parse. An existing timedelta (or None) is returned unchanged.
now (datetime | None) – Reference instant for an RFC 3339 timestamp’s age; defaults to the current UTC time.

Return type:

timedelta | None

Returns:

The parsed timedelta (possibly zero), or None.

click_extra.parse_friendly_duration(value)[source]¶

Parse only a friendly duration (7 days, 12h, a bare number of days).

Returns the parsed timedelta (possibly zero, so "0 days" is timedelta(0)), or None for anything that is not a friendly duration: ISO 8601 forms, calendar units (months, years), and empty or unrecognized values. See parse_duration() for the format-detecting umbrella.

Return type:: timedelta | None

click_extra.parse_iso8601_duration(value)[source]¶

Parse only an ISO 8601 duration (P7D, PT12H, P1WT6H).

Returns the parsed timedelta (possibly zero, so "PT0S" is timedelta(0)), or None for anything that is not an ISO 8601 duration: friendly forms, calendar (year or month) components, and empty or unrecognized values. See parse_duration() for the format-detecting umbrella.

Return type:: timedelta | None

click_extra.parse_test_suite(suite_string, fmt=ConfigFormat.YAML)[source]¶

Parse a serialized test suite string into CLITestCase instances.

fmt selects the serialization format, one of SUITE_FORMATS; it defaults to YAML for string sources with no extension to key on, such as an environment variable. load_test_suite() is the file-based counterpart.

Raises:

ValueError – the suite is empty, fmt cannot express a suite, a mapping suite omits cases, or a case uses unknown directives.
TypeError – the suite is not a list, or a case is not a mapping.
ImportError – the format’s optional parser is not installed.

Return type:

click_extra.pass_context(func)[source]¶

Mark a callback as wanting the active Context as its first argument.

Click’s own click.pass_context() is typed for the base click.Context. A handler annotated with click-extra’s enhanced Context (to reach its extra helpers like ctx.print_table) therefore fails static type checking: function parameters are contravariant, so Callable[[Context], R] is not assignable where a Callable[[click.Context], R] is expected.

This drop-in is typed for the enhanced Context and still accepts handlers typed for the base click.Context (a wider first parameter is allowed), so both type-check. At runtime it forwards the active context unchanged, exactly like click.pass_context().

Return type:: Callable[[ParamSpec(P, bound= None)], TypeVar(R)]

click_extra.pass_obj(f)[source]¶

Similar to pass_context(), but only pass the object on the context onwards (Context.obj). This is useful if that object represents the state of a nested system.

Return type:: t.Callable[P, R]

click_extra.password_option(*param_decls, **kwargs)[source]¶

Add a --password option which prompts for a password, hiding input and asking to enter the value again for confirmation.

Parameters:

param_decls (str) – One or more option names. Defaults to the single value "--password".
kwargs (Any) – Extra arguments are passed to option().

Return type:

Callable[[TypeVar(FC, bound= _AnyCallable | Command)], TypeVar(FC, bound= _AnyCallable | Command)]

click_extra.path(*, path_type=<class 'pathlib.Path'>, exists=False, file_okay=True, dir_okay=True, readable=True, writable=False, executable=False, resolve_path=False, allow_dash=False)[source]¶

Shortcut for click.Path with path_type=pathlib.Path.

Return type:: Path

click_extra.pause(info=None, err=False)[source]¶

This command stops execution and waits for the user to press any key to continue. This is similar to the Windows batch “pause” command. If the program is not run through a terminal, this command will instead do nothing.

Added in version 2.0.

Added in version 4.0: Added the err parameter.

Parameters:

info (str | None) – The message to print before pausing. Defaults to "Press any key to continue...".
err (bool) – if set to message goes to stderr instead of stdout, the same as with echo.

Return type:

click_extra.prep_path(path)[source]¶

Open path for writing as UTF-8 text, or return stdout for -.

Always yields a UTF-8 stream, stdout included, sidestepping the UnicodeEncodeError a non-ASCII payload triggers on Windows, where the console defaults to cp1252. For a real path, missing parent directories are created first, absorbing the mkdir -p a caller would otherwise need.

Note

When stdout is an in-memory capture with no backing file descriptor (Click’s test runner, the Sphinx {click:run} directive that live-renders CLI output in the docs), fileno() raises and the existing stream is returned as-is. Such streams are already Python text objects, so the Windows cp1252 concern does not apply: that only bites a real terminal, which always has a descriptor.

Parameters:: path (Path) – The destination path, or - for stdout.
Return type:: IO[str]
Returns:: A writable text stream. The caller closes it; the stdout stream is wrapped with closefd=False, so closing it leaves the real stdout open.

click_extra.print_data(data, table_format, *, default=None, root_element='records', package='click-extra', **kwargs)[source]¶

Serialize arbitrary Python data and print it to the console.

Wraps serialize_data() with user-friendly error handling for missing optional dependencies.

Parameters:

data (Any) – Arbitrary data to serialize.
table_format (TableFormat) – Target serialization format.
default (Callable | None) – Fallback serializer for custom types. Defaults to str.
root_element (str) – Root element name for XML output.
package (str) – Package name for install instructions in error messages.
kwargs – Extra keyword arguments forwarded to the underlying serializer.

Return type:

click_extra.print_table(table_data, headers=None, table_format=None, sort_key=None, max_column_widths=None, **kwargs)[source]¶

Render a table and print it to the console.

headers entries carrying a column ID (ColumnSpec instances or (label, column_id) pairs) plug the table into the active --sort-by selection: when no explicit sort_key is given, rows sort by the selected columns this table carries, and keep their original order when it carries none. See column_sort_key() for the exact semantics.

ANSI codes carried by cell values and headers depend on the format:

Markup formats with native styling support (see STYLED_FORMATS) get them translated to the format’s own styling markup, unless color output is disabled (--no-color, NO_COLOR, …).
Other markup formats get them stripped from cell values before rendering, unless --color is explicitly forced on the command line.
Plain-text formats keep them raw, and defer to echo()’s sensitivity to the global colorization settings.

Parameters:

sort_key (Callable[[Sequence[str | None]], Any] | None) – Optional callable passed to sorted() as the key argument. When provided, rows are sorted before rendering.
max_column_widths (Sequence[int | Literal['auto'] | None] | int | Literal['auto'] | None) – Width limits, as one entry per column or a single value for all of them. Each entry is a character count, "auto" to absorb the width left on the terminal, or None for no limit. Defaults to the max_width declared by ColumnSpec headers. Silently dropped by formats outside WRAPPABLE_FORMATS.

Return type:

click_extra.progressbar(iterable=None, length=None, label=None, hidden=None, show_eta=None, **kwargs)[source]¶

Drop-in for click.progressbar() honoring --progress and --time.

Click’s own progress bar is determinate, the counterpart to the indeterminate Spinner. This thin wrapper gates its visibility on the same PROGRESS flag the spinner uses, so a single --no-progress (or --accessible, which lowers the progress default) silences both, and gates its estimated-time display on --time.

Parameters:

hidden (bool | None) – tri-state. Left at its default None, the bar follows the resolved --progress flag: hidden when the user (or --accessible) turned progress off, shown otherwise. An explicit True or False forces the bar regardless, mirroring how an explicit color= argument overrides ctx.color on click.echo(). With no active context (the bar used outside a Click command) it defaults to shown.
show_eta (bool | None) – tri-state, like hidden. Left at its default None, the estimated-time-remaining display follows the --time / --no-time flag: shown under --time, hidden otherwise (its default, or outside a command). An explicit True or False forces it, keeping a bare bar’s timing in step with an OperationTrail’s timer. Click’s own default is True.

Return type:

ProgressBar[TypeVar(V)]

Note

The --progress flag gates visibility and --time the ETA. Color is already handled upstream: Click renders the bar through click.echo(), whose color=None resolves against ctx.color, so --no-color / NO_COLOR strip the bar’s ANSI without any work from this wrapper.

click_extra.prompt(text, default=None, hide_input=False, confirmation_prompt=False, type=None, value_proc=None, prompt_suffix=': ', show_default=True, err=False, show_choices=True)[source]¶

Prompts a user for input. This is a convenience function that can be used to prompt a user for input later.

If the user aborts the input by sending an interrupt signal, this function will catch it and raise a Abort exception.

Parameters:

text (str) – the text to show for the prompt.
default (Any | None) – the default value to use if no input happens. If this is not given it will prompt until it’s aborted.
hide_input (bool) – if this is set to true then the input value will be hidden.
confirmation_prompt (bool | str) – Prompt a second time to confirm the value. Can be set to a string instead of True to customize the message.
type (ParamType[Any] | Any | None) – the type to use to check the value against.
value_proc (Callable[[str], Any] | None) – if this parameter is provided it’s a function that is invoked instead of the type conversion to convert a value.
prompt_suffix (str) – a suffix that should be added to the prompt.
show_default (bool | str) – shows or hides the default value in the prompt. If this value is a string, it shows that string in parentheses instead of the actual value.
err (bool) – if set to true the file defaults to stderr instead of stdout, the same as with echo.
show_choices (bool) – Show or hide choices if the passed type is a Choice. For example if type is a Choice of either day or week, show_choices is true and text is “Group by” then the prompt will be “Group by (day, week): “.

Changed in version 8.3.3: show_default can be a string to show a custom value instead of the actual default, matching the help text behavior.

Changed in version 8.3.1: A space is no longer appended to the prompt.

Added in version 8.0: confirmation_prompt can be a custom string.

Added in version 7.0: Added the show_choices parameter.

Added in version 6.0: Added unicode support for cmd.exe on Windows.

Added in version 4.0: Added the err parameter.

Return type:: Any

click_extra.quiet_option(param_decls: Sequence[str] | None = None, **kwargs)¶

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.read_file(path, formats=None)[source]¶

Read a file and parse it, picking the format from its name.

The format is resolved with format_from_path() over formats (every ConfigFormat by default), then the content is parsed with parse_content().

Raises:

ValueError – the file name matches none of the candidate formats.
ImportError – the matched format’s optional parser is not installed.

Return type:

Any

click_extra.read_manpage(command, ctx=None)[source]¶

Typeset a command’s manual and send it to the pager.

The reading counterpart of --help-format man, which emits the roff source a packager installs. Falls back to printing that source, with a warning naming what to install, when no typesetter is available: something on screen beats an error, and the source still carries every word of the manual.

Under --accessible the emphasis is stripped and the pager bypassed (echo_via_pager() streams instead). Both matter to the same reader: a pager is a cursor-driven takeover, and overstrike is worse than the ANSI codes accessible mode already removes, since a screen reader voices N\x08NA\x08AM\x08ME\x08E rather than skipping it.

Return type:: None

click_extra.register_theme(name, theme)[source]¶

Parameters:

name (str) – Lowercase identifier used as the --theme choice value.
theme (HelpTheme) – A HelpTheme instance.

Return type:

click_extra.render_ansi(text, emitter)[source]¶

Rebuild text, replacing each ANSI-styled run by emitter’s markup.

Unstyled runs pass through verbatim, so any markup surrounding the styled runs (table borders, tags produced by another renderer) is preserved byte for byte. Styled runs are handed to emitter one line at a time: runs are split on newlines so no markup wrapper ever crosses a line boundary, which keeps line-oriented markup (LaTeX rows, wiki tables) well-formed even when a style spans multiple lines.

Return type:: str

click_extra.render_columns_markdown_table(columns)[source]¶

Render an iterable of ColumnSpec as a 2-column Markdown table.

Output shape:

| Column | Description |
| :--- | :--- |
| ``Label`` | description |
...

Suitable for inlining into MyST documents via myst_substitutions so the Available columns reference can be auto-generated from a single source of truth.

Return type:: str

click_extra.render_command_tree(command, prog_name=None, ctx=None, width=None)[source]¶

Render the hierarchy rooted at command as a tree with descriptions.

Reuses ctx when given (like the live invocation context), otherwise builds a throwaway one with resilient_parsing=True. The root line is labeled with prog_name when given, else the context’s command path.

Each node carries the command name, its aliases, its operand metavars (mirroring the usage line) and a column-aligned description from full_short_help(), so deprecated commands carry their (Deprecated) marker. Everything is styled with the same theme slots as help screens (invoked_command for the root, subcommand and alias for children, metavar for operands), so the tree follows --theme and --color. The rail switches from box-drawing to ASCII when accessibility mode is active on the context (see ACCESSIBLE).

Descriptions wrap at width, resolved like help screens when not given (ctx.make_formatter(), honoring the terminal_width and max_content_width context settings). Wrapped lines keep the tree rail running through the description column. A label wider than the column (typically a long script path as the root, under wrap --tree) keeps its line to itself and hangs its description underneath, at the column.

Note

The tree is a point-in-time snapshot: groups computing their subcommands from external state (plugins, scanned directories) render exactly what click.Group.list_commands() returns at that moment, in listing order. Cloup section groupings are not rendered.

Caution

A non-group command renders as a single root line: valid, just not very interesting. Like a man page, the output stays meaningful for every command type.

Return type:: str

click_extra.render_help(command, help_format, prog_name=None, ctx=None, **overrides)[source]¶

Render command in one of the HELP_FORMATS.

Reuses ctx when given (like the live invocation context), otherwise builds a throwaway one with resilient_parsing=True, exactly like render_manpage(). Keyword overrides are passed through to extract_command_doc(), and ignored by the carapace format, which carries no version or authorship of its own.

Raises:: ValueError – on an unknown format, listing the known ones.
Return type:: str

click_extra.render_manpage(command, prog_name=None, ctx=None, **overrides)[source]¶

Render a single command’s man page as a roff string.

Reuses ctx when given (like the live invocation context), otherwise builds a throwaway one with resilient_parsing=True. Keyword overrides (version, date, manual, authors, copyright) are passed through to extract_command_doc().

Return type:: str

click_extra.render_manpages(command, prog_name=None, **overrides)[source]¶

Render the whole command tree, one man page per (sub)command.

Returns an ordered mapping of {filename: roff} where each filename is the command path joined by hyphens plus the section suffix (like weather-forecast.1).

Return type:: dict[str, str]

click_extra.render_table(table_data, headers=None, table_format=None, sort_key=None, max_column_widths=None, **kwargs)[source]¶

Render a table and return it as a string.

Parameters:

sort_key (Callable[[Sequence[str | None]], Any] | None) – Optional callable passed to sorted() as the key argument. When provided, rows are sorted before rendering.
max_column_widths (Sequence[int | Literal['auto'] | None] | int | Literal['auto'] | None) – Width limits, as one entry per column or a single value for all of them. Each entry is a character count, "auto" to absorb the width left on the terminal, or None for no limit. Defaults to the max_width declared by ColumnSpec headers. Silently dropped by formats outside WRAPPABLE_FORMATS.

Return type:

CompletedProcess[str]

click_extra.require_sibling_param(params, requester, klass)[source]¶

Return the sibling klass parameter declared on the same command, or raise.

Some options are inert on their own: they drive machinery owned by a sibling option. --no-config and --validate-config, for instance, both depend on the --config option (ConfigOption). This helper centralizes the lookup so every such option raises the same RuntimeError when its required sibling is missing, naming the offending flag.

Parameters:

params (Iterable[Parameter]) – the command’s parameter list to scan.
requester (Parameter) – the parameter requiring the sibling, used to build the error message from its flag names and class.
klass (type[TypeVar(P, bound= Parameter)]) – the sibling parameter class to look for.

Return type:

TypeVar(P, bound= Parameter)

click_extra.resolve_jobs(ctx, count, *, serial_at_debug=False)[source]¶

Resolve how many worker threads to use for a batch of count items.

Returns the number of items to process in parallel; 1 means run sequentially in the calling thread. This is the policy shared by run_jobs() and run_lanes(), exposed on its own for callers that must know the resolved count before they fan out (for example to pick a progress-rendering mode). It collapses to sequential when:

there is no active CLI context (programmatic or test use),
a single item leaves nothing to parallelize, or
the resolved JobsOption count (ctx.meta[click_extra.context.JOBS]) is 1 or less.

Otherwise that count wins, capped at count: there is no point spinning up more workers than there are items.

Parameters:

ctx (Context | None) – the active Click context, read for the resolved --jobs count (and, with serial_at_debug, the verbosity). None forces sequential.
count (int) – how many items are about to be scheduled.
serial_at_debug (bool) – when set, also collapse to sequential at DEBUG verbosity, where coherent per-worker log narration matters more than the speed-up (interleaved threads would scramble it). Off by default.

Return type:

int

click_extra.run_cli(args, *, extra_env=None, cwd=None, timeout=None, label=None, merge_streams=False, errors='replace', windows_creation_flags=0, start_new_session=False, command_level=20, output_level=10, log=None)[source]¶

Run a CLI in a subprocess, disclosing the call and streaming its output live.

A subprocess.run() work-alike for CLI-wrapping tools, with observability built in:

the invocation is logged before the spawn, as the copy-pasteable $ ENV=value command args line of format_cli_prompt(), so a user can reproduce by hand what the tool runs on their system;
each line of the child’s output is forwarded to the logger as it is produced (ANSI-stripped, tagged with label), instead of being held back until the child exits, so a long-running command narrates its progress live;
the child is registered in the live-process registry for the duration of the call, so terminate_live_processes() (wired to Ctrl+C by install_interrupt_handler()) can abort it.

Contract mirrored from subprocess.run():

returns a subprocess.CompletedProcess with the full captured stdout and stderr decoded as UTF-8;
raises subprocess.TimeoutExpired (with the partial capture attached) when the child, or the draining of its output, outlives timeout. The child is killed first — its whole process tree on Windows (see _kill_windows_process_tree()), its whole POSIX process group when spawned with start_new_session, the direct child alone otherwise;
a KeyboardInterrupt mid-run kills the child (with the same tree, group or direct scope), then propagates.

The child reads from subprocess.DEVNULL so it can never block on stdin, and never opens a console window on Windows.

Note

The pipes are opened in universal-newlines text mode, so a bare \r (a child redrawing a progress bar in place) terminates a line just like \n: each redraw is streamed as its own log line, and the captured text normalizes both to \n, exactly as subprocess.Popen.communicate() does.

Parameters:

args (str | Path | None | Iterable[str | Path | None | Iterable[Iterable[str | Path | None | Iterable[TNestedArgs]]]]) – the command line. Nested iterables are flattened, None values dropped, and every element (Path, versions, …) cast to a string; see args_cleanup().
extra_env (Mapping[str, str | None] | None) – environment variables forced over the inherited environment for this call (see env_copy()). They are part of the disclosed prompt line, since reproducing the call requires them.
cwd (Path | str | None) – directory to run the child in. None inherits the caller’s, which is subprocess.run()’s own default. A relative args[0] is resolved by the OS against this directory, not the caller’s, so pass an absolute path (or a name on the PATH) when moving the child elsewhere.
timeout (float | None) – seconds before the child is killed. None waits forever.
label (str | None) – tag identifying this call on each streamed output line, for when several children interleave in one log. Carried as the record’s label attribute, which click_extra.logging.Formatter renders glued to the level name and styled like an invoked command (debug:mas: Warning: ...); a foreign formatter can read record.label itself. Applied to the output lines only, never the prompt line.
merge_streams (bool) – route the child’s stderr into stdout so the OS interleaves both in write order. The result’s stderr is then None, like a subprocess.run() call with stderr=STDOUT.
errors (str) – decoding error handler for the child’s output. The default "replace" swaps undecodable bytes for �; pass "backslashreplace" to keep them inspectable as escapes.
windows_creation_flags (int) – extra Windows process-creation flags, OR-ed with the always-on CREATE_NO_WINDOW. No-op off Windows.
start_new_session (bool) – make the child lead its own POSIX session and process group (subprocess.Popen’s parameter of the same name). Every kill path — the timeout overrun, a mid-run KeyboardInterrupt, and terminate_live_processes() — then signals the whole group, so a grandchild spawned by the child (a shim re-executing the real binary, an installer helper) is reaped along with it instead of surviving as an orphan holding the output pipes open. Off by default, and to be left off when a descendant must keep the controlling terminal: a new session detaches from it, so an interactive prompt raised from inside the child (sudo reading /dev/tty) would fail, and sudo’s tty-keyed credential cache would no longer match. No-op on Windows, where the timeout path already kills the full tree. Only the reaping half of this flag has that Windows equivalent, and the other half has none: a POSIX session also detaches the child from the controlling terminal, where a Windows child keeps sharing the parent’s console and can still reach back into it. A subprocess-heavy test suite is where that surfaces — meta-package-manager’s Windows CI saw a package manager’s own teardown land in the parent pytest process as a mid-run KeyboardInterrupt, which a console control event on the shared console explains and which no POSIX runner showed. The lever there is windows_creation_flags (CREATE_NEW_PROCESS_GROUP), left to the caller because it also changes how a real Ctrl-C reaches the child.
command_level (int) – logging level of the invocation-disclosure line. Defaults to logging.INFO; lower it to logging.DEBUG for internal probes not worth narrating.
output_level (int) – logging level of the streamed output lines. Defaults to logging.DEBUG.
log (Logger | None) – destination logger. Defaults to the root logger, whose level the VerbosityOption family manages.

Return type:

click_extra.run_config_validation(user_conf, *, app_name, params_template, config_schema=None, config_validators=(), fallback_sections=(), schema_strict=False, schema_warn_unknown=False, strict=False, blocked_params=(), collect_all=True)[source]¶

Validate a parsed configuration document in one schema-driven pass.

This is the module-level entry point that unifies click-extra’s three historical validation paths (CLI-parameter strict check, dataclass schema, and app-registered ConfigValidator hooks) behind a single function yielding a single error type. It is deliberately not named validate_config: that name belongs to validate_config(), the callback powering the --validate-config flag.

Stages, in order:

Normalize. Strip reserved keys and expand dotted keys.
Partition. Split opaque sub-trees (schema extension fields plus every registered validator’s extension_path) from the CLI-flag-bound content. Extracted sub-trees land in ValidationReport.opaque_subtrees.
Strict-check the CLI-flag-bound part against params_template, keeping the merged result as ValidationReport.merged_conf (skipped when params_template is None).
Schema-build the app section through the configured callable, producing ValidationReport.schema_instance.
Validate every opaque sub-tree through its registered validator.

Parameters:

user_conf (dict[str, Any]) – The full parsed configuration document.
app_name (str) – Name of the app’s section (used to resolve the section and to root opaque paths and error paths at the document level).
params_template (dict[str, Any] | None) – The CLI-parameter template the strict check runs against. Pass None to skip the strict check entirely (for example, for a schema-only validation).
config_schema (type | Callable[[dict[str, Any]], Any] | None) – Dataclass type or callable describing the typed configuration, or None.
config_validators (Sequence[ConfigValidator]) – Extension validators to run against opaque sub-trees.
fallback_sections (Sequence[str]) – Legacy section names to try when app_name is absent or empty.
schema_strict (bool) – Reject keys the dataclass schema does not recognize.
schema_warn_unknown (bool) – In lax mode, log a warning naming keys the dataclass schema does not recognize (see warn_unknown in make_schema_callable()). Ignored when schema_strict rejects them outright.
strict (bool) – Reject keys the CLI-parameter template does not recognize.
blocked_params (Iterable[str]) – Fully-qualified IDs of parameters excluded from configuration files, used to sharpen strict-mode error messages (a blocked parameter is reported as such, not as unknown).
collect_all (bool) – When True (default), run every stage and collect all errors. When False, the first error short-circuits the rest.

Return type:

ValidationReport

Returns:

A ValidationReport. ValidationError is the single error type recorded by every stage; ValueError / TypeError raised by the strict check or schema callable are wrapped into it.

click_extra.run_jobs(func, items, *, jobs=None, serial_at_debug=False)[source]¶

Run func over items, parallelized per the resolved --jobs count.

The worker count is taken from jobs when given, else resolved from the active command’s JobsOption value by resolve_jobs(), else 1. With a single worker (or at most one item) the items run sequentially and lazily, so a caller can stop early on the first result (for example to abort on the first failure); otherwise they run in a thread pool. Either way results are yielded in submission order, like map().

This is the single-task-per-item special case of run_lanes() (every item is its own lane). Reach for run_lanes() when some items must run serially relative to one another while others run concurrently.

The pool is thread-based, which suits the I/O- and subprocess-bound work CLI tools usually parallelize (each child releases the GIL). The count is a number of logical CPUs: see CPU_COUNT.

items is never materialized: only a bounded window of tasks is queued at a time, so an unbounded or expensive-to-produce stream stays memory-flat and is read no further than the caller consumes.

Parameters:

func (Callable[[TypeVar(T)], TypeVar(R)]) – Called once per item; its return value is yielded.
items (Iterable[TypeVar(T)]) – The work items. Read lazily, a window at a time.
jobs (int | None) – Override the worker count instead of reading it from the context. 1 or fewer forces sequential execution.
serial_at_debug (bool) – forwarded to resolve_jobs() when jobs is not given: collapse to sequential at DEBUG verbosity.

Return type:

Returns:

An iterator over func’s results, in the order of items.

click_extra.run_lanes(func, lanes, *, jobs=None, serial_at_debug=False)[source]¶

Run func over grouped items: serial within a lane, concurrent across.

Each lane is an iterable of items. func is mapped over every item, but a lane’s own items run serially and in order on a single worker, while distinct lanes run concurrently up to the resolved --jobs count. This is the right primitive when some work must be serialized relative to itself (a shared lock, a rate limit, one mailbox file, one package-manager backend) yet still overlap with unrelated work.

run_jobs() is the degenerate case where every lane holds a single item. Concurrency is sized by the number of lanes (one worker per lane), since a lane never splits across workers.

Results are yielded in lane-submission order, a lane’s items in order, like map(). The run stays lazy at any worker count: a lane is materialized only when it is about to be scheduled, and only a bounded window of lanes is in flight, so a caller can break early and the lanes behind it are never read. A lane runs entirely on one worker, so a stateful resource bound to the lane (a per-lane cache, a connection) is touched by only that one thread and needs no lock.

Parameters:

func (Callable[[TypeVar(T)], TypeVar(R)]) – Called once per item; its return value is yielded.
lanes (Iterable[Iterable[TypeVar(T)]]) – The lanes, each an iterable of items. Read lazily, a window of lanes at a time; a lane’s own items are materialized when it is scheduled.
jobs (int | None) – Override the worker count instead of reading it from the context. 1 or fewer forces fully sequential execution.
serial_at_debug (bool) – forwarded to resolve_jobs() when jobs is not given: collapse to sequential at DEBUG verbosity.

Return type:

Returns:

An iterator over func’s results, lane by lane in submission order.

click_extra.run_test_suite(command, cases, *, jobs=1, select_test=None, skip_platform=None, timeout=None, work_directory=None, exit_on_error=False, show_trace_on_error=True, stats=True, show_progress=True)[source]¶

Run a list of test cases against a target command and tally the results.

Cases are parallelized per jobs (see click_extra.execution.run_jobs()): at one worker they run sequentially and lazily, so exit_on_error can stop before the rest start; otherwise they run in a thread pool and every case runs to completion. Either way outcomes are tallied in submission order. On an interactive terminal a click_extra.spinner.Spinner reports progress unless show_progress is false.

Parameters:

command (Path | str) – The target to test: a command name, a command line, or a path to a binary or script.
cases (Sequence[CLITestCase]) – The test cases to run.
jobs (int) – Number of parallel workers; 1 runs sequentially.
select_test (Sequence[int] | None) – 1-based case numbers to run; others are skipped.
skip_platform (Trait | Group | str | None | Iterable[Trait | Group | str | None | Iterable[Trait | Group | str | None | Iterable[Trait | Group | str | None | Iterable[_TNestedReferences]]]]) – Extra platforms (or group IDs) to skip every case on.
timeout (float | None) – Default per-case timeout in seconds when a case sets none.
work_directory (Path | str | None) – Directory every case runs its command in, defaulting to the runner’s own. It moves the target, never the runner: the suite file is read before any case starts, and command is resolved to an absolute path first, so neither is looked up relative to it.
exit_on_error (bool) – Stop at the first failure (sequential runs only).
show_trace_on_error (bool) – Echo the execution trace of each failed case.
stats (bool) – Echo a one-line worker summary up front and a result tally.
show_progress (bool) – Allow the progress spinner on an interactive terminal.

Return type:

Counter

Returns:

A collections.Counter with total, skipped, and failed keys. A non-zero failed count signals the caller to exit with an error.

click_extra.schema_field_infos(schema)[source]¶

Walk a configuration schema dataclass into per-option records.

Introspects the dataclass fields, their type annotations, defaults, and attribute docstrings. Nested dataclass fields expand recursively into dotted keys (test-suite.timeout), honoring click_extra.config.schema.CONFIG_PATH_METADATA_KEY at every level. Records are sorted by key, segment-wise, so a sub-table’s options stay contiguous even when another table’s name shares their prefix (workflow.sync sorts before workflow-pins.sync).

Defaults are read off a pristine schema() instance, so every field must carry a default: configuration schemas are default-complete by construction, since make_schema_callable() instantiates them from partial user data.

Raises:: TypeError – when schema is not a dataclass type.
Return type:: list[SchemaFieldInfo]

click_extra.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) – 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.
unique (bool) – if True, raise an error if more than one parameter of the provided klass is found. Defaults to True.

Return type:

list[Parameter] | Parameter | None

click_extra.secho(message=None, file=None, nl=True, err=False, color=None, **styles)[source]¶

This function combines echo() and style() into one call. As such the following two calls are the same:

click.secho('Hello World!', fg='green')
click.echo(click.style('Hello World!', fg='green'))

All keyword arguments are forwarded to the underlying functions depending on which one they go with.

Non-string types will be converted to str. However, bytes are passed directly to echo() without applying style. If you want to style bytes that represent text, call bytes.decode() first.

Changed in version 8.0: A non-string message is converted to a string. Bytes are passed through without style applied.

Added in version 2.0.

Return type:: None

click_extra.select_columns(columns, selected_ids)[source]¶

Filter and reorder columns according to selected_ids.

Returns columns unchanged when selected_ids is falsy (no projection). Otherwise yields the matching ColumnSpec in the order selected_ids specifies, SQL-SELECT-style. Raises KeyError for unknown IDs so the caller can convert it into a click.UsageError.

Return type:: tuple[ColumnSpec, ...]

click_extra.select_row(row, selected_ids, canonical_ids)[source]¶

Build a positional row by reading cells from row in the selection order.

Falls back to canonical_ids when selected_ids is empty / unset, so the row preserves its canonical column order in the absence of any user selection.

Return type:: tuple

click_extra.serialize_content(fmt, data, **kwargs)[source]¶

Serialize a Python object to a string in the given format.

The dumping counterpart to parse_content(). Per-format defaults can be overridden through kwargs (forwarded to the underlying serializer). JSON5 and JSONC are emitted as plain JSON, a valid subset of both.

Caution

Not every format round-trips: TOML, XML and PLIST have no null type (plistlib even raises on None values), and XML expects a single root mapping, so the caller is responsible for shaping data accordingly. INI, SQLITE and pyproject.toml have no serializer here.

Note

Optional third-party serializers are imported lazily, at the point of use. Writing TOML uses tomlkit (the [toml] extra), unlike reading which relies on the built-in tomllib.

Raises:: ValueError – the format has no serializer.
Return type:: str

click_extra.serialize_data(data, table_format, *, default=None, root_element='records', **kwargs)[source]¶

Serialize arbitrary Python data to a structured format.

Unlike render_table() which expects tabular rows and headers, this function accepts any JSON-compatible data structure (dicts, lists, nested combinations) and serializes it to the requested format.

Only formats in SERIALIZATION_FORMATS are supported.

Parameters:

data (Any) – Arbitrary data to serialize (dicts, lists, scalars).
table_format (TableFormat) – Target serialization format.
default (Callable | None) – Fallback serializer for types not natively supported. Defaults to str, so Path and similar types are stringified automatically. Set to a custom callable for different behavior.
root_element (str) – Root element name for XML output.
kwargs – Extra keyword arguments forwarded to the underlying serializer (like sort_keys or indent for JSON).

Raises:

ValueError – If the format is not a serialization format.

Return type:

click_extra.set_default_theme(theme)[source]¶

Override the process-wide fallback theme.

ThemeOption writes its picked theme to ctx.meta rather than calling this helper, so per-invocation choices do not leak across invocations sharing the same process. Use this only for genuinely process-wide overrides: patch_click() is the canonical caller.

Return type:: None

click_extra.show_params_option(param_decls: Sequence[str] | None = None, is_flag=True, expose_value=False, is_eager=True, help='Show all CLI parameters, their provenance, defaults and value, then exit.', **kwargs)¶

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.sort_by_option(*header_defs, cls=<class 'click_extra.table.SortByOption'>, group=None, **kwargs)[source]¶

Attach a SortByOption to a command.

Forwards the positional header_defs ((label, column_id) pairs) straight to the option constructor and registers a regular Cloup Option, so the --sort-by option composes with @option_group and @constraint like any other option decorator.

Note

Hand-written instead of produced by decorator_factory() because SortByOption accepts its column definitions as positional arguments, which conflicts with the param_decls-first convention the factory relies on.

click_extra.split_ansi(text)[source]¶

Split text into (style, text) runs at ANSI SGR escape boundaries.

A stateful SGR stream parser: each escape updates the current style state (with full and selective resets honored, unlike Style.from_ansi()), and every maximal run of text sharing the same state is yielded with its Style. Unstyled text is yielded with an empty Style. Consecutive runs with equal styles are merged and empty runs are dropped, so wrapping each yielded run produces minimal markup.

Non-SGR escapes carry no style information and are removed from the yielded text, per _strip_unsupported_ansi().

Return type:: Iterator[tuple[Style, str]]

click_extra.style(text, fg=None, bg=None, bold=None, dim=None, underline=None, overline=None, italic=None, blink=None, reverse=None, strikethrough=None, reset=True)[source]¶

Styles a text with ANSI styles and returns the new string. By default the styling is self contained which means that at the end of the string a reset code is issued. This can be prevented by passing reset=False.

Examples:

click.echo(click.style('Hello World!', fg='green'))
click.echo(click.style('ATTENTION!', blink=True))
click.echo(click.style('Some things', reverse=True, fg='cyan'))
click.echo(click.style('More colors', fg=(255, 12, 128), bg=117))

Supported color names:

black (might be a gray)
red
green
yellow (might be an orange)
blue
magenta
cyan
white (might be light gray)
bright_black
bright_red
bright_green
bright_yellow
bright_blue
bright_magenta
bright_cyan
bright_white
reset (reset the color code only)

If the terminal supports it, color may also be specified as:

An integer in the interval [0, 255]. The terminal must support 8-bit/256-color mode.
An RGB tuple of three integers in [0, 255]. The terminal must support 24-bit/true-color mode.

See https://en.wikipedia.org/wiki/ANSI_color and https://gist.github.com/XVilka/8346728 for more information.

Parameters:

text (Any) – the string to style with ansi codes.
fg (int | tuple[int, int, int] | str | None) – if provided this will become the foreground color.
bg (int | tuple[int, int, int] | str | None) – if provided this will become the background color.
bold (bool | None) – if provided this will enable or disable bold mode.
dim (bool | None) – if provided this will enable or disable dim mode. This is badly supported.
underline (bool | None) – if provided this will enable or disable underline.
overline (bool | None) – if provided this will enable or disable overline.
italic (bool | None) – if provided this will enable or disable italic.
blink (bool | None) – if provided this will enable or disable blinking.
reverse (bool | None) – if provided this will enable or disable inverse rendering (foreground becomes background and the other way round).
strikethrough (bool | None) – if provided this will enable or disable striking through text.
reset (bool) – by default a reset-all code is added at the end of the string which means that styles do not carry over. This can be disabled to compose styles.

Changed in version 8.0: A non-string message is converted to a string.

Changed in version 8.0: Added support for 256 and RGB color codes.

Changed in version 8.0: Added the strikethrough, italic, and overline parameters.

Changed in version 7.0: Added support for bright colors.

Added in version 2.0.

Return type:: str

click_extra.table_format_option(param_decls: Sequence[str] | None = None, type=EnumChoice('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'), default=TableFormat.ROUNDED_OUTLINE, expose_value=False, is_eager=True, help='Rendering style of tables.', **kwargs)¶

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.telemetry_option(param_decls: Sequence[str] | None = None, default=False, expose_value=False, envvar=None, show_envvar=True, help='Collect telemetry and usage data.', **kwargs)¶

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.terminate_live_processes()[source]¶

Send SIGTERM to every subprocess currently running through run_cli().

Called from the main thread’s SIGINT handler (see install_interrupt_handler()) so a concurrent fan-out aborts promptly: terminating the children unblocks the worker threads parked in run_cli(), letting the thread pool drain instead of hanging on a child that ignored the terminal’s process-group SIGINT.

A child spawned with start_new_session never receives the terminal’s SIGINT at all (it left the foreground process group), so its whole group is signalled here, descendants included.

Uses SIGTERM rather than SIGKILL so a child still gets to clean up, notably to restore terminal state a sudo password prompt may have altered. The registry is snapshotted under the lock, then signalled outside it, because run_cli() may be discarding its own entries from other threads at the same time.

Return type:: None

click_extra.theme_option(param_decls: Sequence[str] | None = None, default: str = 'dark', is_eager: bool = True, expose_value: bool = False, query_background: bool = False, help: str = 'Color theme used for help screens.', **kwargs)¶

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.timer_option(param_decls: Sequence[str] | None = None, default=False, expose_value=False, is_eager=True, help='Measure and print elapsed execution time.', **kwargs)¶

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.tree_option(param_decls: tuple[str, ...] | None = None, is_flag: bool = True, expose_value: bool = False, is_eager: bool = True, help: str = 'Show the tree of nested subcommands and exit.', **kwargs)¶

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.unstyle(text)[source]¶

Removes ANSI styling information from a string. Usually it’s not necessary to use this function as Click’s echo function will automatically remove styling if necessary.

Added in version 2.0.

Parameters:: text (str) – the text to remove style information from.
Return type:: str

click_extra.validate_config_option(param_decls: Sequence[str] | None = None, type: click.ParamType | Any = <click.types.Path object>, is_eager: bool = True, expose_value: bool = False, help: str = 'Validate the configuration file and exit.', **kwargs: Any)¶

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.verbose_option(param_decls: Sequence[str] | None = None, **kwargs)¶

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.verbosity_option(param_decls: Sequence[str] | None = None, default_logger: Logger | str = 'root', default: LogLevel = LogLevel.WARNING, metavar='LEVEL', type=EnumChoice('CRITICAL', 'ERROR', 'WARNING', 'INFO', 'DEBUG'), help='Either CRITICAL, ERROR, WARNING, INFO, DEBUG.', **kwargs)¶

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.version_option(version=None, *param_decls, cls=<class 'click_extra.version.VersionOption'>, group=None, **kwargs)[source]¶

Attach a VersionOption to a command.

Drop-in compatible with Click’s @version_option: the first positional argument may be an explicit version string. click-extra otherwise auto-detects the version and treats positional arguments as option flags (like every other option decorator), so the two are disambiguated by their leading character: a value starting with - is a flag declaration, anything else is a Click-style version string forwarded into the version template field.

@command
@version_option("1.2.3")  # Click idiom: pins the displayed version.
def my_cmd(): ...

Note

Hand-written instead of produced by decorator_factory() because Click’s leading version positional conflicts with the param_decls-first convention the factory relies on.

click_extra.wrap_ansi(text, width)[source]¶

Wrap text to width visible columns, preserving its ANSI styling.

textwrap.wrap() counts every byte of an ANSI escape toward the line length, so a styled string wraps far earlier than its visible width warrants. Line breaks are computed here on the plain text, then mapped back onto the styled runs of split_ansi(). Like render_ansi(), no escape sequence crosses a line boundary: each returned line carries the styling it needs, opened and closed within the line.

Returns a list of lines, empty text yielding a single empty one.

Note

Where the breaks fall is still textwrap.wrap()’s decision, so long-word breaking and whitespace handling match it exactly. It measures in characters, which means a run of double-width characters occupies more terminal columns than width, as it does everywhere else Click wraps text.

Return type:: list[str]

click_extra.wrap_text(text, width=78, initial_indent='', subsequent_indent='', preserve_paragraphs=False)[source]¶

A helper function that intelligently wraps text. By default, it assumes that it operates on a single paragraph of text but if the preserve_paragraphs parameter is provided it will intelligently handle paragraphs (defined by two empty lines).

If paragraphs are handled, a paragraph can be prefixed with an empty line containing the \b character (\x08) to indicate that no rewrapping should happen in that block.

Parameters:

text (str) – the text that should be rewrapped.
width (int) – the maximum width for the text.
initial_indent (str) – the initial indent that should be placed on the first line as a string.
subsequent_indent (str) – the indent string that should be placed on each consecutive line.
preserve_paragraphs (bool) – if this flag is set then the wrapping will intelligently handle paragraphs.

Changed in version 8.4.0: Width is measured in visible characters. ANSI escape sequences in text, initial_indent, or subsequent_indent no longer count toward the width budget, so styled input wraps based on what the user sees instead of raw byte length.

Return type:: str

click_extra.write_manpages(command, target_dir, prog_name=None, **overrides)[source]¶

Render the command tree and write each man page into target_dir.

Creates target_dir if missing. Returns the list of written paths.

Return type:: list[Path]

click_extra.zero_exit_option(param_decls: Sequence[str] | None = None, default=False, expose_value=False, is_flag=True, help='Always exit with a status code of 0, even when problems are found.', **kwargs)¶

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.

Subpackages¶

Submodules¶

click_extra.blocks module¶

Offline self-updating block toolkit for Markdown sources.

Fence-aware Markdown scanning, the  /  marker grammar, and the walk-rewrite-write loop behind the click-extra refresh-directives command.

The toolkit backs the :matrix: directive ({mod}``click_extra.sphinx.matrix``) and the python:render :mirror: flag, but it depends only on re and pathlib: nothing here imports Sphinx or docutils. Living in the package root rather than under click_extra.sphinx lets a release pipeline or a standalone documentation script reuse replace_region and update_blocks without pulling in the sphinx extra.

click_extra.blocks.OPTION_LINE_RE = re.compile('^[ \\t]*:(?P<key>[\\w+-]+):[ \\t]*(?P<value>.*?)[ \\t]*$')¶: A :key: value MyST directive option line (value optional for flags).

class click_extra.blocks.FenceSpan(start: int, close: int | None)[source]¶

Bases: NamedTuple

A top-level backtick fence in a Markdown source, as line indices.

Create new instance of FenceSpan(start, close)

start: int¶: Index of the opening fence line.

close: int | None¶: Index of the closing fence line, or None when unterminated.

click_extra.blocks.fence_spans(lines)[source]¶

Map each top-level backtick fence’s opening line index to its span.

Fences are consumed as opaque units: a fence line inside an outer fence (a documented example wrapped in a longer code-block fence) never starts a span of its own. A close requires a bare run of the same character, at least as long as the opener, at the same indentation. An unterminated fence spans to the end of the file with close=None.

Return type:: dict[int, FenceSpan]

click_extra.blocks.marker_res(name)[source]¶

Build the (open, close) regexes of a  region.

The grammar is shared by every self-updating marker region: the opening comment is  (args optional, whitespace separated), the closing comment is . Both capture their leading indentation as indent.

Return type:: tuple[Pattern[str], Pattern[str]]

click_extra.blocks.replace_region(text, name, content, *, pad=True)[source]¶

Return text with the body of a  region swapped for content.

Finds the  opening and  closing markers (the grammar of marker_res()) and replaces everything between them with content. The markers themselves are preserved, so the region round-trips: a second call with the same content is a no-op.

When either marker is missing the text is returned unchanged, so the call is safe to fan out over every file of an update_blocks() rewrite even when only some carry the region. This is the generic counterpart to the fence-driven refreshers of click_extra.sphinx.matrix and the python:render :mirror: flag: use it when the content is produced outside the document (a registry dump, an external generator) rather than by an inline directive.

Parameters:: pad (bool) – With the default True, content is padded by one blank line on each side, the usual layout for a Markdown block. Set it to False to keep the blank line after the opening marker (Markdown needs it to start a fresh block) but drop the one before the closing marker, so the region ends flush against it. That flush layout is what mdformat-footnote requires: it strips an HTML comment sitting on its own line right after a footnote definition (executablebooks/ mdformat-footnote#11), so a region wrapping footnotes must place its closing marker on the line immediately below the last body line. An empty content collapses to a single blank line between the markers whatever the padding.
Return type:: str

click_extra.blocks.iter_markdown_files(paths)[source]¶

Yield the Markdown sources under paths (files as-is, dirs recursed).

Return type:: Iterable[Path]

click_extra.blocks.update_blocks(paths, rewrite, *, check=False)[source]¶

Rewrite self-updating blocks in the Markdown sources under paths.

Walks paths (files, or directories recursed for *.md), applies rewrite(text, path) to each, and writes the file back when its content changed. In check mode nothing is written; the return value still lists the files that would change, so a caller can exit non-zero to flag stale documentation in CI.

Return type:: list[Path]
Returns:: the files whose blocks were (or, under check, would be) updated.

click_extra.cli module¶

Click Extra CLI with pre-baking utilities.

click_extra.cli_wrapper module¶

The click-extra wrap command and the machinery to wrap a foreign Click CLI.

Monkey-patches Click’s decorator functions before importing (or running) a target module so its @click.command() / @click.group() produce colorized, keyword-highlighted, themed variants. Also resolves and invokes the target, and introspects it for --params, --man and --tree without firing its callbacks.

Not to be confused with text wrapping: that is click.wrap_text(), exposed at the package root as click_extra.wrap_text.

class click_extra.cli_wrapper.WrapperGroup(*args, help_command=True, sort_subcommands=None, subcommand_priorities=None, **kwargs)[source]¶

Bases: Group

Group that falls back to the wrap subcommand for unknown names.

Known subcommands and their aliases are dispatched normally. Anything else is treated as a target script and forwarded to wrap.

Like Command.__init__, but auto-injects a help subcommand.

Parameters:

help_command (bool) – when True (the default), a help subcommand is automatically registered. Set to False to suppress it, or register your own help subcommand to override it.
sort_subcommands (bool | None) – how subcommands sharing a priority are broken apart. True lists them alphabetically, False in the order they were registered. None (the default) defers to the sort_subcommands context setting, then to True. See must_sort_subcommands().
subcommand_priorities (Mapping[str, float] | None) – maps a subcommand name to its priority relative to DEFAULT_PRIORITY, lowest listed first. Names left out keep the default priority, so numbering a few subcommands moves only those.

resolve_command(ctx, args)[source]¶

Return type:: tuple[str | None, Command | None, list[str]]

click_extra.cli_wrapper.patch_click(theme=None, color=True)[source]¶

Replace Click’s decorator functions with colorized variants.

Must be called before importing the target CLI module so that @click.command() and @click.group() decorators produce colorized commands.

Note

Only the decorator functions are replaced, not the class names (click.Command, click.Group). Replacing class names would break isinstance and issubclass checks in Click internals (_param_memo) and Cloup’s decorator validators.

Note

A decided color (anything but None) is pinned in two places, because the two kinds of target are colorized by different routes. One built with a plain @click.command() picks up the patched decorator and therefore is a _HelpColorsMixin: the context class installed below carries the decision for it. One carrying an explicit cls= (like Flask’s FlaskGroup) keeps its own class and a stock click.Context, and is served by the get_help patch further down instead. Cover a single route and the flag silently works for half the CLIs in the wild, which is what --color=always did until it was pinned here too.

Parameters:

theme (HelpTheme | None) – Color theme to use. None keeps the current default.
color (bool | None) – Tri-state ANSI control mirroring ctx.color: True forces colors on, False strips them, and None (the GNU auto default) defers to the output stream’s TTY status.

Return type:

click_extra.cli_wrapper.unpatch_click()[source]¶

Restore Click’s original decorator functions and methods.

Reverses the changes made by patch_click(). Useful in tests to avoid leaking global state between test cases.

Return type:: None

click_extra.cli_wrapper.resolve_target(script)[source]¶

Resolve a script name to a module path and function name.

Resolution order:

console_scripts entry points from installed packages.
A local project directory: its console_scripts entry point is read from pyproject.toml / setup.cfg and its package is added to sys.path.
.py file path.
Explicit module:function notation.
Bare Python module or package name.

Return type:: tuple[str, str]
Returns:: (module_path, function_name) tuple. function_name is empty when the target should be invoked as a module or script file.
Raises:: click.ClickException – If the script cannot be resolved.

Note

Resolving a local project directory has a side effect: the directory holding its top-level package is prepended to sys.path so the subsequent import succeeds. The target’s own dependencies must still be importable in the current environment.

click_extra.cli_wrapper.invoke_target(script, module_path, function_name, args)[source]¶

Import and call the target CLI.

Reconstructs sys.argv so Click’s argument parsing sees the target’s program name and arguments, and pins __main__.__package__ so the program name Click detects is that same script name.

Note

A target whose Click command is invoked without an explicit prog_name falls back to click.utils._detect_program_name(), which reads __main__.__package__. That attribute states how click-extra itself was launched: a documentation build running python -m sphinx leaked python -m sphinx.flask into a wrapped usage line, and python -m click_extra leaks python -m click_extra.flask the same way. Emptying it for the call pins the detection on its file-execution branch, which answers the basename of sys.argv[0]: the script name set above.

Parameters:

script (str) – Original script name (used as sys.argv[0]).
module_path (str) – Dotted module path or .py file path.
function_name (str) – Function to call, or empty for module execution.
args (tuple[str, ...]) – Arguments to pass to the target CLI.

Return type:

See: https://click.palletsprojects.com/en/stable/api/#click.Group.command_class

click_extra.cli_wrapper.resolve_target_command(script, subcommands=())[source]¶

Import SCRIPT and return its Click command object and a matching context.

Resolves SCRIPT through resolve_target(), imports the module, then obtains the command object without running the CLI: the entry-point attribute when it is itself a command, otherwise by scanning the module’s namespace for Click command instances (preferring groups). Optional subcommands navigate into nested groups, mirroring the path a user would type.

Shared by the wrap command’s introspection modes (--params, --man, --carapace, --tree) so all describe the exact same resolved command.

Raises:: click.ClickException – when no unambiguous Click command can be found, or a requested subcommand does not exist.
Return type:: tuple[Command, Context]

click_extra.cli_wrapper.target_prog_name(script, command)[source]¶

Return the name a user would type to run SCRIPT.

Every rendering of a target is titled with this: a man page’s .TH line, a Carapace spec’s name, a Markdown heading, the root of a --tree. None of them wants the string that was typed to reach the command, which is a filesystem path or a dotted import path as often as it is a command name.

Three shapes, in the order they are distinguished:

A path (a separator, or a .py suffix): its basename, dropping that suffix. path/to/my_cli.py is run as my_cli, not as its own path.
A dotted or colon-separated import path: the command’s own name, which Click took from the function or an explicit name=. An import path names a module, never a binary.
Anything else is a console-script name, already exactly what a user types, and beats the command’s own name when the two differ (Flask’s entry point is flask, its group object is named cli).

Caution

Case 2 is a best effort. A target reached as python -m my_package.cli has no single name a user types, so the command’s own is the closest thing to one. Pass an explicit prog_name to the underlying renderer when that is not what you want in the output.

Return type:: str

click_extra.color module¶

Resolve whether terminal output should be colored.

Owns the --color[=WHEN] and --no-color options, the color environment variables (NO_COLOR, FORCE_COLOR, CLICOLOR, and friends), and the tri-state WHEN resolution. The actual styling lives elsewhere: click_extra.styling (the Style primitive), click_extra.theme (palettes), and click_extra.highlight (help-screen rendering).

click_extra.color.COLOR_ENVVARS: dict[str, bool] = {'CLICOLOR': True, 'CLICOLORS': True, 'CLICOLORS_FORCE': True, 'CLICOLOR_FORCE': True, 'COLOR': True, 'COLORS': True, 'FORCE_COLOR': True, 'FORCE_COLORS': True, 'LLM': False, 'NOCOLOR': False, 'NOCOLORS': False, 'NO_COLOR': False, 'NO_COLORS': False}¶

List of environment variables recognized as flags to switch color rendering on or off.

The key is the name of the variable and the boolean value the value to pass to --color option flag when encountered.

Source:

click_extra.color.COLOR_DISABLING_TERMS = frozenset({'dumb', 'unknown'})¶

TERM values marking a terminal too limited for ANSI niceties.

A dumb or unknown terminal advertises neither SGR color nor the cursor-control codes (carriage return, clear-line) an animation relies on, so both Click Extra’s color resolution (resolve_color_env()) and the spinner’s animation gating (Spinner._resolve_enabled) treat these two values as a hard opt-out. Sharing the set keeps the color and animation axes from drifting apart.

An unset TERM is deliberately excluded: it is common on legitimately color-capable streams (subprocesses, some IDEs) where defaulting to off would be a regression. This matches Rich, which keys its own dumb-terminal detection on the same two values and not on absence.

click_extra.color.is_a_tty(stream)[source]¶

Whether stream reports itself as an interactive terminal.

Probes isatty defensively through getattr(): not every stream object exposes the method (a bare buffer, an in-memory capture, a test double), and a plain stream.isatty() would raise there instead of answering “not a terminal”.

Return type:: bool

click_extra.color.resolve_color_env()[source]¶

Reconcile the recognized color environment variables into a tri-state.

Inspects every variable listed in COLOR_ENVVARS and returns:

True if at least one enabling variable (FORCE_COLOR, CLICOLOR, …) is set. Enabling wins over disabling, so a single one is enough to keep colors.
False if only disabling variables (NO_COLOR, LLM, …) are set.
None when no recognized variable is present, leaving the caller free to apply its own default (typically auto).

A bare variable (no value), or one whose value cannot be parsed as a boolean, counts as activation, in the permissive spirit of the NO_COLOR and FORCE_COLOR conventions.

A dumb or unknown TERM (see COLOR_DISABLING_TERMS) casts a disabling vote as well, so a terminal that cannot render ANSI is treated as color-off even when it still reports as a TTY. Because enabling wins, an explicit FORCE_COLOR stays authoritative over it.

Return type:: bool | None

click_extra.color.forced_color()[source]¶

Force ANSI color while Click Extra captures CLI text for documentation.

Click Extra renders CLI help and output into docs from both the MkDocs plugin (click_extra.mkdocs) and the Sphinx directives (click_extra.sphinx.click). During a build that output is a pipe, not a TTY, so the underlying renderers strip their escape codes. Two independent color systems have to be defeated:

Click’s, gated by should_strip_ansi / ctx.color (what click.echo and the Click and Click Extra help formatters consult). Sphinx’s runner additionally flips this one with click.testing.CliRunner(color=True).
Rich’s, gated by rich.console.Console.is_terminal, which ignores the above and reads FORCE_COLOR (https://force-color.org). This is the system rich-click uses, and color=True never reaches it.

FORCE_COLOR is the only signal common to both systems (Rich reads it directly; Click Extra recognizes it through COLOR_ENVVARS), so it is the lever we set here. We also clear the color-disabling variables Click Extra recognizes (NO_COLOR, LLM, …) so an opt-out in the build environment cannot suppress the rendering, and pin COLORTERM=truecolor so the branded 24-bit themes render at full depth instead of being quantized to the 256-color palette (see supports_truecolor()). The previous environment is restored on exit, so the override never leaks beyond a single capture.

Return type:: Iterator[None]

click_extra.color.query_osc_background(timeout=0.2)[source]¶

Ask the terminal for its background color with an xterm OSC 11 query.

Writes ESC ] 11 ; ? BEL to the terminal and reads back its rgb:RRRR/GGGG/BBBB reply, returning the color as an 8-bit (r, g, b) tuple. Returns None whenever the query cannot run or the terminal stays silent:

on non-POSIX platforms, or when termios / tty are missing;
when stdin or stdout is not a terminal (piped, redirected, captured);
when no reply arrives within timeout seconds.

Caution

The query reads stdin in cbreak mode. If the user has typed ahead, or another reader competes for stdin, those bytes may be consumed here or interleave with the reply (a leading run is harmless: the reply is located with a search()). The terminal mode is always restored through termios.tcsetattr(). Because of this contention, the query is opt-in: it runs only when a caller explicitly allows it (see resolve_background() and ThemeOption’s query_background).

Return type:: tuple[int, int, int] | None

click_extra.color.resolve_background(allow_query=False)[source]¶

Detect whether the terminal has a dark or light background.

Consults each signal in turn and returns the first that resolves, or None when none does (callers then keep their own default). Precedence, highest first:

CLITHEME — the cli-theme convention. A dark or light value (optionally suffixed with a :variant) is a deliberate override and wins outright; auto and anything unrecognized fall through.
The live OSC 11 query (query_osc_background()), but only when allow_query is true. It is the most accurate and the only real-time signal, yet it reads stdin, so it stays opt-in.
COLORFGBG — set by a handful of terminals (rxvt, Konsole) and cached by shell-term-background at shell startup. Read last because it is frequently stale: it reflects the value at terminal launch and is not refreshed when the user switches themes.

Parameters:: allow_query (bool) – permit the stdin-reading OSC 11 query. Off by default.

See also

“Is this terminal dark or light?” has a small ecosystem of prior art, mixing the same two strategies this function does (a cached environment variable versus a live OSC query):

shell-term-background (POSIX shell) runs the OSC query once at shell startup and caches the answer into COLORFGBG, with term-background as its Python reader.
terminal-light, termbg and terminal-colorsaurus (Rust) query OSC 10/11 live, like query_osc_background(); the latter two also read the Windows console.

Return type:: Literal['dark', 'light'] | None

click_extra.color.COLOR_WHEN = ('auto', 'always', 'never')¶

GNU-canonical tri-state values accepted by --color=<WHEN>.

auto defers to terminal detection, always forces ANSI on, never strips it. See GNU coreutils and this discussion.

click_extra.color.COLOR_WHEN_ALIASES: dict[str, str] = {'force': 'always', 'if-tty': 'auto', 'no': 'never', 'none': 'never', 'tty': 'auto', 'yes': 'always'}¶

GNU coreutils synonyms accepted as hidden aliases for each COLOR_WHEN value.

GNU ls accepts yes/force for always, no/none for never and tty/if-tty for auto, alongside the three canonical spellings (see COLOR_WHEN). Click Extra mirrors that leniency but keeps the synonyms out of --help output, error messages and shell completion, which only ever advertise COLOR_WHEN.

click_extra.color.publish_invocation_color(ctx)[source]¶

Mirror ctx.color into _invocation_color for cross-thread readers.

Called by every color callback after it settled its part of the resolution: whichever fires last leaves the final tri-state in the mirror. The first call queues a context-close callback resetting the mirror, so the value never leaks into a later invocation in the same process.

Return type:: None

click_extra.color.invocation_color()[source]¶

The invocation’s resolved color tri-state, reachable from any thread.

Prefers the pinned ctx.color of the calling thread’s own Click context, then the process-wide mirror published by the color callbacks (publish_invocation_color()). None means auto: defer to the output stream’s TTY status, exactly like ctx.color’s own default.

This is what makes --no-color reach output produced outside the main thread, like the subprocess lines click_extra.execution.run_cli() streams through click_extra.logging.StreamHandler.

Return type:: bool | None

class click_extra.color.ColorWhenChoice(choices, case_sensitive=True)[source]¶

Bases: Choice

click.Choice over COLOR_WHEN that also accepts the hidden GNU synonyms (COLOR_WHEN_ALIASES) and native configuration booleans, folding them to a canonical value before validation.

Only the three canonical COLOR_WHEN values reach --help, error messages and shell completion, because the public choices stay canonical. Synonyms and booleans are accepted silently and normalized, so downstream code (ColorOption.set_color(), _WHEN_TO_TRISTATE) only ever sees auto, always or never.

Matching is case-insensitive and whitespace-tolerant, which also makes the canonical values forgiving, such as --color=ALWAYS.

convert(value, param, ctx)[source]¶

Fold synonyms and booleans to canonical, then defer to click.Choice.

A native bool only reaches this method from a structured configuration file: TOML or JSON booleans, or YAML’s coercion of yes/no/on/off/true/false. True maps to always and False to never, consistent with a bare --color and --no-color. The command line always delivers strings, so this never turns --color=true into a valid CLI spelling.

Caution

A configuration boolean therefore diverges from git’s color.ui, where true means auto. Click Extra keeps true equal to always so the yes string synonym and YAML’s coercion of yes to True resolve identically across file formats.

Return type:: Any

class click_extra.color.ColorOption(param_decls=None, is_flag=False, flag_value='always', default='auto', is_eager=True, expose_value=False, help='Colorize the output. A bare --color is the same as --color=always.', **kwargs)[source]¶

Bases: ExtraOption

A pre-configured --color[=WHEN] tri-state option.

This option is eager by default, so other eager options (like --version) are rendered with the resolved color state.

Note

add_to_parser(parser, ctx)[source]¶

Return type:: None

set_color(ctx, param, value)[source]¶

Resolve --color=<WHEN> against the environment and pin ctx.color.

Precedence, highest first:

An explicit --color on the command line.
The color environment variables, but only when the value comes from the built-in default. A configuration file or --accessible (both seen here as a non-DEFAULT source) therefore wins over the environment, matching AccessibleOption.
A color state already pinned by --no-color, a forced test runner, or an explicit Context(color=...): preserved when this option only resolves to auto from its default.
The auto default, leaving ctx.color at None for TTY detection.

Whatever branch settles it, the resolution is mirrored process-wide by publish_invocation_color() so output produced from background threads honors it too.

Return type:: None

class click_extra.color.NoColorOption(param_decls=None, is_flag=True, default=False, is_eager=True, expose_value=False, help='Disable colorization (alias of --color=never).', **kwargs)[source]¶

Bases: ExtraOption

--no-color flag that forces --color=never.

set_no_color(ctx, param, value)[source]¶

Force ctx.color off when a negative alias is passed; no-op otherwise.

Dormant under resilient parsing, for the same reason as ColorOption.set_color(): a never-closed introspection context must not publish the process-wide color mirror.

Return type:: None

click_extra.command_doc module¶

Extract a Click command into a structured document and render it.

extract_command_doc() walks a command (and, through iter_command_contexts(), its whole tree) into a CommandDoc: one extraction carrying the man-pages(7) sections documented in Man-page (NAME, SYNOPSIS, DESCRIPTION, OPTIONS, COMMANDS, ENVIRONMENT, FILES and EXIT STATUS). The model then renders to any of the HELP_FORMATS backends: roff (CommandDoc.to_roff()), Markdown (CommandDoc.to_markdown()) and JSON (CommandDoc.to_dict() / CommandDoc.to_json()), with the Carapace completion spec delegated to click_extra.carapace.

The roff backend is Click Extra’s answer to the unmaintained click-man package. It improves on it by:

working on a command object via click.Command.make_context(), so it needs no console_scripts entry point;
discovering subcommands dynamically through click.Group.list_commands() / click.Group.get_command() with a live context;
honoring Click’s \b no-rewrap marker (rendered as roff .nf / .fi);
rendering boolean flags (--foo / --no-foo) and skipping hidden commands and options;
mirroring Cloup option groups as .SS subsections of OPTIONS (ungrouped options fall under an Other options heading), matching the help screen;
emitting ENVIRONMENT (from auto-generated env vars), FILES (from the --config search pattern) and EXIT STATUS sections that click-man never grew.

Font selection follows the man typographic convention encoded by click_extra.theme.LITERAL_STYLES / REPLACEABLE_STYLES: literal tokens (command and option names) render bold (\fB), replaceable tokens (metavars, operands) render italic (\fI).

click_extra.command_doc.INLINE_LITERAL_RE = re.compile('``([^`]+?)``')¶

Match a reST inline literal ("…``”``) in a docstring.

Click stores docstrings verbatim, so any reST markup the author used to render code-like tokens in HTML docs leaks into Command.help / Command.short_help. The roff and HTML man-page paths translate these matches into the bold/literal markers their renderers understand; the Sphinx index directive translates them into nodes.literal.

click_extra.command_doc.iter_inline_literals(text)[source]¶

Walk text and yield (segment, is_literal) pairs.

Split on INLINE_LITERAL_RE so the consumer can apply different rendering to the literal segments (bold for roff, a literal node for docutils) without re-parsing the regex.

Return type:: Iterator[tuple[str, bool]]

click_extra.command_doc.CLICK_EXTRA_URL = 'https://github.com/kdeldycke/click-extra'¶: Click Extra’s home page, stamped into the provenance comment of every generated man page so a reader of the raw roff knows where it came from.

click_extra.command_doc.MAN_SECTION = '1'¶: Default man page section. Section 1 is for executable programs and shell commands, which is what a Click CLI is.

click_extra.command_doc.DEFAULT_EXIT_STATUS: tuple[tuple[str, str], ...] = (('0', 'Success.'), ('1', 'A runtime error, or an aborted prompt (Ctrl-C, a declined confirmation).'), ('2', 'A usage error: unknown option, invalid value, missing operand, or an unparsable configuration file.'))¶

Conventional exit codes shared by every Click Extra CLI.

Mirrors the EXIT STATUS table in Man-page. Click returns 2 for usage errors (UsageError), 1 for aborts, and 0 on success.

click_extra.command_doc.normalize_examples(examples)[source]¶

Validate and freeze a command’s examples into (description, command) pairs.

Accepts any sequence of two-item sequences, so a list of tuples and a list of lists (what a configuration file or a JSON payload would produce) are both fine. None and an empty sequence both yield an empty tuple.

Raises:: TypeError – when an entry is not a pair of strings, naming the offending entry. Raised at command construction, so a malformed example surfaces on import rather than on the first --help a user runs.
Return type:: tuple[tuple[str, str], ...]

class click_extra.command_doc.DocOptionItem(names, metavar, help, required, optional_value=False)[source]¶

Bases: object

A single OPTIONS entry, extracted from a Click option.

names: tuple[str, ...]¶: All literal spellings: primary opts followed by secondary_opts (so --foo / --no-foo boolean flags render both).

metavar: str | None¶: The rendered metavar, or None when the option takes no value (boolean flags and counters).

help: str | None¶: The option’s help text, possibly carrying a \b no-rewrap marker.

required: bool¶: Whether the option is mandatory.

optional_value: bool = False¶: Whether the option’s value is optional (a bare flag is allowed). Rendered as the attached [=METAVAR] form instead of a space-separated metavar.

to_roff()[source]¶

Render this option as a roff tagged paragraph (.TP).

Return type:: list[str]

property spec: str¶: The option’s spelling and value placeholder, as one plain string.

to_markdown()[source]¶

Render this option as a Markdown list item.

A \b no-rewrap region in the help becomes a fenced block indented under the item, rather than being folded into the sentence: the author aligned it on purpose, and a list item can carry a block as well as a paragraph can.

Return type:: list[str]

to_dict()[source]¶

Render this option as a JSON-serializable mapping.

Return type:: dict[str, Any]

class click_extra.command_doc.DocOptionGroup(options, title=None, help=None)[source]¶

Bases: object

A titled cluster of OPTIONS entries, mirroring a Cloup option group.

A plain Click command, or a Cloup command with no explicit @option_group, yields a single group with title=None: it renders as a flat OPTIONS list with no .SS subsection heading, identical to a man page that never grouped its options.

options: tuple[DocOptionItem, ...]¶: The option entries in this group.

title: str | None = None¶: The subsection heading, rendered as a roff .SS. None for the implicit single group of an ungrouped command (no heading emitted).

help: str | None = None¶: Optional group description, rendered as prose under the heading.

to_roff()[source]¶

Render an optional .SS heading, group help, then the options.

Return type:: list[str]

to_markdown(level=3)[source]¶

Render an optional heading, group help, then the options.

Return type:: list[str]

to_dict()[source]¶

Render this group as a JSON-serializable mapping.

Return type:: dict[str, Any]

class click_extra.command_doc.CommandDoc(name, short_help='', section='1', synopsis_pieces=(), description='', operands=(), option_groups=(), subcommands=(), environment=(), files=(), exit_status=(('0', 'Success.'), ('1', 'A runtime error, or an aborted prompt (Ctrl-C, a declined confirmation).'), ('2', 'A usage error: unknown option, invalid value, missing operand, or an unparsable configuration file.')), examples=(), version=None, date='', manual=None, authors=None, copyright=None)[source]¶

Bases: object

A whole man page in structured form, ready to render to roff.

name: str¶: Full command path, space-joined (like weather forecast).

short_help: str = ''¶: One-line description for the NAME section.

section: str = '1'¶: Man section number.

synopsis_pieces: tuple[str, ...] = ()¶: Usage metavars after the command name ([OPTIONS], CITY, …).

description: str = ''¶: The command’s full help text / docstring for the DESCRIPTION section.

operands: tuple[tuple[str, str], ...] = ()¶: Positional arguments as (metavar, help) pairs.

option_groups: tuple[DocOptionGroup, ...] = ()¶: The OPTIONS entries, partitioned into one or more groups. A command without explicit option groups carries a single untitled group.

subcommands: tuple[tuple[str, str], ...] = ()¶: For groups: (name, short_help) pairs for the COMMANDS section.

environment: tuple[tuple[str, str], ...] = ()¶: ENVIRONMENT entries as (variable_name, help) pairs.

files: tuple[str, ...] = ()¶: FILES entries (configuration search patterns).

exit_status: tuple[tuple[str, str], ...] = (('0', 'Success.'), ('1', 'A runtime error, or an aborted prompt (Ctrl-C, a declined confirmation).'), ('2', 'A usage error: unknown option, invalid value, missing operand, or an unparsable configuration file.'))¶: EXIT STATUS entries as (code, meaning) pairs.

examples: tuple[tuple[str, str], ...] = ()¶

EXAMPLES entries as (description, command_line) pairs.

Collected from the command’s own examples attribute (see click_extra.commands.Command.examples). Empty for a command that declares none, in which case every backend omits the section entirely.

version: str | None = None¶: Version string for the .TH header.

date: str = ''¶: Date for the .TH header (YYYY-MM-DD).

manual: str | None = None¶: Manual name for the .TH header (the centered footer title).

authors: str | None = None¶: AUTHORS section content, or None to omit the section.

copyright: str | None = None¶: COPYRIGHT section content, or None to omit the section.

property title: str¶: The .TH page title: the command path, hyphen-joined and upper-cased.

to_roff()[source]¶

Render the full man page as a roff/troff string.

Return type:: str

to_markdown()[source]¶

Render the whole document as Markdown.

Return type:: str

to_dict()[source]¶

Render the whole document as a JSON-serializable mapping.

Return type:: dict[str, Any]

to_json(indent=2)[source]¶

Serialize to_dict() to a JSON string.

Return type:: str

click_extra.command_doc.extract_command_doc(command, ctx, *, version=None, date=None, manual=None, authors=None, copyright=None)[source]¶

Build a CommandDoc from a Click command and its context.

The context must have been created for command (for example via click.Command.make_context() with resilient_parsing=True), so that auto-generated environment-variable prefixes resolve correctly.

Return type:: CommandDoc

click_extra.command_doc.iter_command_contexts(command, prog_name=None, _parent=None, _path=())[source]¶

Walk a command tree, yielding (path, command, context) for each visible command.

Subcommands are discovered dynamically (click.Group.list_commands() / get_command()), so dynamically-registered commands are included. Hidden commands are skipped. Each context is built with resilient_parsing=True to avoid triggering required-argument errors, prompts, or eager-option side effects.

Return type:: Iterator[tuple[tuple[str, ...], Command, Context]]

click_extra.command_doc.render_manpage(command, prog_name=None, ctx=None, **overrides)[source]¶

Render a single command’s man page as a roff string.

Return type:: str

click_extra.command_doc.render_manpages(command, prog_name=None, **overrides)[source]¶

Render the whole command tree, one man page per (sub)command.

Returns an ordered mapping of {filename: roff} where each filename is the command path joined by hyphens plus the section suffix (like weather-forecast.1).

Return type:: dict[str, str]

click_extra.command_doc.write_manpages(command, target_dir, prog_name=None, **overrides)[source]¶

Render the command tree and write each man page into target_dir.

Creates target_dir if missing. Returns the list of written paths.

Return type:: list[Path]

click_extra.command_doc.install_manpages(command, prog_name=None, **overrides)[source]¶

Write the command tree’s man pages where man can find them.

Targets $XDG_DATA_HOME/man/man1 when that variable is set, else MAN_INSTALL_DIR. Returns the written paths.

Return type:: list[Path]

click_extra.command_doc.HELP_FORMATS: dict[str, str] = {'carapace': 'Carapace completion spec (YAML). Doubles as a command-and-flag tree, and is the shape `carapace` itself consumes. Needs the `yaml` extra.', 'json': 'This command as a JSON object: usage, description, arguments, options grouped as the help screen groups them, environment variables, files, exit codes, and its direct subcommands by name.', 'json-full': 'Every command of the tree as JSON, under a `commands` array, each entry in the `json` shape.', 'man': 'This command as a man page: the roff source a packager installs, which `--man` typesets for reading.', 'markdown': 'This command as a Markdown document, one section per topic.', 'markdown-full': 'Every command of the tree as one Markdown document, in tree order.'}¶

The formats render_help() renders, mapped to their one-line description.

Ordered alphabetically, which is also the order --help-format advertises them in. Adding a format is an entry here plus a branch in render_help(): no new flag, no wider help screen. See Man-page for what each one is good for.

Note

The distinction the plain and -full variants draw is progressive disclosure. A plain render describes one command and names its children, so a reader (a tool or an agent, typically) descends one level at a time instead of pulling a whole tree into a context window to answer a question about one leaf. The -full variants exist for the opposite job: generating documentation, or diffing a CLI’s whole surface between two releases.

click_extra.command_doc.INSTALLABLE_FORMATS: frozenset[str] = frozenset({'carapace', 'man'})¶

The formats with a canonical place on disk their consumer reads them from.

A man page under a man directory, a Carapace spec under Carapace’s. These are the two renderings that are installed rather than read, which is what lets click-extra wrap offer them a destination (--output-dir, --install) and refuse one to the others. A JSON or Markdown document has no such place: nothing goes looking for it, so stdout and a shell redirection are the whole story.

click_extra.command_doc.render_help(command, help_format, prog_name=None, ctx=None, **overrides)[source]¶

Render command in one of the HELP_FORMATS.

Raises:: ValueError – on an unknown format, listing the known ones.
Return type:: str

click_extra.command_doc.MAN_FORMATTERS: tuple[tuple[str, ...], ...] = (('groff', '-man', '-Tutf8', '-rLL={width}n', '-P-c'), ('mandoc', '-Tutf8', '-Owidth={width}'))¶

Commands able to typeset roff into readable terminal text, best first.

Each entry is an argv template read on stdin, with :width: filled from the terminal. groff is the GNU implementation found nearly everywhere a man page is; mandoc covers the BSDs and Alpine, which ship it instead.

Note

-P-c hands -c down to grotty, groff’s terminal driver, pinning the emphasis it produces to the character-backspace pairs OVERSTRIKE_RE matches and read_manpage() strips under --accessible. Left to its own default a grotty recent enough writes SGR escape sequences instead, which that regular expression cannot see: the manual then reaches a screen reader with its emphasis intact, and loses it altogether once the output is not a terminal and the codes are stripped as color. mandoc needs no counterpart: it overstrikes already.

Note

The man binary is deliberately not in this list, even though it is the tool being imitated. Reading roff from stdin is where the implementations diverge: GNU man takes -l -, while the BSD one wants a real file path. Driving the typesetter directly sidesteps a portability problem that buys nothing, since paging is handled here anyway.

click_extra.command_doc.MAN_INSTALL_DIR: Path = PosixPath('/home/runner/.local/share/man/man1')¶

Where --install writes man pages: the user’s own section-1 directory.

The default of the XDG base directory spec, which install_manpages() overrides from XDG_DATA_HOME when that is set. Some systems do not carry this path in their MANPATH, in which case the pages land correctly but man has to be told where to look.

click_extra.command_doc.format_manpage(roff, width=None)[source]¶

Typeset roff into readable terminal text, or None if nothing can.

Parameters:

roff (str) – the man page source, as CommandDoc.to_roff() renders it.
width (int | None) – line length in columns. Defaults to the terminal’s own, so the result matches what man would have produced in the same window.

Return type:

str | None

click_extra.command_doc.OVERSTRIKE_RE = re.compile('.\\x08')¶

Match the character-backspace pairs a roff typesetter emits for emphasis.

A bold N is written N\x08N and an underlined one _\x08N, a convention inherited from line printers that a pager still renders as bold and underline today. Dropping the pair’s first half leaves the plain character.

click_extra.command_doc.read_manpage(command, ctx=None)[source]¶

Typeset a command’s manual and send it to the pager.

Return type:: None

class click_extra.command_doc.ManOption(param_decls=None, is_flag=True, expose_value=False, is_eager=True, help="Read the command's manual page and exit.", **kwargs)[source]¶

Bases: ExtraOption

A pre-configured --man flag that typesets the command’s manual, pages it, and exits.

Note

The flag is named --man, not --show-man or --man-page.

Note

print_man(ctx, param, value)[source]¶

Typeset the invoked command’s manual, page it, then exit.

Return type:: None

class click_extra.command_doc.HelpFormatOption(param_decls=None, expose_value=False, is_eager=True, help='Render the command in the given format and exit.', **kwargs)[source]¶

Bases: ExtraOption

A pre-configured --help-format option printing the command in one of the HELP_FORMATS and exiting.

Note

print_help_format(ctx, param, value)[source]¶

Render the invoked command in the requested format, then exit.

Return type:: None

click_extra.commands module¶

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 use the mixins in here to build up your own custom variants.

click_extra.commands.DEFAULT_PRIORITY: Final[float] = 100.0¶

Implicit priority of any subcommand or option left unnumbered.

Priorities order the subcommands of a Group and the options of a Command, lowest first. Anything the author did not number sits on this line, so a lone {"prep": 1} promotes prep without displacing the rest, and a number above 100 demotes.

Note

Priorities are floats, not integers, so a new entry can be wedged between two existing ones without renumbering: 1.5 lands between 1 and 2.

That trick is as old as interactive computing. JOSS, which RAND put online in 1963, required every line number to be a pair of integers separated by a period (1.1, 10.12): a page and a line within it, jointly a step. DEC’s FOCAL carried the scheme to the PDP-8, with steps running from 1.01 to 31.99. BASIC numbered lines with plain integers, and its 10, 20, 30 convention is programmers buying back the same insertion room by hand.

click_extra.commands.EXTRA_OPTION_SETTINGS: tuple[str, ...] = ('show_choices', 'show_envvar')¶: Click Extra context settings forced onto every option when set to non-None.

click_extra.commands.default_params(screen=None)[source]¶

Default additional options added to @command and @group.

Parameters:

screen (VersionScreen | None) –

a VersionScreen for --version to draw in place of its one-line message. Reach it through the params hook, binding the screen with functools.partial so each decorated command still gets its own fresh option instances:

@group(params=partial(default_params, screen=MY_SCREEN))
def cli():
    pass

Return type:

list[Option]

Caution

The order of options has been carefully crafted to handle subtle edge-cases and avoid leaky states in unit tests.

You can still override this hard-coded order for aesthetic 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 naturally reset after each invocation (which is not the case in unit tests).

--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
--export-config FORMAT
--accessible

Hint

--accessible is placed before --color and --table-format so it can lower their defaults (via default_map) before they are resolved.
--color / --no-color
--progress / --no-progress
--theme
--params
--table-format FORMAT
--verbosity LEVEL
-v, --verbose
-q, --quiet
--tree
--man
--help-format FORMAT
--version
-h, --help

Attention

This is the option produced by the @click.decorators.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, 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 setting.

Note

The list below is the processing order, and it is the only one these edge-cases care about. The help screen reads a separate presentation order, which the option_priorities argument of @command and @group reshuffles without touching a single callback. See param_priority(), added for click_extra#544 issue.

class click_extra.commands.Command(*args, version_fields=None, config_schema=None, config_strict=False, schema_strict=False, fallback_sections=(), config_validators=(), included_params=None, excluded_params=None, extra_option_at_end=True, option_priorities=None, populate_auto_envvars=True, extra_keywords=None, excluded_keywords=None, examples=(), **kwargs)[source]¶

Bases: _HelpColorsMixin, Command

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

List of extra parameters:

Parameters:

version_fields (dict[str, Any] | None) – dictionary of VersionOption template field overrides forwarded to the version option. Accepts any field from VersionOption.template_fields (like prog_name, version, git_branch). Lets you customize --version output from the command decorator without replacing the default params list.
config_strict (bool) – forwarded to the default ConfigOption’s strict setting: configuration keys not matching any CLI parameter raise an error instead of being silently ignored. Like the other config_* and *_params forwards, it spares you from replacing the whole default params list to customize the config option.
excluded_params (Sequence[str] | None) – additional parameter IDs to block from configuration files, merged into the default ConfigOption’s excluded_params blocklist. Additive, unlike the option-level excluded_params which replaces the default blocklist entirely. Items are fully-qualified parameter IDs (like mycli.mail_sources). Mutually exclusive with included_params.
extra_keywords (HelpKeywords | None) – a HelpKeywords instance whose entries are merged into the auto-collected keyword set. Use this to inject additional strings for help screen highlighting.
excluded_keywords (HelpKeywords | None) – a HelpKeywords instance whose entries are removed from the auto-collected keyword set. Use this to suppress highlighting of specific strings.
examples (Sequence[Sequence[str]]) – a sequence of (description, command) string pairs showing the command in use. They are rendered in an Examples: section of the help screen, in the man page, and in every –help-format rendering. A malformed pair raises TypeError here, at command construction, rather than on the first --help a user runs.
extra_option_at_end (bool) – reorders all parameters attached to the command, by moving all instances of ExtraOption at the end of the parameter list. The original order of the options is preserved among themselves.
option_priorities (Mapping[str, float] | None) – maps an option to its priority in the help screen, relative to DEFAULT_PRIORITY, lowest shown first. Keys are matched against each parameter’s long and short flags first, then its destination name, so the --config / --no-config pair (which shares the config destination) stays addressable one flag at a time. Presentation only: self.params, and with it the order callbacks are evaluated in, is left alone. Positional arguments are never reordered, their sequence being part of the command’s grammar.
populate_auto_envvars (bool) – forces all parameters to have their auto-generated environment variables registered. This address the shortcoming of click which only evaluates them dynamically. By forcing their registration, the auto-generated environment variables gets displayed in the help screen, fixing click#2483 issue. On Windows, environment variable names are case-insensitive, so we normalize them to uppercase.

By default, these Click context settings are applied:

auto_envvar_prefix = self.name (Click feature)

Auto-generate environment variables for all options, using the command ID as prefix. The prefix is normalized to be uppercased and all non-alphanumerics replaced by underscores.
help_option_names = ("--help", "-h") (Click feature)

Allow help screen to be invoked with either –help or -h options.
show_default = True (Click feature)

Show all default values in help screen.

Additionally, these Cloup context settings are set:

align_option_groups = False (Cloup feature)

Aligns option groups in help screen.
show_constraints = True (Cloup feature)

Show all constraints in help screen.
show_subcommand_aliases = True (Cloup feature)

Show all subcommand aliases in help screen.

Click Extra also adds its own context_settings:

show_choices = None (Click Extra feature)

If set to True or False, will force that value on all options, so we can globally show or hide choices when prompting a user for input. Only makes sense for options whose prompt property is set.

Defaults to None, which will leave all options untouched, and let them decide of their own show_choices setting.
show_envvar = None (Click Extra feature)

If set to True or False, will force that value on all options, so we can globally enable or disable the display of environment variables in help screen.

Defaults to None, which will leave all options untouched, and let them decide of their own show_envvar setting. The rationale being that discoverability of environment variables is enabled by the --params option, which is active by default on extra commands. So there is no need to surcharge the help screen.

This addresses the click#2313 issue.

To override these defaults, you can pass your own settings with the context_settings parameter:

@command(
    context_settings={
        "show_default": False,
        ...
    }
)

context_class¶: alias of Context

examples: tuple[tuple[str, str], ...] = ()¶

(description, command) pairs showing the command in use.

option_priorities: dict[str, float]¶

context_settings: dict[str, Any]¶: an optional dictionary with defaults passed to the context.

param_priority(param)[source]¶

Priority of param in the help screen.

Defaults to DEFAULT_PRIORITY, and is otherwise resolved against option_priorities by trying each of the parameter’s flags in turn, then its destination name.

Important

Positional arguments always resolve to the default: their sequence is part of the command’s grammar, not a matter of presentation.

Return type:: float

main(args=None, prog_name=None, **kwargs)[source]¶

Pre-invocation step that is instantiating the context, then call invoke() within it.

Caution

During context instantiation, each option’s callbacks are called. These might break the execution flow (like --help or --version).

Return type:: Any

make_context(info_name, args, parent=None, **extra)[source]¶

Intercept the call to the original click.core.Command.make_context so we can keep a copy of the raw, pre-parsed arguments provided to the CLI.

See also

See click_extra.context.RAW_ARGS for the full rationale and the upstream-proposal notes (related: click#1279).

Return type:: Any

format_examples(ctx, formatter)[source]¶

Write an Examples: section listing the command’s examples.

Return type:: None

format_epilog(ctx, formatter)[source]¶

Insert the examples section ahead of the epilog.

Places it after the options and subcommands, which is where a reader arrives once they know what the command accepts, and keeps the author’s own epilog as the last word on the screen.

Return type:: None

parse_args(ctx, args)[source]¶

Like parent’s parse_args but with better error messages for single-dash multi-character tokens.

Return type:: list[str]

class click_extra.commands.ColorizedCommand(name, context_settings=None, callback=None, params=None, help=None, epilog=None, short_help=None, options_metavar='[OPTIONS]', add_help_option=True, no_args_is_help=False, hidden=False, deprecated=False)[source]¶

Bases: _HelpColorsMixin, Command

Click Command with help colorization but no extra params.

Mixes in _HelpColorsMixin for keyword highlighting and uses Context for the colorized formatter, without inheriting from Command (which would inject default_params).

Use this as a base for lightweight subcommands (like help) or for monkey-patching third-party CLIs (via patch_click()).

context_class¶: alias of Context

class click_extra.commands.ColorizedGroup(name=None, commands=None, invoke_without_command=False, no_args_is_help=None, subcommand_metavar=None, chain=False, result_callback=None, **kwargs)[source]¶

Bases: _HelpColorsMixin, Group

Click Group with help colorization but no extra params.

Same as ColorizedCommand but for groups.

context_class¶: alias of Context

class click_extra.commands.HelpCommand(name, context_settings=None, callback=None, params=None, help=None, epilog=None, short_help=None, options_metavar='[OPTIONS]', add_help_option=True, no_args_is_help=False, hidden=False, deprecated=False)[source]¶

Bases: ColorizedCommand

Synthetic subcommand that displays help for the parent group or a subcommand.

Auto-injected into every Group. Supports nested resolution: mycli help subgroup subcmd shows the help for subcmd within subgroup.

invoke(ctx)[source]¶

Resolve the command path and display its help.

Return type:: None

class click_extra.commands.Group(*args, help_command=True, sort_subcommands=None, subcommand_priorities=None, **kwargs)[source]¶

Bases: Command, Group

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

Like Command.__init__, but auto-injects a help subcommand.

Parameters:

help_command (bool) – when True (the default), a help subcommand is automatically registered. Set to False to suppress it, or register your own help subcommand to override it.
sort_subcommands (bool | None) – how subcommands sharing a priority are broken apart. True lists them alphabetically, False in the order they were registered. None (the default) defers to the sort_subcommands context setting, then to True. See must_sort_subcommands().
subcommand_priorities (Mapping[str, float] | None) – maps a subcommand name to its priority relative to DEFAULT_PRIORITY, lowest listed first. Names left out keep the default priority, so numbering a few subcommands moves only those.

command_class¶

Makes commands of a Group be instances of Command.

That way all subcommands created from a Group benefits from the same defaults and extra help screen colorization.

alias of Command

group_class¶

Let Group produce sub-groups that are also of Group type.

See: https://click.palletsprojects.com/en/stable/api/#click.Group.group_class

alias of type

subcommand_priorities: dict[str, float]¶

must_sort_subcommands(ctx)[source]¶

Resolve whether subcommand listings are alphabetical.

Return type:: bool

subcommand_priority(name)[source]¶

Priority of the name subcommand.

Defaults to DEFAULT_PRIORITY.

Return type:: float

list_commands(ctx)[source]¶

Subcommand names in presentation order.

Return type:: list[str]

list_sections(ctx, include_default_section=True)[source]¶

Like cloup.Group.list_sections, but ordering the default section.

Note

Return type:: list[Section]

add_command(cmd, name=None, **kwargs)[source]¶

Like cloup.Group.add_command, but replaces an auto-injected HelpCommand when the user registers their own help subcommand.

Return type:: None

invoke(ctx)[source]¶

Inject _default_subcommands and _prepend_subcommands from config.

_prepend_subcommands always prepends subcommands to the invocation, regardless of whether CLI subcommands were provided. Only works with chain=True groups.

Return type:: Any

class click_extra.commands.LazySubcommand(import_path, section=None, fallback_to_default_section=True)[source]¶

Bases: object

Declaration of a lazily-imported subcommand of a LazyGroup.

Carries the registration settings cloup.Group.add_command() accepts, which a bare import path cannot express. A subcommand needing none of them is declared as a plain string instead.

import_path: str¶: Where to import the command object from, as "<module-name>.<command-name>".

section: Section | None = None¶

Help-screen section the subcommand is filed under, once imported.

fallback_to_default_section: bool = True¶

Whether to file the subcommand under the default section when section is None.

class click_extra.commands.LazyGroup(*args, lazy_subcommands=None, **kwargs)[source]¶

Bases: Group

A Group that supports lazy loading of subcommands.

Hint

This implementation is based on the snippet from Click’s documentation: Defining the lazy group.

It has been extended to work with Click Extra’s config_option in click_extra#1332 issue.

lazy_subcommands maps command names to their import paths.

Tip

lazy_subcommands is a map of the form:

{"<command-name>": "<module-name>.<command-object-name>"}

For example:

{"mycmd": "my_cli.commands.mycmd"}

A subcommand needing registration settings on top of its import path is declared with a LazySubcommand instead of a bare string:

{"mycmd": LazySubcommand("my_cli.commands.mycmd", section=my_section)}

lazy_subcommands: dict[str, LazySubcommand]¶

get_command(ctx, cmd_name)[source]¶

Get a command by name, loading lazily if necessary.

Return type:: Command | None

click_extra.decorators module¶

Decorators for group, commands and options.

class click_extra.decorators.CommandDecorator(*args, **kwargs)[source]¶

Bases: Protocol[CommandT_co]

Static type of the command decorators built by decorator_factory.

Mirrors Click’s own overloads for @command/@group so type checkers infer the produced command class, while also covering the no-parenthesis form enabled by allow_missing_parenthesis.

class click_extra.decorators.ParameterDecorator(*args, **kwargs)[source]¶

Bases: Protocol

Static type of the option and argument decorators built by decorator_factory.

These decorators attach a parameter to the callback and return it unchanged, so the decorated function keeps its own type. The two overloads cover the bare (no-parenthesis) and parenthesized forms.

click_extra.decorators.allow_missing_parenthesis(dec_factory)[source]¶

Allow to use decorators with or without parenthesis.

As proposed in Cloup issue #127.

click_extra.decorators.decorator_factory(dec, *new_args, **new_defaults)[source]¶

Clone decorator with a set of new defaults.

Overloads:

dec (Any), new_args (Any), cls (type[CommandT_co]), new_defaults (Any) → CommandDecorator[CommandT_co]
dec (Any), new_args (Any), cls (type[ParamT] | None), new_defaults (Any) → ParameterDecorator

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

The two overloads give static type checkers a precise signature for the decorators this factory produces: command-style decorators (cls is a click.Command subclass) report the resulting command class, while parameter-style decorators (cls is a click.Parameter subclass, or absent) return the decorated callback unchanged. Both overloads model the optional-parenthesis behaviour added by allow_missing_parenthesis, which plain inference cannot recover. See CommandDecorator and ParameterDecorator for the produced shapes.

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 Command, 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.

click_extra.decorators.command(*args, **kwargs)¶

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.decorators.group(*args, **kwargs)¶

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.decorators.option(*args, group=None, **attrs)¶

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.decorators.argument(*args, help=None, **attrs)¶

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.decorators.help_option(*args, **kwargs)¶

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.decorators.version_option(version=None, *param_decls, cls=<class 'click_extra.version.VersionOption'>, group=None, **kwargs)[source]¶

Attach a VersionOption to a command.

@command
@version_option("1.2.3")  # Click idiom: pins the displayed version.
def my_cmd(): ...

Note

Hand-written instead of produced by decorator_factory() because Click’s leading version positional conflicts with the param_decls-first convention the factory relies on.

click_extra.decorators.lazy_group(*args, **kwargs)¶

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.decorators.multicall_group(*args, **kwargs)¶

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.decorators.accessible_option(param_decls: Sequence[str] | None = None, is_flag=True, default=False, is_eager=True, expose_value=False, help='Accessibility mode: disable colors and render tables in a borderless, screen-reader-friendly format.', **kwargs)¶

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.decorators.color_option(param_decls: Sequence[str] | None = None, is_flag=False, flag_value='always', default='auto', is_eager=True, expose_value=False, help='Colorize the output. A bare --color is the same as --color=always.', **kwargs)¶

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.decorators.columns_option(param_decls: Sequence[str] | None = None, columns: Sequence[ColumnSpec] | None = None, type=None, default: Sequence[str] | None = (), expose_value: bool = False, is_eager: bool = True, help: str = 'Restrict and reorder table columns, SQL SELECT-style. Comma-separated list of column IDs. Default: all columns in canonical order.', **kwargs)¶

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.decorators.config_option(param_decls: Sequence[str] | None = None, metavar='CONFIG_PATH', type=UNPROCESSED, help='Location of the configuration file. Supports local path with glob patterns or remote URL.', is_eager: bool = True, expose_value: bool = False, file_format_patterns: dict[ConfigFormat, Sequence[str] | str] | Iterable[ConfigFormat] | ConfigFormat | None = None, file_pattern_flags: int = 4104, roaming: bool = True, force_posix: bool = False, search_pattern_flags: int = 285504, search_parents: bool = False, stop_at: Path | str | Literal[Sentinel.VCS] | None = Sentinel.VCS, cascade: bool = False, excluded_params: Iterable[str] | None = None, included_params: Iterable[str] | None = None, strict: bool = False, config_schema: type | Callable[[dict[str, Any]], Any] | None = None, schema_strict: bool = False, fallback_sections: Sequence[str] = (), config_validators: Sequence[ConfigValidator] = (), **kwargs)¶

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.decorators.export_config_option(param_decls: Sequence[str] | None = None, type: click.ParamType | Any = None, metavar: str = 'FORMAT', is_eager: bool = True, expose_value: bool = False, help: str = 'Export the configuration in the selected format to <stdout>, then exit.', **kwargs: Any)¶

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.decorators.jobs_option(param_decls: Sequence[str] | None = None, default='auto', expose_value=False, show_default=True, type=<click_extra.execution.JobCount object>, help="Number of parallel jobs. Accepts an integer, 'auto' (the host's logical CPUs minus one) or 'max' (all logical CPUs). 0 runs sequentially.", **kwargs)¶

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.decorators.help_format_option(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)¶

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.decorators.man_option(param_decls: tuple[str, ...] | None = None, is_flag: bool = True, expose_value: bool = False, is_eager: bool = True, help: str = "Read the command's manual page and exit.", **kwargs)¶

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.decorators.no_color_option(param_decls: Sequence[str] | None = None, is_flag=True, default=False, is_eager=True, expose_value=False, help='Disable colorization (alias of --color=never).', **kwargs)¶

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.decorators.no_config_option(param_decls: Sequence[str] | None = None, type=UNPROCESSED, help='Ignore all configuration files and only use command line parameters and environment variables.', is_flag=True, flag_value=Sentinel.NO_CONFIG, is_eager=True, expose_value=False, **kwargs)¶

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.decorators.quiet_option(param_decls: Sequence[str] | None = None, **kwargs)¶

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.decorators.show_params_option(param_decls: Sequence[str] | None = None, is_flag=True, expose_value=False, is_eager=True, help='Show all CLI parameters, their provenance, defaults and value, then exit.', **kwargs)¶

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.decorators.table_format_option(param_decls: Sequence[str] | None = None, type=EnumChoice('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'), default=TableFormat.ROUNDED_OUTLINE, expose_value=False, is_eager=True, help='Rendering style of tables.', **kwargs)¶

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.decorators.telemetry_option(param_decls: Sequence[str] | None = None, default=False, expose_value=False, envvar=None, show_envvar=True, help='Collect telemetry and usage data.', **kwargs)¶

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.decorators.theme_option(param_decls: Sequence[str] | None = None, default: str = 'dark', is_eager: bool = True, expose_value: bool = False, query_background: bool = False, help: str = 'Color theme used for help screens.', **kwargs)¶

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.decorators.timer_option(param_decls: Sequence[str] | None = None, default=False, expose_value=False, is_eager=True, help='Measure and print elapsed execution time.', **kwargs)¶

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.decorators.tree_option(param_decls: tuple[str, ...] | None = None, is_flag: bool = True, expose_value: bool = False, is_eager: bool = True, help: str = 'Show the tree of nested subcommands and exit.', **kwargs)¶

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.decorators.validate_config_option(param_decls: Sequence[str] | None = None, type: click.ParamType | Any = <click.types.Path object>, is_eager: bool = True, expose_value: bool = False, help: str = 'Validate the configuration file and exit.', **kwargs: Any)¶

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.decorators.verbose_option(param_decls: Sequence[str] | None = None, **kwargs)¶

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.decorators.verbosity_option(param_decls: Sequence[str] | None = None, default_logger: Logger | str = 'root', default: LogLevel = LogLevel.WARNING, metavar='LEVEL', type=EnumChoice('CRITICAL', 'ERROR', 'WARNING', 'INFO', 'DEBUG'), help='Either CRITICAL, ERROR, WARNING, INFO, DEBUG.', **kwargs)¶

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.decorators.zero_exit_option(param_decls: Sequence[str] | None = None, default=False, expose_value=False, is_flag=True, help='Always exit with a status code of 0, even when problems are found.', **kwargs)¶

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.decorators.sort_by_option(*header_defs, cls=<class 'click_extra.table.SortByOption'>, group=None, **kwargs)[source]¶

Attach a SortByOption to a command.

Note

click_extra.envvar module¶

Type for dict-like environment variables.

click_extra.envvar.TEnvVarID = str | None¶: Type of environment variable names.

click_extra.envvar.TNestedEnvVarIDs¶

Type for arbitrary nested environment variable names.

alias of Iterable[str | None | Iterable[TNestedEnvVarIDs]]

click_extra.envvar.TEnvVars¶

Type for dict-like environment variables.

alias of Mapping[str, str | None]

click_extra.envvar.parse_envvar_flag(value)[source]¶

Read an environment flag’s value as a boolean, permissively.

The single interpretation shared by every flag-like variable Click Extra reads by hand (NO_COLOR and friends, ACCESSIBLE, DO_NOT_TRACK): the value is parsed through configparser.RawConfigParser.BOOLEAN_STATES, and anything unparsable counts as activation, in the permissive spirit of the NO_COLOR and FORCE_COLOR conventions where the variable’s bare presence is the signal.

Callers handle presence themselves: pass the value only when the variable is set, an unset variable being no vote at all.

Return type:: bool

click_extra.envvar.merge_envvar_ids(*envvar_ids)[source]¶

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, so we normalize them to uppercase as the standard library does.

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

Return type:: tuple[str, ...]

click_extra.envvar.clean_envvar_id(envvar_id)[source]¶

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 not consistent regarding case-handling of environment variable.

Return type:: str

click_extra.envvar.param_auto_envvar_id(param, ctx)[source]¶

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

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

Return type:: str | None

click_extra.envvar.param_envvar_ids(param, ctx)[source]¶

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().

Names are normalized to uppercase on Windows by merge_envvar_ids().

Return type:: tuple[str, ...]

click_extra.envvar.temporary_env(set_vars=None, unset_vars=())[source]¶

Apply environment variable changes for the block’s duration, then restore.

set_vars are written into os.environ and unset_vars removed. On exit, every touched variable is restored to its pre-block state: recreated with its former value, or removed when it did not exist before.

The process environment is patched directly (not through test-framework fixtures) so the helper serves production code paths and test harnesses alike, with a single restore discipline.

Return type:: Iterator[None]

click_extra.envvar.env_copy(extend=None)[source]¶

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

Mimics Python’s original implementation by returning None if no extend content are provided.

A None value removes its variable from the copy instead of setting it, which is the only way to hide an inherited variable from a child process: assigning the empty string leaves it set, and a flag read by bare presence (see parse_envvar_flag()) counts that as activation. Same convention as click.testing.CliRunner.invoke()’s own env argument, and the reason TEnvVars values are typed optional.

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

Return type:: Mapping[str, str | None] | None

click_extra.execution module¶

Type for arbitrary nested CLI arguments.

Arguments can be str, pathlib.Path objects or None values.

click_extra.execution.TNestedArgs¶

Type for arbitrary nested CLI arguments.

Arguments can be str, pathlib.Path objects or None values.

alias of Iterable[str | Path | None | Iterable[TNestedArgs]]

click_extra.execution.CPU_COUNT = 4¶

Number of logical CPUs available to this process, or None if undetermined.

A count of logical processors (hardware threads), resolved by _logical_cpu_count(): os.process_cpu_count() on Python 3.13+, falling back to os.cpu_count() on older runtimes. On a CPU with simultaneous multi-threading (Intel Hyper-Threading, AMD SMT) a 4-physical-core chip reports 8. It is therefore not a count of physical cores, and is usually larger than what physical-core tools report, such as psutil.cpu_count(logical=False) or pytest-xdist’s -n auto (which counts physical cores). Parallelism here is keyed on the logical count on purpose: subprocess- and I/O-bound work overlaps well across hardware threads.

click_extra.execution.DEFAULT_JOBS = 3¶

Default number of parallel jobs: CPU_COUNT minus one reserved core.

Leaves one logical CPU free for the main process and system tasks, but only on hosts with three logical CPUs or more: on smaller hosts the reservation would collapse the pool to a single (sequential) worker, and threads waiting on subprocesses and I/O cost nothing there, so the whole machine is used instead. Falls back to 1 (sequential) when the count cannot be determined.

Caution

On a single-CPU host this still resolves to 1 and the default silently runs sequentially. JobCount.convert() logs whenever a parallel-intent keyword collapses to a single job this way: as a warning for an explicit request, at info level for the option’s own default.

class click_extra.execution.JobCount[source]¶

Bases: ParamType

Parse a --jobs value: an integer or the auto/max keyword.

Resolves the symbolic keywords against the host’s logical CPU count (CPU_COUNT), counting hardware threads, not physical cores:

auto resolves to DEFAULT_JOBS (one fewer than the available logical CPUs, except on hosts with fewer than three, where reserving a core would leave a single worker), the same heuristic used as the option’s default.
max resolves to CPU_COUNT (every available logical CPU).

Any other token is parsed as an integer and left to JobsOption.validate_jobs() for clamping and range-checking. Resolving the keywords here keeps the value handed downstream a plain int, so consumers never have to know about the keywords.

name: str = 'jobs'¶: the descriptive name of this type

choices = ('auto', 'max')¶

Symbolic keywords accepted besides an integer count, in render order.

Exposed as choices so the help colorizer highlights them like click.Choice values: the keyword collector duck-types on this attribute (see the getattr(param.type, "choices", ...) branch in _HelpColorsMixin._collect_params). It is also the single source of truth reused by get_metavar() and convert(), so the metavar and the parser never drift apart.

get_metavar(param, ctx=None)[source]¶: Render [auto|max|INTEGER] (brackets included, as Choice does).

convert(value, param, ctx)[source]¶

Resolve a keyword to a logical-core count, else parse as an integer.

An already-resolved integer is returned untouched, so option defaults and re-validation can flow back through conversion unharmed. When a parallel-intent keyword (auto/max) resolves to a single job, the collapse is logged: the request reads as “use several cores”, but the host has too few logical CPUs, so execution is silently sequential. An explicit request (command line, environment variable, config file) logs a warning; the option’s own default only logs at info level, else every bare invocation on a 1-CPU host would emit a warning the user never asked for, polluting captured runner streams and the CLI output rendered in Sphinx docs.

Return type:: int

shell_complete(ctx, param, incomplete)[source]¶

Suggest the auto/max keywords; an integer count is free-form.

Completion proposes only the symbolic keywords, matched case-insensitively to mirror how convert() lower-cases its input. An integer has no finite set to enumerate, so none is offered, yet convert() still accepts one.

Return type:: list[CompletionItem]

class click_extra.execution.JobsOption(param_decls=None, default='auto', expose_value=False, show_default=True, type=<click_extra.execution.JobCount object>, help="Number of parallel jobs. Accepts an integer, 'auto' (the host's logical CPUs minus one) or 'max' (all logical CPUs). 0 runs sequentially.", **kwargs)[source]¶

Bases: ExtraOption

A pre-configured --jobs option to control parallel execution.

The resolved value is stored as an int in ctx.meta[click_extra.context.JOBS].

Warning

validate_jobs(ctx, param, value)[source]¶

Validate the resolved job count and store it in context metadata.

Return type:: None

click_extra.execution.resolve_jobs(ctx, count, *, serial_at_debug=False)[source]¶

Resolve how many worker threads to use for a batch of count items.

there is no active CLI context (programmatic or test use),
a single item leaves nothing to parallelize, or
the resolved JobsOption count (ctx.meta[click_extra.context.JOBS]) is 1 or less.

Otherwise that count wins, capped at count: there is no point spinning up more workers than there are items.

Parameters:

ctx (Context | None) – the active Click context, read for the resolved --jobs count (and, with serial_at_debug, the verbosity). None forces sequential.
count (int) – how many items are about to be scheduled.
serial_at_debug (bool) – when set, also collapse to sequential at DEBUG verbosity, where coherent per-worker log narration matters more than the speed-up (interleaved threads would scramble it). Off by default.

Return type:

int

click_extra.execution.run_jobs(func, items, *, jobs=None, serial_at_debug=False)[source]¶

Run func over items, parallelized per the resolved --jobs count.

The pool is thread-based, which suits the I/O- and subprocess-bound work CLI tools usually parallelize (each child releases the GIL). The count is a number of logical CPUs: see CPU_COUNT.

items is never materialized: only a bounded window of tasks is queued at a time, so an unbounded or expensive-to-produce stream stays memory-flat and is read no further than the caller consumes.

Parameters:

func (Callable[[TypeVar(T)], TypeVar(R)]) – Called once per item; its return value is yielded.
items (Iterable[TypeVar(T)]) – The work items. Read lazily, a window at a time.
jobs (int | None) – Override the worker count instead of reading it from the context. 1 or fewer forces sequential execution.
serial_at_debug (bool) – forwarded to resolve_jobs() when jobs is not given: collapse to sequential at DEBUG verbosity.

Return type:

Returns:

An iterator over func’s results, in the order of items.

click_extra.execution.run_lanes(func, lanes, *, jobs=None, serial_at_debug=False)[source]¶

Run func over grouped items: serial within a lane, concurrent across.

run_jobs() is the degenerate case where every lane holds a single item. Concurrency is sized by the number of lanes (one worker per lane), since a lane never splits across workers.

Parameters:

func (Callable[[TypeVar(T)], TypeVar(R)]) – Called once per item; its return value is yielded.
lanes (Iterable[Iterable[TypeVar(T)]]) – The lanes, each an iterable of items. Read lazily, a window of lanes at a time; a lane’s own items are materialized when it is scheduled.
jobs (int | None) – Override the worker count instead of reading it from the context. 1 or fewer forces fully sequential execution.
serial_at_debug (bool) – forwarded to resolve_jobs() when jobs is not given: collapse to sequential at DEBUG verbosity.

Return type:

Returns:

An iterator over func’s results, lane by lane in submission order.

class click_extra.execution.TimerOption(param_decls=None, default=False, expose_value=False, is_eager=True, help='Measure and print elapsed execution time.', **kwargs)[source]¶

Bases: 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.context.START_TIME].

print_timer()[source]¶

Compute and print elapsed execution time.

Return type:: None

init_timer(ctx, param, value)[source]¶

Set up the execution-timer machinery for the current invocation.

Return type:: None

class click_extra.execution.ZeroExitOption(param_decls=None, default=False, expose_value=False, is_flag=True, help='Always exit with a status code of 0, even when problems are found.', **kwargs)[source]¶

Bases: ExtraOption

A pre-configured -0/--zero-exit option flag.

The resolved value is stored in ctx.meta[click_extra.context.ZERO_EXIT], aligning with every other Click Extra option’s per-invocation context-meta storage pattern.

Warning

This option is a placeholder: it does not alter the CLI’s exit code by itself. Downstream code must read ctx.meta[click_extra.context.ZERO_EXIT] and act on it.

set_zero_exit(ctx, param, value)[source]¶

Store the resolved zero-exit flag on the context’s meta dict.

Read via click_extra.context.get(ctx, click_extra.context.ZERO_EXIT).

Return type:: None

click_extra.execution.PROMPT = '$ '¶: Prompt used to simulate the CLI execution.

Hint

Use ASCII characters to avoid issues with Windows terminals.

click_extra.execution.INDENT = ' '¶: Constants for rendering of CLI execution.

click_extra.execution.args_cleanup(*args)[source]¶

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

Helps serialize 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.

Return type:: tuple[str, ...]

click_extra.execution.highlight_bin_name(program, theme=None)[source]¶

Style the binary’s own name inside program, leaving its directory plain.

Parameters:

program (str) – the command, path and all.
theme (HelpTheme | None) – palette to style with. Defaults to the theme the current invocation runs under, see format_cli_prompt().

Return type:

Returns:

the styled command.

click_extra.execution.format_cli_prompt(cmd_args, extra_env=None, theme=None, prompt=None)[source]¶

Render the shell prompt simulating a CLI invocation, for logs and dry-runs.

the prompt sigil with bracket, the structural-token style;
each environment assignment as envvar name, plain =, default value;
the program’s binary name with invoked_command, its directory plain (see highlight_bin_name());
the -/-- flags with option; other arguments stay plain.

Useful to print a copy-pasteable command trace in debug logs, dry-runs and test output.

Parameters:

cmd_args (Iterable[str]) – the command line to render.
extra_env (Mapping[str, str | None] | None) – environment assignments to prefix it with.
theme (HelpTheme | None) – palette to style the line with. Defaults to the theme the current invocation runs under, which is what a CLI printing its own trace wants. A caller drawing the line onto a surface of its own choosing (a light capture, say) passes the one that surface can show.
prompt (str | None) – sigil to draw before the command, when the shell being pictured is not the one running. A capture mimicking a Windows terminal passes PS C:\>; None keeps PROMPT, which is this platform’s.

Return type:

CompletedProcess[str]

Returns:

the styled prompt line.

click_extra.execution.terminate_live_processes()[source]¶

Send SIGTERM to every subprocess currently running through run_cli().

A child spawned with start_new_session never receives the terminal’s SIGINT at all (it left the foreground process group), so its whole group is signalled here, descendants included.

Return type:: None

click_extra.execution.install_interrupt_handler(ctx)[source]¶

Make the first Ctrl+C terminate in-flight subprocesses, then abort as usual.

Must run in the main thread: signal.signal() refuses to install a handler from any other, so a non-main-thread caller (embedded use, some tests) is a no-op that keeps the default Ctrl+C behavior.

Return type:: None

click_extra.execution.run_cli(args, *, extra_env=None, cwd=None, timeout=None, label=None, merge_streams=False, errors='replace', windows_creation_flags=0, start_new_session=False, command_level=20, output_level=10, log=None)[source]¶

Run a CLI in a subprocess, disclosing the call and streaming its output live.

A subprocess.run() work-alike for CLI-wrapping tools, with observability built in:

the invocation is logged before the spawn, as the copy-pasteable $ ENV=value command args line of format_cli_prompt(), so a user can reproduce by hand what the tool runs on their system;
each line of the child’s output is forwarded to the logger as it is produced (ANSI-stripped, tagged with label), instead of being held back until the child exits, so a long-running command narrates its progress live;
the child is registered in the live-process registry for the duration of the call, so terminate_live_processes() (wired to Ctrl+C by install_interrupt_handler()) can abort it.

Contract mirrored from subprocess.run():

returns a subprocess.CompletedProcess with the full captured stdout and stderr decoded as UTF-8;
raises subprocess.TimeoutExpired (with the partial capture attached) when the child, or the draining of its output, outlives timeout. The child is killed first — its whole process tree on Windows (see _kill_windows_process_tree()), its whole POSIX process group when spawned with start_new_session, the direct child alone otherwise;
a KeyboardInterrupt mid-run kills the child (with the same tree, group or direct scope), then propagates.

The child reads from subprocess.DEVNULL so it can never block on stdin, and never opens a console window on Windows.

Note

Parameters:

args (str | Path | None | Iterable[str | Path | None | Iterable[Iterable[str | Path | None | Iterable[TNestedArgs]]]]) – the command line. Nested iterables are flattened, None values dropped, and every element (Path, versions, …) cast to a string; see args_cleanup().
extra_env (Mapping[str, str | None] | None) – environment variables forced over the inherited environment for this call (see env_copy()). They are part of the disclosed prompt line, since reproducing the call requires them.
cwd (Path | str | None) – directory to run the child in. None inherits the caller’s, which is subprocess.run()’s own default. A relative args[0] is resolved by the OS against this directory, not the caller’s, so pass an absolute path (or a name on the PATH) when moving the child elsewhere.
timeout (float | None) – seconds before the child is killed. None waits forever.
label (str | None) – tag identifying this call on each streamed output line, for when several children interleave in one log. Carried as the record’s label attribute, which click_extra.logging.Formatter renders glued to the level name and styled like an invoked command (debug:mas: Warning: ...); a foreign formatter can read record.label itself. Applied to the output lines only, never the prompt line.
merge_streams (bool) – route the child’s stderr into stdout so the OS interleaves both in write order. The result’s stderr is then None, like a subprocess.run() call with stderr=STDOUT.
errors (str) – decoding error handler for the child’s output. The default "replace" swaps undecodable bytes for �; pass "backslashreplace" to keep them inspectable as escapes.
windows_creation_flags (int) – extra Windows process-creation flags, OR-ed with the always-on CREATE_NO_WINDOW. No-op off Windows.
start_new_session (bool) – make the child lead its own POSIX session and process group (subprocess.Popen’s parameter of the same name). Every kill path — the timeout overrun, a mid-run KeyboardInterrupt, and terminate_live_processes() — then signals the whole group, so a grandchild spawned by the child (a shim re-executing the real binary, an installer helper) is reaped along with it instead of surviving as an orphan holding the output pipes open. Off by default, and to be left off when a descendant must keep the controlling terminal: a new session detaches from it, so an interactive prompt raised from inside the child (sudo reading /dev/tty) would fail, and sudo’s tty-keyed credential cache would no longer match. No-op on Windows, where the timeout path already kills the full tree. Only the reaping half of this flag has that Windows equivalent, and the other half has none: a POSIX session also detaches the child from the controlling terminal, where a Windows child keeps sharing the parent’s console and can still reach back into it. A subprocess-heavy test suite is where that surfaces — meta-package-manager’s Windows CI saw a package manager’s own teardown land in the parent pytest process as a mid-run KeyboardInterrupt, which a console control event on the shared console explains and which no POSIX runner showed. The lever there is windows_creation_flags (CREATE_NEW_PROCESS_GROUP), left to the caller because it also changes how a real Ctrl-C reaches the child.
command_level (int) – logging level of the invocation-disclosure line. Defaults to logging.INFO; lower it to logging.DEBUG for internal probes not worth narrating.
output_level (int) – logging level of the streamed output lines. Defaults to logging.DEBUG.
log (Logger | None) – destination logger. Defaults to the root logger, whose level the VerbosityOption family manages.

Return type:

click_extra.highlight module¶

Help-screen keyword highlighting and the colorized help formatter.

Hosts the engine that collects highlightable keywords from a Click context (HelpKeywords, _HelpColorsMixin) and renders them with the active theme: HelpFormatter styles --help output and highlight() applies a styling function to arbitrary matches. Split out of click_extra.color, which now focuses on --color/--no-color resolution.

class click_extra.highlight.HelpKeywords(cli_names=<factory>, subcommands=<factory>, command_aliases=<factory>, arguments=<factory>, long_options=<factory>, short_options=<factory>, choices=<factory>, choice_metavars=<factory>, metavars=<factory>, envvars=<factory>, defaults=<factory>)[source]¶

Bases: object

Structured collection of keywords extracted from a Click context for help screen highlighting.

Each field corresponds to a semantic category with its own styling.

cli_names: set[str]¶

subcommands: set[str]¶

command_aliases: set[str]¶

arguments: set[str]¶

long_options: set[str]¶

short_options: set[str]¶

choices: set[str]¶

choice_metavars: set[str]¶

metavars: set[str]¶

envvars: set[str]¶

defaults: set[str]¶

merge(other)[source]¶

Merge another HelpKeywords into this one.

Each set field is updated with the corresponding set from other.

Return type:: None

subtract(other)[source]¶

Remove keywords found in other from this instance.

Each set field is difference-updated with the corresponding set from other. Mirror of merge().

Return type:: None

class click_extra.highlight.HelpFormatter(*args, **kwargs)[source]¶

Bases: HelpFormatter

Extends Cloup’s custom HelpFormatter to highlights options, choices, metavars and default values.

This is being discussed for upstream integration at:

Forces theme to the active one for the current Click context.

Also transform Cloup’s standard HelpTheme to our own HelpTheme.

theme: HelpTheme¶

keywords: HelpKeywords¶

Keywords to highlight, collected from the rendered command’s context.

excluded_keywords: HelpKeywords | None¶: Keywords subtracted from the cross-reference passes, or None.

write_usage(prog, args='', prefix=None)[source]¶

ANSI-aware override of cloup.HelpFormatter.write_usage.

Note

Todo

Drop this override once the minimum supported Click rises to

8.4.0 (which includes pallets/click#3420). The term_len-based visible-width check below becomes redundant once Click’s own wrapper counts visible width.

Return type:: None

highlight_extra_keywords(help_text)[source]¶

Highlight extra keywords in help screens based on the theme.

Return type:: str

getvalue()[source]¶

Wrap original Click.HelpFormatter.getvalue() to force extra-colorization on rendering.

Return type:: str

click_extra.highlight.highlight(content, patterns, styling_func, ignore_case=False)[source]¶

Highlights parts of the content that matches patterns.

Takes care of overlapping parts within the content, so that the styling function is applied only once to each contiguous range of matching characters.

Todo

Support case-foldeing, so we can have the Straße string matching the Strasse content.

This could be tricky as it messes with string length and characters index, which our logic relies on.

Danger

Roundtrip through lower-casing/upper-casing is a can of worms, because some characters change length when their case is changed:

Return type:: str

click_extra.humanize module¶

Human-readable rendering of machine values.

Formatters that turn raw numbers into the compact strings shown in terminal output, tables and reports. The reverse direction, parsing a human-written value back into a machine type, lives in click_extra.types (see Duration).

click_extra.humanize.format_size(size, *, units='iec', precision=1)[source]¶

Render a byte count as a compact, human-readable string.

Parameters:

size (float) – The number of bytes. A negative value keeps a leading -.
units (Literal['iec', 'si', 'jedec']) – The unit system to render in, one of _UNIT_SYSTEMS: iec (the default) for binary powers with the unambiguous KiB/MiB symbols, si for decimal powers with kB/MB, or jedec for binary powers with the customary but imprecise KB/MB.
precision (int) – Number of fractional digits for every unit above bytes. A byte count is always rendered as a whole number.

Return type:

Returns:

The size followed by a space and its unit, like 1.5 KiB. The integer part is grouped with thousands separators.

Raises:

ValueError – If units is not a known unit system.

click_extra.humanize.format_duration(duration)[source]¶

Render an elapsed duration compactly: 2.3s, 1:05, then 1:02:03.

The reverse direction, parsing a human-written duration back into a timedelta, lives in click_extra.types (see Duration).

Parameters:: duration (float | timedelta) – The elapsed time, as a number of seconds or a timedelta.
Return type:: str
Returns:: The compact rendering described above.

click_extra.logging module¶

Logging utilities.

Todo

Let the -v/-q counter reach beyond the current LogLevel range, as sketched by the -vvvv (trace) and -q (silence everything) notes that used to live on _VerbosityOption:

a TRACE pseudo-level below LogLevel.DEBUG (numeric value 5, mirroring logging.DEBUG - 5) so repeated -v can surface finer-grained tracing past DEBUG;
a SILENT pseudo-level above LogLevel.CRITICAL (any value above logging.CRITICAL) so repeated -q can suppress every record, including LogLevel.CRITICAL.

Both require extending LogLevel, which ripples into the --verbosity EnumChoice, the Formatter level-name color lookup and the level-ordering tests. They are intentionally left out of the symmetric-counter change that introduced -q, where the counter simply clamps at DEBUG/CRITICAL.

class click_extra.logging.LogLevel(*values)[source]¶

Bases: IntEnum

Mapping of canonical log level names to their integer level.

That’s our own version of logging._nameToLevel, but:

sorted from lowest to highest verbosity,
excludes the following levels:
- NOTSET, which is considered internal
- WARN, which is obsolete
- FATAL, which shouldn’t be used and has been replaced by CRITICAL

CRITICAL = 50¶

ERROR = 40¶

WARNING = 30¶

INFO = 20¶

DEBUG = 10¶

click_extra.logging.DEFAULT_LEVEL: LogLevel = LogLevel.WARNING¶

WARNING is the default level we expect any loggers to starts their lives at.

WARNING has been chosen as it is the level at which the default Python’s global root logger is set up.

This value is also used as the default level for VerbosityOption .

class click_extra.logging.StreamHandler(stream=None)[source]¶

Bases: StreamHandler

A handler to output logs to the console.

Wraps logging.StreamHandler, but use click.echo() to support color printing.

Only <stderr> or <stdout> are allowed as output stream.

If stream is not specified, <stderr> is used by default

Initialize the handler.

If stream is not specified, sys.stderr is used.

property stream: IO[Any]¶

The stream to which logs are written.

A proxy of the parent logging.StreamHandler’s stream attribute.

Redefined here to enforce checks on the stream value.

emit(record)[source]¶

Use click.echo() to print to the console.

Return type:: None

class click_extra.logging.Formatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)[source]¶

Bases: Formatter

Click Extra’s default log formatter.

Initialize the formatter with specified format strings.

Use a style parameter of ‘%’, ‘{’ or ‘$’ to specify that you want to use one of %-formatting, str.format() ({}) formatting or string.Template formatting in your format string.

Changed in version 3.2: Added the style parameter.

formatMessage(record)[source]¶

Colorize the record’s log level name before calling the standard formatter.

Colors are sourced from a click_extra.theme.HelpTheme, resolved per-invocation via click_extra.theme.get_current_theme().

The record’s levelname is restored afterwards: a record may be formatted more than once (several handlers, a captured then re-rendered record), and must not accumulate styling or glued labels.

Return type:: str

click_extra.logging.basicConfig(*, filename=None, filemode='a', format='{levelname}: {message}', datefmt=None, style='{', level=None, stream=None, handlers=None, force=False, encoding=None, errors='backslashreplace', stream_handler_class=<class 'click_extra.logging.StreamHandler'>, file_handler_class=<class 'logging.FileHandler'>, formatter_class=<class 'click_extra.logging.Formatter'>)[source]¶

Configure the global root logger.

This function is a wrapper around Python standard library’s logging.basicConfig(), but with additional parameters and tweaked defaults.

It sets up the global root logger, and optionally adds a file or stream handler to it.

Differences in default values:

Argument	`basicConfig()` default	`logging.basicConfig()` default
`style`	`{`	`%`
`format`	`{levelname}: {message}`	`%(levelname)s:%(name)s:%(message)s`

This function takes the same parameters as logging.basicConfig(), but require them to be all passed as explicit keywords arguments.

Parameters:

filename (str | None) – Specifies that a logging.FileHandler be created, using the specified filename, rather than an StreamHandler.
filemode (str) –
If filename is specified, open the file in this mode.

Defaults to a.
format (str | None) –
Use the specified format string for the handler.

Defaults to {levelname}: {message}.
datefmt (str | None) – Use the specified date/time format, as accepted by time.strftime().
style (Literal['%', '{', '$']) –
If format is specified, use this style for the format string:
- % for printf-style,
- { for str.format(),
- $ for string.Template.
Defaults to {.
level (int | str | None) – Set the root logger level to the specified level.
stream (IO[Any] | None) – Use the specified stream to initialize the StreamHandler. Note that this argument is incompatible with filename - if both are present, a ValueError is raised.
handlers (Iterable[Handler] | None) – If specified, this should be an iterable of already created handlers to add to the root logger. Any handlers which don’t already have a formatter set will be assigned the default formatter created in this function. Note that this argument is incompatible with filename or stream - if both are present, a ValueError is raised.
force (bool) – If this argument is specified as True, any existing handlers attached to the root logger are removed and closed, before carrying out the configuration as specified by the other arguments.
encoding (str | None) – Name of the encoding used to decode or encode the file. To be specified along with filename, and passed to logging.FileHandler for opening the output file.
errors (str | None) – Optional string that specifies how encoding and decoding errors are to be handled by the logging.FileHandler. Defaults to backslashreplace. Note that if None is specified, it will be passed as such to open().

Return type:

Important

Always keep the signature of this function, the default values of its parameters and its documentation in sync with the one from Python’s standard library.

These new arguments are available for better configurability:

Parameters:

stream_handler_class (type[Handler]) – A logging.Handler class that will be used in logging.basicConfig() to create a default stream-based handler. Defaults to StreamHandler.
file_handler_class (type[Handler]) – A logging.Handler class that will be used in logging.basicConfig() to create a default file-based handler. Defaults to logging.FileHandler.
formatter_class (type[Formatter]) – A logging.Formatter class of the formatter that will be used in logging.basicConfig() to setup the default formatter. Defaults to Formatter.

Note

I don’t like the camel-cased name of this function and would have called it basic_config(), but it’s kept this way for consistency with Python’s standard library logging.basicConfig().

click_extra.logging.new_logger(name='root', *, propagate=False, force=True, **kwargs)[source]¶

Setup a logger in the style of Click Extra.

By default, this helper will:

Fetch the logger registered under the name parameter, or creates a new one with that name if it doesn’t exist,
Set the logger’s propagate attribute to False,
Force removal of any existing handlers and formatters attached to the logger,
Attach a new StreamHandler with Formatter,
Return the logger object.

This function is a wrapper around basicConfig() and takes the same keywords arguments.

Parameters:

name (str) – ID of the logger to setup. If None, Python’s root logger will be used. If a logger with the provided name is not found in the global registry, a new logger with that name will be created.
propagate (bool) – Sets the logger’s propagate attribute. Defaults to False.
force (bool) – Same as the force parameter from logging.basicConfig() and basicConfig(). Defaults to True.
kwargs – Any other keyword parameters supported by logging.basicConfig() and basicConfig().

Return type:

Logger

class click_extra.logging.VerbosityOption(param_decls=None, default_logger='root', default=LogLevel.WARNING, metavar='LEVEL', type=EnumChoice('CRITICAL', 'ERROR', 'WARNING', 'INFO', 'DEBUG'), help='Either CRITICAL, ERROR, WARNING, INFO, DEBUG.', **kwargs)[source]¶

Bases: _VerbosityOption

--verbosity LEVEL option to set the log level of _VerbosityOption.

Set up a verbosity-altering option.

Parameters:: default_logger (Logger | str) – If a logging.Logger object is provided, that’s the instance to which we will set the level to. If the parameter is a string and is found in the global registry, we will use it as the logger’s ID. Otherwise, we will create a new logger with new_logger() Default to the global root logger.

set_level(ctx, param, value)[source]¶

Record the --verbosity value, then reconcile.

The value passed to --verbosity is saved in ctx.meta[click_extra.context.VERBOSITY].

Return type:: None

class click_extra.logging.VerboseOption(param_decls=None, **kwargs)[source]¶

Bases: _CounterOption

--verbose/-v option to raise the log level of _VerbosityOption by one step per repetition.

Each -v raises the verbosity by one LogLevel step. The option can be repeated, so -vv (or -v -v) raises it by two steps.

The base level the counter starts from is sourced from VerbosityOption.default. So with --verbosity’s default left at WARNING:

-v raises the level to INFO,
-vv raises the level to DEBUG,
any further repetition is clamped at the loudest level, so -vvvvv for example resolves to DEBUG.

Set up a verbosity-altering option.

Parameters:: default_logger – If a logging.Logger object is provided, that’s the instance to which we will set the level to. If the parameter is a string and is found in the global registry, we will use it as the logger’s ID. Otherwise, we will create a new logger with new_logger() Default to the global root logger.

class click_extra.logging.QuietOption(param_decls=None, **kwargs)[source]¶

Bases: _CounterOption

--quiet/-q option to lower the log level of _VerbosityOption by one step per repetition.

The symmetric counterpart of VerboseOption: where -v raises the verbosity one LogLevel step at a time, -q lowers it. Starting from VerbosityOption.default (WARNING by default):

-q lowers the level to ERROR,
-qq lowers the level to CRITICAL,
any further repetition is clamped at the quietest level, so -qqqqq for example resolves to CRITICAL.

Set up a verbosity-altering option.

Parameters:: default_logger – If a logging.Logger object is provided, that’s the instance to which we will set the level to. If the parameter is a string and is found in the global registry, we will use it as the logger’s ID. Otherwise, we will create a new logger with new_logger() Default to the global root logger.

click_extra.logo module¶

Terminal rendition of the Click Extra brand mark.

The mark of docs/assets/logo-square.svg is six cubes stacked three-two-one. Here they are rebuilt as flat shaded solids — one color per face, no outline anywhere — and painted with half blocks, two sub-pixels to a terminal line.

Flat faces are what let one palette serve a light terminal and a dark one. An outlined mark carries its shape in the outline, so every stroke has to out-contrast whatever sits behind it, and the artwork’s own palette spans too wide a range for that: six of its colors vanish on white, two more on black. A flat mark carries its shape in the difference between its three planes, which no background can touch, leaving only the silhouette to keep its distance. That fits comfortably in the middle of the range, which is where FACE_COLORS sits.

Caution

The mark’s structure is carried by color: strip the ANSI codes and it collapses into one silhouette. VersionScreen therefore only draws it where color reaches the output, falling back to the plain --version line everywhere else — which is also the form machine readers parse.

click_extra.logo.DOCS_URL = 'https://kdeldycke.github.io/click-extra'¶: Canonical documentation host, advertised on the version screen.

click_extra.logo.TAGLINE = 'Drop-in replacement for Click and Cloup'¶: What the project is, spelled out under the program name.

click_extra.logo.UNIT = 2¶

Scale of the whole mark, in sub-pixels.

Every dimension is a multiple of it, so the mark is 12 * UNIT columns wide and 5 * UNIT lines tall. Two is the largest that still seats the mark beside the version screen’s facts inside eighty columns: 24 columns of mark, three of gutter and fifty of facts comes to 77. Three would need 89, and the screen would decline to draw itself on any standard terminal.

click_extra.logo.LEVELS: tuple[tuple[int, int], ...] = ((0, 0), (0, 1), (0, 2), (1, 0), (1, 1), (2, 0))¶

Each cube’s (row, column) up the pyramid, bottom row first.

Also the order FACE_COLORS is written in, and the order the mark is painted in: a cube resting on two others has to be laid down after them.

click_extra.logo.BRAND_HUES: tuple[int, ...] = (41, 94, 306, 279, 210, 156)¶

Each cube’s hue in degrees, in LEVELS order.

Read off the ribbon that outlines each cube’s top face in the artwork. The mark has no per-cube hue of its own — cube one alone carries gold, green and olive across its six ribbons — so this is a reading of the artwork rather than a recovery of it. It keeps the terminal mark recognizably the same six colors people already associate with the logo, which an evenly spaced spectrum would not.

click_extra.logo.SATURATION = 0.62¶: HLS saturation shared by every face. Vivid enough to tell six hues apart.

click_extra.logo.PLANE_LUMINANCE: dict[str, float] = {'l': 0.13, 'r': 0.22, 't': 0.36}¶

WCAG relative luminance per plane: the lid, then the two walls.

Chosen as a band rather than per color, so every hue is equally far from both backgrounds. The floor of the band is what the mark shows against white and the ceiling what it shows against black, which is why it sits in the middle: the widest band tried reads beautifully on black and falls to 1.74:1 on white.

The 2.25:1 it leaves between a cube’s lid and its dark wall is well past what an eye needs to see a facet, and it survives every dichromacy, planes differing in luminance alone.

click_extra.logo.FACE_COLORS: tuple[dict[str, str], ...] = ({'l': '#7F611E', 'r': '#A37B26', 't': '#CB9A30'}, {'l': '#40721B', 'r': '#519122', 't': '#66B52A'}, {'l': '#AD28A1', 'r': '#D344C6', 't': '#E17FD8'}, {'l': '#9730CC', 'r': '#AE5ED9', 't': '#C58CE4'}, {'l': '#2767A8', 'r': '#3985D0', 't': '#70A7DD'}, {'l': '#1B724F', 'r': '#229265', 't': '#2BB87F'})¶

Each cube’s three face colors, in LEVELS order.

Derived, not picked: every entry is its cube’s BRAND_HUES hue at SATURATION, taken to the luminance its plane declares in PLANE_LUMINANCE. Written out rather than computed at import so the palette stays greppable and a designer can hand-tune one value; test_palette_follows_its_derivation fails if a tuned value drifts off the system.

Emitted as 24-bit color. The 256-color cube cannot separate all eighteen, and the usual reason to prefer it does not apply: no touching pair of faces collides there, so a terminal that downsamples still shows six distinct cubes.

click_extra.logo.geometry()[source]¶

One cube’s dimensions, in sub-pixels.

A lid four units wide and two tall is 2:1 dimetric, and the smallest such rhombus whose half-height is a whole number — which the row pitch needs. The body matches the lid’s width over two, making every box a true cube.

Return type:: dict[str, int]

click_extra.logo.size()[source]¶

The mark’s footprint in sub-pixels, columns by rows.

Return type:: tuple[int, int]

click_extra.logo.LOGO_WIDTH = 24¶: Columns the mark occupies.

click_extra.logo.LOGO_LINES = 10¶: Terminal lines the mark renders to, two sub-pixel rows making one.

click_extra.logo.faces()[source]¶

Every visible face, bottom row first, as whole-sub-pixel polygons.

2:1 dimetric rather than the artwork’s 30 degrees, and integer vertices rather than a sampled rendering, for the same reason: a 30-degree edge advances 1.732 sub-pixels per row, which no grid can hold, so it comes out as a stair of uneven treads that the eye reads as fraying. Two across for every one down tiles a square grid exactly, and every tread is then the same.

Return type:: list[tuple[int, str, list[tuple[int, int]]]]

click_extra.logo.sub_pixels()[source]¶

The mark as a grid of flat colors, hit-tested against the face polygons.

Rasterizing the mark and reading pixels back would hand the antialiaser a say in the palette: every boundary it smooths mints a color belonging to neither face, and a rendition this size comes back carrying over a hundred of them. Testing each sub-pixel’s centre against the polygons keeps it to the eighteen declared, three per cube, which is what makes the edges read as steps rather than smudge.

Return type:: list[list[tuple[int, int, int] | None]]

click_extra.logo.render_logo()[source]¶

Paint the mark into styled lines, each exactly LOGO_WIDTH wide.

A cell whose two sub-pixels carry different colors paints the top one as foreground over the bottom one as background, which is what fits two independent colors on one line. Runs of cells sharing a color pair are styled together rather than one escape sequence per character, keeping the mark from tripling in size.

Trailing blanks are kept: VersionScreen pads a ragged logo for us, but a mark that arrives square costs it nothing to measure.

Return type:: tuple[str, ...]

click_extra.logo.brand_facts()[source]¶

The interpreter and platform every screen reports, plus this project’s own.

Return type:: dict[str, str]

click_extra.logo.BRAND_SCREEN = VersionScreen(logo=(' \x1b[38;2;43;184;127m▄▄██▄▄\x1b[0m ', ' \x1b[38;2;27;114;79m█\x1b[0m\x1b[38;2;43;184;127m\x1b[48;2;27;114;79m▀▀\x1b[0m\x1b[38;2;43;184;127m██\x1b[0m\x1b[38;2;43;184;127m\x1b[48;2;34;146;101m▀▀\x1b[0m\x1b[38;2;34;146;101m█\x1b[0m ', ' \x1b[38;2;27;114;79m████\x1b[0m\x1b[38;2;34;146;101m████\x1b[0m ', ' \x1b[38;2;197;140;228m▄▄██\x1b[0m\x1b[38;2;27;114;79m\x1b[48;2;197;140;228m▀▀\x1b[0m\x1b[38;2;27;114;79m█\x1b[0m\x1b[38;2;34;146;101m█\x1b[0m\x1b[38;2;34;146;101m\x1b[48;2;112;167;221m▀▀\x1b[0m\x1b[38;2;112;167;221m██▄▄\x1b[0m ', ' \x1b[38;2;151;48;204m█\x1b[0m\x1b[38;2;197;140;228m\x1b[48;2;151;48;204m▀▀\x1b[0m\x1b[38;2;197;140;228m██\x1b[0m\x1b[38;2;197;140;228m\x1b[48;2;174;94;217m▀▀\x1b[0m\x1b[38;2;174;94;217m█\x1b[0m\x1b[38;2;39;103;168m█\x1b[0m\x1b[38;2;112;167;221m\x1b[48;2;39;103;168m▀▀\x1b[0m\x1b[38;2;112;167;221m██\x1b[0m\x1b[38;2;112;167;221m\x1b[48;2;57;133;208m▀▀\x1b[0m\x1b[38;2;57;133;208m█\x1b[0m ', ' \x1b[38;2;151;48;204m████\x1b[0m\x1b[38;2;174;94;217m████\x1b[0m\x1b[38;2;39;103;168m████\x1b[0m\x1b[38;2;57;133;208m████\x1b[0m ', ' \x1b[38;2;203;154;48m▄▄██\x1b[0m\x1b[38;2;151;48;204m\x1b[48;2;203;154;48m▀▀\x1b[0m\x1b[38;2;151;48;204m█\x1b[0m\x1b[38;2;174;94;217m█\x1b[0m\x1b[38;2;174;94;217m\x1b[48;2;102;181;42m▀▀\x1b[0m\x1b[38;2;102;181;42m██\x1b[0m\x1b[38;2;39;103;168m\x1b[48;2;102;181;42m▀▀\x1b[0m\x1b[38;2;39;103;168m█\x1b[0m\x1b[38;2;57;133;208m█\x1b[0m\x1b[38;2;57;133;208m\x1b[48;2;225;127;216m▀▀\x1b[0m\x1b[38;2;225;127;216m██▄▄\x1b[0m ', '\x1b[38;2;127;97;30m█\x1b[0m\x1b[38;2;203;154;48m\x1b[48;2;127;97;30m▀▀\x1b[0m\x1b[38;2;203;154;48m██\x1b[0m\x1b[38;2;203;154;48m\x1b[48;2;163;123;38m▀▀\x1b[0m\x1b[38;2;163;123;38m█\x1b[0m\x1b[38;2;64;114;27m█\x1b[0m\x1b[38;2;102;181;42m\x1b[48;2;64;114;27m▀▀\x1b[0m\x1b[38;2;102;181;42m██\x1b[0m\x1b[38;2;102;181;42m\x1b[48;2;81;145;34m▀▀\x1b[0m\x1b[38;2;81;145;34m█\x1b[0m\x1b[38;2;173;40;161m█\x1b[0m\x1b[38;2;225;127;216m\x1b[48;2;173;40;161m▀▀\x1b[0m\x1b[38;2;225;127;216m██\x1b[0m\x1b[38;2;225;127;216m\x1b[48;2;211;68;198m▀▀\x1b[0m\x1b[38;2;211;68;198m█\x1b[0m', '\x1b[38;2;127;97;30m████\x1b[0m\x1b[38;2;163;123;38m████\x1b[0m\x1b[38;2;64;114;27m████\x1b[0m\x1b[38;2;81;145;34m████\x1b[0m\x1b[38;2;173;40;161m████\x1b[0m\x1b[38;2;211;68;198m████\x1b[0m', ' \x1b[38;2;127;97;30m▀▀█\x1b[0m\x1b[38;2;163;123;38m█▀▀\x1b[0m \x1b[38;2;64;114;27m▀▀█\x1b[0m\x1b[38;2;81;145;34m█▀▀\x1b[0m \x1b[38;2;173;40;161m▀▀█\x1b[0m\x1b[38;2;211;68;198m█▀▀\x1b[0m '), tagline='Drop-in replacement for Click and Cloup', facts=<function brand_facts>, gutter=' ')¶

Click Extra’s own --version screen.

Mounted on the click-extra CLI, and the shape a CLI of your own would copy:

from functools import partial
from click_extra import group
from click_extra.commands import default_params

@group(params=partial(default_params, screen=BRAND_SCREEN))
def cli():
    pass

The mark is painted once, here, since it never changes. brand_facts() is passed uncalled so its values are read when --version is, not when this module is imported — the habit that keeps a costlier fact from being charged to every invocation.

click_extra.multicall module¶

Multicall / argv[0] dispatch: one binary answering to many names.

A multicall binary is a single executable whose behavior is selected by the name it is invoked with: bzip2, bunzip2 and bzcat are the same file, vim and view differ by default options, and BusyBox multiplexes hundreds of applets behind symlinks pointing at one binary. MulticallGroup brings the pattern to Click Extra: a group that, when invoked under the name of one of its subcommands, skips the group and behaves exactly like that subcommand as a standalone binary.

Declare one with multicall_group():

from click_extra import argument, echo, multicall_group, option


@multicall_group()
def kitchen():
    '''A multicall kitchen appliance.'''


@kitchen.command()
@option("--temperature", default="180")
@argument("dishes", nargs=-1)
def bake(temperature, dishes):
    '''Bake dishes in the oven.'''


@kitchen.command()
@option("--hours", default="2")
@argument("bottles", nargs=-1)
def chill(hours, bottles):
    '''Chill bottles in the fridge.'''

Invoked as kitchen, the CLI is a regular group. Invoked through a symlink named bake (or any other subcommand name), it is the bake command: one flat argument parse, its own usage line and help screen, and the full set of Click Extra options merged in:

$ kitchen bake --temperature 200 pie       # regular group dispatch
$ ln -s $(which kitchen) bake
$ bake --temperature 200 pie               # same thing, no subcommand

A personality maps to a sequence of tokens, not just a subcommand, so a name can also pre-fill options (bzcat is bzip2 --decompress --stdout):

@multicall_group(personalities={"chill-fast": ("chill", "--hours", "1")})
def kitchen():
    ...

Note

Behavioral notes for personality mode:

The group’s own callback does not run: the personality is a standalone command with no parent context.
Configuration and environment variable namespaces follow the personality name: bake reads its configuration from the bake app dir and the BAKE_* environment variables, the way a standalone binary would, and not from the group’s kitchen namespace.
The invocation name a command was started under is also exposed on its own, for custom dispatch logic: see click_extra.context.INVOCATION_NAME.

click_extra.multicall.WINDOWS_EXE_SUFFIX = '.exe'¶

Suffix of Windows console-script wrappers, stripped from argv[0].

On Windows, entry points are materialized as .exe shims, so a symlink named bake lands in argv[0] as bake.exe.

click_extra.multicall.normalize_personality(tokens)[source]¶

Normalize a personality mapping value into a tuple of CLI tokens.

Accepts a bare subcommand name ("chill") or a token sequence (("chill", "--hours", "1")). The first token names the subcommand the personality dispatches to; the rest is prepended to the user’s arguments.

Raises:

TypeError – when the value is neither a string nor a sequence.
ValueError – on an empty sequence or a non-string token.

Return type:

tuple[str, ...]

class click_extra.multicall.PersonalitiesCommand(name, context_settings=None, callback=None, params=None, help=None, epilog=None, short_help=None, options_metavar='[OPTIONS]', add_help_option=True, no_args_is_help=False, hidden=False, deprecated=False)[source]¶

Bases: ColorizedCommand

Synthetic subcommand listing every name a MulticallGroup answers to.

Auto-injected into every MulticallGroup, the way HelpCommand is injected into every Group: the group mode needs a place to enumerate the symlink names, and a subcommand costs no new top-level option on the group’s help screen.

invoke(ctx)[source]¶

List each personality next to the command line it invokes.

Return type:: None

class click_extra.multicall.MulticallGroup(*args, personalities=None, personalities_command=True, **kwargs)[source]¶

Bases: Group

A Group dispatching on its invocation name, BusyBox-style.

The invocation name is, in precedence order:

an explicit prog_name passed to main() (what click_extra.testing.CliRunner uses to simulate a symlink),
else the unresolved basename of sys.argv[0].

Like Group.__init__, but with multicall dispatch.

Parameters:

personalities (Mapping[str, str | Sequence[str]] | None) – maps an invocation name to the tokens it invokes: a bare subcommand name ("chill") or a token sequence (("chill", "--hours", "1")) whose extra tokens are prepended to the user’s arguments. Left to None, every non-hidden, non-synthetic subcommand is its own personality.
personalities_command (bool) – when True (the default), a personalities subcommand is auto-registered on the group, listing every invocation name the binary answers to. Register your own personalities subcommand to override it.

personalities: dict[str, tuple[str, ...]]¶

resolve_invocation_name(prog_name=None)[source]¶

The name this binary was invoked under.

An explicit prog_name wins: it is what makes the feature testable without symlinks on disk. Otherwise the unresolved basename of sys.argv[0] is used, with a trailing .exe stripped on Windows.

Return type:: str | None

list_personalities()[source]¶

Every personality name mapped to the tokens it invokes.

The explicit personalities mapping when one was declared, else every non-hidden, non-synthetic subcommand mapped to itself.

Return type:: dict[str, tuple[str, ...]]

match_personality(name)[source]¶

Tokens to invoke when called under name, or None to fall through.

Return type:: tuple[str, ...] | None

main(args=None, prog_name=None, **kwargs)[source]¶

Dispatch on the invocation name before any argument parsing.

A matching personality runs as a standalone command, the group’s own options merged into it, its extra tokens prepended to the arguments. Anything else delegates to the regular group main().

Return type:: Any

build_personality(name, tokens)[source]¶

Synthesize the standalone command the name personality runs as.

Cloup computes its help layout (arguments, option_groups, ungrouped_options) from params inside __init__, so a patched copy parses every merged option but only renders the subcommand’s own on its help screen.
Click Extra’s own Command.__init__ does work that must run over the merged set: extra_option_at_end reordering, option priorities, auto envvar population and help-keyword collection.

Return type:: Command

click_extra.myst_converter module¶

Convert reST docstrings to MyST in Python source files.

Transforms reST markup in docstrings and comments to MyST markdown. The companion Sphinx extension click_extra.sphinx.myst_docstrings converts the MyST back to reST at build time, so sphinx.ext.autodoc still works.

Conversions applied (in order):

Cross-references: :role:`target` -> {role}`target`
Named links: `text <url>``_ -> text <url>`_
Inline code: ``code`` -> `code`
#: comment blocks: strip prefix, convert directives, re-wrap.
Directives: .. directive:: + indented body -> ```` `{directive} `` / ```` ` ``

Only docstrings (bare string-expression statements, located with ast) and comments (located with tokenize) are transformed. String literals, f-strings, and every other piece of runtime code pass through byte-for-byte: a regex pattern or an error message that happens to contain reST markup is not documentation and must not be rewritten.

Safe to re-run: already-converted MyST syntax does not match the reST patterns, so the script is idempotent.

Note

f-string exclusion: Cross-reference and inline-code regexes exclude targets containing { so that interpolation-style placeholders (like {self.id} in a documented format template) are untouched.

Note

Nested fences stay as reST: A directive whose body already contains a triple-backtick fence is left in reST. Converting it would nest two same-level fences, which markdown cannot delimit, and the build-time extension passes reST through unchanged anyway.

Note

Nested directives stay as reST: A .. code-block:: inside a converted backtick-fenced warning directive is emitted as-is. The hook handles this correctly because it re-indents the body when converting back to reST.

Note

Link labels lose backticks: `sys.platform <url>`_ is valid MyST but reST has no nested markup. The hook strips backticks from labels before emitting the reST link.

click_extra.myst_converter.detect_source_package(pyproject_path=None)[source]¶

Locate the project’s single source package from its script entry points.

Parameters:: pyproject_path (Path | None) – Path of the pyproject.toml to inspect. Defaults to the one in the current working directory.
Return type:: Path
Returns:: Path of the single detected package directory.
Raises:: ValueError – When pyproject.toml is missing, declares no script entry point, or several distinct packages are detected.

click_extra.myst_converter.convert_xrefs(text)[source]¶

Convert reST cross-references to MyST syntax.

Return type:: str

click_extra.myst_converter.convert_links(text)[source]¶

Convert reST named hyperlinks to markdown links.

Return type:: str

click_extra.myst_converter.convert_inline_code(text)[source]¶

Convert reST double-backtick literals to single-backtick.

Return type:: str

click_extra.myst_converter.convert_directives(text)[source]¶

Convert reST directives to MyST backtick fences in a single pass.

Body lines are collected by indentation (deeper than the .. line) and dedented to the fence level. Trailing blank lines between consecutive directives are preserved as a single separator.

Nested reST directives (like .. code-block:: inside .. warning::) are emitted as-is in the fence body. The hook re-indents them during the reST round-trip.

A directive whose body contains a triple-backtick fence is left in reST entirely: converting it would produce two same-level fences that markdown cannot tell apart, and a longer outer fence is no better since the build-time hook only recognizes triple-backtick fences.

Symmetrically, existing fences are opaque: a reST directive inside a fence body is exactly what a previous conversion of nested directives produces (the inner one stays reST by design), so re-scanning it would break idempotency and nest same-level fences.

Return type:: str

click_extra.myst_converter.convert_comment_blocks(text)[source]¶

Convert #: Sphinx comment docstrings.

Consecutive #: lines are collected, the prefix is stripped, all conversions are applied to the extracted content, and the prefix is re-added.

Return type:: str

click_extra.myst_converter.convert_source(source)[source]¶

Convert reST markup to MyST in a Python module’s docstrings and comments.

Return type:: str

click_extra.myst_converter.convert_file(filepath)[source]¶

Apply all conversions to a single Python file.

Returns True if the file was modified.

Return type:: bool

click_extra.myst_converter.convert_directory(directory)[source]¶

Convert all Python files in a directory from reST to MyST docstrings.

Parameters:: directory (Path) – Directory to process recursively.
Return type:: list[Path]
Returns:: List of files that were modified.

click_extra.output module¶

Send command output to a file path or to stdout.

Helpers for the common --output option pattern, where a - value means “write to stdout” instead of creating a file literally named -.

click_extra.output.STDOUT_SENTINEL = '-'¶: Conventional --output value asking for stdout instead of a file on disk.

click_extra.output.is_stdout(path)[source]¶

Return True when path is the stdout sentinel -.

Guards against accidentally creating a file literally named - in the current directory.

Return type:: bool

click_extra.output.prep_path(path)[source]¶

Open path for writing as UTF-8 text, or return stdout for -.

Note

Parameters:: path (Path) – The destination path, or - for stdout.
Return type:: IO[str]
Returns:: A writable text stream. The caller closes it; the stdout stream is wrapped with closefd=False, so closing it leaves the real stdout open.

click_extra.parameters module¶

Our own flavor of Option, Argument and parameters.

class click_extra.parameters.P¶

Type variable bound to click.Parameter, letting require_sibling_param() return the exact subclass it was asked to find.

alias of TypeVar(‘P’, bound=Parameter)

click_extra.parameters.PARAM_PATH_SEP = '.'¶: Separator joining the keys of a parameter’s fully-qualified path (cli.subcommand.param).

click_extra.parameters.search_params(params, klass, include_subclasses=True, unique=True)[source]¶

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

Parameters:

params (Iterable[Parameter]) – list of parameter instances to search in.
klass (type[Parameter]) – the class of the parameters to look for.
include_subclasses (bool) – 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.
unique (bool) – if True, raise an error if more than one parameter of the provided klass is found. Defaults to True.

Return type:

list[Parameter] | Parameter | None

click_extra.parameters.last_param(params, klass)[source]¶

Return the last parameter of exactly klass in params, or None.

Parameters:

params (Iterable[Parameter]) – the command’s parameter list to scan.
klass (type[Parameter]) – the exact parameter class to look for.

Return type:

Parameter | None

click_extra.parameters.require_sibling_param(params, requester, klass)[source]¶

Return the sibling klass parameter declared on the same command, or raise.

Parameters:

params (Iterable[Parameter]) – the command’s parameter list to scan.
requester (Parameter) – the parameter requiring the sibling, used to build the error message from its flag names and class.
klass (type[TypeVar(P, bound= Parameter)]) – the sibling parameter class to look for.

Return type:

TypeVar(P, bound= Parameter)

click_extra.parameters.full_short_help(command)[source]¶

Return the command’s canonical one-line short help, untruncated.

Click’s click.Command.get_short_help_str() truncates to 45 characters by default with a trailing "..." so subcommand listings fit a terminal column. That bound is wrong for generated documentation and completion specs, where the NAME / COMMANDS sections carry the full description and the renderer wraps text on its own.

The lookup mirrors Click’s order: an explicit short_help wins, otherwise the first paragraph of command.help is joined into one line. A truthy deprecated flag prepends (Deprecated) so the flag stays visible.

Return type:: str

click_extra.parameters.resolve_param_help(param, ctx)[source]¶

Return a parameter’s help text, including the dynamically-generated ones.

Reading param.help covers the options that carry a static string, and misses the ones that compute their help from the context: Click Extra’s own -v / -q derive theirs from the resolved base verbosity, and leave the attribute at None (see get_help_record()). Falling back to the help record picks those up.

The record also carries Click’s bracket fields ([default: …], [required], [env var: …]), appended to the prose behind two spaces. They are stripped here: they are not the author’s documentation, and every backend of this module renders them (or deliberately does not) from structured fields of its own.

Return type:: str | None

click_extra.parameters.param_spellings(param)[source]¶

All literal spellings of a parameter: primary opts then secondary_opts.

A boolean flag pair yields both forms (--foo, --no-foo); a plain option yields just its declared names.

Return type:: tuple[str, ...]

click_extra.parameters.short_long_opts(opts)[source]¶

Split option spellings into the first short (-x) and long (--xy) form.

Either element is the empty string when that form is absent.

Return type:: tuple[str, str]

click_extra.parameters.option_value_kind(param)[source]¶

Classify how an option consumes a value, the basis for rendering its metavar.

"flag": takes no value. A boolean switch (--foo, --foo/--no-foo), a flag with a custom flag_value (--no-config), or a counter (-v).
"optional": the value may be omitted. Click models this as is_flag=False with a flag_value set, so a bare --color stands for the flag value while --color=never passes an explicit one.
"required": consumes a value (--config CONFIG_PATH).

Note

The discriminator is Click’s is_flag (plus count), not is_bool_flag: a flag carrying a custom flag_value such as NoConfigOption reports is_bool_flag=False yet still takes no value.

Return type:: Literal['flag', 'optional', 'required']

click_extra.parameters.resolve_flag_value(param)[source]¶

The value param’s primary declaration stands for.

Released Click materializes it in flag_value: None for a plain option or a counter, True for a boolean flag, and the declared value otherwise (--color standing for always). Click’s development branch leaves that attribute as the UNSET sentinel and answers the same question lazily in flag_activation_value, so reading either attribute on its own is right on only one of the two, and storing the sentinel anywhere it will be read back as a value silently turns the flag off.

Return type:: Any

click_extra.parameters.is_repeatable(param)[source]¶

Whether the parameter may be supplied several times (multiple or count).

Return type:: bool

class click_extra.parameters.Argument(*args, help=None, **attrs)[source]¶

Bases: _ParameterMixin, Argument

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

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

class click_extra.parameters.Option(*args, group=None, **attrs)[source]¶

Bases: _ParameterMixin, Option

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

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

class click_extra.parameters.ExtraOption(*args, group=None, **attrs)[source]¶

Bases: Option

Dedicated to option implemented by click-extra itself.

Note

set_<key> publishes a resolved value to ctx.meta (set_color, set_no_color, set_theme, set_telemetry, set_progress, set_accessible, set_zero_exit, the verbosity options’ set_level);
init_<system> additionally installs a ctx helper or records a snapshot (init_timer, init_formatter, init_columns, init_sort);
validate_<thing> coerces and validates the raw input (validate_jobs, validate_config);
print_* renders output and exits (print_man, print_params, print_and_exit).

handle_parse_result(ctx, opts, args)[source]¶: Record the parameter source before delegating to the base implementation.

Warning

Click 8.4.0 (PR pallets/click#3404) reordered Parameter.handle_parse_result so ctx.set_parameter_source runs after process_value. Callbacks that introspect their own provenance via ctx.get_parameter_source(self.name) therefore read None instead of the actual source. ColorOption, ConfigOption, and ShowParamsOption rely on this introspection (from their eager callback) to decide whether an env var should override the default (--color), whether the --config path was user-supplied, and what to render in the Source column of --params. JobsOption relies on the same introspection from its type’s non-eager convert() (JobCount), to decide whether an auto/max collapsing to a single job logs as a warning (explicit request) or at info level (the option’s own default).

Click 8.4.1 restored the pre-8.4.0 contract upstream (PR pallets/click#3484), so this override only matters for Click 8.4.0 itself, which sits inside click-extra’s supported >= 8.3.1 range. Pre-recording the source here, for every option regardless of eagerness, keeps that contract on every supported Click. super().handle_parse_result re-records the same value at the canonical time, so the slot arbitration logic introduced by #3404 is unaffected: slot_empty is computed from ctx.params, not from _parameter_source.

consume_value runs twice as a side effect: once here and once in super. Both calls are pure for click-extra’s existing options (no env var side effects, no prompt): consume_value only resolves the raw value and its source, it never invokes the parameter’s type.convert(), so this pre-record cannot itself trigger a callback’s or a type’s logging or validation twice. Should a future subclass need prompt behavior, this override would need to cache the result instead.

The pre-record is skipped when the slot already carries a source from an earlier option sharing the same name (Click’s feature-switch pattern), so the arbitration logic in super still sees the original existing_source rather than a stale rewrite from this option.

class click_extra.parameters.ParamStructure[source]¶

Bases: object

Utilities to introspect CLI options and commands structure.

Structures are represented by a tree-like dict.

Access to a node is available using a serialized path string composed of the keys to descend to that node, separated by a dot ..

excluded_params: frozenset[str]¶

Fully-qualified IDs of the parameters to block from the structure.

included_params: frozenset[str] | None¶

Allowlist of parameter IDs, mutually exclusive with excluded_params.

None disables the allowlist. It is resolved into excluded_params by build_param_trees(), once every parameter ID is known.

static init_tree_dict(*path, leaf=None)[source]¶

Utility method to recursively create a nested dict structure whose keys are provided by path list and at the end is populated by a copy of leaf.

Return type:: Any

static get_tree_value(tree_dict, *path)[source]¶

Get in the tree_dict the value located at the path.

Raises KeyError if no item is found at the provided path.

Return type:: Any

walk_params()[source]¶

Generate an unfiltered list of all CLI parameters.

Everything is included, from top-level groups to subcommands, and from options to arguments.

Return type:: Iterator[tuple[tuple[str, ...], Parameter]]

Yields a 2-element tuple:

a tuple of keys leading to the parameter;
the parameter object itself.

Thin adapter over walk_command_params(): it resolves the root CLI from the active context and drops the per-parameter context that the free function also yields.

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 map_click_type(click_type)[source]¶

Map a Click parameter type instance to its Python equivalent.

Returns str for unrecognised custom types, since command-line parameters are strings by default.

See the list of custom types provided by Click.

Return type:: type[str | int | float | bool | list]

static get_param_type(param)[source]¶

Get the Python type of a Click parameter.

Returns str for unrecognised custom types, since command-line parameters are strings by default.

See the list of custom types provided by Click.

Return type:: type[str | int | float | bool | list]

build_param_trees()[source]¶

Build and return the parameters tree structure.

This removes parameters whose fully-qualified IDs are in the excluded_params blocklist.

If included_params was provided, it is resolved into excluded_params here, where all parameter IDs are available.

Return type:: dict[str, Any]

property params_template: dict[str, Any][source]¶

Returns a tree-like dictionary whose keys shadows the CLI options and subcommands and values are None.

Perfect to serve as a template for configuration files.

property params_objects: dict[str, Any][source]¶

Returns a tree-like dictionary whose keys shadows the CLI options and subcommands and values are parameter objects.

Perfect to parse configuration files and user-provided parameters.

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 hidden property is only supported by Option, not Argument.

Todo

Return type:: str | None

click_extra.parameters.format_param_row(param, ctx, path, is_structured)[source]¶

Compute the structural table cells for a Click parameter.

For structured formats (JSON, YAML, etc.), values are native Python types. For visual formats, values are themed strings matching help-screen styling.

The remaining table columns (allowed_in_conf, value, source, config_file) require live context and are filled in by render_params_table().

Return type:: dict[str, Any]

click_extra.parameters.make_resilient_context(command, info_name=None, parent=None)[source]¶

Build an introspection context for a command.

Parses no arguments and sets resilient_parsing=True so required-argument errors, prompts and eager-option side effects stay dormant: the canonical way to materialize a click.Context purely to read a command’s structure (its parameters, env-var prefix and subcommands), shared by the man-page and Carapace exporters.

Return type:: Context

click_extra.parameters.iter_subcommands(command, ctx, *, skip_hidden=True)[source]¶

Yield a group’s direct subcommands as (name, command) pairs.

Subcommands are discovered dynamically through click.Group.list_commands() / get_command(), in listing order, so lazily-registered commands are included. A non-group yields nothing, a name resolving to None is skipped, and hidden subcommands are skipped unless skip_hidden is False (completion specs keep them, flagged hidden; documentation drops them).

Return type:: Iterator[tuple[str, Command]]

click_extra.parameters.iter_params_for_display(command, ctx)[source]¶

Yield a command’s parameters in the order its help screen lists them.

A Click Extra command keeps two orders apart: command.params is the processing order, which decides when each callback fires, while the help screen reads the presentation order Cloup caches in arguments, option_groups and ungrouped_options (see click_extra.commands.Command.param_priority()). Reading get_params() therefore renders a man page, a Markdown document or a completion spec whose flags no longer match the --help its reader just saw. This is the accessor every such renderer should go through.

Falls back to get_params() for a command that carries no Cloup option groups, where the two orders are the same list. Any parameter attached after construction, and so absent from the cached groups, is yielded last rather than dropped.

Return type:: Iterator[Parameter]

click_extra.parameters.walk_command_params(cmd, ctx, parent_keys=())[source]¶

Walk the parameter tree of a Click command and all its subcommands.

Yields (path_keys, param, owning_ctx) for every parameter found on cmd and, recursively, on each subcommand. Each subcommand is walked under its own freshly-built child context, so context-sensitive metadata (notably the auto-generated environment variable, which derives from Context.auto_envvar_prefix) is computed at the correct nesting level rather than inherited from the root.

A subcommand whose name collides with a sibling parameter at the same level is skipped: a single fully-qualified path cannot address both an option and a subcommand at once.

Return type:: Iterator[tuple[tuple[str, ...], Parameter, Context]]

click_extra.parameters.replay_raw_args(subject_ctx)[source]¶

Re-parse the captured raw arguments to recover per-parameter values.

Click discards the pre-parsed arguments once processing is done, so the value and provenance of each parameter cannot be read back directly. When RAW_ARGS was captured on the context (by Command/Group), replaying it through a fresh parser rebuilds the opts mapping that Parameter.consume_value consults, without re-firing eager callbacks: handle_parse_result is never called here, only the parser.

Returns an empty mapping when no raw arguments were captured, so callers can fall back to parameter defaults.

Return type:: dict[str, Any]

click_extra.parameters.param_config_source(root_ctx, keys)[source]¶

Return the configuration file supplying a parameter’s default_map value.

keys is the parameter’s fully-qualified path, root command name first and parameter name last, as yielded by walk_command_params(). Returns None when no configuration file was loaded, when the parameter is absent from every loaded layer, or when the context carries no layered default_map at all.

The walk mirrors how Click resolves default_map, so the attribution matches the value Click actually picks:

Root-level parameters are looked up in the root context’s ~collections.ChainMap, whose first layers are the loaded files in precedence order (see CONF_SOURCES): the first layer naming the parameter wins.
A subcommand section resolves against that same ChainMap, but Click keeps descending inside the single layer that named the first segment: the file owning a subcommand section owns its whole sub-tree.

Note

Lazy subcommands receive their section from the merged configuration document, injected into the front layer by _apply_config_to_parent_context(): those values are attributed to the highest-precedence file even when several files contributed to the merge.

Return type:: Path | URL | None

click_extra.parameters.render_params_table(subject_ctx, *, default_columns=None)[source]¶

Introspect subject_ctx.command and print its parameter metadata table.

Walks the command and any nested subcommands, emitting one row per parameter. The table format and column selection are read from subject_ctx.meta (see TABLE_FORMAT and COLUMNS); when neither is set, a sibling --table-format / --columns option on the command is consulted, then the default_columns fallback, then the canonical order.

When subject_ctx.meta carries pre-parsed RAW_ARGS, the value and source columns are resolved by replaying those arguments against the command parser; otherwise they fall back to the parameter defaults.

This is the shared rendering core behind both print_params() (introspecting the live CLI) and the click-extra wrap --params path (introspecting a foreign target). The caller is responsible for exiting the context afterwards.

Important

Click does not keep the raw, pre-parsed arguments around, so values and their provenance cannot be read back directly. The workaround replays RAW_ARGS (captured on the context by Command/Group) through the command parser, calling consume_value() rather than handle_parse_result() so eager callbacks are not re-triggered.

Return type:: None

class click_extra.parameters.ShowParamsOption(param_decls=None, is_flag=True, expose_value=False, is_eager=True, help='Show all CLI parameters, their provenance, defaults and value, then exit.', **kwargs)[source]¶

Bases: ExtraOption, ParamStructure

A pre-configured option adding a --params option.

Note

Rich column registry for the --params table.

classmethod column_labels()[source]¶

Return just the display labels of TABLE_HEADERS (in order).

Return type:: tuple[str, ...]

classmethod column_ids()[source]¶

Return just the stable IDs of TABLE_HEADERS (in order).

Return type:: tuple[str, ...]

classmethod default_columns()[source]¶

Return the columns rendered when --columns asks for no projection.

Every column but the optional ones, which stay addressable by ID and out of the way until named.

Return type:: tuple[_ColumnSpec, …]

classmethod default_column_ids()[source]¶

Return the stable IDs of default_columns() (in order).

Return type:: tuple[str, ...]

classmethod default_column_labels()[source]¶

Return the display labels of default_columns() (in order).

Return type:: tuple[str, ...]

classmethod find_column(column_id)[source]¶

Return the ColumnSpec matching column_id.

Raises KeyError if no column has this ID; callers should convert the error into a click.UsageError when surfaced to a user.

classmethod render_doc_table()[source]¶

Render TABLE_HEADERS as a Markdown table for documentation.

Return type:: str

excluded_params¶: Deactivates the blocking of any parameter.

included_params¶: No allowlist filter; show all parameters.

print_params(ctx, param, value)[source]¶

Introspect the current CLI and print its parameter metadata table.

Return type:: None

click_extra.prebake module¶

Bake build-time metadata into Python source files before compilation.

Compiled binaries (Nuitka, PyInstaller) and git-less runtimes (Docker images, archive checkouts) cannot resolve version or Git metadata at runtime the way click_extra.version.VersionOption does. The values must instead be written into the source before the build, by rewriting the relevant dunder assignments (__version__, __git_short_hash__, …) in place with ast.

This mirrors shadow-rs, which injects build-time constants (BRANCH, SHORT_COMMIT, COMMIT_HASH, COMMIT_DATE, TAG, …) into Rust binaries at compile time.

Todo

Add the following build-time template fields, mirroring the constants shadow-rs injects:

{build_time}: when the distribution was built (shadow-rs exposes it as BUILD_TIME, with RFC 2822 and RFC 3339 variants BUILD_TIME_2822 / BUILD_TIME_3339).
{build_os} / {build_target} / {build_target_arch}: the OS, target triple and architecture the build ran on. These describe the build host, unlike {env_info} which reports the runtime Python, OS and architecture, so both are worth keeping for cross-built binaries.

click_extra.prebake.prebake_version(file_path, local_version)[source]¶

Pre-bake a __version__ string with a PEP 440 local version identifier.

Reads file_path, finds the __version__ assignment via ast, and, if the version contains .dev and does not already contain +, appends +<local_version>.

This is the compile-time complement to the runtime click_extra.version.VersionOption.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).

Return type:: str | None

click_extra.prebake.prebake_dunder(file_path, name, value)[source]¶

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

Reads file_path, finds a top-level name = "" assignment via 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 acts as a falsy sentinel that stays type-consistent with baked values (always str).

This is the generic counterpart to 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).

Return type:: str | None

click_extra.prebake.discover_package_init_files()[source]¶

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].

Return type:: list[Path]

click_extra.pygments module¶

Pygments lexers, filters, and formatters for ANSI escape sequences.

Parses ANSI SGR escape sequences (ECMA-48 / ISO 6429) from terminal output and renders them as colored HTML with CSS classes. Supports the standard 8/16 named colors, the 256-color indexed palette, and 24-bit RGB.

SGR text attributes: bold, faint, italic, underline, blink, reverse video, strikethrough, and overline.

OSC 8 hyperlinks are rendered as HTML <a> tags. Other OSC sequences are silently stripped.

Note

24-bit RGB colors (SGR 38;2;r;g;b and 48;2;r;g;b) are preserved by default and rendered by AnsiHtmlFormatter as inline style="color: #rrggbb" / style="background-color: #rrggbb" spans (CSS classes cannot enumerate 16.7M colors). Other token components (bold, named colors, palette indices) keep their CSS-class rendering. Pass true_color=False to AnsiColorLexer, AnsiFilter, or any session lexer (via get_lexer_by_name(..., true_color=False)) to opt into quantization to the nearest entry in the 256-color palette instead.

click_extra.pygments.Ansi = ('Ansi',)¶

Unified token namespace for ANSI styling.

Compound tokens from the lexer (like Token.Ansi.Bold.Red) and individual style components (like Token.Ansi.Red) share this single namespace. The formatter decomposes compound tokens into individual CSS classes at render time.

click_extra.pygments.DEFAULT_TOKEN_TYPE = ('Generic', 'Output')¶

Default Pygments token type to render with ANSI support.

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

class click_extra.pygments.AnsiColorLexer(*args, **kwargs)[source]¶

Bases: Lexer

Lexer for text containing ANSI escape sequences.

Parses Select Graphic Rendition (SGR) codes and emits compound Token.Ansi.* tokens representing the active styling state. OSC 8 hyperlinks emit Token.AnsiLinkStart / Token.AnsiLinkEnd structural tokens. All other escape sequences are silently stripped.

Supported SGR codes:

Text attributes: bold (1), faint (2), italic (3), underline (4), blink (5), reverse video (7), strikethrough (9), overline (53), and their resets.
Named colors: standard (30-37, 40-47) and bright (90-97, 100-107).
256-color indexed palette (38;5;n, 48;5;n).
24-bit RGB (38;2;r;g;b, 48;2;r;g;b), quantized to the nearest 256-color entry.

Supported OSC sequences:

OSC 8 hyperlinks: rendered as <a> tags by AnsiHtmlFormatter. Only URLs with safe schemes (http, https, mailto, ftp, ftps) are emitted; others are stripped.

Initialize the lexer.

Parameters:: true_color – Default True. 24-bit RGB sequences are preserved as Token.Ansi.FG_{rrggbb} / Token.Ansi.BG_{rrggbb} tokens, which AnsiHtmlFormatter renders as inline style="color: #rrggbb" / style="background-color: #rrggbb" attributes (CSS classes cannot enumerate 16.7M colors). Pass False to quantize 24-bit RGB to the nearest entry in the 256-color palette and emit Token.Ansi.C{n} / Token.Ansi.BGC{n} tokens that map to CSS classes via the style dict.

name = 'ANSI Color'¶: Full name of the lexer, in human-readable form

aliases = ('ansi-color', 'ansi', 'ansi-terminal')¶: A list of short, unique identifiers that can be used to look up the lexer from a list, e.g., using get_lexer_by_name().

get_tokens_unprocessed(text)[source]¶

Parse ANSI escape sequences from text and yield styled tokens.

SGR sequences update the styling state. OSC 8 hyperlinks emit structural Token.AnsiLinkStart / Token.AnsiLinkEnd tokens. All other escape sequences are consumed and stripped.

Return type:: Iterator[tuple[int, _TokenType, str]]

class click_extra.pygments.AnsiFilter(**options)[source]¶

Bases: Filter

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

Initialize an AnsiColorLexer and configure the token_type to be colorized.

Parameters:: true_color – Forwarded to the inner AnsiColorLexer to control whether 24-bit RGB sequences are preserved as FG_/BG_ hex tokens for inline-style rendering (default True) or quantized to the 256-color palette. See AnsiColorLexer for details.

Note

Only one token_type is supported. All Pygments session lexers (ShellSessionBaseLexer and the manually-maintained list in collect_session_lexers) emit terminal output exclusively as Generic.Output. No upstream issue or PR proposes splitting output into additional token types (like Generic.Error for stderr). If that changes, this filter would need to accept a set of token types instead of a single one. See pygments#1148 and pygments#2499 for the closest related discussions.

filter(lexer, stream)[source]¶

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

Return type:: Iterator[tuple[_TokenType, str]]

click_extra.pygments.collect_session_lexers()[source]¶

Retrieve all lexers producing shell-like sessions in Pygments.

This function contains a manually-maintained list of lexers, to which we dynamically add lexers inheriting from ShellSessionBaseLexer.

Hint

To help maintain this list, there is a test that will fail if a new REPL/terminal-like lexer is added to Pygments but not referenced here.

Return type:: Iterator[type[Lexer]]

click_extra.pygments.LEXER_MAP: dict[type[Lexer], type[Lexer]] = {<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 session lexers to their ANSI-capable variants.

click_extra.pygments.EXTRA_ANSI_CSS: dict[str, str] = {'Blink': 'animation: ansi-blink 1s step-end infinite', 'Bold': 'font-weight: bold', 'Faint': 'opacity: 0.5', 'Italic': 'font-style: italic', 'Overline': 'text-decoration: overline', 'Reverse': 'filter: invert(1)', 'Strikethrough': 'text-decoration: line-through', 'Underline': 'text-decoration: underline'}¶

All SGR text attribute CSS declarations.

Maps Token.Ansi component names to CSS declarations. These are kept out of the Pygments style dict (_ANSI_STYLES) to prevent Furo’s dark-mode CSS generator from injecting color: #D0D0D0 fallbacks that conflict with foreground color tokens.

Used by AnsiHtmlFormatter.get_token_style_defs to inject CSS rules that both standalone pygmentize and Furo’s dark-mode CSS generator pick up.

class click_extra.pygments.AnsiHtmlFormatter(**kwargs)[source]¶

Bases: HtmlFormatter

HTML formatter with ANSI color and hyperlink support.

Extends Pygments’ HtmlFormatter to handle compound Token.Ansi.* tokens by decomposing them into individual CSS classes, augments the base style with ANSI color definitions for the 256-color indexed palette, and renders OSC 8 hyperlinks as HTML <a> tags.

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

Creates a new style instance that inherits from the one provided by the user, but updates its styles attribute with ANSI token definitions from _ANSI_STYLES.

name = 'ANSI HTML'¶: Full name for the formatter, in human-readable form.

aliases: ClassVar[list[str]] = ['ansi-html']¶: A list of short, unique identifiers that can be used to lookup the formatter from a list, e.g. using get_formatter_by_name().

format_unencoded(tokensource, outfile)[source]¶

Render tokens to HTML, converting OSC 8 link and 24-bit RGB markers to tags.

Replaces Token.AnsiLinkStart / Token.AnsiLinkEnd with Unicode Private Use Area markers, strips FG_/BG_ 24-bit RGB components from compound tokens and replaces them with PUA markers carrying the hex value, delegates to Pygments’ HTML rendering, then post-processes the output to swap markers for <a> and inline-styled  tags.

Return type:: None

get_token_style_defs(arg=None)[source]¶

Extend Pygments’ token CSS with rules for SGR attributes it cannot express.

Overriding get_token_style_defs (rather than get_style_defs) ensures that Furo’s dark-mode CSS generator, which calls this method directly, also picks up the extra rules built by _extra_ansi_css_lines.

get_ansi_style_defs(arg=None)[source]¶

Return only this formatter’s ANSI CSS, dropping Pygments’ base syntax-token rules.

The MkDocs plugin layers these over a theme’s own syntax highlighting, so it must not pull in the standard token rules (those would override the theme). Keeps the -Ansi-* token rules plus everything _extra_ansi_css_lines adds. Owning this selection here, next to the rules it returns, keeps the MkDocs plugin from hard-coding this formatter’s class names and CSS internals.

Return type:: str

click_extra.pytest module¶

Pytest fixtures and marks to help testing Click CLIs.

click_extra.pytest.runner()[source]¶

Runner fixture for click_extra.testing.CliRunner.

Pins HOME (and its platform-specific equivalents) to a subdirectory of the runner’s isolated filesystem so configuration-file discovery is deterministic and independent of the ambient environment. Without this, the handful of tests asserting on the config-search debug output depend on the caller’s HOME: hermetic builders set HOME=/homeless-shelter, which would otherwise leak into those assertions.

The environment is patched directly (via temporary_env()) rather than through the monkeypatch fixture on purpose: depending on monkeypatch here would tear it down after isolated_filesystem removed the working directory it tries to restore, breaking unrelated tests that chdir within the runner.

Warning

The pinning is scoped to each test requesting this fixture, but a cache filled from inside one is not: a module-global populated lazily during a test records what a home-less environment answered, and keeps serving that for the rest of the worker’s session. A binary resolved through a $HOME-dependent shim is the usual victim, answering an error rather than a version, after which every later test on that worker sees the tool as missing. Seed such a cache from a session-scoped fixture, which runs before the first test and outside this isolation.

click_extra.pytest.invoke(runner)[source]¶: Invoke fixture shorthand for click_extra.testing.CliRunner.invoke().

click_extra.pytest.isolated_app_dir(monkeypatch, tmp_path)[source]¶

Repoint configuration-file discovery at a fresh, empty directory.

The default --config search pattern derives from click.get_app_dir(), which resolves to the host configuration folder (~/Library/Application Support/<app> on macOS, ~/.config/<app> on Unix, %APPDATA%\<app> on Windows). Any configuration file living there bleeds into every in-process CLI invocation, making a test suite pass or fail depending on the developer’s personal configuration.

This fixture repoints get_app_dir (both click’s and the reference bound into click-extra’s config machinery) at a per-test temporary directory, whatever application name is requested. It returns that directory, so a test can also plant a configuration file in it to exercise the default discovery against a controlled file.

An explicit --config <path> bypasses the default search pattern and is left unaffected.

Note

The runner() fixture pins HOME and its platform equivalents inside an isolated filesystem, which also redirects the discovery paths built from the home directory — but only for tests requesting that fixture. This one intercepts get_app_dir directly, covering any in-process invocation, without touching HOME (a suite may need the real one elsewhere) and without leaking into subprocesses.

To make a whole suite hermetic, alias it to an autouse fixture in your conftest.py:

import pytest


@pytest.fixture(autouse=True)
def isolate_user_config(isolated_app_dir):
    return isolated_app_dir

click_extra.pytest.command_decorators(no_commands=False, no_groups=False, no_click=False, no_cloup=False, no_extra=False, with_parenthesis=True, with_types=False)[source]¶

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

Return type:

tuple[ParameterSet, ...]

Returns:

Pytest parameters covering each command-like decorator variant:

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()

click_extra.pytest.option_decorators(no_options=False, no_arguments=False, no_click=False, no_cloup=False, no_extra=False, with_parenthesis=True, with_types=False)[source]¶

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

Return type:

tuple[ParameterSet, ...]

Returns:

Pytest parameters covering each parameter-like decorator variant:

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()

click_extra.pytest.create_config(tmp_path)[source]¶: A generic fixture to produce a temporary configuration file.

click_extra.pytest.assert_output_regex()[source]¶

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

Designed for the regexes defined above.

click_extra.rst_to_myst module¶

Convert sphinx-apidoc RST output to MyST markdown.

Note

The converter handles only the narrow RST subset that sphinx-apidoc generates: section headings (title + underline), automodule directives with indented options, and structural headers like Submodules.

Autodoc directives cannot be used as native MyST directives because they perform internal rST nested parsing that requires an rST parser context only {eval-rst} provides. See MyST-Parser #587.

click_extra.rst_to_myst.convert_apidoc_rst_to_myst(content)[source]¶

Convert sphinx-apidoc RST to MyST markdown with {eval-rst} blocks.

Parameters:: content (str) – RST content produced by sphinx-apidoc.
Return type:: str
Returns:: Equivalent MyST markdown.

click_extra.rst_to_myst.convert_rst_files_in_directory(directory)[source]¶

Convert sphinx-apidoc RST files to MyST markdown in the given directory.

For each .rst file containing .. automodule:: directives:

If a .md file with the same stem exists, delete the .rst (the existing markdown takes precedence).
Otherwise, convert the RST content to MyST and write a .md file, then delete the .rst.

Parameters:: directory (Path) – Directory to scan for .rst files.
Return type:: list[Path]
Returns:: List of newly created .md file paths.

click_extra.screenshot module¶

Width a capture is taken and rendered at, see AUTO_COLUMNS.

click_extra.screenshot.TColumns: TypeAlias = int | typing.Literal['auto']¶: Width a capture is taken and rendered at, see AUTO_COLUMNS.

class click_extra.screenshot.CaptureFormat(*values)[source]¶

Bases: Enum

Document formats a capture can be rendered to.

The value doubles as the file extension format_from_path() matches on.

HTML = 'html'¶

Selectable, searchable text in a self-contained <pre>.

Built on ansi_to_html(), so it needs no extra.

SVG = 'svg'¶

A picture of a terminal window, for a surface that strips inline HTML.

Laid out on a character grid by render_svg().

class click_extra.screenshot.CaptureBackground(*values)[source]¶

Bases: Enum

Terminal chrome a capture is drawn on.

A capture freezes the colors of the run it pictures, so the chrome has to answer to the palette that run was colored for. Neither direction survives the other: a screen colored for a dark terminal is unreadable on white, and click-extra’s own light and manpage themes wash out on the dark chrome a renderer defaults to.

The value doubles as the --background choice the CLI offers.

DARK = 'dark'¶: What a terminal, and this package’s default theme, usually look like.

LIGHT = 'light'¶: For a CLI rendered with a light-background theme.

click_extra.screenshot.DEFAULT_PRESET = ('No terminal at all', ((), ''), 0, '$', "'Fira Code', 'Cascadia Code', Menlo, Consolas, monospace", ('#292929', '#c5c8c6', ('#2e3436', '#cc0000', '#4e9a06', '#c4a000', '#3465a4', '#75507b', '#06989a', '#d3d7cf', '#555753', '#ef2929', '#8ae234', '#fce94f', '#729fcf', '#ad7fa8', '#34e2e2', '#eeeeec'), '#292929'), ('#ffffff', '#000000', ('#2e3436', '#cc0000', '#4e9a06', '#c4a000', '#3465a4', '#75507b', '#06989a', '#d3d7cf', '#555753', '#ef2929', '#8ae234', '#fce94f', '#729fcf', '#ad7fa8', '#34e2e2', '#eeeeec'), '#ffffff'))¶

Terminal a capture with no --preset is drawn as.

plain mimics no desktop, which is what a capture wearing no decoration should resolve its colors against. Naming it here is what keeps the two formats looking like the same terminal, and keeps one catalog answering for every palette a capture can use: without it the default colors would be a second set of literals free to drift from the one the presets publish.

click_extra.screenshot.CAPTURE_PALETTES: dict[CaptureBackground, TerminalPalette] = {CaptureBackground.DARK: ('#292929', '#c5c8c6', ('#2e3436', '#cc0000', '#4e9a06', '#c4a000', '#3465a4', '#75507b', '#06989a', '#d3d7cf', '#555753', '#ef2929', '#8ae234', '#fce94f', '#729fcf', '#ad7fa8', '#34e2e2', '#eeeeec'), '#292929'), CaptureBackground.LIGHT: ('#ffffff', '#000000', ('#2e3436', '#cc0000', '#4e9a06', '#c4a000', '#3465a4', '#75507b', '#06989a', '#d3d7cf', '#555753', '#ef2929', '#8ae234', '#fce94f', '#729fcf', '#ad7fa8', '#34e2e2', '#eeeeec'), '#ffffff')}¶

Colors each chrome resolves a capture’s ANSI codes against.

A palette carries the 16 ANSI colors alongside the background and foreground, which is the other half of the job: a CLI naming blue leaves the shade to whoever draws it, and the one that reads on white is not the one that reads on #292929.

click_extra.screenshot.CAPTURE_BACKGROUND = '#292929'¶

Background a dark capture is drawn on.

Stating it is not optional: a help screen colored for a dark terminal is unreadable on a page that defaults to white.

click_extra.screenshot.CAPTURE_FOREGROUND = '#c5c8c6'¶: Color of the text a dark capture leaves unstyled. See CAPTURE_BACKGROUND.

click_extra.screenshot.LIGHT_CAPTURE_BACKGROUND = '#ffffff'¶

Background a light capture is drawn on.

See CAPTURE_BACKGROUND: an SVG and an HTML capture of the same run have to look like the same terminal.

click_extra.screenshot.LIGHT_CAPTURE_FOREGROUND = '#000000'¶

Color of the text a light capture leaves unstyled.

See LIGHT_CAPTURE_BACKGROUND.

click_extra.screenshot.PROMPT_THEMES: dict[CaptureBackground, HelpTheme | None] = {CaptureBackground.DARK: None, CaptureBackground.LIGHT: HelpTheme(invoked_command=Style(fg='black', bold), command_help=<function identity>, heading=Style(fg='magenta', underline), constraint=Style(fg='magenta'), section_help=<function identity>, col1=<function identity>, col2=<function identity>, alias=Style(fg='blue', bold), alias_secondary=Style(fg='blue', bold, dim), epilog=<function identity>, critical=Style(fg='red', bold), error=Style(fg='red'), warning=Style(fg='magenta'), info=<function identity>, debug=Style(fg='blue', dim), option=Style(fg='blue', bold), subcommand=Style(fg='blue', bold), choice=Style(fg='magenta', bold), metavar=Style(fg='blue', dim, italic), bracket=Style(dim), envvar=Style(fg='magenta', dim), default=Style(fg='green', dim, italic), range_label=Style(fg='blue', dim), required=Style(fg='red', dim), argument=Style(fg='blue', italic), deprecated=Style(fg='red'), search=Style(fg='green'), success=Style(fg='green'), cross_ref_highlight=True, subheading=Style(fg='blue', dim))}¶

Theme the prompt line is drawn with, per chrome.

The captured output arrives already colored by the CLI that produced it, under whatever theme that run was told to use. The prompt is the one line this process draws itself, so it is the one that would otherwise land on white chrome in the dark default’s near-white invoked_command style, invisible.

None keeps whatever theme the invocation already runs under. So does a missing entry: the mapping is read through dict.get(), and BUILTIN_THEMES is empty when a trimmed install drops themes.toml.

click_extra.screenshot.NO_PAINT = 'none'¶

Border or shadow value asking for none to be drawn.

SVG’s own keyword for an absent paint, so it reaches the stroke attribute unchanged, and CSS’s for an absent shadow.

click_extra.screenshot.OPAQUE = 1.0¶

Opacity of a window showing nothing of what sits behind it.

Anything under it is what a terminal calls transparency: the backdrop, or the page embedding the capture, comes through the window’s body while its text, frame and title bar stay as they are. 0.0 leaves the text alone on the page.

click_extra.screenshot.CAPTURE_BORDERS: dict[CaptureBackground, str] = {CaptureBackground.DARK: 'rgba(255,255,255,0.35)', CaptureBackground.LIGHT: 'rgba(0,0,0,0.25)'}¶

Color the window frame is drawn in, per chrome.

The dark entry is a translucent white that reads against #292929 and against nothing else: a light capture framed with it is a white window on a white page, the shape of the terminal only guessable from its text. Each chrome names a frame its own background can show.

click_extra.screenshot.CAPTURE_SHADOWS: dict[CaptureBackground, str] = {CaptureBackground.DARK: 'rgba(0,0,0,0.5)', CaptureBackground.LIGHT: 'rgba(0,0,0,0.25)'}¶

Color the window’s drop shadow floods with, per chrome.

Where the frame states the window’s edge, the shadow lifts it off whatever page embeds the capture, which is the other half of not dissolving into it. A reader whose renderer drops the filter still gets the frame.

click_extra.screenshot.WATERMARK_INK = 'rgba(128,128,128,0.85)'¶

Color the credit line is drawn in.

The one paint in a capture that answers to neither chrome, because it is the one thing drawn outside the window: the margin is transparent, so the mark sits on whatever page embeds the image, which the capture never gets to see. A white mark suits the dark chrome it was picked for and disappears on a README; a neutral gray reads on both, and dims into a backdrop when one is painted.

click_extra.screenshot.DEFAULT_BORDER_WIDTH = 1¶: Thickness, in pixels, of the frame drawn around the window.

click_extra.screenshot.TITLEBAR_HEIGHT = 40¶

Height, in pixels, of the strip a title and its buttons sit in.

The padding a renderer leaves above the text, which is what a window’s chrome occupies. Restated here because a capture wearing neither decoration nor caption drops the strip, and one drawn as a real terminal paints it.

click_extra.screenshot.DEFAULT_RADIUS = 8¶

How round the window’s corners are, in pixels.

The radius a renderer draws on its own, which is what a terminal on a desktop looks like. Zero squares them, for a capture meant to read as a plain block.

click_extra.screenshot.SHADOW_BLUR = 6¶: Standard deviation, in pixels, of the drop shadow’s blur.

click_extra.screenshot.SHADOW_OFFSET = 3¶: Downward offset, in pixels, of the drop shadow.

click_extra.screenshot.CSS_SIDE_ANGLES = {'to bottom': 180.0, 'to bottom left': 225.0, 'to bottom right': 135.0, 'to left': 270.0, 'to left bottom': 225.0, 'to left top': 315.0, 'to right': 90.0, 'to right bottom': 135.0, 'to right top': 45.0, 'to top': 0.0, 'to top left': 315.0, 'to top right': 45.0}¶

Angle each CSS side keyword names, in degrees clockwise from to top.

to bottom is what a gradient opening with no direction at all means, which is why it doubles as the default. See gradient_svg().

click_extra.screenshot.DEFAULT_MARGIN = 48¶

Transparent pixels left around the window, on all four sides.

Room for the shadow to fall into, first of all: a filter draws outside the shape it is applied to, and anything past the image’s own box is cut. It is also what a backdrop has to show through, and what keeps the window from touching the text of the page embedding it.

click_extra.screenshot.DEFAULT_PADDING = 8¶

Pixels added inside the window, around the captured text.

On top of the few a renderer adds on its own (8, and 40 above for the title bar), which leaves a help screen’s first column tight against the frame.

click_extra.screenshot.TITLE_SIZE = 18¶: Height, in pixels, of the caption drawn in a window’s title bar.

click_extra.screenshot.WATERMARK_SIZE = 13¶

Height, in pixels, of the credit line’s glyphs.

Below the terminal’s own text, since a mark competing with the screen it credits is a mark in the way.

click_extra.screenshot.WATERMARK_INSET = 12¶

Pixels between the credit line and the image’s bottom-right corner.

It is drawn in the margin, the one band of a capture that carries nothing else. A capture shot with margin=0 has no such band, and the line lands on the window’s own corner instead of beside it.

click_extra.screenshot.DEFAULT_WATERMARK = 'generated with click-extra 9.0.0'¶

Credit line every capture carries unless another one, or none, is asked for.

A capture travels: it lands on a slide, in a README, on a social card, far from the page that explains where it came from. The mark is what still says so, and names the release that drew it, so a reader can tell an image shot two years ago from one shot today.

Note

This is a default, not a fixture. --watermark "" draws none, and any other text replaces it: a project crediting itself rather than its tooling is the expected case, not an exception.

click_extra.screenshot.CAPTURE_TERMINAL_HINTS: dict[CaptureBackground, dict[str, str]] = {CaptureBackground.DARK: {'CLITHEME': 'dark', 'COLORFGBG': '15;0'}, CaptureBackground.LIGHT: {'CLITHEME': 'light', 'COLORFGBG': '0;15'}}¶

Environment a terminal of each chrome would carry, handed to the command.

A capture is a terminal simulated for a command that cannot see one: its width is pinned and its colors forced, because a pipe would have it wrap to a guess and print none. Its background is the third thing a terminal states and a pipe does not, through the two variables resolve_background() reads: the cli-theme CLITHEME, and COLORFGBG carrying foreground;background palette indices.

So a CLI asking for –theme auto renders for the chrome its picture is drawn on, instead of falling back to dark inside a light window. A CLI that never asks is unaffected: the variables only answer a question it does not put.

click_extra.screenshot.CAPTURE_FONT_STACK = "'Fira Code', 'Cascadia Code', Menlo, Consolas, monospace"¶

Monospaced fonts a capture asks for, best first.

Nothing is embedded and nothing is fetched, so both formats set the text in the first family the reader already has, and a capture renders the same offline, on a page forbidding third-party requests, and in a viewer that speaks no CSS @font-face.

Family names are single-quoted on purpose: this lands in a double-quoted style attribute, which a double quote here would terminate early.

click_extra.screenshot.CELL_HEIGHT = 20.0¶: Height of one glyph cell, in pixels, which is also the text’s font size.

click_extra.screenshot.FONT_ASPECT_RATIO = 0.61¶

Width-to-height ratio of the font a capture is laid out for.

Fira Code’s, the first family CAPTURE_FONT_STACK asks for. Every monospaced fallback behind it is close enough that the grid holds, and textLength pins each run to its columns for the ones that are not.

click_extra.screenshot.CELL_WIDTH = 12.2¶: Width of one glyph cell, in pixels. One character of a monospaced terminal.

click_extra.screenshot.LINE_HEIGHT = 24.4¶: Vertical distance between two consecutive text baselines, in pixels.

click_extra.screenshot.CELL_BLEED = 0.25¶

Pixels a cell’s background is grown by, past the line it belongs to.

Two rectangles meeting on an exact boundary leave a hairline of page showing through when a renderer rounds their edges to different pixels. Overlapping them slightly is what closes that seam, and is invisible because the color painted twice is the same color.

click_extra.screenshot.CELL_TOP_INSET = 1.5¶

Pixels between a line’s top edge and the cell backgrounds drawn on it.

A glyph does not fill its line box: the leading sits above the tallest letter. Starting the paint just under that keeps a highlighted run reading as one block of color rather than as a band taller than the text it marks.

click_extra.screenshot.TILE_RUN = 8¶

Cells of tiling characters drawn before their offset is restated.

Small enough that a font whose tiles are a fraction of a pixel off the grid cannot drift a visible amount before the next offset resets it, and large enough that a table’s rule stays a handful of elements rather than one per cell. See tile_runs().

click_extra.screenshot.DIM_RATIO = 0.4¶: How far a dim run’s ink is mixed toward the background, see blend().

click_extra.screenshot.RTL_BIDI_CLASSES = frozenset({'AL', 'AN', 'R'})¶

Unicode bidirectional classes written right to left.

Right-to-left letters, Arabic letters and Arabic-Indic numbers, as unicodedata.bidirectional() names them. See is_bidirectional().

click_extra.screenshot.WINDOW_PADDING = 8¶

Pixels every window keeps between its frame and its text, on three sides.

The fourth is the top, where TITLEBAR_HEIGHT answers instead. This is the window’s own breathing room, before the padding a capture may ask for on top.

click_extra.screenshot.WINDOW_INSET = 1¶

Pixels between the image’s edge and the window’s frame.

A stroke straddles the shape it outlines, so a frame drawn flush with the viewBox loses its outer half to the crop. Inset by more than that half and the whole line shows.

click_extra.screenshot.AUTO_COLUMNS: Literal['auto'] = 'auto'¶

Width asking for the one the captured text itself decides.

Neither end of the pipeline is pinned: the command wraps to whatever terminal it finds (Click’s own 80 when that is a pipe, or a documentation build), and the image is laid out at the longest line that came back, see fit_columns(). Nothing the command printed folds inside the picture then, which is what a line the command does not wrap on its own needs: a prompt, a wide table, a machine-readable dump.

The cost is that the picture stops being a fixed-width terminal, so a capture meant to sit beside others at the same width should name that width instead.

click_extra.screenshot.DEFAULT_COLUMNS = 80¶

Terminal width a capture is taken at, in characters.

Both ends of the pipeline have to agree on it: the command wraps its output to this width, and the renderer lays the image out at the same one. Let them disagree and the rendered lines overrun the image. 80 is the width Click itself falls back to off a terminal, which makes it the value a capture lands on by accident anyway.

click_extra.screenshot.MIN_COLUMNS = 20¶

Narrowest width a capture is rendered at.

A floor on AUTO_COLUMNS as much as on an explicit width: a command printing nothing but blank lines would otherwise ask for an image no glyph fits in.

click_extra.screenshot.LINE_NUMBER_SEPARATOR = ' │ '¶

Rule drawn between a line’s number and the line itself.

A vertical bar rather than a bare space, so the gutter reads as a column of its own even where the output is itself indented.

click_extra.screenshot.DEFAULT_TRUNCATION = '[...]'¶: Marker standing in for the lines trim_lines() cut away.

click_extra.screenshot.PADDING = ' \xa0'¶

Characters separating one column of a capture from the next.

render_svg() emits every space as a non-breaking one, so the padding survives an XML round-trip and no renderer collapses a run of them.

click_extra.screenshot.number_lines(text, start=1)[source]¶

Prefix each line of text with its number, in a dim gutter.

The numbers are drawn into the terminal text rather than into a column of the image, which is the same trade Pygments makes with its inline line numbers: every renderer places them for free, and every reader copying the capture copies them too.

Right-aligned on the widest number, so the gutter is one column whatever the output’s length, and separated by LINE_NUMBER_SEPARATOR.

Parameters:

text (str) – captured output, ANSI escape sequences included.
start (int) – number given to the first line.

Return type:

CompletedProcess[str]

Returns:

the numbered text.

click_extra.screenshot.preset_palette(preset, background)[source]¶

The colors a preset shows on the given chrome.

Return type:: TerminalPalette

click_extra.screenshot.resolve_palette(preset, background)[source]¶

The colors a capture resolves its ANSI codes against.

The preset’s palette on the given chrome, or the default terminal’s (CAPTURE_PALETTES) when no preset dresses the capture. The one resolution rule shared by render() and render_html(), so the two formats cannot disagree on what a chrome looks like.

Return type:: TerminalPalette

click_extra.screenshot.is_bidirectional(text)[source]¶

Whether text carries a character written right to left.

Arabic, Hebrew and their neighbours are reordered by whoever draws them, and the cursive ones are shaped: a letter’s form depends on what it joins. A terminal grid describes neither, which is why render_svg() stops pinning such a run to an exact width.

Parameters:: text (str) – the text to inspect.
Return type:: bool
Returns:: True when at least one character is right-to-left.

click_extra.screenshot.cell_width(text)[source]¶

Columns text occupies on a terminal’s character grid.

Not its length: a CJK ideograph is drawn two cells wide, a combining mark none at all. wcwidth.wcswidth() answers for both, and returns -1 for a string carrying a control character, where the count of characters is the closest thing to an answer left.

Parameters:: text (str) – the text to measure.
Return type:: int
Returns:: the number of cells it occupies.

click_extra.screenshot.fit_columns(text)[source]¶

Width, in characters, of the longest line in text.

ANSI escapes are stripped first: they style the glyphs around them and occupy no cell of their own. Measured in terminal cells, so a line of CJK asks for the two columns per glyph it is drawn with. Floored at MIN_COLUMNS.

Parameters:: text (str) – captured output, ANSI escape sequences included.
Return type:: int
Returns:: the width laying every line out without folding any.

click_extra.screenshot.capture_output(args, *, columns=80, background=CaptureBackground.DARK, merge_stderr=False, timeout=None)[source]¶

Run a command and capture its output, ANSI escape sequences and all.

A command whose output is a pipe rather than a terminal strips its own colors, and wraps to whatever width it can guess. Both are pinned here: forced_color() sets the FORCE_COLOR lever every mainstream color system obeys and clears any opt-out the environment carries, while COLUMNS fixes the width the command wraps to.

Only stdout is captured by default. That is what keeps a capture free of the progress lines and build chatter a wrapper like uv writes to stderr, with no shell redirection to remember.

Parameters:

args (str | Path | None | Iterable[str | Path | None | Iterable[Iterable[str | Path | None | Iterable[TNestedArgs]]]]) – the command line, in the nested form run_cli() accepts.
columns (int | Literal['auto']) – terminal width, in characters, the command wraps its output to. AUTO_COLUMNS pins nothing and lets the command find its own.
background (CaptureBackground) – chrome the capture is headed for, stated to the command the way a terminal would, see CAPTURE_TERMINAL_HINTS.
merge_stderr (bool) – fold stderr into the captured output, for a command printing its help there.
timeout (float | None) – seconds before the command is killed. None waits forever.

Return type:

Returns:

the completed process, whose stdout holds the captured text.

click_extra.screenshot.trim_lines(text, *, head=None, tail=None, truncation='[...]')[source]¶

Keep only the first head and last tail lines of text.

Whatever is dropped is replaced by a single truncation line, so the image admits that it was cut rather than pretending to be the whole output. Text short enough to survive both bounds comes back untouched, with no marker.

Parameters:

text (str) – the captured output.
head (int | None) – number of leading lines to keep, or None for no head bound.
tail (int | None) – number of trailing lines to keep, or None for no tail bound.
truncation (str) – line standing in for what was cut.

Return type:

Returns:

the trimmed text.

click_extra.screenshot.palette_color(color, palette)[source]¶

Resolve any color a Style carries to a hex string.

The 16 named and indexed ANSI slots are not colors, they are names: a terminal decides what its red looks like, and a capture has no terminal, so they answer to palette. Every other form a style can carry (a 24-bit triplet, a 256-cube index, a hex string) already states its own color and passes through.

Parameters:

color (object) – the value to resolve, as Style holds it.
palette (TerminalPalette) – the terminal colors to resolve names against.

Return type:

Returns:

the color, as #rrggbb.

Raises:

ValueError – when the value names no color.

click_extra.screenshot.blend(color, into, ratio)[source]¶

Mix color toward into, the way a terminal fades dim text.

SVG has no dim, and thinning the glyphs with opacity would let whatever sits behind the capture show through them. Mixing the two colors up front keeps the text opaque and lands the same shade.

Parameters:

color (str) – the color to fade, as #rrggbb.
into (str) – the color to fade it toward, usually the background.
ratio (float) – how far to go, from 0.0 (unchanged) to 1.0 (into).

Return type:

Returns:

the blended color, as #rrggbb.

click_extra.screenshot.grid(text, columns)[source]¶

Lay ANSI text out on a terminal’s character grid.

The one place a capture stops being a stream and becomes a picture. Each styled run of split_ansi() is split at newlines into rows, then placed on the column it starts at, measured in cells rather than characters so a wide glyph takes the two it is drawn with.

A line reaching past columns soft-wraps onto the next row, the way it would on a terminal that narrow, rather than being cropped: a command is free to print a line it never wraps itself (a long URL, a wide table, a machine-readable dump), and a picture that silently swallowed the overflow would be lying about what ran. A glyph straddling the edge moves down whole.

Returning the column with each run is what lets render_svg() place a run without measuring anything back out of its own output.

Parameters:

text (str) – captured output, ANSI escape sequences included.
columns (int) – width of the grid, in cells.

Return type:

list[list[tuple[Style, str, int]]]

Returns:

one list of (style, text, column) runs per row.

click_extra.screenshot.gradient_svg(value, unique_id, width, height)[source]¶

Translate a CSS gradient into the paint server SVG draws it with.

An SVG fill takes a paint: a color, or a reference to a gradient declared as an element of its own. The syntax a page’s CSS carries, linear-gradient(135deg, #ff9a9e, #fad0c4), means nothing to it, and a capture handed one would come out unpainted. So the CSS is read here and re-emitted as the element SVG does understand, which is what lets the same --backdrop value serve both formats.

Understood: linear-gradient opening with an optional angle (135deg) or side keyword (to bottom right, see CSS_SIDE_ANGLES), and radial-gradient, both followed by two or more color stops, each pinnable at a percentage. Anything else returns None and is left alone, being a plain color as far as this is concerned.

The gradient is placed in user space, which is what makes it exact rather than approximated: the CSS line runs through the image’s center at the given angle, and is as long as the box measures along it (|W·sinθ| + |H·cosθ|), while a radial one reaches the farthest corner.

Parameters:

value (str) – the --backdrop value, gradient or not.
unique_id (str) – identifier the paint server is declared under.
width (float) – width of the image the gradient fills, in pixels.
height (float) – its height.

Return type:

tuple[str, str] | None

Returns:

the <defs> markup and the fill value referencing it, or None when the value is not a gradient this understands.

click_extra.screenshot.titlebar_strip(left, top, width, *, paint, radius)[source]¶

Paint the strip a terminal seats its title and buttons in.

A capture leaves that strip the color of the terminal itself, where a real window carries a chrome of its own: the strip is what a reader’s eye reads as the top of a window rather than as the first line of output.

Drawn as a path rather than a rectangle because only its top corners follow the window’s own rounding; the bottom two meet the text and stay square.

Parameters:

left (float) – where the window starts, in pixels.
top (float) – where the window starts vertically, in pixels.
width (float) – how wide the window is, in pixels.
paint (str) – color to fill the strip with.
radius (int) – the window’s corner radius, in pixels.

Return type:

Returns:

the SVG markup.

click_extra.screenshot.watermark_svg(text, *, width, height, paint, font_stack="'Fira Code', 'Cascadia Code', Menlo, Consolas, monospace")[source]¶

Draw the credit line in the image’s bottom-right corner.

Placed in the margin rather than over the terminal, which is what keeps it from covering a line of output: a capture is a picture of text, and a mark crossing that text costs the reader the thing being shown.

Carries a watermark class, so a reader taking a capture apart can tell the one run the renderer never captured from the ones it did.

Parameters:

text (str) – the credit to draw. Empty draws nothing.
width (float) – width of the whole image, in pixels.
height (float) – its height, in pixels.
paint (str) – color to draw the text in, alpha included.
font_stack (str) – fonts it is set in, the capture’s own.

Return type:

Returns:

the SVG markup, empty when there is nothing to draw.

click_extra.screenshot.window_buttons(buttons, *, width, color, font_stack="'Fira Code', 'Cascadia Code', Menlo, Consolas, monospace")[source]¶

Draw a title bar’s decorations, as the terminal being mimicked draws them.

Two conventions, and a window carries one or the other: macOS fills round buttons on the left, Windows and GNOME set glyphs against the right edge. Both are placed in the window’s own coordinates, so they follow it wherever the frame moves it.

Parameters:

buttons (WindowButtons) – which decorations to draw.
width (float) – width of the window they are drawn in, in pixels.
color (str) – paint for the glyphs. Circles carry their own.
font_stack (str) – fonts the glyphs are set in, the window’s own.

Return type:

Returns:

the SVG markup, empty when the window wears none.

click_extra.screenshot.column_segments(text, column)[source]¶

Cut a run of text into the columns it actually occupies.

A run carries its own padding: a help screen’s –count INTEGER Number of greetings. is one styled run holding two columns and the gutter between them. Drawn as a single element, the second column only lands where it belongs if the renderer honors textLength and resolves the font, because the gutter’s width is being paid for in glyphs. librsvg does neither, and the columns collapse onto each other.

Cutting the run at its gutters and giving each piece its own offset asks nothing of the renderer but to draw glyphs at coordinates.

Parameters:

text (str) – the run’s text, padding included.
column (int) – the terminal column the run starts on.

Return type:

Iterator[tuple[str, int]]

Returns:

each column’s text, with the column it starts on.

click_extra.screenshot.tile_runs(text, column)[source]¶

Break a column’s text into the pieces drawn as one element each.

Ordinary text is one piece: the renderer lays it out and textLength holds the result to the width it occupies.

Text carrying a tile (_TILING_RE) is cut into groups of at most TILE_RUN cells, each landing on a stated offset. A <text> element is the smallest thing some renderers position at all: librsvg (and through it rsvg-convert and ImageMagick) honors the first x of an element and then lays every following glyph out at the font’s own advance, ignoring both textLength and any further x. A rule of 75 tiles drawn a tenth of a pixel narrow therefore ends a whole cell short of the │ below it, and the table’s corners miss. Restating the offset every few cells bounds that error to well under a pixel, whatever the font, and costs a tile nothing since none of them ligate.

Parameters:

text (str) – the column’s text.
column (int) – the terminal column it starts on.

Return type:

Iterator[tuple[str, int]]

Returns:

each piece, with the column it starts on.

click_extra.screenshot.glyph_offsets(text, column)[source]¶

Place a piece of text on the grid, as the attributes SVG reads.

A right-to-left piece is pinned by its offset alone: it is reordered and shaped by whoever draws it, and holding it to a width fights that.

Parameters:

text (str) – the piece’s glyphs.
column (int) – the terminal column it starts on.

Return type:

Returns:

the x attribute, and a textLength where one applies.

click_extra.screenshot.style_rules(style, palette)[source]¶

Compile a style to the CSS an SVG text run is drawn with.

Parameters:

style (Style) – the run’s style, as split_ansi() yields it.
palette (TerminalPalette) – the terminal colors to resolve names against.

Return type:

Returns:

the CSS declarations, semicolon-separated.

click_extra.screenshot.run_paint(style, palette)[source]¶

The color painted behind a run, or None where it shows the terminal’s own.

Parameters:

style (Style) – the run’s style.
palette (TerminalPalette) – the terminal colors to resolve names against.

Return type:

str | None

Returns:

the background color, as #rrggbb, or None to paint nothing.

click_extra.screenshot.render_svg(text, *, columns, title='', unique_id=None, palette=('#292929', '#c5c8c6', ('#2e3436', '#cc0000', '#4e9a06', '#c4a000', '#3465a4', '#75507b', '#06989a', '#d3d7cf', '#555753', '#ef2929', '#8ae234', '#fce94f', '#729fcf', '#ad7fa8', '#34e2e2', '#eeeeec'), '#292929'), font_stack="'Fira Code', 'Cascadia Code', Menlo, Consolas, monospace", border='none', border_width=1, radius=8, backdrop='none', shadow='none', margin=0, padding=0, buttons=(('#ff5f57', '#febc2e', '#28c840'), ''), buttons_color=None, titlebar='none', collapse_titlebar=False, opacity=1.0, watermark='', watermark_color='rgba(128,128,128,0.85)')[source]¶

Draw captured terminal text as a picture of a terminal window.

A terminal is a fixed grid of identically-sized cells, which is what makes this arithmetic rather than typesetting: grid() says which cell each run of same-styled characters starts on, and every coordinate below is that column times CELL_WIDTH.

Two primitives draw everything. A <rect> fills the cells behind a run that carries a background, and a <text> draws its glyphs, pinned to its columns with textLength so the layout survives a reader who does not have the font.

Note

A run’s padding is left out of its <text> and paid for in the x offset instead. Written the other way, a column only lands where it belongs if the glyphs are exactly the width assumed here, which asks the renderer to both honor textLength and resolve the font. A web browser does both. librsvg (and through it rsvg-convert and ImageMagick) ignores textLength, and a file manager, a git client or a thumbnailer commonly falls back to a proportional font. Starting each run on its own column asks neither.

Parameters:

text (str) – captured output, ANSI escape sequences included.
columns (int) – width of the terminal, in characters.
title (str) – caption drawn in the window’s title bar. Empty draws none.
unique_id (str | None) – prefix namespacing this document’s CSS classes and element IDs, see render(). Derived from the content when not given.
palette (TerminalPalette) – terminal colors the capture’s ANSI codes resolve against.
font_stack (str) – fonts the text is set in, best first.
border (str) – paint for the window’s frame. NO_PAINT draws none.
border_width (int) – thickness of that frame, in pixels.
radius (int) – how round the window’s corners are, in pixels.
backdrop (str) – paint filling the whole image, margin included, or a CSS gradient, see gradient_svg(). NO_PAINT leaves it transparent.
shadow (str) – color the window’s drop shadow floods with.
margin (int) – transparent pixels left around the window, on all four sides.
padding (int) – pixels added inside the window, around the text.
buttons (WindowButtons) – decorations drawn in the title bar.
buttons_color (str | None) – paint for the glyph decorations. Circles carry their own colors. None takes the palette’s foreground.
titlebar (str) – paint for the strip the title and buttons sit in. NO_PAINT leaves it the terminal’s own color.
collapse_titlebar (bool) – drop that strip, closing the window over the first line of text. For a capture wearing neither decoration nor caption.
opacity (float) – how solid the window’s body is, from OPAQUE down to 0.0. Only the body thins out: the frame, the title bar and the text keep their own paint.
watermark (str) – credit line drawn in the image’s bottom-right corner.
watermark_color (str) – color that line is drawn in, alpha included.

Return type:

Returns:

the SVG source.

click_extra.screenshot.render_html(text, *, title='', full=True, background=CaptureBackground.DARK, preset=None, border='none', border_width=1, radius=8, backdrop='none', shadow='none', margin=0, padding=0, buttons=None, buttons_color='#c5c8c6', font_stack="'Fira Code', 'Cascadia Code', Menlo, Consolas, monospace", titlebar='none', collapse_titlebar=False, opacity=1.0, watermark='', watermark_color='rgba(128,128,128,0.85)')[source]¶

Render captured terminal text to HTML.

The <pre> carries its own inline styling, so a fragment pasted into an existing page needs no stylesheet and cannot be restyled out of legibility by the host. Nothing else is needed either: a <pre> preserves the capture’s own spacing, which is what spares HTML the column arithmetic render_svg() performs for a picture.

Caution

The text is escaped before its ANSI is translated, the order click_extra.table uses for its html format. Skip it and any < a CLI prints opens a tag: click-extra’s own --export-config help says it writes to <stdout>.

Note

An OSC 8 hyperlink loses its URL and keeps its visible text: the escape is dropped rather than turned into an <a>.

Parameters:

text (str) – captured output, ANSI escape sequences included.
title (str) – <title> of the document. Ignored for a fragment.
full (bool) – wrap the <pre> in a standalone document. False returns the <pre> alone, to paste into a page that has its own.
background (CaptureBackground) – chrome to draw on, see CaptureBackground.
border (str) – color of the block’s frame, see render_svg().
border_width (int) – thickness of that frame, in pixels.
radius (int) – how round the block’s corners are, in pixels.
backdrop (str) – paint filling the page behind the block.
shadow (str) – color of the block’s drop shadow, see render_svg().
margin (int) – pixels left around the block, on all four sides.
padding (int) – pixels added inside the block, on top of its own.
buttons (WindowButtons | None) – ignored. HTML reflows with the page embedding it, so it carries the text and its colors, not a window drawn around them.
buttons_color (str) – ignored, see buttons.
titlebar (str) – ignored, see buttons.
collapse_titlebar (bool) – ignored, see buttons.
opacity (float) – how solid the block’s background is, from OPAQUE down to 0.0, where the page shows straight through the text.
watermark (str) – credit line drawn under the block, against its right edge, where an SVG draws it in the margin. Empty draws none.
watermark_color (str) – color that line is drawn in, alpha included.

Return type:

Returns:

the rendered markup.

click_extra.screenshot.render(text, *, format=CaptureFormat.SVG, columns=80, title='', unique_id=None, full=True, background=CaptureBackground.DARK, preset=None, border=None, border_width=1, radius=None, backdrop='none', shadow=None, margin=48, padding=8, opacity=1.0, watermark='generated with click-extra 9.0.0', watermark_color=None)[source]¶

Render captured terminal text to the document format names.

Parameters:

text (str) – captured output, ANSI escape sequences included.
format (CaptureFormat) – which document to produce.
columns (int | Literal['auto']) – terminal width, in characters, an SVG is laid out at, or AUTO_COLUMNS for the width its own longest line asks for. HTML reflows, so it ignores this.
title (str) – caption drawn in an SVG’s window chrome, or an HTML document’s <title>.
unique_id (str | None) – SVG only. Prefix namespacing the source’s CSS classes and element IDs. Pinning it to something stable (the output file’s name, say) keeps a regenerated capture diffing line by line, instead of renaming every class as soon as a single character of output changes. Characters a CSS class name cannot carry are folded to a dash.
full (bool) – HTML only. See render_html().
background (CaptureBackground) – chrome to draw on, see CaptureBackground.
border (str | None) – color of the window’s frame. None takes the one the chrome can show, see CAPTURE_BORDERS; NO_PAINT draws none.
border_width (int) – thickness of that frame, in pixels.
radius (int | None) – how round the window’s corners are, in pixels. Zero squares them.
backdrop (str) – paint filling the image behind the window, margin included. NO_PAINT leaves it transparent.
shadow (str | None) – color of the window’s drop shadow. None takes the chrome’s own, see CAPTURE_SHADOWS; NO_PAINT draws none.
margin (int) – transparent pixels left around the window, on all four sides.
padding (int) – pixels added inside the window, around the text.
opacity (float) – how solid the window’s body is, from OPAQUE down to 0.0. Below it, whatever the capture is laid over shows through.
watermark (str) – credit line drawn in the image’s bottom-right corner, see DEFAULT_WATERMARK. An empty string draws none.
watermark_color (str | None) – color that line is drawn in. None takes WATERMARK_INK, which reads on a page of either color.

Return type:

Returns:

the rendered document.

Raises:

ImportError – rendering SVG without the screenshot extra installed.

click_extra.screenshot.capture(args, *, format=CaptureFormat.SVG, columns=80, prompt=None, head=None, tail=None, truncation='[...]', merge_stderr=False, timeout=None, line_numbers=False, title='', unique_id=None, full=True, background=CaptureBackground.DARK, preset=None, border=None, border_width=1, radius=None, backdrop='none', shadow=None, margin=48, padding=8, opacity=1.0, watermark='generated with click-extra 9.0.0', watermark_color=None)[source]¶

Run a command and render its output as a document.

Chains capture_output(), trim_lines() and render(). The invocation is drawn above the output as a shell prompt, styled by the active theme through format_cli_prompt(), so the capture shows what to type to reproduce it.

Parameters:

args (str | Path | None | Iterable[str | Path | None | Iterable[Iterable[str | Path | None | Iterable[TNestedArgs]]]]) – the command line to run.
format (CaptureFormat) – which document to produce.
columns (int | Literal['auto']) – terminal width, in characters, or AUTO_COLUMNS to pin none and lay the image out at what the command printed.
prompt (str | None) – command line to display, when it differs from the one run. uv run --frozen -- my-cli reproduces a capture from a checkout, but my-cli is what a reader types. An empty string draws no prompt at all.
head (int | None) – number of leading output lines to keep.
tail (int | None) – number of trailing output lines to keep.
truncation (str) – line standing in for the lines cut by head or tail.
merge_stderr (bool) – fold stderr into the captured output.
timeout (float | None) – seconds before the command is killed.
line_numbers (bool) – draw each line’s number in a gutter, see number_lines(). The prompt counts as the first of them, being the invocation everything under it came from.
title (str) – see render().
unique_id (str | None) – see render().
full (bool) – see render().
background (CaptureBackground) – see render().
border (str | None) – see render().
border_width (int) – see render().
radius (int | None) – see render().
backdrop (str) – see render().
shadow (str | None) – see render().
margin (int) – see render().
padding (int) – see render().
opacity (float) – see render().
watermark (str) – see render().
watermark_color (str | None) – see render().

Return type:

tuple[str, int]

Returns:

the rendered document, and the command’s exit code.

click_extra.screenshot.format_from_path(path)[source]¶

Pick the capture format a file name asks for.

Parameters:: path (Path) – where the capture is to be written.
Return type:: CaptureFormat
Returns:: the CaptureFormat its extension names.
Raises:: ValueError – when the extension names no format.

click_extra.screenshot_presets module¶

The bundled catalog of terminal presets a capture can be drawn as.

A capture is a picture of a terminal, and terminals do not look alike. A preset carries the four things that make one recognizable, so a reader placing the image knows which desktop it came from:

the window decorations, three round buttons on the left for macOS, three glyphs on the right for Windows, a single one for GNOME;
the palette its colors resolve against, which is what turns a bright blue into Campbell’s #3B78FF or Tango’s #729FCF;
the font the terminal ships with;
the prompt its shell draws, $ against PS C:\>.

None of it is applied unless asked for: a capture with no preset keeps the renderer’s own neutral window, which is what every image in this project’s documentation is drawn as.

Caution

A palette here is a published default, transcribed from the scheme each terminal ships (Campbell and One Half Light for Windows Terminal, Basic and Pro for Apple’s Terminal, Tango for GNOME), and cross-checked against iTerm2-Color-Schemes. It is what the terminal looks like out of the box, not what any given reader has configured theirs to.

class click_extra.screenshot_presets.TerminalPalette(background: str, foreground: str, ansi: tuple[str, ...], titlebar: str)[source]¶

Bases: NamedTuple

The colors a terminal resolves a capture’s ANSI codes against.

The 16 ansi entries are the standard palette in the canonical order: black, red, green, yellow, blue, magenta, cyan, white, then the same eight in their bright variants.

Create new instance of TerminalPalette(background, foreground, ansi, titlebar)

background: str¶: Color behind the text, as CSS spells it.

foreground: str¶: Color of the text a CLI leaves unstyled.

ansi: tuple[str, ...]¶: The 16 palette entries, normal eight first.

titlebar: str¶

Color of the strip the window’s title and buttons sit in.

A window’s chrome, which the desktop paints rather than the terminal: a shade off the background, so the top of the window reads as a window rather than as the first line of output.

class click_extra.screenshot_presets.WindowButtons(circles: tuple[str, ...] = (), glyphs: str = '')[source]¶

Bases: NamedTuple

The decorations a terminal draws in its title bar.

Two shapes cover the desktops: macOS draws filled circles on the left, Windows and GNOME draw glyphs on the right. None in either field leaves that half undrawn, which is what a bare window asks for.

Create new instance of WindowButtons(circles, glyphs)

circles: tuple[str, ...]¶: Colors of the round buttons drawn from the left, in order.

glyphs: str¶: Characters drawn from the right, closing button last.

click_extra.screenshot_presets.MACOS_BUTTONS: Final = (('#ff5f57', '#febc2e', '#28c840'), '')¶: Close, minimize and zoom, the three round buttons of an Aqua title bar.

click_extra.screenshot_presets.WINDOWS_BUTTONS: Final = ((), '－□✕')¶: Minimize, maximize and close, the three glyphs of a Windows title bar.

click_extra.screenshot_presets.GNOME_BUTTONS: Final = ((), '✕')¶: The single close button a GNOME window carries by default.

click_extra.screenshot_presets.APPLE_ANSI: Final = ('#000000', '#c23621', '#25bc24', '#adad27', '#492ee1', '#d338d3', '#33bbc8', '#cbcccd', '#818383', '#fc391f', '#31e722', '#eaec23', '#5833ff', '#f935f8', '#14f0f0', '#e9ebeb')¶: Palette shared by Apple Terminal’s Basic and Pro schemes.

click_extra.screenshot_presets.CAMPBELL_ANSI: Final = ('#0c0c0c', '#c50f1f', '#13a10e', '#c19c00', '#0037da', '#881798', '#3a96dd', '#cccccc', '#767676', '#e74856', '#16c60c', '#f9f1a5', '#3b78ff', '#b4009e', '#61d6d6', '#f2f2f2')¶: Palette of Campbell, the scheme Windows Terminal opens with.

click_extra.screenshot_presets.ONE_HALF_LIGHT_ANSI: Final = ('#383a42', '#e45649', '#50a14f', '#c18301', '#0184bc', '#a626a4', '#0997b3', '#fafafa', '#4f525d', '#df6c75', '#98c379', '#e4c07a', '#61afef', '#c577dd', '#56b5c1', '#ffffff')¶: Palette of One Half Light, the light scheme Windows Terminal ships.

click_extra.screenshot_presets.TANGO_ANSI: Final = ('#2e3436', '#cc0000', '#4e9a06', '#c4a000', '#3465a4', '#75507b', '#06989a', '#d3d7cf', '#555753', '#ef2929', '#8ae234', '#fce94f', '#729fcf', '#ad7fa8', '#34e2e2', '#eeeeec')¶: Palette of Tango, which GNOME Terminal ships in a dark and a light dress.

class click_extra.screenshot_presets.TerminalPreset(label: str, buttons: WindowButtons, radius: int, prompt: str, font_stack: str, dark: TerminalPalette, light: TerminalPalette)[source]¶

Bases: NamedTuple

A terminal a capture can be drawn as.

Pass one to click-extra screenshot --preset, or to a click:run block as :screenshot-preset:. Anything stated alongside it wins: a preset picks the defaults, it does not lock them.

Create new instance of TerminalPreset(label, buttons, radius, prompt, font_stack, dark, light)

label: str¶: Human name of the terminal, for the documentation and the help screen.

buttons: WindowButtons¶: Decorations drawn in the title bar, see WindowButtons.

radius: int¶: How round the window’s corners are, in pixels.

prompt: str¶: Sigil the terminal’s usual shell draws before a command.

font_stack: str¶

Fonts the capture asks for, the terminal’s own first.

Nothing is embedded, so a reader without the family falls back down the list. Which is why each ends with the same generic monospace a browser always resolves.

dark: TerminalPalette¶: Colors the terminal shows on its dark scheme.

light: TerminalPalette¶: Colors it shows on its light one.

click_extra.screenshot_presets.PRESETS: Final[dict[str, TerminalPreset]] = {'linux': ('GNOME Terminal', ((), '✕'), 6, '$', "'Ubuntu Mono', 'DejaVu Sans Mono', monospace", ('#2e3436', '#d3d7cf', ('#2e3436', '#cc0000', '#4e9a06', '#c4a000', '#3465a4', '#75507b', '#06989a', '#d3d7cf', '#555753', '#ef2929', '#8ae234', '#fce94f', '#729fcf', '#ad7fa8', '#34e2e2', '#eeeeec'), '#303030'), ('#ffffff', '#2e3436', ('#2e3436', '#cc0000', '#4e9a06', '#c4a000', '#3465a4', '#75507b', '#06989a', '#d3d7cf', '#555753', '#ef2929', '#8ae234', '#fce94f', '#729fcf', '#ad7fa8', '#34e2e2', '#eeeeec'), '#ebebeb')), 'macos': ('Apple Terminal', (('#ff5f57', '#febc2e', '#28c840'), ''), 10, '$', "'SF Mono', Menlo, Monaco, monospace", ('#000000', '#f2f2f2', ('#000000', '#c23621', '#25bc24', '#adad27', '#492ee1', '#d338d3', '#33bbc8', '#cbcccd', '#818383', '#fc391f', '#31e722', '#eaec23', '#5833ff', '#f935f8', '#14f0f0', '#e9ebeb'), '#3a3a3a'), ('#ffffff', '#000000', ('#000000', '#c23621', '#25bc24', '#adad27', '#492ee1', '#d338d3', '#33bbc8', '#cbcccd', '#818383', '#fc391f', '#31e722', '#eaec23', '#5833ff', '#f935f8', '#14f0f0', '#e9ebeb'), '#e9e9e9')), 'plain': ('No terminal at all', ((), ''), 0, '$', "'Fira Code', 'Cascadia Code', Menlo, Consolas, monospace", ('#292929', '#c5c8c6', ('#2e3436', '#cc0000', '#4e9a06', '#c4a000', '#3465a4', '#75507b', '#06989a', '#d3d7cf', '#555753', '#ef2929', '#8ae234', '#fce94f', '#729fcf', '#ad7fa8', '#34e2e2', '#eeeeec'), '#292929'), ('#ffffff', '#000000', ('#2e3436', '#cc0000', '#4e9a06', '#c4a000', '#3465a4', '#75507b', '#06989a', '#d3d7cf', '#555753', '#ef2929', '#8ae234', '#fce94f', '#729fcf', '#ad7fa8', '#34e2e2', '#eeeeec'), '#ffffff')), 'windows': ('Windows Terminal', ((), '－□✕'), 0, 'PS C:\\>', "'Cascadia Code', 'Cascadia Mono', Consolas, monospace", ('#0c0c0c', '#cccccc', ('#0c0c0c', '#c50f1f', '#13a10e', '#c19c00', '#0037da', '#881798', '#3a96dd', '#cccccc', '#767676', '#e74856', '#16c60c', '#f9f1a5', '#3b78ff', '#b4009e', '#61d6d6', '#f2f2f2'), '#202020'), ('#fafafa', '#383a42', ('#383a42', '#e45649', '#50a14f', '#c18301', '#0184bc', '#a626a4', '#0997b3', '#fafafa', '#4f525d', '#df6c75', '#98c379', '#e4c07a', '#61afef', '#c577dd', '#56b5c1', '#ffffff'), '#f3f3f3'))}¶

Every terminal a capture can be drawn as, alphabetically.

plain is the odd one out: it mimics no desktop, dropping the buttons and the rounded corners for a capture that has to read as a block of output rather than as a window, on a slide or in a paper.

click_extra.spinner module¶

An indeterminate terminal spinner for long-running, blocking work.

Click ships click.progressbar(), but it is determinate: it needs a known length or an iterable to advance through. Some work has no measurable progress: a blocking subprocess, a network round-trip, a query whose duration is unknown. For those, the only honest feedback is “something is happening”.

Spinner fills that gap. It animates a small frame sequence on a daemon thread, so the caller can stay blocked in a single call (communicate(), urlopen(), …) while the spinner keeps turning:

from time import sleep

from click_extra import Spinner

with Spinner("Brewing tea"):
    sleep(5)  # A blocking call with no measurable progress.

Caution

The spinner draws with carriage returns and ANSI control codes, so it is a no-op whenever its output stream is not a TTY (a pipe, a file, a captured test buffer, a CI log), unless enabled is forced. This keeps redirected output and machine-readable formats clean.

Note

On Windows, Spinner.start() enables the console’s virtual-terminal processing so the ANSI control codes animate in place rather than print literally (⠋␛[0m … ␛[K). Modern terminals (Windows Terminal, recent conhost) already have it on; this just covers older consoles.

click_extra.spinner.active_spinner(stream=None)[source]¶

Return the innermost Spinner currently animating, or None.

A spinner-typed view of _active_line(), skipping any progress-bar indicator that may own the line instead. With stream given, only a spinner drawing on that very stream matches.

Return type:: Spinner | None

class click_extra.spinner.Spinner(label='', *, frames=None, spinner=None, reverse=False, interval=None, delay=0.0, style=None, timer=False, stream=None, enabled=None, hide_cursor=True, beep=False)[source]¶

Bases: object

A thread-animated, indeterminate progress spinner usable as a context manager.

Note

Configure (but do not start) the spinner.

Parameters:

label (str | Callable[..., Any]) – text shown after the spinner glyph. As a special case, a bare @Spinner decorator passes the wrapped function here instead; it is detected and the label defaults to empty.
frames (Sequence[str] | None) – the animation frames, cycled in order. Defaults to SPINNER_FRAMES, or the spinner preset’s frames when given.
spinner (SpinnerPreset | None) – a SpinnerPreset from the SPINNERS catalog (spinner=SPINNERS["moon"]), supplying both frames and a tuned interval. An explicit frames or interval still overrides it.
reverse (bool) – cycle the frames backwards, spinning the animation the other way. Set it when the rotation runs counter to what you expect; it composes with any custom frames.
interval (float | None) – seconds between two frames. Defaults to 0.1, or the spinner preset’s interval when given.
delay (float) – seconds to wait before drawing the first frame. A non-zero delay keeps the spinner silent for calls that finish quickly, so it only surfaces once an operation is genuinely slow.
style (Style | None) – a Style applied to the spinner glyph, label and timer (Style(fg="cyan", bold=True)). Color is decoupled from animation: --no-color / NO_COLOR strip it while the spinner keeps spinning (see ProgressOption).
timer (bool | Callable[[float], str]) – append the elapsed wall-clock time to the spinner, and to any final ok() / fail() line. True uses format_duration() for the default compact format (2.3s, 1:05, then 1:02:03). Pass a callable (seconds: float) -> str to format the duration yourself, like timer=lambda s: f"{s / 60:.0f}m" for whole minutes.
stream (IO[str] | None) – where to draw; defaults to sys.stderr so the spinner never mixes into stdout data.
enabled (bool | None) – force the spinner on or off. None (the default) auto-detects, animating only when stream is a TTY.
hide_cursor (bool) – hide the text cursor while spinning and restore it on stop.
beep (bool) – ring the terminal bell once when the spinner stops. It fires only when the spinner was active, so a disabled or redirected spinner stays silent.

Raises:

ValueError – if style carries a color or attribute that cannot be rendered.

label: str¶

Text drawn after the spinner glyph.

Reassign it at any time while the spinner runs to reflect the current step; the animation thread reads it afresh on every frame.

property elapsed_time: float¶

Seconds elapsed since start(), frozen once stop() is called.

Returns 0.0 before the spinner has started.

property shown: bool¶

Whether the spinner has drawn at least one frame to its stream.

with Spinner("Baking bread") as spinner:
    bake()
    if spinner.shown:
        spinner.ok()

start()[source]¶

Begin animating on a background thread, unless the spinner is disabled.

Return type:: None

stop()[source]¶

Halt the animation and erase the spinner line.

Idempotent and safe to call when the spinner never started. Restores the cursor and clears the line only if the animation actually drew to the terminal.

Return type:: None

echo(message='')[source]¶

Print message on its own line above the running spinner.

Return type:: None

ok(symbol=None, *, style=None)[source]¶

Stop the spinner and leave a persistent success line on screen.

Return type:: None

fail(symbol=None, *, style=None)[source]¶

Stop the spinner and leave a persistent failure line on screen.

The failure counterpart of ok(), defaulting to KO_GLYPH (✘) painted with the active theme’s error slot.

Return type:: None

click_extra.spinner.trail_glyph(ok)[source]¶

Return the themed ✓ or ✘ glyph for a trail line or finisher.

The success glyph OK_GLYPH painted with the active theme’s success slot, or the failure glyph KO_GLYPH painted with its error slot.

Return type:: str

click_extra.spinner.trail_line(ok, message)[source]¶

Format one ✓/✘ trail line: a status glyph followed by message.

Return type:: str

class click_extra.spinner.OperationTrail(*, label='', unit='', total=0, jobs=1, spinner=None, progress_bar=False, timer=None, clock='elapsed', enabled=None, echo_sequential=True, delay=0.0, stream=None)[source]¶

Bases: object

A ✓/✘ progress trail and finisher for a batch of operations.

sequential (jobs <= 1): echo each outcome as it lands, with no aggregate indicator (each operation is free to keep its own per-call Spinner). finish() appends the elapsed time.
concurrent (jobs > 1): drive one aggregate Spinner (per-call spinners would collide on the shared stream), buffering outcomes until it first draws, then streaming the rest live above it. Pick the animation from the SPINNERS catalog with spinner=.
progress bar (progress_bar=True): drive one aggregate determinate bar carrying the {done}/:total:` tally, with outcomes streaming above it. Serves sequential and concurrent batches alike, and needs a known `total.

from click_extra.execution import run_jobs
from click_extra.spinner import OperationTrail

with OperationTrail(label="Fetching", unit="feeds", total=len(feeds),
                    jobs=jobs) as trail:
    def fetch(feed):
        trail.mark(*pull(feed))  # pull() returns (ok, message).

    list(run_jobs(fetch, feeds, jobs=jobs))
    trail.finish(
        trail.ok_count == len(feeds),
        f"Fetched {trail.ok_count}/{len(feeds)} feeds",
    )

Configure (but do not start) the trail.

Parameters:

label (str) – present-tense verb for the running aggregate indicator ("Fetching"), composed into its {label} {done}/{total} {unit} tally.
unit (str) – the noun counted in the tally ("files", "feeds").
total (int) – how many outcomes are expected, for the done/total count.
jobs (int) – the batch’s worker count; > 1 selects the concurrent rendering (one aggregate spinner), <= 1 the sequential one (plain echoed lines).
spinner (SpinnerPreset | None) – a SpinnerPreset from the SPINNERS catalog (spinner=SPINNERS["moon"]) for the concurrent aggregate spinner. Ignored by the sequential and progress-bar renderings, and mutually exclusive with progress_bar.
progress_bar (bool) – render the aggregate indicator as a determinate click.progressbar() instead of a spinner, for a sequential or concurrent batch alike. Requires a positive total (a bar needs a length) and is mutually exclusive with spinner.
timer (bool | Callable[[float], str] | None) – append each operation’s and the batch’s elapsed time to the trail lines and the finisher. None (the default) follows the CLI’s --time / --no-time flag; True forces timing on with format_duration()’s compact clock, a callable (seconds: float) -> str forces it on with a custom format, and False forces it off. Per-operation times come from a seconds argument to mark(), filled in automatically by an operation() handle.
clock (Literal['elapsed', 'eta']) – whether a running aggregate indicator shows elapsed time ("elapsed", the default: a stopwatch counting up, visible from the start) or remaining time ("eta": an estimate from the batch’s rate, appearing only once an outcome lets it be computed). Both the progress bar and the concurrent spinner honor "eta" (the spinner reuses Click’s progress-bar estimate, since the trail knows its total). Per-operation and finisher times are always elapsed.
enabled (bool | None) – force the trail on or off. None (the default) auto-detects: the sequential echo renders only on an interactive stream, and the aggregate indicator applies its own TTY gate.
echo_sequential (bool) – whether a sequential batch echoes its outcome lines and finisher at all. Turn it off when the batch has another output that is the real product (a result table) and the trail would be noise; an aggregate indicator is unaffected.
delay (float) – seconds before the aggregate indicator first draws: a fast batch then completes without ever flashing one.
stream (IO[str] | None) – where to render; defaults to sys.stderr so the trail never mixes into stdout data.

Raises:

ValueError – if progress_bar is set without a positive total, or together with spinner, or if clock is neither "elapsed" nor "eta".

property ok_count: int¶: How many marked outcomes have succeeded so far.

mark(ok, message, seconds=None)[source]¶

Record one ✓/✘ outcome: tally it and render its trail line.

Parameters:: seconds (float | None) – the operation’s own elapsed time. When timer is on it is formatted and appended to message as (2.3s). An operation() handle fills this in from when it was created; pass it yourself when you already hold a duration.
Return type:: None

finish(ok, summary)[source]¶

Render the persistent ✓/✘ {summary} finisher.

Return type:: None

operation()[source]¶

Start a timed operation, returning a handle to record its outcome.

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

Return type:: _Operation

class click_extra.spinner.ProgressOption(param_decls=None, is_flag=True, default=True, is_eager=True, expose_value=False, help='Show progress indicators during long operations. Disabled for non-interactive output (pipes, dumb terminals, CI) and by --accessible.', **kwargs)[source]¶

Bases: ExtraOption

A pre-configured --progress/--no-progress flag gating spinner display.

Note

The spinner is therefore silenced by two things only, neither of them color:

non-interactive output – a pipe, file, CI log, or TERM=dumb terminal that cannot move the cursor (see Spinner._resolve_enabled);
explicit intent – --no-progress or --accessible.

This option is eager. It no longer reads ctx.color, so its position relative to ColorOption is not load-bearing.

set_progress(ctx, param, value)[source]¶

Publish whether progress spinners may be shown.

Return type:: None

click_extra.spinner.progressbar(iterable=None, length=None, label=None, hidden=None, show_eta=None, **kwargs)[source]¶

Drop-in for click.progressbar() honoring --progress and --time.

Parameters:

hidden (bool | None) – tri-state. Left at its default None, the bar follows the resolved --progress flag: hidden when the user (or --accessible) turned progress off, shown otherwise. An explicit True or False forces the bar regardless, mirroring how an explicit color= argument overrides ctx.color on click.echo(). With no active context (the bar used outside a Click command) it defaults to shown.
show_eta (bool | None) – tri-state, like hidden. Left at its default None, the estimated-time-remaining display follows the --time / --no-time flag: shown under --time, hidden otherwise (its default, or outside a command). An explicit True or False forces it, keeping a bare bar’s timing in step with an OperationTrail’s timer. Click’s own default is True.

Return type:

ProgressBar[TypeVar(V)]

Note

click_extra.spinner_presets module¶

The bundled catalog of terminal spinner presets.

Ported from cli-spinners, with frame intervals converted from milliseconds to seconds.

click_extra.spinner_presets.ASCII_SPINNER_FRAMES: Final = ('-', '\\', '|', '/')¶: Plain ASCII animation frames, for terminals or fonts lacking Unicode glyphs.

click_extra.spinner_presets.SPINNER_FRAMES: Final = ('⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏')¶

Default animation frames: the ubiquitous Braille-dots spinner.

Ten frames give a smooth rotation in any UTF-8 terminal. Fall back to ASCII_SPINNER_FRAMES where Braille glyphs are unavailable.

class click_extra.spinner_presets.SpinnerPreset(frames: tuple[str, ...], interval: float)[source]¶

Bases: NamedTuple

A named spinner animation: its frames and the interval they look best at.

The SPINNERS catalog is ported from cli-spinners, with intervals converted from milliseconds to seconds. Pass one to Spinner via its spinner argument.

Create new instance of SpinnerPreset(frames, interval)

frames: tuple[str, ...]¶: The animation frames, cycled in order.

interval: float¶: Seconds between two frames, tuned per spinner upstream.

click_extra.spinner_presets.SPINNERS: Final = {'aesthetic': (('▰▱▱▱▱▱▱', '▰▰▱▱▱▱▱', '▰▰▰▱▱▱▱', '▰▰▰▰▱▱▱', '▰▰▰▰▰▱▱', '▰▰▰▰▰▰▱', '▰▰▰▰▰▰▰', '▰▱▱▱▱▱▱'), 0.08), 'arc': (('◜', '◠', '◝', '◞', '◡', '◟'), 0.1), 'arrow': (('←', '↖', '↑', '↗', '→', '↘', '↓', '↙'), 0.1), 'arrow2': (('⬆️ ', '↗️ ', '➡️ ', '↘️ ', '⬇️ ', '↙️ ', '⬅️ ', '↖️ '), 0.08), 'arrow3': (('▹▹▹▹▹', '▸▹▹▹▹', '▹▸▹▹▹', '▹▹▸▹▹', '▹▹▹▸▹', '▹▹▹▹▸'), 0.12), 'balloon': ((' ', '.', 'o', 'O', '@', '*', ' '), 0.14), 'balloon2': (('.', 'o', 'O', '°', 'O', 'o', '.'), 0.12), 'betaWave': (('ρββββββ', 'βρβββββ', 'ββρββββ', 'βββρβββ', 'ββββρββ', 'βββββρβ', 'ββββββρ'), 0.08), 'binary': (('010010', '001100', '100101', '111010', '111101', '010111', '101011', '111000', '110011', '110101'), 0.08), 'bluePulse': (('🔹 ', '🔷 ', '🔵 ', '🔵 ', '🔷 '), 0.1), 'bounce': (('⠁', '⠂', '⠄', '⠂'), 0.12), 'bouncingBall': (('( ● )', '( ● )', '( ● )', '( ● )', '( ●)', '( ● )', '( ● )', '( ● )', '( ● )', '(● )'), 0.08), 'bouncingBar': (('[ ]', '[= ]', '[== ]', '[=== ]', '[====]', '[ ===]', '[ ==]', '[ =]', '[ ]', '[ =]', '[ ==]', '[ ===]', '[====]', '[=== ]', '[== ]', '[= ]'), 0.08), 'boxBounce': (('▖', '▘', '▝', '▗'), 0.12), 'boxBounce2': (('▌', '▀', '▐', '▄'), 0.1), 'christmas': (('🌲', '🎄'), 0.4), 'circle': (('◡', '⊙', '◠'), 0.12), 'circleHalves': (('◐', '◓', '◑', '◒'), 0.05), 'circleQuarters': (('◴', '◷', '◶', '◵'), 0.12), 'clock': (('🕛 ', '🕐 ', '🕑 ', '🕒 ', '🕓 ', '🕔 ', '🕕 ', '🕖 ', '🕗 ', '🕘 ', '🕙 ', '🕚 '), 0.1), 'dots': (('⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'), 0.08), 'dots10': (('⢄', '⢂', '⢁', '⡁', '⡈', '⡐', '⡠'), 0.08), 'dots11': (('⠁', '⠂', '⠄', '⡀', '⢀', '⠠', '⠐', '⠈'), 0.1), 'dots12': (('⢀⠀', '⡀⠀', '⠄⠀', '⢂⠀', '⡂⠀', '⠅⠀', '⢃⠀', '⡃⠀', '⠍⠀', '⢋⠀', '⡋⠀', '⠍⠁', '⢋⠁', '⡋⠁', '⠍⠉', '⠋⠉', '⠋⠉', '⠉⠙', '⠉⠙', '⠉⠩', '⠈⢙', '⠈⡙', '⢈⠩', '⡀⢙', '⠄⡙', '⢂⠩', '⡂⢘', '⠅⡘', '⢃⠨', '⡃⢐', '⠍⡐', '⢋⠠', '⡋⢀', '⠍⡁', '⢋⠁', '⡋⠁', '⠍⠉', '⠋⠉', '⠋⠉', '⠉⠙', '⠉⠙', '⠉⠩', '⠈⢙', '⠈⡙', '⠈⠩', '⠀⢙', '⠀⡙', '⠀⠩', '⠀⢘', '⠀⡘', '⠀⠨', '⠀⢐', '⠀⡐', '⠀⠠', '⠀⢀', '⠀⡀'), 0.08), 'dots13': (('⣼', '⣹', '⢻', '⠿', '⡟', '⣏', '⣧', '⣶'), 0.08), 'dots14': (('⠉⠉', '⠈⠙', '⠀⠹', '⠀⢸', '⠀⣰', '⢀⣠', '⣀⣀', '⣄⡀', '⣆⠀', '⡇⠀', '⠏⠀', '⠋⠁'), 0.08), 'dots2': (('⣾', '⣽', '⣻', '⢿', '⡿', '⣟', '⣯', '⣷'), 0.08), 'dots3': (('⠋', '⠙', '⠚', '⠞', '⠖', '⠦', '⠴', '⠲', '⠳', '⠓'), 0.08), 'dots4': (('⠄', '⠆', '⠇', '⠋', '⠙', '⠸', '⠰', '⠠', '⠰', '⠸', '⠙', '⠋', '⠇', '⠆'), 0.08), 'dots5': (('⠋', '⠙', '⠚', '⠒', '⠂', '⠂', '⠒', '⠲', '⠴', '⠦', '⠖', '⠒', '⠐', '⠐', '⠒', '⠓', '⠋'), 0.08), 'dots6': (('⠁', '⠉', '⠙', '⠚', '⠒', '⠂', '⠂', '⠒', '⠲', '⠴', '⠤', '⠄', '⠄', '⠤', '⠴', '⠲', '⠒', '⠂', '⠂', '⠒', '⠚', '⠙', '⠉', '⠁'), 0.08), 'dots7': (('⠈', '⠉', '⠋', '⠓', '⠒', '⠐', '⠐', '⠒', '⠖', '⠦', '⠤', '⠠', '⠠', '⠤', '⠦', '⠖', '⠒', '⠐', '⠐', '⠒', '⠓', '⠋', '⠉', '⠈'), 0.08), 'dots8': (('⠁', '⠁', '⠉', '⠙', '⠚', '⠒', '⠂', '⠂', '⠒', '⠲', '⠴', '⠤', '⠄', '⠄', '⠤', '⠠', '⠠', '⠤', '⠦', '⠖', '⠒', '⠐', '⠐', '⠒', '⠓', '⠋', '⠉', '⠈', '⠈'), 0.08), 'dots8Bit': (('⠀', '⠁', '⠂', '⠃', '⠄', '⠅', '⠆', '⠇', '⡀', '⡁', '⡂', '⡃', '⡄', '⡅', '⡆', '⡇', '⠈', '⠉', '⠊', '⠋', '⠌', '⠍', '⠎', '⠏', '⡈', '⡉', '⡊', '⡋', '⡌', '⡍', '⡎', '⡏', '⠐', '⠑', '⠒', '⠓', '⠔', '⠕', '⠖', '⠗', '⡐', '⡑', '⡒', '⡓', '⡔', '⡕', '⡖', '⡗', '⠘', '⠙', '⠚', '⠛', '⠜', '⠝', '⠞', '⠟', '⡘', '⡙', '⡚', '⡛', '⡜', '⡝', '⡞', '⡟', '⠠', '⠡', '⠢', '⠣', '⠤', '⠥', '⠦', '⠧', '⡠', '⡡', '⡢', '⡣', '⡤', '⡥', '⡦', '⡧', '⠨', '⠩', '⠪', '⠫', '⠬', '⠭', '⠮', '⠯', '⡨', '⡩', '⡪', '⡫', '⡬', '⡭', '⡮', '⡯', '⠰', '⠱', '⠲', '⠳', '⠴', '⠵', '⠶', '⠷', '⡰', '⡱', '⡲', '⡳', '⡴', '⡵', '⡶', '⡷', '⠸', '⠹', '⠺', '⠻', '⠼', '⠽', '⠾', '⠿', '⡸', '⡹', '⡺', '⡻', '⡼', '⡽', '⡾', '⡿', '⢀', '⢁', '⢂', '⢃', '⢄', '⢅', '⢆', '⢇', '⣀', '⣁', '⣂', '⣃', '⣄', '⣅', '⣆', '⣇', '⢈', '⢉', '⢊', '⢋', '⢌', '⢍', '⢎', '⢏', '⣈', '⣉', '⣊', '⣋', '⣌', '⣍', '⣎', '⣏', '⢐', '⢑', '⢒', '⢓', '⢔', '⢕', '⢖', '⢗', '⣐', '⣑', '⣒', '⣓', '⣔', '⣕', '⣖', '⣗', '⢘', '⢙', '⢚', '⢛', '⢜', '⢝', '⢞', '⢟', '⣘', '⣙', '⣚', '⣛', '⣜', '⣝', '⣞', '⣟', '⢠', '⢡', '⢢', '⢣', '⢤', '⢥', '⢦', '⢧', '⣠', '⣡', '⣢', '⣣', '⣤', '⣥', '⣦', '⣧', '⢨', '⢩', '⢪', '⢫', '⢬', '⢭', '⢮', '⢯', '⣨', '⣩', '⣪', '⣫', '⣬', '⣭', '⣮', '⣯', '⢰', '⢱', '⢲', '⢳', '⢴', '⢵', '⢶', '⢷', '⣰', '⣱', '⣲', '⣳', '⣴', '⣵', '⣶', '⣷', '⢸', '⢹', '⢺', '⢻', '⢼', '⢽', '⢾', '⢿', '⣸', '⣹', '⣺', '⣻', '⣼', '⣽', '⣾', '⣿'), 0.08), 'dots9': (('⢹', '⢺', '⢼', '⣸', '⣇', '⡧', '⡗', '⡏'), 0.08), 'dotsCircle': (('⢎ ', '⠎⠁', '⠊⠑', '⠈⠱', ' ⡱', '⢀⡰', '⢄⡠', '⢆⡀'), 0.08), 'dqpb': (('d', 'q', 'p', 'b'), 0.1), 'dwarfFortress': ((' ██████£££ ', '☺██████£££ ', '☺██████£££ ', '☺▓█████£££ ', '☺▓█████£££ ', '☺▒█████£££ ', '☺▒█████£££ ', '☺░█████£££ ', '☺░█████£££ ', '☺ █████£££ ', ' ☺█████£££ ', ' ☺█████£££ ', ' ☺▓████£££ ', ' ☺▓████£££ ', ' ☺▒████£££ ', ' ☺▒████£££ ', ' ☺░████£££ ', ' ☺░████£££ ', ' ☺ ████£££ ', ' ☺████£££ ', ' ☺████£££ ', ' ☺▓███£££ ', ' ☺▓███£££ ', ' ☺▒███£££ ', ' ☺▒███£££ ', ' ☺░███£££ ', ' ☺░███£££ ', ' ☺ ███£££ ', ' ☺███£££ ', ' ☺███£££ ', ' ☺▓██£££ ', ' ☺▓██£££ ', ' ☺▒██£££ ', ' ☺▒██£££ ', ' ☺░██£££ ', ' ☺░██£££ ', ' ☺ ██£££ ', ' ☺██£££ ', ' ☺██£££ ', ' ☺▓█£££ ', ' ☺▓█£££ ', ' ☺▒█£££ ', ' ☺▒█£££ ', ' ☺░█£££ ', ' ☺░█£££ ', ' ☺ █£££ ', ' ☺█£££ ', ' ☺█£££ ', ' ☺▓£££ ', ' ☺▓£££ ', ' ☺▒£££ ', ' ☺▒£££ ', ' ☺░£££ ', ' ☺░£££ ', ' ☺ £££ ', ' ☺£££ ', ' ☺£££ ', ' ☺▓££ ', ' ☺▓££ ', ' ☺▒££ ', ' ☺▒££ ', ' ☺░££ ', ' ☺░££ ', ' ☺ ££ ', ' ☺££ ', ' ☺££ ', ' ☺▓£ ', ' ☺▓£ ', ' ☺▒£ ', ' ☺▒£ ', ' ☺░£ ', ' ☺░£ ', ' ☺ £ ', ' ☺£ ', ' ☺£ ', ' ☺▓ ', ' ☺▓ ', ' ☺▒ ', ' ☺▒ ', ' ☺░ ', ' ☺░ ', ' ☺ ', ' ☺ &', ' ☺ ☼&', ' ☺ ☼ &', ' ☺☼ &', ' ☺☼ & ', ' ‼ & ', ' ☺ & ', ' ‼ & ', ' ☺ & ', ' ‼ & ', ' ☺ & ', '‼ & ', ' & ', ' & ', ' & ░ ', ' & ▒ ', ' & ▓ ', ' & £ ', ' & ░£ ', ' & ▒£ ', ' & ▓£ ', ' & ££ ', ' & ░££ ', ' & ▒££ ', '& ▓££ ', '& £££ ', ' ░£££ ', ' ▒£££ ', ' ▓£££ ', ' █£££ ', ' ░█£££ ', ' ▒█£££ ', ' ▓█£££ ', ' ██£££ ', ' ░██£££ ', ' ▒██£££ ', ' ▓██£££ ', ' ███£££ ', ' ░███£££ ', ' ▒███£££ ', ' ▓███£££ ', ' ████£££ ', ' ░████£££ ', ' ▒████£££ ', ' ▓████£££ ', ' █████£££ ', ' ░█████£££ ', ' ▒█████£££ ', ' ▓█████£££ ', ' ██████£££ ', ' ██████£££ '), 0.08), 'earth': (('🌍 ', '🌎 ', '🌏 '), 0.18), 'fingerDance': (('🤘 ', '🤟 ', '🖖 ', '✋ ', '🤚 ', '👆 '), 0.16), 'fish': (('~~~~~~~~~~~~~~~~~~~~', '> ~~~~~~~~~~~~~~~~~~', 'º> ~~~~~~~~~~~~~~~~~', '(º> ~~~~~~~~~~~~~~~~', '((º> ~~~~~~~~~~~~~~~', '<((º> ~~~~~~~~~~~~~~', '><((º> ~~~~~~~~~~~~~', ' ><((º> ~~~~~~~~~~~~', '~ ><((º> ~~~~~~~~~~~', '~~ <>((º> ~~~~~~~~~~', '~~~ ><((º> ~~~~~~~~~', '~~~~ <>((º> ~~~~~~~~', '~~~~~ ><((º> ~~~~~~~', '~~~~~~ <>((º> ~~~~~~', '~~~~~~~ ><((º> ~~~~~', '~~~~~~~~ <>((º> ~~~~', '~~~~~~~~~ ><((º> ~~~', '~~~~~~~~~~ <>((º> ~~', '~~~~~~~~~~~ ><((º> ~', '~~~~~~~~~~~~ <>((º> ', '~~~~~~~~~~~~~ ><((º>', '~~~~~~~~~~~~~~ <>((º', '~~~~~~~~~~~~~~~ ><((', '~~~~~~~~~~~~~~~~ <>(', '~~~~~~~~~~~~~~~~~ ><', '~~~~~~~~~~~~~~~~~~ <', '~~~~~~~~~~~~~~~~~~~~'), 0.08), 'fistBump': (('🤜\u3000\u3000\u3000\u3000🤛 ', '🤜\u3000\u3000\u3000\u3000🤛 ', '🤜\u3000\u3000\u3000\u3000🤛 ', '\u3000🤜\u3000\u3000🤛\u3000 ', '\u3000\u3000🤜🤛\u3000\u3000 ', '\u3000🤜✨🤛\u3000\u3000 ', '🤜\u3000✨\u3000🤛\u3000 '), 0.08), 'flip': (('_', '_', '_', '-', '`', '`', "'", '´', '-', '_', '_', '_'), 0.07), 'grenade': (('، ', '′ ', ' ´ ', ' ‾ ', ' ⸌', ' ⸊', ' |', ' ⁎', ' ⁕', ' ෴ ', ' ⁓', ' ', ' ', ' '), 0.08), 'growHorizontal': (('▏', '▎', '▍', '▌', '▋', '▊', '▉', '▊', '▋', '▌', '▍', '▎'), 0.12), 'growVertical': (('▁', '▃', '▄', '▅', '▆', '▇', '▆', '▅', '▄', '▃'), 0.12), 'hamburger': (('☱', '☲', '☴'), 0.1), 'hearts': (('💛 ', '💙 ', '💜 ', '💚 ', '💗 '), 0.1), 'layer': (('-', '=', '≡'), 0.15), 'line': (('-', '\\', '|', '/'), 0.13), 'line2': (('⠂', '-', '–', '—', '–', '-'), 0.1), 'material': (('█▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁', '██▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁', '███▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁', '████▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁', '██████▁▁▁▁▁▁▁▁▁▁▁▁▁▁', '██████▁▁▁▁▁▁▁▁▁▁▁▁▁▁', '███████▁▁▁▁▁▁▁▁▁▁▁▁▁', '████████▁▁▁▁▁▁▁▁▁▁▁▁', '█████████▁▁▁▁▁▁▁▁▁▁▁', '█████████▁▁▁▁▁▁▁▁▁▁▁', '██████████▁▁▁▁▁▁▁▁▁▁', '███████████▁▁▁▁▁▁▁▁▁', '█████████████▁▁▁▁▁▁▁', '██████████████▁▁▁▁▁▁', '██████████████▁▁▁▁▁▁', '▁██████████████▁▁▁▁▁', '▁██████████████▁▁▁▁▁', '▁██████████████▁▁▁▁▁', '▁▁██████████████▁▁▁▁', '▁▁▁██████████████▁▁▁', '▁▁▁▁█████████████▁▁▁', '▁▁▁▁██████████████▁▁', '▁▁▁▁██████████████▁▁', '▁▁▁▁▁██████████████▁', '▁▁▁▁▁██████████████▁', '▁▁▁▁▁██████████████▁', '▁▁▁▁▁▁██████████████', '▁▁▁▁▁▁██████████████', '▁▁▁▁▁▁▁█████████████', '▁▁▁▁▁▁▁█████████████', '▁▁▁▁▁▁▁▁████████████', '▁▁▁▁▁▁▁▁████████████', '▁▁▁▁▁▁▁▁▁███████████', '▁▁▁▁▁▁▁▁▁███████████', '▁▁▁▁▁▁▁▁▁▁██████████', '▁▁▁▁▁▁▁▁▁▁██████████', '▁▁▁▁▁▁▁▁▁▁▁▁████████', '▁▁▁▁▁▁▁▁▁▁▁▁▁███████', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁██████', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁█████', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁█████', '█▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁████', '██▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁███', '██▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁███', '███▁▁▁▁▁▁▁▁▁▁▁▁▁▁███', '████▁▁▁▁▁▁▁▁▁▁▁▁▁▁██', '█████▁▁▁▁▁▁▁▁▁▁▁▁▁▁█', '█████▁▁▁▁▁▁▁▁▁▁▁▁▁▁█', '██████▁▁▁▁▁▁▁▁▁▁▁▁▁█', '████████▁▁▁▁▁▁▁▁▁▁▁▁', '█████████▁▁▁▁▁▁▁▁▁▁▁', '█████████▁▁▁▁▁▁▁▁▁▁▁', '█████████▁▁▁▁▁▁▁▁▁▁▁', '█████████▁▁▁▁▁▁▁▁▁▁▁', '███████████▁▁▁▁▁▁▁▁▁', '████████████▁▁▁▁▁▁▁▁', '████████████▁▁▁▁▁▁▁▁', '██████████████▁▁▁▁▁▁', '██████████████▁▁▁▁▁▁', '▁██████████████▁▁▁▁▁', '▁██████████████▁▁▁▁▁', '▁▁▁█████████████▁▁▁▁', '▁▁▁▁▁████████████▁▁▁', '▁▁▁▁▁████████████▁▁▁', '▁▁▁▁▁▁███████████▁▁▁', '▁▁▁▁▁▁▁▁█████████▁▁▁', '▁▁▁▁▁▁▁▁█████████▁▁▁', '▁▁▁▁▁▁▁▁▁█████████▁▁', '▁▁▁▁▁▁▁▁▁█████████▁▁', '▁▁▁▁▁▁▁▁▁▁█████████▁', '▁▁▁▁▁▁▁▁▁▁▁████████▁', '▁▁▁▁▁▁▁▁▁▁▁████████▁', '▁▁▁▁▁▁▁▁▁▁▁▁███████▁', '▁▁▁▁▁▁▁▁▁▁▁▁███████▁', '▁▁▁▁▁▁▁▁▁▁▁▁▁███████', '▁▁▁▁▁▁▁▁▁▁▁▁▁███████', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁█████', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁████', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁████', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁████', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁███', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁███', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁██', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁██', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁██', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁█', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁█', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁█', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁', '▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁'), 0.017), 'mindblown': (('😐 ', '😐 ', '😮 ', '😮 ', '😦 ', '😦 ', '😧 ', '😧 ', '🤯 ', '💥 ', '✨ ', '\u3000 ', '\u3000 ', '\u3000 '), 0.16), 'monkey': (('🙈 ', '🙈 ', '🙉 ', '🙊 '), 0.3), 'moon': (('🌑 ', '🌒 ', '🌓 ', '🌔 ', '🌕 ', '🌖 ', '🌗 ', '🌘 '), 0.08), 'noise': (('▓', '▒', '░'), 0.1), 'orangeBluePulse': (('🔸 ', '🔶 ', '🟠 ', '🟠 ', '🔶 ', '🔹 ', '🔷 ', '🔵 ', '🔵 ', '🔷 '), 0.1), 'orangePulse': (('🔸 ', '🔶 ', '🟠 ', '🟠 ', '🔶 '), 0.1), 'pipe': (('┤', '┘', '┴', '└', '├', '┌', '┬', '┐'), 0.1), 'point': (('∙∙∙', '●∙∙', '∙●∙', '∙∙●', '∙∙∙'), 0.125), 'pong': (('▐⠂ ▌', '▐⠈ ▌', '▐ ⠂ ▌', '▐ ⠠ ▌', '▐ ⡀ ▌', '▐ ⠠ ▌', '▐ ⠂ ▌', '▐ ⠈ ▌', '▐ ⠂ ▌', '▐ ⠠ ▌', '▐ ⡀ ▌', '▐ ⠠ ▌', '▐ ⠂ ▌', '▐ ⠈ ▌', '▐ ⠂▌', '▐ ⠠▌', '▐ ⡀▌', '▐ ⠠ ▌', '▐ ⠂ ▌', '▐ ⠈ ▌', '▐ ⠂ ▌', '▐ ⠠ ▌', '▐ ⡀ ▌', '▐ ⠠ ▌', '▐ ⠂ ▌', '▐ ⠈ ▌', '▐ ⠂ ▌', '▐ ⠠ ▌', '▐ ⡀ ▌', '▐⠠ ▌'), 0.08), 'rollingLine': (('/ ', ' - ', ' \\ ', ' |', ' |', ' \\ ', ' - ', '/ '), 0.08), 'runner': (('🚶 ', '🏃 '), 0.14), 'sand': (('⠁', '⠂', '⠄', '⡀', '⡈', '⡐', '⡠', '⣀', '⣁', '⣂', '⣄', '⣌', '⣔', '⣤', '⣥', '⣦', '⣮', '⣶', '⣷', '⣿', '⡿', '⠿', '⢟', '⠟', '⡛', '⠛', '⠫', '⢋', '⠋', '⠍', '⡉', '⠉', '⠑', '⠡', '⢁'), 0.08), 'shark': (('▐|\\____________▌', '▐_|\\___________▌', '▐__|\\__________▌', '▐___|\\_________▌', '▐____|\\________▌', '▐_____|\\_______▌', '▐______|\\______▌', '▐_______|\\_____▌', '▐________|\\____▌', '▐_________|\\___▌', '▐__________|\\__▌', '▐___________|\\_▌', '▐____________|\\▌', '▐____________/|▌', '▐___________/|_▌', '▐__________/|__▌', '▐_________/|___▌', '▐________/|____▌', '▐_______/|_____▌', '▐______/|______▌', '▐_____/|_______▌', '▐____/|________▌', '▐___/|_________▌', '▐__/|__________▌', '▐_/|___________▌', '▐/|____________▌'), 0.12), 'simpleDots': (('. ', '.. ', '...', ' '), 0.4), 'simpleDotsScrolling': (('. ', '.. ', '...', ' ..', ' .', ' '), 0.2), 'smiley': (('😄 ', '😝 '), 0.2), 'soccerHeader': ((' 🧑⚽️ 🧑 ', '🧑 ⚽️ 🧑 ', '🧑 ⚽️ 🧑 ', '🧑 ⚽️ 🧑 ', '🧑 ⚽️ 🧑 ', '🧑 ⚽️ 🧑 ', '🧑 ⚽️🧑 ', '🧑 ⚽️ 🧑 ', '🧑 ⚽️ 🧑 ', '🧑 ⚽️ 🧑 ', '🧑 ⚽️ 🧑 ', '🧑 ⚽️ 🧑 '), 0.08), 'speaker': (('🔈 ', '🔉 ', '🔊 ', '🔉 '), 0.16), 'squareCorners': (('◰', '◳', '◲', '◱'), 0.18), 'squish': (('╫', '╪'), 0.1), 'star': (('✶', '✸', '✹', '✺', '✹', '✷'), 0.07), 'star2': (('+', 'x', '*'), 0.08), 'timeTravel': (('🕛 ', '🕚 ', '🕙 ', '🕘 ', '🕗 ', '🕖 ', '🕕 ', '🕔 ', '🕓 ', '🕒 ', '🕑 ', '🕐 '), 0.1), 'toggle': (('⊶', '⊷'), 0.25), 'toggle10': (('㊂', '㊀', '㊁'), 0.1), 'toggle11': (('⧇', '⧆'), 0.05), 'toggle12': (('☗', '☖'), 0.12), 'toggle13': (('=', '*', '-'), 0.08), 'toggle2': (('▫', '▪'), 0.08), 'toggle3': (('□', '■'), 0.12), 'toggle4': (('■', '□', '▪', '▫'), 0.1), 'toggle5': (('▮', '▯'), 0.1), 'toggle6': (('ဝ', '၀'), 0.3), 'toggle7': (('⦾', '⦿'), 0.08), 'toggle8': (('◍', '◌'), 0.1), 'toggle9': (('◉', '◎'), 0.1), 'triangle': (('◢', '◣', '◤', '◥'), 0.05), 'weather': (('☀️ ', '☀️ ', '☀️ ', '🌤 ', '⛅️ ', '🌥 ', '☁️ ', '🌧 ', '🌨 ', '🌧 ', '🌨 ', '🌧 ', '🌨 ', '⛈ ', '🌨 ', '🌧 ', '🌨 ', '☁️ ', '🌥 ', '⛅️ ', '🌤 ', '☀️ ', '☀️ '), 0.1)}¶

Named spinner animations ported from cli-spinners, keyed by name.

Each value is a SpinnerPreset bundling frames and a tuned interval. Select one with Spinner’s spinner argument:

from click_extra import Spinner, SPINNERS

with Spinner("Brewing tea", spinner=SPINNERS["moon"]):
    ...

Unlike the upstream \b-based renderers, Spinner redraws the whole line, so the multi-character animations (bouncingBar, pong, shark, …) render correctly here.

click_extra.table module¶

Width limits of a table: one entry per column, or a scalar for all of them.

click_extra.table.ColumnWidth = int | typing.Literal['auto'] | None¶: Width limit of a single column: a character count, auto, or no limit.

click_extra.table.MaxColumnWidths = collections.abc.Sequence[int | typing.Literal['auto'] | None] | int | typing.Literal['auto'] | None¶: Width limits of a table: one entry per column, or a scalar for all of them.

class click_extra.table.TableFormat(*values)[source]¶

Bases: 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.

ALIGNED = 'aligned'¶

ASCIIDOC = 'asciidoc'¶

COLON_GRID = 'colon-grid'¶

CSV = 'csv'¶

CSV_EXCEL = 'csv-excel'¶

CSV_EXCEL_TAB = 'csv-excel-tab'¶

CSV_UNIX = 'csv-unix'¶

DOUBLE_GRID = 'double-grid'¶

DOUBLE_OUTLINE = 'double-outline'¶

FANCY_GRID = 'fancy-grid'¶

FANCY_OUTLINE = 'fancy-outline'¶

GITHUB = 'github'¶

GRID = 'grid'¶

HEAVY_GRID = 'heavy-grid'¶

HEAVY_OUTLINE = 'heavy-outline'¶

HJSON = 'hjson'¶

HTML = 'html'¶

JIRA = 'jira'¶

JSON = 'json'¶

JSON5 = 'json5'¶

JSONC = 'jsonc'¶

LATEX = 'latex'¶

LATEX_BOOKTABS = 'latex-booktabs'¶

LATEX_LONGTABLE = 'latex-longtable'¶

LATEX_RAW = 'latex-raw'¶

MEDIAWIKI = 'mediawiki'¶

MIXED_GRID = 'mixed-grid'¶

MIXED_OUTLINE = 'mixed-outline'¶

MOINMOIN = 'moinmoin'¶

ORGTBL = 'orgtbl'¶

OUTLINE = 'outline'¶

PIPE = 'pipe'¶

PLAIN = 'plain'¶

PRESTO = 'presto'¶

PRETTY = 'pretty'¶

PSQL = 'psql'¶

ROUNDED_GRID = 'rounded-grid'¶

ROUNDED_OUTLINE = 'rounded-outline'¶

RST = 'rst'¶

SIMPLE = 'simple'¶

SIMPLE_GRID = 'simple-grid'¶

SIMPLE_OUTLINE = 'simple-outline'¶

TEXTILE = 'textile'¶

TOML = 'toml'¶

TSV = 'tsv'¶

UNSAFEHTML = 'unsafehtml'¶

VERTICAL = 'vertical'¶

XML = 'xml'¶

YAML = 'yaml'¶

YOUTRACK = 'youtrack'¶

property is_markup: bool¶

Whether this format is a markup rendering.

property supports_styling: bool¶

Whether ANSI codes are translated to this format’s native styling.

See STYLED_FORMATS for the registry, and the rationale behind each excluded markup format.

property is_wrappable: bool¶

Whether this format renders a cell wrapped onto several lines.

See WRAPPABLE_FORMATS for the registry, and the rationale behind each excluded format.

click_extra.table.MARKUP_FORMATS = frozenset({TableFormat.ASCIIDOC, TableFormat.CSV, TableFormat.CSV_EXCEL, TableFormat.CSV_EXCEL_TAB, TableFormat.CSV_UNIX, TableFormat.GITHUB, TableFormat.HJSON, TableFormat.HTML, TableFormat.JIRA, TableFormat.JSON, TableFormat.JSON5, TableFormat.JSONC, TableFormat.LATEX, TableFormat.LATEX_BOOKTABS, TableFormat.LATEX_LONGTABLE, TableFormat.LATEX_RAW, TableFormat.MEDIAWIKI, TableFormat.MOINMOIN, TableFormat.ORGTBL, TableFormat.PIPE, TableFormat.RST, TableFormat.TEXTILE, TableFormat.TOML, TableFormat.TSV, TableFormat.UNSAFEHTML, TableFormat.XML, TableFormat.YAML, TableFormat.YOUTRACK})¶: Subset of table formats that are considered as markup rendering.

click_extra.table.STYLED_FORMATS: dict[TableFormat, Callable[[str], str]] = {TableFormat.HTML: <function ansi_to_html>, TableFormat.JIRA: <function ansi_to_jira>, TableFormat.LATEX: <function ansi_to_latex>, TableFormat.LATEX_BOOKTABS: <function ansi_to_latex>, TableFormat.LATEX_LONGTABLE: <function ansi_to_latex>, TableFormat.LATEX_RAW: <function ansi_to_latex>, TableFormat.MEDIAWIKI: <function ansi_to_html>, TableFormat.TEXTILE: <function ansi_to_textile>, TableFormat.UNSAFEHTML: <function ansi_to_html>}¶

Markup formats able to express styles natively, mapped to their ANSI translator.

print_table() runs the rendered output of these formats through their translator, converting the ANSI codes carried by cells and headers into the format’s own styling markup: inline-CSS HTML s for the HTML pair and MediaWiki (which accepts embedded HTML), Textile %{...} spans, Jira {color:...} macros, and xcolor-based LaTeX macros.

Note

Translation happens on the rendered output, not on cell values, on purpose. tabulate escapes cell content for some formats (html escapes HTML entities, non-raw latex variants escape TeX specials) while ANSI sequences pass through unscathed, so pre-render translation would get its markup mangled by those escaping rules. Post-render injection also keeps column-width computation on the ANSI text, which tabulate measures correctly.

Important

Every markup format absent from this registry keeps the historical behavior: ANSI codes are stripped from cells before rendering. The verdict, format by format:

asciidoc: no portable inline styling. Colors require stylesheet-defined roles or +++ passthrough blocks tied to the HTML backend, both lossy and non-standard.
csv, csv-excel, csv-excel-tab, csv-unix, tsv: data interchange formats, with no concept of styling.
github, pipe: GitHub sanitizes inline style attributes from rendered Markdown, so translated HTML spans would not display any color there. Raw ANSI can still be forced with --color for terminal Markdown viewers which support escape sequences.
hjson, json, json5, jsonc, toml, xml, yaml: structured serialization formats meant for programmatic consumption. Styling is presentation, not data.
moinmoin: MoinMoin wiki markup has no standard inline color syntax, and embedded HTML is disabled by default.
orgtbl: Org-mode has emphasis markers but no inline color markup.
rst: reStructuredText needs custom roles backed by a stylesheet for inline color; there is no standard inline syntax.
youtrack: undocumented by JetBrains and scheduled for removal in python-tabulate 0.11.

click_extra.table.DEFAULT_FORMAT = TableFormat.ROUNDED_OUTLINE¶: Default table format, if none is specified.

click_extra.table.RECORD_KEY = 'record'¶: Key used for each record in structured formats that require named containers (TOML [[record]], XML <record>).

click_extra.table.XML_ROOT_KEY = 'records'¶: Root element name for XML table output.

click_extra.table.SERIALIZATION_FORMATS = frozenset({TableFormat.HJSON, TableFormat.JSON, TableFormat.JSON5, TableFormat.JSONC, TableFormat.TOML, TableFormat.XML, TableFormat.YAML})¶: Structured serialization formats whose renderers escape raw ESC bytes, making post-render strip_ansi() ineffective.

click_extra.table.AUTO_WIDTH: Final = 'auto'¶

Sentinel asking for a column width derived from the space left on the terminal.

Annotated Final so it narrows to Literal["auto"] instead of str, which is what lets it stand in for the raw string anywhere a ColumnWidth is expected.

click_extra.table.MIN_COLUMN_WIDTH = 8¶: Floor applied to an AUTO_WIDTH column, so a crowded table still renders a usable column instead of collapsing it to nothing.

click_extra.table.WRAPPABLE_FORMATS = frozenset({TableFormat.COLON_GRID, TableFormat.DOUBLE_GRID, TableFormat.DOUBLE_OUTLINE, TableFormat.FANCY_GRID, TableFormat.FANCY_OUTLINE, TableFormat.GRID, TableFormat.HEAVY_GRID, TableFormat.HEAVY_OUTLINE, TableFormat.MIXED_GRID, TableFormat.MIXED_OUTLINE, TableFormat.OUTLINE, TableFormat.PLAIN, TableFormat.PRESTO, TableFormat.PRETTY, TableFormat.PSQL, TableFormat.ROUNDED_GRID, TableFormat.ROUNDED_OUTLINE, TableFormat.RST, TableFormat.SIMPLE, TableFormat.SIMPLE_GRID, TableFormat.SIMPLE_OUTLINE, TableFormat.VERTICAL})¶

Formats laying a wrapped cell over several lines while keeping it one cell.

Column widths are a presentation hint: they are honored by the formats listed here and silently dropped by every other one, the same way styling degrades per format in STYLED_FORMATS. Dropping is the point, as a width forced onto a format below would corrupt its output.

Important

Every format absent from this registry renders max_column_widths unusable, for one of four reasons:

aligned: this module’s own zero-padding format. tabulate does not indent its continuation lines, so a wrapped cell escapes its column.
github, jira, orgtbl, pipe: continuation lines are emitted as additional table rows. They look right in a terminal, but a Markdown, Jira or Org renderer reads them as extra records.
asciidoc, html, latex, latex-booktabs, latex-longtable, latex-raw, mediawiki, moinmoin, textile, unsafehtml, youtrack: the line break lands raw inside the cell markup, where the target renderer either collapses it back to a space or breaks the row. These formats delegate wrapping to whatever displays them.
csv, csv-excel, csv-excel-tab, csv-unix, tsv, and the SERIALIZATION_FORMATS: data interchange, where a line break inside a field changes the record rather than its presentation.

click_extra.table.EMOJI_PRESENTATION_SELECTOR = '️'¶: Unicode VARIATION SELECTOR-16, asking for the emoji form of what precedes it.

click_extra.table.NARROW_EMOJI_PRESENTATION_TERMINALS = frozenset({'Apple_Terminal'})¶

$TERM_PROGRAM values of terminals ignoring an emoji-presentation request.

UTS #51 makes an emoji-presentation sequence (a character followed by EMOJI_PRESENTATION_SELECTOR) two columns wide. That is what wcwidth measures, and what a terminal implementing Unicode 9 widths advances the cursor by. A terminal named here advances by the base character’s own width instead, so ⁉️ (U+2049 U+FE0F) takes one column and its glyph is painted over the next one.

Measuring such a cell as two columns there pads its row one column short, and every rule right of that cell lands early: the table looks broken on exactly the rows carrying an emoji. A character wide in its own right (✅, U+2705) carries no selector and is never in question.

Detection reads $TERM_PROGRAM, which a multiplexer overwrites with its own name, and rightly so: under tmux or screen it is the multiplexer that lays the cells out.

click_extra.table.EMOJI_PRESENTATION_RE = re.compile('.️')¶: Matches one emoji-presentation sequence: a character and the selector.

click_extra.table.render_table(table_data, headers=None, table_format=None, sort_key=None, max_column_widths=None, **kwargs)[source]¶

Render a table and return it as a string.

Parameters:

sort_key (Callable[[Sequence[str | None]], Any] | None) – Optional callable passed to sorted() as the key argument. When provided, rows are sorted before rendering.
max_column_widths (Sequence[int | Literal['auto'] | None] | int | Literal['auto'] | None) – Width limits, as one entry per column or a single value for all of them. Each entry is a character count, "auto" to absorb the width left on the terminal, or None for no limit. Defaults to the max_width declared by ColumnSpec headers. Silently dropped by formats outside WRAPPABLE_FORMATS.

Return type:

click_extra.table.print_table(table_data, headers=None, table_format=None, sort_key=None, max_column_widths=None, **kwargs)[source]¶

Render a table and print it to the console.

ANSI codes carried by cell values and headers depend on the format:

Markup formats with native styling support (see STYLED_FORMATS) get them translated to the format’s own styling markup, unless color output is disabled (--no-color, NO_COLOR, …).
Other markup formats get them stripped from cell values before rendering, unless --color is explicitly forced on the command line.
Plain-text formats keep them raw, and defer to echo()’s sensitivity to the global colorization settings.

Parameters:

sort_key (Callable[[Sequence[str | None]], Any] | None) – Optional callable passed to sorted() as the key argument. When provided, rows are sorted before rendering.
max_column_widths (Sequence[int | Literal['auto'] | None] | int | Literal['auto'] | None) – Width limits, as one entry per column or a single value for all of them. Each entry is a character count, "auto" to absorb the width left on the terminal, or None for no limit. Defaults to the max_width declared by ColumnSpec headers. Silently dropped by formats outside WRAPPABLE_FORMATS.

Return type:

click_extra.table.serialize_data(data, table_format, *, default=None, root_element='records', **kwargs)[source]¶

Serialize arbitrary Python data to a structured format.

Unlike render_table() which expects tabular rows and headers, this function accepts any JSON-compatible data structure (dicts, lists, nested combinations) and serializes it to the requested format.

Only formats in SERIALIZATION_FORMATS are supported.

Parameters:

data (Any) – Arbitrary data to serialize (dicts, lists, scalars).
table_format (TableFormat) – Target serialization format.
default (Callable | None) – Fallback serializer for types not natively supported. Defaults to str, so Path and similar types are stringified automatically. Set to a custom callable for different behavior.
root_element (str) – Root element name for XML output.
kwargs – Extra keyword arguments forwarded to the underlying serializer (like sort_keys or indent for JSON).

Raises:

ValueError – If the format is not a serialization format.

Return type:

click_extra.table.print_data(data, table_format, *, default=None, root_element='records', package='click-extra', **kwargs)[source]¶

Serialize arbitrary Python data and print it to the console.

Wraps serialize_data() with user-friendly error handling for missing optional dependencies.

Parameters:

data (Any) – Arbitrary data to serialize.
table_format (TableFormat) – Target serialization format.
default (Callable | None) – Fallback serializer for custom types. Defaults to str.
root_element (str) – Root element name for XML output.
package (str) – Package name for install instructions in error messages.
kwargs – Extra keyword arguments forwarded to the underlying serializer.

Return type:

class click_extra.table.TableFormatOption(param_decls=None, type=EnumChoice('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'), default=TableFormat.ROUNDED_OUTLINE, expose_value=False, is_eager=True, help='Rendering style of tables.', **kwargs)[source]¶

Bases: ExtraOption

A pre-configured option that is adding a --table-format flag to select the rendering style of a table.

ctx.render_table(table_data, headers, **kwargs): renders and returns the table as a string,
ctx.print_table(table_data, headers, **kwargs): renders and prints the table to the console.

Where:

table_data is a 2-dimensional iterable of iterables for rows and cells values,
headers is a list of string to be used as column headers,
**kwargs are any extra keyword arguments supported by the underlying table formatting function.

init_formatter(ctx, param, table_format)[source]¶

Save the resolved table_format in the context’s shared meta.

The render_table() and print_table() context methods read it back at call time.

Return type:: None

click_extra.table.column_sort_key(header_defs, sort_columns=None, cell_key=None)[source]¶

Build a row sort key from the sort_columns a table actually carries.

Return type:: Callable[[Sequence[str | None]], tuple] | None

class click_extra.table.ColumnSpec(id, label, description='', max_width=None, optional=False)[source]¶

Bases: object

Rich description of a single column in a rendered table.

Three fields, all required-by-convention even though description defaults to empty so quick prototypes do not have to write a sentence for every column:

id: stable, snake_case identifier used by --columns to address the column, to key structured-format serializations, and to thread state through click_extra.context.COLUMNS.
label: the human-readable header shown at the top of the rendered table.
description: a MyST/Markdown blurb describing what the column represents. Used to auto-generate the column reference in the documentation.

A fourth, max_width, is purely optional presentation.

Note

Frozen + slots: instances are immutable and lightweight. Tuples of ColumnSpec are intended to be defined as module-level constants (like click_extra.parameters.ShowParamsOption.TABLE_HEADERS).

id: str¶: Stable, snake_case identifier addressing this column from CLI flags and code.

label: str¶: Human-readable header label rendered at the top of the table.

description: str¶

MyST/Markdown description of what the column carries.

Used to auto-generate the Available columns section in the docs via the show_params_columns_table MyST substitution. Plain text without inline markup is fine: links and emphasis are optional sugar.

max_width: int | Literal['auto'] | None¶

Width limit of this column, as a character count or AUTO_WIDTH.

Cells longer than the limit wrap onto several lines, in the formats able to render that (see WRAPPABLE_FORMATS). None, the default, lets the column take whatever width its widest cell needs.

Declaring the width here rather than passing a positional list to render_table() keeps it attached to its column, so it survives a --columns projection that drops or reorders columns.

optional: bool¶

Whether the column is left out of the table until --columns asks for it.

A column carrying long free-form prose costs every other column its width once it joins the default projection, which is a poor trade for a reader who did not ask for it. Marking it optional keeps it out of the unprojected table while leaving it addressable by ID, so a consumer that wants it (a structured-format export feeding a machine, typically) selects it explicitly.

click_extra.table.render_columns_markdown_table(columns)[source]¶

Render an iterable of ColumnSpec as a 2-column Markdown table.

Output shape:

| Column | Description |
| :--- | :--- |
| ``Label`` | description |
...

Suitable for inlining into MyST documents via myst_substitutions so the Available columns reference can be auto-generated from a single source of truth.

Return type:: str

click_extra.table.select_columns(columns, selected_ids)[source]¶

Filter and reorder columns according to selected_ids.

Return type:: tuple[ColumnSpec, ...]

click_extra.table.select_row(row, selected_ids, canonical_ids)[source]¶

Build a positional row by reading cells from row in the selection order.

Falls back to canonical_ids when selected_ids is empty / unset, so the row preserves its canonical column order in the absence of any user selection.

Return type:: tuple

class click_extra.table.ColumnsType(accepted_ids=())[source]¶

Bases: MultiChoice

Column-flavored alias of click_extra.types.MultiChoice.

Pins the comma separator and case-sensitive matching (column IDs are snake_case identifiers, not free-form strings), and renames the metavar fallback to COLUMNS instead of the generic MULTI. The accepted_ids constructor keyword is a column-flavored alias of MultiChoice.choices.

Initialize the type.

Parameters:

choices – the accepted values. When non-empty, convert() rejects unknown tokens with fail. When empty, the type behaves as a pure separator-aware parser and leaves validation to the consumer.
separator – the token boundary. Use any single character; this also drives the metavar rendering ([a<sep>b<sep>c]).
case_sensitive – when False, tokens match choices case-insensitively and the returned tuple holds the canonical (original-case) values from choices.

name: str = 'columns'¶: the descriptive name of this type

class click_extra.table.ColumnsOption(param_decls=None, columns=None, type=None, default=(), expose_value=False, is_eager=True, help='Restrict and reorder table columns, SQL SELECT-style. Comma-separated list of column IDs. Default: all columns in canonical order.', **kwargs)[source]¶

Bases: ExtraOption

A --columns option that lets users restrict and reorder table columns.

Accepts a comma-separated list of column IDs, SQL-SELECT-style:

$ my-cli --columns id,spec,value --params

Empty / unset means render every column in canonical order: the default behavior, indistinguishable from not passing --columns at all.

columns: tuple[ColumnSpec, ...]¶: Column registry this option advertises and validates against (may be empty).

init_columns(ctx, param, columns)[source]¶

Store the selected column IDs on the context for later projection.

Validation of the IDs against the registry happens inside convert(), before this callback runs, so this just threads the parsed selection onto the context.

Return type:: None

class click_extra.table.SortByOption(*header_defs, param_decls=None, columns=None, default=None, expose_value=False, cell_key=None, help='Sort table by this column. Repeat to set priority.', **kwargs)[source]¶

Bases: ExtraOption

A --sort-by option whose choices are derived from column definitions.

COLUMNS = (
    ColumnSpec("package_id", "Package ID"),
    ColumnSpec("package_name", "Name"),
    ColumnSpec("manager_id", "Manager"),
)


@command
@table_format_option
@columns_option(columns=COLUMNS)
@sort_by_option(columns=COLUMNS)
@pass_context
def my_cmd(ctx):
    ctx.print_table(rows, [col.label for col in COLUMNS])

@group
@sort_by_option("package_id", "package_name", "manager_id")
def my_cli():
    pass


@my_cli.command
def installed():
    print_table(rows, [("Package ID", "package_id"), ("Manager", "manager_id")])


@my_cli.command
def managers():
    print_table(rows, [("Manager", "manager_id"), ("Path", None)])

field_vocabulary¶

Whether definitions are bare column IDs, untied to any table layout.

In this mode init_sort() only publishes the selection on the context: the sort is resolved per table at print_table() time.

init_sort(ctx, param, sort_columns)[source]¶

Publish the row sort key on the context’s shared meta.

Return type:: None

click_extra.telemetry module¶

Telemetry utilities.

class click_extra.telemetry.TelemetryOption(param_decls=None, default=False, expose_value=False, envvar=None, show_envvar=True, help='Collect telemetry and usage data.', **kwargs)[source]¶

Bases: ExtraOption

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

The resolved value is stored in ctx.meta[click_extra.context.TELEMETRY], aligning with every other Click Extra option’s per-invocation context-meta storage pattern.

See also

set_telemetry(ctx, param, value)[source]¶

Reconcile the flag with DO_NOT_TRACK and store the result on ctx.meta.

Note

Return type:: None

click_extra.test_suite module¶

Declarative, black-box CLI test suites.

A test suite is a list of CLITestCase invocations: each runs a target command (a name, a command line, or a path to a binary) once with extra parameters, then checks its exit code and stdout/stderr against literal, substring, or regex expectations. Cases carry their own platform skip/only rules, so one suite runs across operating systems unchanged.

Suites are written in any list-capable configuration format and loaded with load_test_suite() (which picks the format from the file extension) or parse_test_suite() (which parses a serialized string). TOML and JSON are built in; YAML and the other SUITE_FORMATS need their matching click-extra[…] extra. run_test_suite() drives a list of cases against a target, parallelized per the resolved --jobs count (see click_extra.execution.run_jobs()) and reporting live progress through a click_extra.spinner.Spinner.

This is the black-box, subprocess-level complement to click_extra.testing.CliRunner, which drives a CLI in-process.

Todo

Tokenize a Windows command line with quoting/escaping support, like shlex does on POSIX. The str.split() fallback _split_args uses there only splits on whitespace, so a quoted argument such as --name "two words" is wrongly broken into three tokens. Use w32lex, the Windows counterpart to shlex.

click_extra.test_suite.SUITE_FORMATS: tuple[ConfigFormat, ...] = (ConfigFormat.TOML, ConfigFormat.JSON, ConfigFormat.YAML, ConfigFormat.JSON5, ConfigFormat.JSONC, ConfigFormat.HJSON)¶

Configuration formats a test suite can be serialized in, built-in ones first.

These are the formats able to represent a top-level list of case mappings, matched against a file’s extension by load_test_suite(). TOML and JSON parse with no extra dependency; the others each need their matching click-extra[…] extra. TOML has no bare top-level array, so a TOML suite lists its cases under a [[cases]] array of tables (see parse_test_suite()); the others use a bare list. INI (no nesting) and XML (no natural list representation) are excluded.

Per-format availability is resolved by ConfigFormat, so a format whose parser is not installed raises an ImportError pointing at its extra at parse time.

exception click_extra.test_suite.SkippedTest[source]¶

Bases: Exception

Raised when a test case should be skipped.

class click_extra.test_suite.CLITestCase(cli_parameters=<factory>, env=<factory>, unset_env=<factory>, skip_platforms=<factory>, only_platforms=<factory>, timeout=None, exit_code=None, strip_ansi=False, output_contains=<factory>, stdout_contains=<factory>, stderr_contains=<factory>, output_regex_matches=<factory>, stdout_regex_matches=<factory>, stderr_regex_matches=<factory>, output_regex_fullmatch=None, stdout_regex_fullmatch=None, stderr_regex_fullmatch=None, execution_trace=None)[source]¶

Bases: object

A single CLI test case: how to invoke the command and what to expect.

cli_parameters: tuple[str, ...] | str¶

Arguments and options appended to the command-under-test.

A plain string is split into arguments (on spaces on Windows, with shlex elsewhere); a list or tuple is used as-is.

env: dict[str, str]¶

Environment variables set on the command, over the inherited environment.

Applied to that one child process, never to the suite runner’s own environment, so cases stay independent under --jobs. See unset_env to take a variable away instead.

unset_env: tuple[str, ...] | str¶

Environment variables removed from the inherited environment.

A separate directive rather than a null value in env because TOML has no null literal, and a suite is as likely to be written in TOML as in YAML. Removing a variable that is not set is a no-op.

Platforms (or platform-group IDs) on which to skip this case.

Accepts extra_platforms identifiers such as linux, macos, windows, in any case, mixed freely with group IDs.

Restrict this case to these platforms; skip it everywhere else.

The mirror image of skip_platforms, using the same identifiers.

timeout: float | str | None = None¶

Seconds before the command is killed and the case fails as a timeout.

Falls back to the command’s --timeout default, then to no limit.

exit_code: int | str | None = None¶: Expected process exit code; the case fails on any other code.

strip_ansi: bool = False¶: Strip ANSI escape sequences from the captured output before matching.

output_contains: tuple[str, ...] | str¶

Substrings that must all be present in the combined output.

stdout_contains: tuple[str, ...] | str¶: Substrings that must all be present in stdout.

stderr_contains: tuple[str, ...] | str¶: Substrings that must all be present in stderr.

output_regex_matches: tuple[Pattern | str, ...] | str¶: Regexes that must each match somewhere in the combined output (searched, re.DOTALL). See output_contains for the merged-stream semantics.

stdout_regex_matches: tuple[Pattern | str, ...] | str¶: Regexes that must each match somewhere in stdout (searched, re.DOTALL).

stderr_regex_matches: tuple[Pattern | str, ...] | str¶: Regexes that must each match somewhere in stderr (searched, re.DOTALL).

output_regex_fullmatch: Pattern | str | None = None¶: Regex that must fully match the combined output, line by line. See output_contains for the merged-stream semantics.

stdout_regex_fullmatch: Pattern | str | None = None¶: Regex that must fully match stdout, line by line.

stderr_regex_fullmatch: Pattern | str | None = None¶: Regex that must fully match stderr, line by line.

execution_trace: str | None = None¶

Rendering of the command execution and its output.

Populated after the case runs, for inspection on failure; not a directive you set in a test suite.

property has_merged_output_directives: bool¶: Whether any output_* directive (merged stream) is set.

property has_separate_stream_directives: bool¶: Whether any stdout_* or stderr_* directive (separate streams) is set.

run_cli_test(command, additional_skip_platforms, default_timeout, work_directory=None)[source]¶

Run a CLI command and check its output against the test case.

The provided command can be either:

a path to a binary or script to execute;
a command name to be searched in the PATH,
a command line with arguments to be parsed and executed by the shell.

The case’s env and unset_env directives are layered over the inherited environment for this child process only.

Return type:: None

click_extra.test_suite.cases_from_data(data)[source]¶

Build CLITestCase instances from already-parsed suite data.

Raises:

ValueError – the suite is empty, a mapping suite omits cases, or a case uses unknown directives.
TypeError – the suite is not a list, or a case is not a mapping.

Return type:

click_extra.test_suite.parse_test_suite(suite_string, fmt=ConfigFormat.YAML)[source]¶

Parse a serialized test suite string into CLITestCase instances.

Raises:

ValueError – the suite is empty, fmt cannot express a suite, a mapping suite omits cases, or a case uses unknown directives.
TypeError – the suite is not a list, or a case is not a mapping.
ImportError – the format’s optional parser is not installed.

Return type:

click_extra.test_suite.load_test_suite(path)[source]¶

Read a test suite file and parse it by the format of its extension.

Raises:

ValueError – the file extension matches no suite format.
ImportError – the matched format’s optional parser is not installed.

Return type: