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

Themes and palettes

click-extra ships seven built-in themes (dark, light, dracula, monokai, nord, solarized_dark, plus a monochrome manpage) and is the only Click-ecosystem library that lets end users define new themes or override existing ones from the CLI’s --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 expose themes through Python or environment variables, not the CLI’s own configuration file:

• 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.

• 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.

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 --show-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

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.

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

• #1048 - Aligns directive’s block_text content to rST’s

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

click-contrib/click-log

• #18 - Add trailing dot to help text