Upstream

Click Extra was born as a collection of patches for unmaintained or slow-moving click-contrib addons. Over time, many of these fixes were contributed back upstream, and the project grew into a significant contributor to the Click ecosystem.

This page tracks click-extra’s relationship with its upstream dependencies: code contributed back, issues reported, workarounds provided, and features that upstream declined.

Code contributed upstream

PRs authored by the click-extra maintainer and merged into upstream projects.

click

Default and sentinel handling:

• #3137 - Provide altered context to callbacks to hide UNSET values as None

• #3068 - Hide Sentinel.UNSET values for defaults processed by Context.invoke

• #3048 - Regroup sentinels

• #3030 - Differentiate absence of value and value of absence for default and flag_value arguments

• #2956 - Fix reconciliation of envvar with default, flag_value and type parameters for flag options

• #3225 - Fix callable flag_value being instantiated when used as a default

• #3224 - Hide Sentinel.UNSET values as None in lookup_default()

• #3299 - Fix speculative empty string check

• #3240 - Reduce blast-radius of UNSET in default_map

• #3248 - Reorder ParameterSource

• #3239 - Reconcile default value passing and default activation

Help system:

• #2811 - Fix eagerness of help option generated by help_option_names

• #2840 - Move --help option defaults from its class to its decorator

• #2563 - Deduplicate --help option definition

• #2517 - Split generation of help extra items and rendering

• #3328 - Show default string in prompt

• #3250 - Mark make_default_short_help as private API

Enum and Choice support:

• #3004 - Fix rendering of Enum choices’ default

• #3053 - Add more tests on Enum rendering

Testing:

• #2523 - Keep track of <stderr> and <stdout> mix in CliRunner results

• #3151 - Randomized and parallel tests

• #3238 - Fix pager test leaks

• #3235 - Allow debugger interactions in tests

• #3012 - Add two new tests for Parameter.__init__

• #3223 - Add cross-reference to tests from test_defaults.py

• #2680 - Fix closing of callbacks on CLI exit

• #3244 - Expose original file descriptor in CliRunner

Documentation:

• #3330 - Path normalization documentation clean-up + shlex.split extensive tests

• #3245 - Document and fix command sanitizing with shlex.split

• #3049 - Tone-down the case of default=True for flags in documentation

• #2815 - Add links to third-party projects enhancing Click

• #2534 - Remove Python 2 compatibility code from docs

• #3333 - Click-specific contribution guidelines

python-tabulate

• #151 - Add new rounded/simple/double _grid/_outline formats

• #183 - Implement heavy/mixed _grid/_outline formats

• #204 - Fix multiline folding of table formats rendering unseparated cells

• #410 - Fix alignments in github tables

pygments

• #1529 - Add missing prompt color for Solarized style

furo

• #657 - Use the reference HtmlFormatter class defined on PygmentsBridge

• #426 - Allow GitHub edit link without Read the Docs

cloup

• #153 - Use the same (Deprecated) label as in Click

pallets-sphinx-themes

• #62 - Render .. click:run:: code blocks with shell-session lexer

• #69 - Remove Python 2 compatibility code

click-contrib/sphinx-click

• #117 - Add reference to complementary Click CLI documentation helpers

• #118 - Typo fix

click-contrib/click-log

• #24 - Add missing string interpolation in error message

• #4 - Add Trove classifiers

• #2 - Fix parsing of unicode logs

Upstreamed from click-extra

Issues that click-extra solved with local workarounds first. The fix was later contributed upstream and the workaround removed from click-extra.

click

• #2811 / #2563 - Help option eagerness and deduplication. click-extra had custom HelpOption fixes; contributed upstream and removed locally.

• #2680 - Callbacks not properly closed on CLI exit. click-extra patched Option to force-close; contributed the fix upstream.

• #2523 / #2522 - CliRunner conflating stderr and stdout. click-extra backported the fix before the Click release.

• #2516 / #2517 - Help extra items (default, envvar, required) were computed and rendered together. click-extra needed them split to inject colorization; contributed the refactor upstream.

cloup

• #160 / #162 - cloup.Group ignored command_class for subcommands. click-extra worked around it; Cloup fixed it in a later release.

• #177 - cloup.Color could not be rendered by Sphinx. click-extra had an exception handler; Cloup fixed the import.

Addressed by click-extra

Issues that remain open or unfixed upstream. click-extra provides the solution.

Color and terminal support

click-extra implements NO_COLOR, FORCE_COLOR, and full help colorization with a theme system, addressing long-standing Click gaps:

• click#558 - Support FORCE_COLOR in click.echo

• click#1090 - Color output from CI jobs

• click#1498 - Support for NO_COLOR proposal

• click#2207 - Support NO_COLOR environment variable

• click#2111 - Context.color = False doesn’t override echo(color=True)

• click#2110 - testing.CliRunner.invoke cannot pass color for Context instantiation

• click-help-colors#17 - Highlighting of options, choices and metavars

• cloup#95 - Highlights options, choices and metavars

• cloup#97 - Styling metavars, default values, env var, choices

Terminal captures as SVG

click-extra’s screenshot command renders a captured terminal to SVG with its own click_extra.screenshot.render_svg(). It was built on Rich’s Console.export_svg() until 9.0.0, which is where these came from: everything below is a defect the exported image carried, reported upstream and still unfixed.

Open upstream, and fixed here:

• rich#3576 - Underscores on the last captured line are clipped when exporting to SVG: the terminal’s clip path is computed as (rows + 1) × line_height - 1, one pixel shorter than the text it contains, which cuts the descenders off the last line. Reported in 2024 with the fix named in the report; rich#3611 and rich#3991 both propose it and neither is merged, so rich 15.0.0 still ships it. render_svg sizes the clip to the text block.

• rich#2742 - SVG font rendering too narrow for Asian language: a run’s textLength is computed from its character count while its column advance uses terminal cells, so the two disagree for every glyph that is not exactly one cell. The error runs both ways. Chinese, Japanese, Hangul, fullwidth Latin and emoji are drawn at half their width and stack on each other; a decomposed éàü is drawn at twice its width, and a zero-width-joiner family emoji at two and a half times. Open since 2023. render_svg sizes both from click_extra.screenshot.cell_width().

• rich#2536 - Can we fix this render glitch in SVG output?: box-drawing characters do not meet cleanly, which the maintainer answers would need replacing them with drawn shapes. Open since 2022, and not addressed here either: click-extra’s tables and command tree draw the same characters.

Also carried by every image Rich exports, and dropped here:

• The exported document references one clipPath per line but defines them for every line but the last, so the final row of every capture carries a dangling reference. A browser ignores it, a strict SVG 1.1 renderer drops the element it is attached to. render_svg clips the text block as a whole, which removes the per-line paths and the failure mode with them.

• The stylesheet carries two @font-face rules pointing at a CDN, so a committed image reaches the network to render as intended, and falls back silently offline or behind a content-security policy. render_svg names a font stack and embeds nothing, which is also what rich#2153 and rich#2526 run into from the other end.

• A run’s inter-column padding is written inside its <text> element, so a column only lands correctly where the renderer both honors textLength and resolves the font: librsvg, and through it rsvg-convert and ImageMagick, does neither (rich#2153, rich#3034). render_svg starts each run on its own column.

• Every line ends with a <text> element containing only a newline, drawing nothing. Removing those, the per-line clip paths and the webfont rules together took this documentation’s 21 committed captures from 451 KB to 247 KB.

Themes and palettes

click-extra ships seven built-in themes (dark, light, dracula, monokai, nord, solarized_dark, plus a monochrome manpage) and covers every surface an end user reaches for: the --theme flag, a machine-wide CLICK_EXTRA_THEME variable next to the per-CLI <CLI>_THEME, and — alone in the Click ecosystem — new themes and overrides declared in the CLI’s own --config file ([tool.<cli>.themes.<name>]). Click itself has no theme system (formatter-level customization is still WIP upstream), and the competing rich help layers stop at Python and environment variables:

• click#561 - Add Custom Formatter System: open since 2016, the prerequisite for a Click-native theme API.

• click#3097 - WIP: Help page customization low level api: open PR exploring the formatter customization Click maintainers committed to in #561.

• rich-click#219 - Colour themes (can be set by user): closed completed in August 2025; rich-click now ships themes settable via RICH_CLICK_THEME env var or Python config, but not via the wrapped CLI’s own configuration file. CLICK_EXTRA_THEME follows the same shape, one variable for every CLI in the ecosystem.

• rich-click#311 - Using themes outside click: open follow-up showing the demand for richer theme reuse.

Configuration validation

click-extra’s config pipeline exposes an extension hook (ConfigValidator) so apps can validate data-keyed sub-tables ([tool.<cli>.managers.<id>], [tool.<cli>.plugins], …) inside the same strict-check pipeline that polices CLI-flag-bound keys. --validate-config collects every error before exiting and surfaces all failures with the same rooted ValidationError shape.

This is click-extra’s own design rather than an answer to a documented upstream issue: Click maintainers have closed every config-file proposal as out of scope (#1753, #386, #42, #971) and deferred to external packages, so validation of those external config files lives wherever each package chose to put it. The closest related upstream gap is click_config_file#11 (listed under Configuration files above): “warn when providing unsupported options in the config file?”: open since 2018 in an unmaintained package.

Configuration files

click-extra’s config module replaces the functionality of several unmaintained packages, with multi-format support (TOML, YAML, JSON, INI, XML), pyproject.toml integration, and a precedence chain:

• configmanager#164 - Should be used?

• configmanager#152 - XML format

• configmanager#139 - TOML format

• click_config_file#26 - Don’t require FILE for --config when implicit=False?

• click_config_file#11 - Warn when providing unsupported options in the config file?

• click_config_file#9 - Additional configuration providers

• click-configfile#9 - Inquiry on Repo Status

• click-configfile#8 - Exclude some options from config file

• click-configfile#5 - Interpolation

• click-configfile#2 - Order of configuration file and environment variable value

Version option

click-extra’s VersionOption adds template variables for git metadata (branch, hash, date, tag), environment info, and Python/OS details, with pre-baking for compiled binaries:

• click#2324 - Can’t pass click.version_option() to click.MultiCommand(params=)

• click#2331 - version_option module name and package name are not equivalent

• click#1756 - Path and Python version for version message formatting

Environment variables

click-extra auto-generates environment variables for all options and adds show_envvar as a global context setting:

• click#2483 - Missing auto-generated environment variables in help screen & case-sensitivity

• click#2313 - Add show_envvar as global setting via context_settings (like show_default)

Logging

click-extra’s logging module replaces the unmaintained click-log package:

• click-log#29 - Log level is leaking between invocations: hack to force-reset it

• click-log#30 - Add a no-color option, method or parameter to disable coloring globally

Progress spinner

click-extra’s Spinner is a thread-animated, indeterminate progress spinner for blocking work of unknown duration. It supersedes the click-spinner package, last released in 2020 and openly looking for a maintainer since 2022. By design it resolves the issues and pull requests still open or rejected against that package:

• click-spinner#27 - Support for more spinner types and custom spinners: closed unmerged over maintenance concerns; click-extra accepts any frames sequence and ships a 90-entry SPINNERS catalog ported from cli-spinners (a superset of the molovo/revolver set this PR proposed), including the multi-character animations the PR had to drop because click-spinner’s backspace renderer could not erase them.

• click-spinner#33 - PEP 561 compatible (inline types): closed unmerged and redirected to typeshed; click-extra is fully annotated and ships py.typed.

• click-spinner#34 - Feature request: spin clockwise / click-spinner#35: open issue, abandoned PR; click-extra exposes a reverse flag.

• click-spinner#36 - Spinner left last symbol on cmd / click-spinner#37: open; click-extra erases the line with \r\x1b[K rather than a non-destructive \b that lingers in terminals like VS Code.

• click-spinner#41 - Fix output in corner cases: open; click-extra always erases on exit and never rings the bell on a disabled or redirected stream.

• click-spinner#42 - Printing to stdout breaks the spinner: open; click-extra defaults to stderr so stdout data stays clean, and its echo() method prints above the animation without corrupting it.

Progress bar

click-extra’s progressbar is a drop-in for click.progressbar that also repairs a rendering bug in Click’s own bar:

• click#3571 - click.progressbar doesn’t show full completion when using show_pos=True combined with update_min_steps: open; a bar whose length is not a multiple of update_min_steps freezes its position below completion (14/20 instead of 20/20). click-extra’s wrapper flushes the trailing sub-threshold steps on finish so the final position renders.

Option parsing

• click#2779 - Wrong error message when wrong multicharacter short option is passed

Multi-value options

click-extra’s MultiChoice type parses a single comma-separated token into a tuple of validated values: the pick-many counterpart to click.Choice, with a rendered [a,b,c] metavar that mirrors click.Choice’s [a|b|c] and per-value highlighting in the help colorizer. The canonical Click idiom for this is multiple=True + Choice, which requires the flag to be repeated (--tag a --tag b --tag c); SQL SELECT a, b, c-style syntax has been requested upstream multiple times and not shipped:

• click#2771 - Allow nargs=-1 in options with a non-whitespace separator: open, exactly the same feature request.

• click#2537 - Allow nargs=-1 for click.option: closed as not planned, the earlier space-separated variant.

The --columns option on --params is the headline consumer; the type is also exposed at the package root for arbitrary tags / categories / modes use cases in downstream CLIs.

Normalized arguments

• click#1279 - Provide access to a normalized list of args that will result in the same params

Command tree

click-extra ships a --tree flag on every command, the standalone @tree_option decorator, and a wrap --tree mode that prints the subcommand hierarchy of any Click CLI without running it. That covers the whole checklist of the tree view rich-click has planned for its 1.10 release:

• rich-click#269 - --tree integration: open since August 2025, filed by rich-click’s maintainer after the author of the treeclick plugin reached out. It proposes a @click.tree_option() decorator, a rich-click --tree [cmd] mode working on any Click CLI, and opt-in wiring through context_settings: the same three surfaces click-extra exposes (default option, standalone decorator, CLI wrapper).

• rich-click#270 - Subcommand tree view: first-concept PR from treeclick’s author, self-described as rough and stalled since September 2025.

• rich-click#275 - 1.10 roadmap: tracks the --tree option and @click.tree_option() among the planned features.

One design difference: treeclick embeds the tree inside --help output through custom TreeGroup/TreeCommand classes, and the older click-command-tree package registers a tree subcommand on the user’s group, walking the static commands mapping. click-extra renders the view behind a dedicated eager flag, like --man and --params: the plain help screen stays untouched, a flag cannot collide with the user’s own subcommand namespace, and the live-context walk includes lazily-registered commands.

Shell completion

click-extra exports any Click command tree to a Carapace completion spec, so a CLI gets native completion across every shell Carapace supports (Bash, Zsh, Fish, Nushell, PowerShell, Elvish, and more) from a single generated file. Click’s built-in completion is wired per shell and installed by hand; one spec covers them all:

• click#3188 - Native Carapace Support: closed as out of scope for the core framework, with the maintainers suggesting a separately-released project. click-extra is that project.

ANSI rendering in documentation

click-extra provides ANSI-capable session lexers, an HTML formatter, and Sphinx integration for rendering ANSI-colored CLI output in documentation, with 24-bit true-color rendering enabled by default:

• pygments#1148 - Can’t format console/shell-session output that includes ANSI colors

• pygments#477 - Support ANSI (ECMA-48) color-coded text input

• pygments-ansi-color#31 - Support ANSI styles

• pygments-ansi-color#32 - Set default style (merged)

• pygments-ansi-color#33 - AnsiHtmlFormatter and ANSI-aware shell-like lexers

• pygments-ansi-color#34 - Add color swatches (closed)

• pygments-ansi-color#35 - Add AnsiHtmlFormatter (open, unmaintained upstream)

• nbsphinx#852 - Sphinx & Pygments integration for ANSI rendering

• kitty#5482 - ANSI shell sessions in Sphinx documentation

• sphinx-contrib/ansi#9 - ANSI Codes in output

• MyST-Parser#845 - Add an extension to support GitHub alerts

Sphinx click:source and click:run directives

click-extra maintains and extends the click:source/click:run directives originally from pallets-sphinx-themes:

• pallets-sphinx-themes#61 - Move .. click:example:: and .. click:run:: implementation to sphinx-click

• sphinx-click#110 - Supports .. click:example:: and .. click:run:: directives

• cloup#92 - Use sphinx directive to generate output of full examples in the docs

Sphinx python:* directives and live document rendering

The python:source, python:run, python:render, python:render-myst, and python:render-rst directives extend the click:* family to arbitrary Python (no Click CLI required). The render* variants parse the captured stdout as live document content: generated tables, headings, admonitions, and cross-references become first-class document nodes rather than a code block. This replaces the docs_update.py regenerator + marker-region pattern that many downstream click-extra-consuming projects use (Meta Package Manager, Mail Deduplicate, …), so the rendered HTML is always current at build time without a separate generation step. And when the generated Markdown should also live in the committed source (rendering on GitHub, reviewable in diffs), the :mirror: flag keeps a marker-delimited copy below the fence, refreshed by click-extra refresh-directives alongside the {matrix} blocks.

The click:* half of this story remains stuck upstream: the directives still live in pallets-sphinx-themes despite open requests to move them where Click users actually look for them, and MyST integration is unfinished:

• sphinx-click#158 - Move custom directives into Sphinx-click: open, acknowledged by maintainers.

• sphinx-click#127 - Support myst-parser: open, click directives still RST-only upstream.

• pallets-sphinx-themes#61: open since 2022, also flagged in the previous section.

The python:* half (rendering executed Python output as live document content) is click-extra’s own design rather than an answer to a single upstream ticket.

Declined by upstream

PRs and features rejected by upstream maintainers. click-extra provides the functionality regardless.

python-tabulate

• #261 - Add support for alignments in Markdown tables

• #260 - Renders GitHub-Flavored Markdown tables in canonical format

click-extra maintains a local patch for GitHub-Flavored Markdown table alignment.

dbcli/cli_helpers

• #79 - Replace local tabulate formats with those available upstream

Open upstream

PRs and issues still pending upstream.

click

• #3036 - Add support for set and frozenset as native Click types

pygments

• #2716 - Add examples to all lexers

• #2415 - Mermaid syntax highlighting

• #2414 - Pure-CSS line numbering

python-tabulate

• #426 - Respect padding in pipe/github separator rows

executablebooks/MyST-Parser

• #1119 - Batch syntax for consecutive same-type directives

• content_offset is inflated by one when a directive’s option block precedes a body ending in blank line(s), shifting the reported source line of every body element. Worked around for myst-parser <= 5.1.0 in click_extra.sphinx.click._myst_content_offset_inflation; a root-cause fix is prepared upstream. (The earlier block_text alignment #1048 was superseded and merged as #1164, still unreleased.)

• The open rework #1175 makes a directive’s content_offset document-relative (the rST convention) but does not fix the inflation above. When it releases, click_extra.sphinx.click.ClickDirective.abs_content_offset collapses onto its rST branch (content_offset verbatim) instead of adding directive.lineno; see the sketch tracked for that migration.

click-contrib/click-log

• #18 - Add trailing dot to help text