ChangelogΒΆ

10.3.1.dev0 (unreleased)ΒΆ

Warning

This version is not released yet and is under active development.

10.3.0 (2026-11-18)ΒΆ

  • Breaking: Raise the Click floor to 8.5.1, dropping the shims for the spec of hidden options and the envvar of error hints.

  • Breaking: Raise the myst-parser floor of the sphinx extra to 5.2.0, dropping the shim for the content_offset that older releases over-counted.

  • Breaking: DependencyMatrixGroup gains a trailing last_date field, so it no longer unpacks into four values.

  • Deprecated: The tabs-vertical class of sphinx-design tab-sets now logs a click_extra.tabs_vertical warning and stops working in 11.0.0. Set the :orientation: vertical option of sphinx-design 0.8.0 instead.

  • Deprecated: ERASE_IN_LINE, PARTIAL_CSI_RE, SELECT_GRAPHIC_RENDITION and TerminalScreen of click_extra.capture.recording now warn and stop resolving in 11.0.0. Import TerminalScreen from click_extra.capture.terminal instead.

  • Add a report_url argument to @command and @group: an error the CLI has no rule for then ends the run with a bug report to paste into an issue.

  • Add log_report(), which logs a bug report of the same shape without ending the run, and describe_error(), compact_frames() and culprit_function() to fill one in.

  • Record full-screen programs with screenshot --record and record_command(): the screen now follows cursor addressing, scroll regions, line drawing and the alternate screen.

  • Keep a style per cell in TerminalScreen, so a redraw over the start of a row keeps the rest of that row.

  • Run a recorded command with TERM=xterm-256color, and note a screen only once its redraw settles, so no frame shows a half-drawn screen.

  • Draw each background and run of text that frames of an animated SVG capture share once, timed over those frames, which shrinks recordings up to three times.

  • Add --palette to screenshot, reading a Windows Terminal or iTerm2 color scheme, and --font to screenshot and snippet, naming the fonts a capture asks for.

  • Add the :screenshot-palette: and :screenshot-font: directive options, which match --palette and --font.

  • Add --start and --end to screenshot --record, and :screenshot-start: and :screenshot-end: to the directives, to keep one slice of a recording.

  • Add read_palette(), parse_font_stack(), start_at() and end_at() to the Python API, with matching palette, font_stack, start and end arguments of record_and_render().

  • Send SIGTERM to a run_cli child that outlives its timeout, and SIGKILL only after a grace period, so sudo can forward the first to the command it escalated.

  • In a dependency compatibility matrix, show – instead of βœ… for a major that came out after the last release of a superseded range.

  • Let the default_options_uncolored_help and default_options_colored_help regexes match the help screens of Click 8.6.0, which no longer breaks a line after a hyphen.

  • Fix links to release anchors, like changelog.md#v1-4-2, failing with myst.xref_missing under myst-parser 5.2.0 when headings take their slug from make_id.

  • Fix prep_path() opening - past a replaced sys.stdout, like Click’s CliRunner(capture="fd"), which kept its output out of click:run blocks.

  • Fix --export-config writing UNSET instead of null for a parameter without a default on a plain Click command.

  • Fix format_cli_prompt() and the run_cli logs showing a variable to unset as NAME=None, which a pasted copy sets: the line now opens on env -u NAME.

  • Fix unpickling the NO_CONFIG and VCS sentinels, which raised ValueError: <object object> is not a valid Sentinel.

  • Fix a lone XML element naming a multi-value option, which failed with Value must be an iterable.: it now reads as a one-item list.

  • Skip the process-tree tests where the process table does not list the test process, like in the MacPorts build sandbox.

  • List hjson, pyyaml and tomlrt in the test dependency group: the test suite needs them, so a distribution build must install them.

10.2.0 (2026-11-06)ΒΆ

Note

10.2.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Deprecated: tile_runs() and TILE_RUN of click_extra.capture.svg, which captures no longer use, now warn and stop resolving in 11.0.0.

  • Add the click_extra_release_anchors Sphinx setting, which anchors each changelog release on its version, like #v1-4-2, in place of a positional #idN.

  • Highlight the row and column under the pointer in the two-axis tables of a Sphinx build, and make each one-link cell clickable as a whole.

  • Tint the cells of two-axis tables in Sphinx builds by state: green for βœ…, red for ❌ and grey for –.

  • Add the tabs-vertical class for sphinx-design tab-sets, which stacks their labels down a left rail, and use it on the install page.

  • Add click_extra.sphinx.announcement.years_since(), which counts the whole years from a date to the day of the build, for a banner like β€œmaintained for 5+ years”.

  • Keep the mermaid_d3_zoom of sphinxcontrib-mermaid off the autoclasstree diagrams of a Sphinx build, so the mouse wheel scrolls the page over them.

  • Sign the linkcheck requests of a Sphinx build to github.com with GITHUB_TOKEN when it is set, release downloads excepted.

  • Add the documentation site to the package metadata, so PyPI links to it.

  • Trim matrix tables to the support envelope, which can leave out the oldest release ranges, then the oldest versions no remaining range supports.

  • Add the full-history option to the matrix directive and marker, which keeps every release range.

  • Add the <!-- envelope --> region, which refresh-directives fills with the dated obsolete bounds of the support envelope across the axes it names.

  • Mark a dependency release published after a matrix range was replaced as – for that range, like a Python that did not exist yet.

  • Read matrix column headers from their newest bound, like 9.4.x ← 9.3.4, while the columns run newest first.

  • Fix Sphinx builds publishing sphinx.ext.viewcode pages that no documented object links to, one per such module on a parallel read.

  • Fix Sphinx pickling the whole build environment into the doctree of each page holding an {eval-rst}, python:render-rst or python:render-myst block.

  • Fix MyST docstrings merging two inline code spans when the first ends in a role-shaped word, or in punctuation before an _ span.

  • Fix MyST docstrings breaking a double-backtick code span that holds single backticks, which Sphinx reported as an unterminated inline literal.

  • Fix a dependency matrix listing the development version that uv.lock locks from a git branch as a column, like 8.5.0.dev0.

  • Fix a re-spelled floor-only requires-python ending its matrix range early, which left out the Pythons released later in that range.

  • Fix the runner pytest fixture leaving XDG_CACHE_HOME unpinned, so get_cache_dir() resolved to the cache of the user running the tests.

  • Fix SVG and HTML captures leaving a band between stacked rows of block characters like β–€β–„β–ˆ, which are now drawn as rectangles filling their cell.

  • Fix Braille patterns, like spinner frames, in SVG and HTML captures overflowing their column when the font lacks Braille: they are now drawn as dots.

  • Fix seams between box-drawing characters in SVG and HTML captures, which are now drawn as lines meeting at every join.

  • Fix the social card image of the documentation, and add canonical links, a sitemap and a sidebar logo readable in dark mode.

  • Replace the benchmark’s 🟑 mark with πŸͺ« and its N/A with a blank cell, and grade πŸͺ« two cobra cells that rely on Viper.

  • Document the :force: option of click:run: it highlights output its lexer cannot parse, and logs no Sphinx warning.

  • Document the accessibility, carapace, context, layout, mkdocs, styling, theme and tree modules in the API reference.

  • Add GNU Guix, MacPorts and openSUSE Tumbleweed install instructions, and a man pages section, to the installation page.

10.1.1 (2026-11-02)ΒΆ

Note

10.1.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Deprecated: click_extra.blocks imports again, as an alias of click_extra.markdown.blocks that warns on each name it serves, until its removal in 11.0.0.

10.1.0 (2026-11-02)ΒΆ

Note

10.1.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Export MissingExtraError, env_copy() and machine_envvars_apply() from the package root, so they import as from click_extra import ....

  • Add click_extra.layout.number_frames(), which numbers each frame of an animation at the gutter width of the tallest one.

  • A subcommand section of a configuration file leaves the keys it does not set to context_settings["default_map"], as root keys do.

  • click-extra snippet reads a source from standard input as UTF-8, like a source file.

  • Fix cascade=True losing the keys a less local file sets in a subcommand section that a more local file also defines.

  • Fix the Config file column of --params naming the wrong file for a key in a cascade of three or more files.

  • Fix the Config file column of --params printing a remote configuration URL with a slash missing, like https:/example.com/basket.toml.

  • Fix --help and man pages printing a --config URL default with a single slash after its scheme.

  • Fix unpatch_click() to restore the default theme that patch_click() replaced, and keep the default when patch_click() set no theme.

  • Fix the xml format writing invalid XML for a name like 0 or apple pie in tables and serialize_data(), and dropping columns under numeric headers.

  • Fix click-extra screenshot ending in a traceback when the command it captures cannot start: it now exits with an error message.

  • Fix click-extra screenshot --timeout ending in a traceback when the command outlives it: it now exits with an error message.

  • Fix click-extra snippet ending in a traceback on a non-UTF-8 source, and emptying the output file when that source is stdin.

  • Fix record_command() leaving both ends of its pseudo-terminal open when the command it records cannot start.

  • Fix animated captures with line numbers moving every row one cell right on the frames that reach 10 lines.

  • Fix --help-format markdown writing &, < and > as raw HTML, which hid text like <stdout> in a browser.

  • Fix --tree and man pages keeping Click’s \b marker when a command’s first paragraph opens with it.

  • Fix the click:tree summary table cutting each command description at 45 characters and hiding the cut.

  • Fix a | in a click:config default value splitting its row of the summary table.

  • Fix click:config table links missing the section of a key with accented letters or leading digits.

  • Fix refresh-directives and Sphinx builds skipping a <!--mirror-src comment that has no space after <!--.

  • Fix linkcheck reporting every link of the click-extra-manpages directive as broken: only an HTML build writes the pages they point at.

10.0.0 (2026-11-01)ΒΆ

Note

10.0.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Breaking: Drop Python 3.10, past its end of life: click-extra now requires Python 3.11 or newer.

  • Breaking: Raise the floors of Click to 8.5.0, Cloup to 4.0.0, tabulate to 0.10 and extra-platforms to 14.0.0, dropping the shims older releases needed.

  • Breaking: Regroup the modules into the capture and markdown packages and split the largest ones. Every name the package root exported in 9.x still imports from it, so prefer it to module paths.

  • Breaking: Move screenshot, screenshot_svg, screenshot_html, screenshot_presets, snippet and recording into click_extra.capture, as screenshot, svg, html, presets, snippet and recording.

  • Breaking: Move Chrome, its defaults and the paint constants like NO_PAINT to capture.presets, and parse_hold() and parse_pause() to capture.svg. The capture format_from_path() becomes CaptureFormat.from_path().

  • Breaking: Move blocks to click_extra.markdown.blocks, merge myst_converter and rst_to_myst into click_extra.markdown.myst, and move theme_docs to click_extra.sphinx.theme_docs.

  • Breaking: FenceSpan gains an end field, so it no longer builds from two arguments or unpacks into two values.

  • Breaking: Move the helpers of click_extra.parameters, like ParamStructure and search_params(), to param_tools, and ShowParamsOption with render_params_table() to show_params.

  • Breaking: Move Context and POSIXLY_CORRECT_ENVVAR from click_extra.context to click_extra.commands, and the table options, ColumnsType and column_sort_key() from click_extra.table to click_extra.table_options.

  • Breaking: Move JobsOption, JobCount, resolve_jobs(), run_jobs() and run_lanes() to click_extra.jobs, and the version resolvers like env_summary() to click_extra.version_facts.

  • Breaking: Move OperationTrail and trail_line() to click_extra.trail and progressbar() to click_extra.progress, out of click_extra.spinner.

  • Breaking: Split config.option into config.discovery and config.export, and sphinx.click into sphinx.click_runner and sphinx.click_reference.

  • Breaking: Move open_ansi() from click_extra.styling to the new click_extra.ansi module, along with the escape and palette helpers styling kept private.

  • Breaking: Move read_project_scripts(), entry_point_package(), locate_package_root(), discover_package_init_files() and detect_source_package() to click_extra.project. detect_source_package() now takes the project directory.

  • Breaking: Remove the module aliases deprecated in 9.x, like theme.nocolor_theme and table.select_columns. Import each name from the module its warning named.

  • Breaking: Remove the deprecated allow_query, merge_streams, unique and enabled arguments, color="forced", and the window arguments of render_html().

  • Breaking: Remove the is_root, default_opts and inherited_opts arguments of extract_carapace_command(), which had no effect.

  • Breaking: Remove the public compiled patterns blocks.OPTION_LINE_RE, the *_RE constants of myst_converter, myst_converter.FENCE_OPEN_RE and command_doc.OVERSTRIKE_RE, which strip_overstrike() replaces.

  • Breaking: Remove MAN_INSTALL_DIR, CARAPACE_SPECS_DIR, PARSER_SUPPORT and SQLITE_SUPPORT: install directories resolve when called, and ConfigFormat.enabled probes a parser on first use.

  • Breaking: Remove pytest.skip_naked, command_doc.CLICK_EXTRA_URL, credit_segments(), run_paint(), preset_palette() and the CAPTURE_BACKGROUND-style color constants, and make format_param_row() private.

  • Breaking: click_extra.sphinx no longer re-exports the blocks helpers and the capture configuration names, and click_extra.config no longer re-exports ClickExtraConfig, TestSuiteConfig and PrebakeConfig.

  • Breaking: Remove click_extra.sphinx.alerts and MYST_NATIVE_ALERTS_VERSION. The sphinx extra now requires myst-parser 5.1: list alert in myst_enable_extensions to render GitHub alerts.

  • Breaking: Remove the jsonc extra and the json-with-comments dependency behind it: JSONC is now built in, its comments and trailing commas stripped in-house before json reads the file.

  • Breaking: Remove the xml extra and the xmltodict dependency behind it: XML is now built in, read with the standard library’s expat parser and written in-house, with the same @attribute, #text and repeated-element conventions.

  • Breaking: Remove click_extra/themes.toml: built-in themes live in theme.py and build on first lookup, so BUILTIN_THEMES and get_theme_registry() return mappings, not dict instances.

  • Breaking: Merge color.COLOR_WHEN and spinner.LIVE_MODES into color.WHEN, and rename CaptureBackground to color.TerminalBackground, a StrEnum whose members equal "dark" and "light".

  • Breaking: Replace MAN_FORMATTERS and sphinx.manpages.HTML_RENDERERS with one command_doc.MAN_TYPESETTERS table.

  • Breaking: The capture functions take one chrome=Chrome(...) instead of its fields, and CHROME_FIELDS and fold_chrome_arguments() are gone.

  • Breaking: render_html() takes a resolved palette like render_svg(), and no longer takes watermark_url.

  • Breaking: Table headers and --sort-by column definitions no longer accept a (label, column_id) tuple. Pass a ColumnSpec instead.

  • Breaking: ColumnsType takes its column IDs as choices, like MultiChoice, whose get_metavar() now takes Click’s (param, ctx) signature.

  • Breaking: TimerOption.print_timer() takes the start time of the run it reports, and VersionOption raises TypeError instead of ValueError for an unknown key in fields or styles.

  • Breaking: print_table() and print_data() raise output.MissingExtraError, a ClickException, instead of SystemExit when an optional dependency is missing.

  • Breaking: convert-to-myst and detect_source_package() refuse a console script naming several functions, as wrap does.

  • Breaking: A MyST docstring fence closes on any bare run at least as long, so a nested fence needs a longer outer one.

  • Breaking: Report a malformed themes table under the invalid_theme and invalid_theme_shape codes, in snake case like the other validation codes.

  • Breaking: ctx.meta["click_extra.conf_source"] and the locations of click_extra.conf_sources hold a remote configuration’s URL as a str, instead of a boltons URL object.

  • Breaking: Remove the {env_info} version field, its click_extra.env_info context key and its JSON dump in --verbosity DEBUG logs. Append env_summary() to a version message for the interpreter and the platform in one line.

  • Breaking: A list two cascading configuration files both set resolves to the most local one, like every other value. The two used to be concatenated.

  • Add strip_ansi() to click_extra.ansi, which removes every ANSI escape sequence from a string or bytes, and template_segments() to click_extra.version.

  • Add get_cache_dir(), which locates the user cache directory of a CLI, and export it with xdg_dir() from the package root.

  • Export from the package root the helpers other projects import from submodules, like env_summary(), default_facts(), KO_GLYPH and cell_width().

  • Add CSV_FORMATS to click_extra.table: the table formats Python’s csv module renders.

  • Add symbol, style and color arguments to trail_glyph(), which now also draws the marker of Spinner.ok() and Spinner.fail().

  • Add iter_subcommand_contexts() to click_extra.param_tools, the walk every command-tree renderer shares.

  • Add resolve_entry_point() to click_extra.project, and walk_fences(), rewrite_fences() and rewrite_file() to click_extra.markdown.blocks.

  • Read and write each page once in click-extra refresh-directives, which composes the now public rewrite_screenshot_regions(), rewrite_matrix_blocks() and rewrite_mirrors().

  • Add machine_envvars_apply() to click_extra.envvar, which tells an option callback whether a machine-wide variable like CLICK_EXTRA_THEME may set its value.

  • Add setdefault() to click_extra.context, and is_dumb_terminal() to click_extra.color.

  • Add find_git_root(), GIT_TIMEOUT and the check and timeout arguments of run_git(), which now removes only the final newline of an output.

  • Add short_help to LazySubcommand, to list a lazy subcommand without importing it.

  • Add a click_extra.config_docstring_heading Sphinx warning for each Markdown heading in an option docstring that click:config renders.

  • Accept any mapping in env_copy(), not only a dict.

  • ValidationError subclasses ValueError, and a new invalid_key code joins unknown_parameter and schema_error.

  • Add a config_cascade argument to @command and @group, which turns on the cascade of the default --config option without replacing it.

  • Draw the Config file column of --params by default when the --config option cascades.

  • Add a --wrap-marker option to the screenshot and snippet commands, which closes each row a fold cut short on ↡ or a chosen character.

  • Drop the boltons and deepmerge dependencies, replaced by in-house code and the standard library.

  • The toml extra installs tomlrt in place of tomlkit to write TOML configuration exports and tables.

  • Draw a progressbar() bar on stderr by default, not stdout, and redraw it at most once every 0.1 seconds instead of once per item.

  • run_lanes() runs a single lane in the calling thread, whatever the --jobs count, like run_jobs() runs a single item.

  • List the injected personalities subcommand after the author’s own under sort_subcommands=False, like help.

  • prebake version prints the baked __version__ the way prebake all does.

  • The CLICK_EXTRA_THEME warning lists auto among the accepted palettes.

  • Let <CLI>_ACCESSIBLE outrank the machine-wide ACCESSIBLE variable, and ACCESSIBLE=0 turn off the accessible mode a configuration file turns on.

  • Ignore the blanks around the value of ACCESSIBLE and DO_NOT_TRACK, so DO_NOT_TRACK=" 0 " no longer reads as an opt-out.

  • Name uv pip install 'click-extra[<extra>]' in every missing optional dependency error, quoted for the shell.

  • --params no longer prompts for an option declaring a prompt, and keeps its rows in parameter path order whichever column --columns puts first.

  • The -v/-q debug trace says β€œby 1 level”, not β€œby 1 levels”.

  • Add the 3.15 release date to PYTHON_RELEASE_DATES, so the matrix directive caps a floor-only requires-python correctly.

  • Switch a standard stream that does not speak UTF-8 to UTF-8 as a command starts, through the new force_unicode_output(), so redirected tables stop crashing on Windows code pages.

  • Shorten import click_extra: it no longer loads subprocess, termios, tty, tomllib, the converters, the trail and progress-bar code or the optional configuration parsers.

  • Build the default options of @command and @group once instead of twice.

  • Run a CLI without a configuration file without importing extra_platforms or wcmatch, and find the module behind --version without scanning all loaded modules.

  • Start the click-extra CLI faster, by loading its test-suite, screenshot, snippet and prebake commands on first use.

  • Draw an SVG still about twice as fast, and import click_extra.pygments four times faster.

  • Cache the type hints of configuration schemas, so a CLI with a large dataclass schema starts and loads its configuration faster.

  • Fix AttributeError: testing when a subcommand or subgroup carries its own --version option outside a test runner.

  • Fix --version printing Click Extra’s version for a CLI started with no frame under it, like from an atexit hook or a C host.

  • Fix --version printing None for a CLI started from a thread or an executor, like with threading.Thread(target=cli.main).

  • Fix MulticallGroup personalities losing the version fields pinned with fields or version_fields.

  • Fix registering a personalities subcommand on a MulticallGroup, and a personality whose subcommand is a plain Click command.

  • Fix --time of an outer run measuring from the start of a nested run of the same command.

  • Fix run_cli() holding back a Ctrl+C in the main thread until a child that never got the interrupt exits.

  • Fix a second Ctrl+C landing while the run prints its wait notice, which raised a reentrant RuntimeError on stderr instead of quitting.

  • Raise a Ctrl+C that a free-threaded Python turns into RuntimeError: release unlocked lock within run_jobs() or run_lanes() as the interrupt again.

  • Fix an operation trail’s progress bar hanging on Ctrl+C while a paused terminal blocks its elapsed clock.

  • Fix a recording ignoring Ctrl+C outside the main thread, and leaving behind the descendants of a command ignoring SIGTERM.

  • Fix a recording splitting one screen in two on a sequence like ESC [ 2 SP q, and an auto-width capture with a cursor crashing on blank output.

  • Fix a log record emitted while a progressbar() bar is open, which printed on the bar’s row instead of a line of its own.

  • Fix a log record skipping a handler of the root logger when Python collected the context of a failed run while handling it.

  • Fix the version field listing being skipped for a logger set below DEBUG.

  • Fix CliRunner.invoke() ignoring the runner’s own catch_exceptions setting when a call leaves the argument out.

  • Fix CLITestCase accepting execution_trace as a suite directive, and comparing cases by the trace a run fills in.

  • Fix split_ansi() leaving escape sequences other than CSI and OSC in place, like the ESC ( B of tput sgr0.

  • Fix the ANSI lexers keeping the last byte of ESC # 8, eating the letter after an escape ending on ~, and dropping blank lines around output.

  • Fix the true_color option of the ANSI lexers reading -O true_color=false as true, and their subclasses doubling their name prefix.

  • Fix --help crashing on a plain cloup.HelpTheme in the theme formatter setting, and on a group listing a name it cannot resolve.

  • Fix a color option under another name than --color, which ignored the color variables like NO_COLOR.

  • Reject malformed hex colors like #-1-1-1 or ##abc in styles and themes, instead of reading negative or shifted channels.

  • Fix Style.to_dict() writing an IntEnum palette index as its member name, and HelpTheme.with_() reporting unknown slots unsorted.

  • Fix ctx.meta after --version: len(), iteration, views, copy(), pop() and setdefault() now see its lazy fields.

  • Fix --params drawing a cross for a custom confirmation_prompt string, and the grammar of its warning on a plain Click command.

  • Fix print_table() padding markup formats by terminal emoji width, and the vertical format misaligning styled, wide or missing labels.

  • Fix EnumChoice raising AssertionError or AttributeError on bad input: it raises TypeError and ValueError.

  • Fix --validate-config and config_strict rejecting the keys a dataclass config_schema reads: an unknown key of a schema-only section now draws a warning.

  • Fix a strict-mode dotted-key conflict and a non-string key like YAML’s 1: raising a traceback instead of a validation error.

  • Fix the per-file strict check of cascade=True rejecting an extension point, like the built-in themes table.

  • Fix an INI section addressing a subcommand passing its values as text, which broke list options.

  • Fix the deprecation warning of a fallback section printed twice when the file defines themes.

  • Fix run_config_validation() with an empty app_name, which now reads the whole document.

  • Report a missing PyYAML for --help-format carapace as Error: with exit code 1, not a traceback.

  • Fix the EXAMPLES section of generated man pages, which showed a backslash before each dash of an example command.

  • Fix render_help() ignoring a passed prog_name when it names a Carapace spec.

  • Fix wrap --params ignoring the context settings of its target and of its subcommands, like their auto_envvar_prefix.

  • Fix help NAME suggestions leaving out lazy subcommands, and help --search listing hidden ones.

  • Fix click:tree missing lazy subcommands and ignoring the list_commands() order: it walks like --tree and skips hidden subcommands.

  • Fix a click:run prompt reading past the end of its input, which raised IndexError instead of aborting like Click.

  • Fix :screenshot: captures written again on every build when unchanged, and a pipe splitting a row of the click:tree summary table.

  • Fix the MyST docstring converter separating directive options from their directive, and rewriting the content of code blocks.

  • Fix refresh-directives deleting content between two <!-- mirror-src --> generators, and ending a region at a marker quoted in a code block.

  • Fix split_options() reading a line that opens on a reST role as an option, and replace_region() rewriting markers quoted in a fence.

  • Fix the dependency matrix missing the uv.lock version of a dependency spelled with capitals, underscores or dots.

  • Fix refresh-directives rewriting form feeds and failing on a tag name that is not UTF-8, and stop its tag listing after 5 seconds.

  • Fix the screenshot command reporting an --emphasize-lines past the end of the capture as a traceback.

  • Fix prebake mangling a value holding a quote or a backslash, and misplacing a placeholder that follows non-ASCII text on its line.

  • Draw the auto truncation rule of a capture across the whole window without wrapping past --columns, and stop it taking on a style the cut left open.

  • Read the HTML of the mandoc and groff man-page renderers as UTF-8 on every platform.

  • Name --syntax-style, which colors the code, in the snippet help example, instead of the help screen’s --theme.

  • Document the click_extra.sphinx.python module in the API reference.

9.5.1 (2026-10-27)ΒΆ

Note

9.5.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add a click_extra.todo_unrendered Sphinx warning for each {todo} in a docstring that no page renders, which no todolist can list.

  • Read {git_long_hash} and {git_short_hash} from the direct_url.json record of a CLI installed from a Git URL, so its dev version names its commit.

  • Drop the release from the artifacts a build generates: the @generated stamp of captures, man pages and Carapace specs, and the default watermark of screenshots and snippets.

  • Fix dotted-key expansion splitting the keys of an extension point: a key ending in a dot logged a warning, or failed in strict mode.

  • Fix the todo-list deduplication keeping two entries for an attribute that a package re-exports.

  • Fix the git fields of --version raising on a branch or tag name that is not UTF-8, and read them as UTF-8 on Windows too.

  • Fix the runner pytest fixture letting a color variable of the caller’s shell, like FORCE_COLOR, add ANSI codes to the output a test checks.

  • Measure test coverage with coverage run instead of pytest-cov, which the test dependency group no longer installs.

9.5.0 (2026-10-22)ΒΆ

Note

9.5.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Deprecated: click_extra.version.visible_width is click_extra.layout.cell_width under its own name, and stops resolving in 10.0.0.

  • Deprecated: INLINE_LITERAL_RE moved from click_extra.command_doc to click_extra.parameters, and stops resolving from its old module in 10.0.0.

  • Deprecated: The buttons, buttons_color, titlebar and collapse_titlebar arguments of render_html(), which it never read, now warn and stop working in 10.0.0.

  • Deprecated: The CAPTURE_BACKGROUND, CAPTURE_FOREGROUND, LIGHT_CAPTURE_BACKGROUND and LIGHT_CAPTURE_FOREGROUND constants of click_extra.screenshot_presets are the fields of the CAPTURE_PALETTES entries, and stop resolving in 10.0.0.

  • Deprecated: click_extra.screenshot.STDOUT_PATH is click_extra.output.STDOUT_SENTINEL under its own name, and stops resolving in 10.0.0.

  • Deprecated: FENCE_OPEN_RE of click_extra.myst_converter warns and stops resolving in 10.0.0: read fences with click_extra.blocks.fence_spans().

  • Add LazyChoice to click_extra.types, a Choice reading its values from a callable on first use, so a module providing them stays off the startup path of the CLI.

  • Add ConfigOption.apply_command_settings(), which @command and @group call to hand their configuration settings to the default --config option.

  • Add ParamStructure.is_excluded(), and a descend argument to walk_params() and walk_command_params() that skips a subcommand without importing it.

  • Accept a callable as the logo of a VersionScreen, called when --version draws the screen: the click-extra CLI no longer paints its own mark at startup.

  • Add child_context(), clean_help(), iter_inline_literals() and choice_values() to click_extra.parameters, the helpers every renderer of a CLI reads it through.

  • Add normalize_envvar_id() to click_extra.envvar, which spells an environment variable name the way the platform reads it.

  • Add ReferenceDirective, the base class of click:tree and click:config, and the ClickDirective.evaluate() and ClickRunner.without_build_logging() methods to click_extra.sphinx.click.

  • Add iter_command_docs() to click_extra.command_doc, which resolves the distribution metadata of a command tree once for all its pages, so their man pages render faster.

  • Add read_project_scripts(), entry_point_package(), locate_package_root() and prebake_dunders() to click_extra.prebake, dunder_name() to click_extra.version, and xdg_dir() to click_extra.carapace.

  • Add parse_columns(), parse_pause(), parse_hold() and capture_environment() to click_extra.screenshot, and emphasis_paint() and credit_markup() to click_extra.screenshot_svg.

  • Add the DEFAULT_FORMAT and DEFAULT_STYLE constants to click_extra.logging, CLEAR_LINE, HIDE_CURSOR, SHOW_CURSOR and DEFAULT_INTERVAL to click_extra.spinner, and DEFAULT_TRUE_COLOR to click_extra.pygments.

  • Halve the import time of click_extra: wcwidth, PyYAML, wcmatch, extra-platforms and several standard library modules now load on the code path that uses them.

  • Stop reading source files while --version locates the CLI module at startup.

  • Resolve the file_pattern_flags and search_pattern_flags of ConfigOption on first use: both default to None, and the pattern sanity check runs on the first configuration load instead of at decoration.

  • Load a configuration file without importing the lazy subcommands an included_params allowlist leaves out: included_params=() imports none of them.

  • Stop the verbosity options from removing the handlers of the root logger: a command adds its own handler for the time of a run. Call new_logger() to keep one outside a run. Closes #1998.

  • Print log records in the style of Click Extra during the run of any command that carries one of its options, like a standalone @config_option.

  • Give each logger the level it had before a run back when the run ends, a failed parse included: it was reset to WARNING, or left changed after a failed parse.

  • Keep the format new_logger() or basicConfig() gave the root logger when a command is defined after the call, which used to reset it.

  • Set the log handlers and the log level of a Sphinx build aside while a click:run block runs its command, as in a reader’s own shell.

  • Highlight the keywords of a help screen with one regular expression per style, instead of compiling one per keyword on every render.

  • Highlight ANSI output faster in Sphinx: the Pygments style and the CSS classes of the ANSI tokens are built once per process instead of once per highlighted block.

  • Render an animated capture faster: a row that stays the same from one frame to the next is drawn once.

  • Read the git history of a project once per matrix refresh, in two git calls, instead of three calls per tag for every block.

  • Resolve each git and build value once per click-extra prebake all run and write each file once: the fields it skips are logged at INFO instead of being echoed.

  • Spell the choices of an Enum the way Click completes them in the Carapace spec, the man page and the Markdown and JSON documents: APPLE, where Fruit.APPLE was listed.

  • Clean the help text of a Carapace spec like the other documents: no \b no-rewrap marker in a flag description, and no reST backticks in a command description.

  • Pass each configuration value to a wrapped CLI as --key=value, which keeps a value starting with a dash intact.

  • Label matrix tables with the name the project declares in pyproject.toml by default: the name of the checkout folder is now the fallback.

  • Label the lines of a matrix table with their source line, so a diagnostic in an rST page names the right one.

  • Move the click_extra_* configuration constants of the Sphinx extension and their registration to click_extra.sphinx.click, which click_extra.sphinx still exports.

  • Validate the :screenshot-columns:, :screenshot-blank:, :screenshot-blink: and :screenshot-hold: options of the Sphinx directives with the parsers the capture commands use, so a bad value is rejected with the same message.

  • Render faint text in the Pygments HTML output at opacity: 0.6, the value Style.to_css() writes, instead of 0.5.

  • Name a deprecated option by Click’s Parameter.spec on Click 8.6 and later, where Option no longer overrides the deprecated human_readable_name.

  • Raise the Pygments floor of the sphinx extra from 2.14 to 2.18, the oldest release Sphinx 8.0.0 imports with.

  • Raise the mkdocs-click floor of the test dependency group from 0.8 to 0.8.1, and its pytest-cov floor from 4 to 7.

  • Keep the built-in themes validator when @command or @group declares config_validators, which used to drop it.

  • Raise TypeError from VersionOption.pin_field() for a field the template does not know, as @command(version_fields=...) does.

  • List under --params the environment variables a subcommand with its own auto_envvar_prefix reads, where names derived from its parent’s prefix were listed.

  • Report a bad --hold value of click-extra screenshot as an invalid option value, naming the option, and reject a negative hold in render_svg() as a negative blank already was.

  • Write a capture to a file named - when its --output path resolves to one: only a bare - sends it to the terminal.

  • Export the completion variable Click reads for a program whose name holds a dot, like garden.py: the spec named _GARDEN.PY_COMPLETE, which Click never reads.

  • Name the man page of a subcommand after the name it is registered under, as the COMMANDS section of its parent does.

  • Answer to the name of a lazy subcommand in a MulticallGroup, which fell back to the group help.

  • Accept a compiled regular expression in the regex directives of a CLITestCase, as their type hints allow, which dataclasses.replace() on such a case needed too.

  • Run click-extra prebake all and a bare convert-to-myst on a project laid out under src/, or declaring its console scripts in setup.cfg, which found no package.

  • Resolve the home directory of install_manpages() and install_carapace_spec() when they are called, where it was fixed at import.

  • Accept the handlers argument in basicConfig() and new_logger(), which always raised ValueError.

  • Warn about a click_extra_manpages entry missing its script from the click-extra-manpages directive, which skipped it silently.

  • Read a truncated or unknown-mode extended color escape, like 38;2;255;128, in the ANSI Pygments lexer the way split_ansi() does: its stray parameters count as attribute codes.

  • Fix the ANSI Pygments lexer dropping an SGR escape with an empty parameter, like \x1b[;31m, which now reads as a reset followed by red.

  • Fix python:run ignoring its :screenshot: option: the directive writes the capture like click:run does.

  • Fix an OSC 8 hyperlink left open in the rendered HTML when an SGR reset lands inside the link.

  • Fix --version printing None in a binary Nuitka compiles with --main-entry-point, whether the entry point is a function or a command object.

  • Read the git and build fields baked into a package’s __init__.py when the CLI sits in another module of that package, like __main__.

  • Name a CLI started from a package’s __main__ module after the package in {exec_name}, for a console script and a binary as for python -m.

  • Fix a Ctrl+C that could hang the process instead of ending it, when it landed while Click Extra updated its list of running subprocesses.

  • Fix a Ctrl+C ignored until a running task ended, when it landed as run_jobs() or run_lanes() started to wait for that task.

  • Load an empty configuration from an explicit --config with nothing to read, like /dev/null, nul on Windows or an empty file, which exited with code 2. Closes #2005.

  • Read a named pipe given to --config like a file, which reported that no configuration file was found.

  • Name the format of a --config file that parses to nothing, like a TOML file of comments only, where it reported a parse error.

  • Warn in the logging documentation that new_logger() removes every handler of the logger it sets up, the root one by default.

  • Fix the documentation render tests failing in a new environment, as for a packager: the docs group now holds tomlkit, and the tests carry the network marker.

  • Run the test suite with every direct dependency at its declared floor, in a lowest-direct cell of the full test matrix.

9.4.1 (2026-10-04)ΒΆ

Note

9.4.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Deprecated: The is_root, default_opts and inherited_opts arguments of extract_carapace_command now warn and have no effect, and stop working in 10.0.0.

  • Add the @progress_option decorator, to give a plain Click command the --progress/--no-progress flag.

  • End the process by SIGINT after Click’s Aborted! on a Ctrl+C, so a calling shell stops its own loop. It used to exit with status 1.

  • Print Aborted! before the close callbacks of an aborted run, where it used to print after them.

  • Send SIGTERM to the commands run_cli started when a Ctrl+C aborts the CLI, then SIGKILL three seconds later to them and their descendants, without calling install_interrupt_handler.

  • Say that an interrupted run waits for its running tasks, and quit at once on a second Ctrl+C instead of printing a traceback.

  • Stop each running lane of run_lanes after its current item when the run is interrupted, instead of running the lane to its end.

  • End an OperationTrail interrupted by Ctrl+C on a ✘ Interrupted after 2/5 feeds finisher, and print the outcomes of tasks finishing after it.

  • Honor _default_subcommands and _prepend_subcommands on groups of any class, where only click_extra.group did: on a bare invocation, and on a subgroup reached through an ancestor’s --config.

  • Stop Spinner and OperationTrail from drawing under --no-progress and --accessible when left at live="auto", as progressbar already did.

  • Read each color variable by its own convention: NO_COLOR=0 and CLICOLOR=1 no longer force color into pipes, and an empty value counts as unset.

  • Apply the per-CLI <CLI>_COLOR and <CLI>_NO_COLOR variables to the --help and --version screens too.

  • Silence the --config and --no-config status lines under -q or a --verbosity above WARNING, wherever the flag sits on the command line.

  • List the default options under the root command’s flags in the Carapace spec, instead of persistentflags that offered them after a subcommand, where Click rejects them.

  • Restore every variable temporary_env changed when one of the changes fails halfway through, or an interrupt lands between two.

  • Stop Spinner and the progress bar of OperationTrail within a second when their stream no longer drains, like a terminal paused with Ctrl+S, instead of hanging.

  • Kill a recorded command that ignores SIGTERM two seconds after the recording ends, instead of waiting for it to exit on its own.

  • Hold a second Ctrl+C until run_cli has killed its child, which the interrupt used to skip, leaving the child running.

  • Terminate the whole process tree of each command in terminate_live_processes on Windows, where a descendant survived and held the command’s output.

  • Show the cursor again when SIGTERM kills a process with a spinner or progress bar drawing, instead of leaving it hidden in the terminal.

  • Run a Click Extra CLI with python -c, which used to crash with RuntimeError: Cannot find module of <frame …>.

  • Read the configuration once on a bare invocation running its configured subcommands, which used to load it twice and repeat the Load configuration matching line.

  • Quote each environment variable in the error hint of an option, which read (env var: '('WEATHER_UNITS',)').

  • Compare the frameworks on the benchmark page against the 50 clig.dev guidelines a framework can implement.

  • Mark the benchmark cells with βœ…, 🟑 and ❌, each linked to the documentation or source code that backs it.

  • Document the behaviors commands inherit from Click and Cloup: output streams, prompts, confirmation, aliases, deprecation warnings and more.

  • Highlight the row and column under the pointer in every table of the documentation.

9.4.0 (2026-10-01)ΒΆ

Note

9.4.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add a click_extra_fail_on_warnings Sphinx option that fails the build on the listed warning types only, like myst.xref_missing.

  • Fix the IndexError a {matrix} dependency block raised when its column bound is a bare major, as a >=9 floor yields whenever the release list is empty.

  • Leave a {matrix} dependency block untouched when PyPI cannot be read, so refresh-directives --check no longer reports drift on a network failure.

  • Fix the dead links from the ConfigOption API documentation to the extra dependencies and platformdirs sections.

  • Repoint the version, commands and context pages at setuptools-scm’s new documentation URL, Cloup’s src/ layout and the glibc getopt manual.

  • Document that a MyST docstring links another page with {doc} or {ref}, since a page.md target ships dead.

9.3.5 (2026-09-28)ΒΆ

Note

9.3.5 is available on 🐍 PyPI and πŸ™ GitHub.

  • Honor the _default_subcommands and _prepend_subcommands configuration keys on any group carrying @config_option, not just on click_extra.group. Closes #1976.

  • Honor both reserved keys on a bare invocation of a click_extra.group, which used to print the help screen before reading the configuration.

9.3.4 (2026-09-23)ΒΆ

Note

9.3.4 is available on 🐍 PyPI and πŸ™ GitHub.

  • Deprecated: Importing CLI_ECOSYSTEM_PACKAGES from click_extra.version now warns, and stops working in 10.0.0. The constant moved to a private module and has no public replacement.

  • Point deprecation warnings at the caller’s code even when a click or cloup frame sits in between: the walk behind the warning’s stacklevel now skips the whole CLI ecosystem.

  • Kill the descendants of a timed-out or interrupted run_cli child that was spawned without start_new_session, instead of the child alone. A killed sudo no longer leaves the command it escalated running.

  • Add an Arch Linux tab to the installation page: click-extra is in the AUR as python-click-extra.

  • Tell packagers to run the test suite against the wheel they built: a bare pytest imports the click_extra the system carries.

9.3.3 (2026-09-19)ΒΆ

Note

9.3.3 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix from click_extra import * emitting Click’s deprecation warnings for get_binary_stream and get_text_stream under Click 8.5. Like Click’s own star import, it no longer binds them: import them by name instead.

9.3.2 (2026-09-19)ΒΆ

Note

9.3.2 is available on 🐍 PyPI and πŸ™ GitHub.

  • Deprecated: Make select_columns, select_row and render_columns_markdown_table importable from click_extra.table again, as aliases of their click_extra.columns versions until 10.0.0.

  • Add corner_header to click_extra.table, naming both axes of a two-axis table in its top-left cell.

  • Name both axes in the top-left cell of matrix tables, like click-extra ↴ \ cloup β†’.

  • Keep the first column of a corner-labeled table on one line in Sphinx builds: a narrow screen scrolls the table instead of wrapping its row labels.

  • Drop the Released column of matrix tables: add :show-date: to follow each row label with its first release date instead.

  • Bin the columns of matrix dependency tables by release: each covers a run of PyPI releases that every range treats alike, labeled like 3.0.1 β†’ 3.0.4.

  • Support cloup 4.0: re-export its ArgumentKwargs and OptionKwargs, and stop import click_extra from emitting Click deprecation warnings, which BaseCommand, MultiCommand, OptionParser and the stream getters now emit only when used.

  • Declare Python 3.15 support in the package classifiers.

  • Fix matrix tables with a Spec column merging release ranges that declare different specifiers into one row, which showed only the oldest one.

  • Fix the matrix directive rendering an all-❌ row for a Poetry caret or tilde range on a suffixed version, like ^2.0.0.post1.

  • Fix matrix row labels naming the same X.Y.x twice when a minor series splits across two rows: the split bound now shows its exact version.

  • Add a Cloup compatibility table to the installation page, and name both axes of the benchmark, executables and MyST docstring comparison tables.

9.3.1 (2026-09-18)ΒΆ

Note

9.3.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix the --jobs help and documentation, which said auto always leaves one logical CPU free: hosts with fewer than three use all of them.

  • Fix click:run and python:run blocks ending early when the output holds a code fence of its own, which spilled the rest of it into the page.

  • Document HelpFormat, DocOptionItem.attached_value and build_moment, which 9.3.0 shipped without a docs mention.

  • Fix the HelpFormatOption docstring, which described --man as --help-format roff, a format that does not exist.

  • Fix the API documentation of TerminatedEchoingStdin, which rendered an invisible EOT character where it meant to show \x04.

  • Skip test_sphinx_runner_resets_version_resolution without the sphinx extra, instead of failing on an ImportError, so pytest -m "not network" passes without the docs toolchain.

9.3.0 (2026-09-18)ΒΆ

Note

9.3.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Breaking: Print OperationTrail lines and its finisher off an interactive terminal too, where no spinner or progress bar draws. Pass visible=False to keep a trail silent.

  • Breaking: Make every argument of an option class after param_decls keyword-only, like ColorOption(default="never"): pass them by name.

  • Breaking: Drop RESET from click_extra.version: import it from click_extra.layout, which already carried it.

  • Breaking: Split click_extra.screenshot: the SVG renderer and the window vocabulary (render_svg, NO_PAINT, OPAQUE, AUTO_HOLD, DEFAULT_WATERMARK, the cell metrics) move to click_extra.screenshot_svg, render_html to click_extra.screenshot_html, and CaptureBackground, the capture palettes, resolve_palette, DEFAULT_PRESET and CAPTURE_FONT_STACK to click_extra.screenshot_presets.

  • Breaking: Move ColumnSpec, select_columns, select_row and render_columns_markdown_table from click_extra.table to click_extra.columns. The root package still exports them.

  • Breaking: Move the screenshot and snippet commands to click_extra.cli_capture and the prebake group to click_extra.cli_prebake. The click-extra CLI is unchanged.

  • Deprecated: Replace the enabled argument of Spinner with live ("auto", "always" or "never"), and that of OperationTrail with visible and live; enabled resolves until 10.0.0.

  • Deprecated: Rename the merge_streams argument of run_cli to merge_stderr, and allow_query of resolve_background to query_background, matching capture_output and ThemeOption; the old names resolve until 10.0.0.

  • Deprecated: Drop the unique argument of search_params, whose False returned every match as a list: filter the parameters directly instead. It resolves until 10.0.0.

  • Deprecated: Replace color="forced" in CliRunner.invoke with a force_color=True argument; "forced" resolves until 10.0.0.

  • Deprecated: Replace the (label, column_id) tuple with a ColumnSpec in table headers, SortByOption and column_sort_key; the tuple resolves until 10.0.0.

  • Deprecated: Replace the window arguments of render, capture, record_and_render and render_snippet, like margin and watermark, with one chrome=Chrome(...); they resolve until 10.0.0.

  • Add rewrite_fenced_regions, split_options, skip_region and region_markers to click_extra.blocks: the marker-region refresh the :mirror: and :screenshot: directive options share.

  • Add build_moment to click_extra.version, the SOURCE_DATE_EPOCH-aware instant --version and the man page date both stamp.

  • Add attached_value to DocOptionItem, the [=METAVAR] form of an option taking an optional value.

  • Add sortable to ColumnSpec, keeping a column in the table layout without offering it to --sort-by.

  • Show a Spinner’s elapsed time under --time by default, as OperationTrail and progressbar do.

  • Type the result of search_params and last_param as the parameter class they look for, so a match needs no isinstance check.

  • Set Context.color too from the force_color class attribute of CliRunner, as the new force_color argument does, unless a call passes color=False.

  • Match MultiChoice tokens regardless of case by default, as EnumChoice and ThemeChoice do. Pass case_sensitive=True for an exact match.

  • Add HelpFormat, the enum of --help-format formats. render_help takes a member or its value, and HELP_FORMATS maps each member to its description.

  • Tag the prompt line run_cli logs with its label too, so an interleaved log attributes each command as well as its output.

  • Add label_style and timer_style to Spinner, painting the label and the timer (parentheses included) apart from style, on every frame and on the kept ok() / fail() line.

  • Start a log message spanning several lines below its level prefix, so a block like a command’s captured output keeps its columns instead of shifting its first line right.

  • Name the INI option a value cannot be converted for in the error, as an argfile does, instead of raising the bare conversion error.

  • Strip the ANSI escapes embedded in a Spinner label when color is off, so --no-color and NO_COLOR also hold for a label styled by hand.

  • Fix an OperationTrail batch that finishes inside its delay leaving no trail on screen: its lines now echo plainly, with its finisher if it has one, as a sequential batch’s do.

  • Fix OperationTrail lines and finisher written above a drawn indicator keeping their color under --no-color or NO_COLOR, and a Spinner on a worker thread missing --no-color.

  • Fix an option typed EnumChoice with a None default failing validation when left out, reading it as a choice named None.

  • Fix run_cli(start_new_session=True) leaving descendants running after a timeout or interrupt when they started a session of their own, as CPAN.pm’s make test does.

  • Fix a markup table padded by the rendering terminal’s own emoji widths: a github table rendered from Apple Terminal came out one column wider on every row holding an emoji-presentation sequence than mdformat pads it.

9.2.0 (2026-09-15)ΒΆ

Note

9.2.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Breaking: Drop click_extra.table.NARROW_EMOJI_PRESENTATION_TERMINALS. Which terminals narrow an emoji-presentation sequence now comes from wcwidth’s own measured tables.

  • Breaking: Drop LINE_NUMBER_SEPARATOR and RTL_BIDI_CLASSES from click_extra.screenshot. Both moved to click_extra.layout, which is where to import them from now.

  • Add a click_extra.layout module for terminal-grid work, holding the new center_in_rule and pad_to alongside cell_width, fit_columns, grid, is_bidirectional, number_lines and wrap_ansi. Every function above stays importable where it was.

  • Add open_ansi(), returning the ANSI escapes a string leaves in effect, to splice a styled fragment into styled text.

  • Add separator, subcommand and deprecated theme slots, painting the -- end-of-options separator, a command path’s last component, and the deprecation markers a new HelpKeywords.deprecated field matches.

  • Take theme names on click-extra themes, rendering only those in the order given, each headed by its name centered in a rule. auto stands for the palette the terminal background resolves to.

  • Draw the --truncation marker of a capture as a dotted rule spanning the kept lines, centered on βœ‚. Naming a marker still takes it verbatim.

  • Close every click-extra help screen with example invocations.

  • Highlight more of a help screen: an example invocation’s subcommand and the options it accepts, a numeric value beside the option it feeds, each part of an enumerated metavar, and an operand named in a description.

  • Name what an option takes on every click-extra screen with one vocabulary: SECONDS for a duration, COLOR for a CSS color, PIXELS for a pixel count, and FILE or DIRECTORY for a path.

  • Give click-extra screenshot --hold and --columns the metavars [auto|FLOAT] and [auto|INTEGER], naming what each accepts.

  • Replace the inline value lists of the table --columns, click-extra test-suite --skip-platform and click-extra wrap --table-format with metavars. The man, markdown and json renders list the values.

  • Resolve --version afresh for each click:run block, instead of letting the first render in a documentation build answer for every later one. A page could publish a version screen with no version on it.

  • Stop {env_info} crashing when the working directory it reports has been deleted. Requires boltons 26.2.0.

  • Count a double-width character as the two columns it takes when wrapping styled text and laying out the --version screen. Requires wcwidth 0.8.3.

  • Line up a table carrying an emoji-presentation glyph on every terminal wcwidth has measured, instead of Apple Terminal alone.

  • Keep an OSC 8 hyperlink intact through wrap_ansi(), which used to drop its markers and leave the display text alone.

  • Return a Click Extra theme from HelpTheme.dark() and HelpTheme.light(), which used to hand back a bare cloup.HelpTheme missing every extra slot.

  • Keep a deprecation message colored past a keyword quoted inside it: a highlighted option or command name used to strip the color off the rest of the message.

  • Name every spelling of a deprecated option in the notice Click prints, as --apt-cyg / --no-apt-cyg. It reported 'apt_cyg', the Python identifier, which is the one spelling no user can type.

  • Warn about a deprecated parameter a configuration file switches on. Click stops one rank short of the configuration, leaving the one place a selection outlives the project it names.

  • Draw the columns a ShowParamsOption subclass declares in its default_columns(), which --params ignored in favor of the base class’s.

  • Keep the help-screen section of an option a params hook swaps for a subclass of it, which used to be drawn under Other options instead.

  • Read a repeatable boolean flag as the toggle it is, in --export-config and in INI files, instead of as a list of values that dumped an unset one as [].

  • Leave a subcommand’s options out of --export-config when the schema marks their section opaque. The export used to write a file its own loader refused.

  • Check a MultiChoice value given as a list against its choices, as a configuration file provides it. An unknown column ID reached select_columns and raised KeyError there.

  • Close a [default: ...] field on its own bracket when the default value is itself bracketed, as [default: [...]].

  • List click-extra gradient under its whole first sentence. An abbreviation cut it to β€œRender 24-bit RGB gradients vs.”

  • State the --rows, --hold, --blank, --blink, --submit and --speed defaults of click-extra screenshot in their own sentence, replacing a second [default: ...] field written into the help text.

9.1.0 (2026-09-03)ΒΆ

Note

9.1.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add --record to click-extra screenshot, running the command under a pseudo-terminal and writing an animated SVG of every screen it draws, paced by --rows, --hold, --blank and --speed, and backed by the new record_and_render().

  • Draw the invocation above a capture as a shell prompt; --prompt overrides or hides it, and --closing-prompt draws the prompt the shell returns to once the command exits.

  • Draw a terminal cursor on a capture with --cursor and --blink, or render_svg(cursor=…), blinking or steady, in the --preset terminal’s own shape.

  • Open a recorded animation by typing its command line out, with --typing, --submit and the new type_line().

  • Add :screenshot-cursor:, :screenshot-blink:, :screenshot-prompt:, :screenshot-typing:, :screenshot-submit: and :screenshot-closing-prompt: to the click:run directive.

  • Animated captures now take hold="auto" (and :screenshot-hold: auto), pausing the loop on the final screen for as long as its line count asks; a :screenshot-record: block defaults to it.

  • --validate-config now accepts every location --config accepts: a folder, a glob pattern, or an http/https URL, on top of a file path.

  • Read *.jwcc configuration files with the JSON5 parser, which already accepts the comments and trailing commas JWCC adds to JSON.

  • Group the default options into Configuration, Output, Logging and Introspection sections, drawn after a command’s own options in every render.

  • Add ExtraOptionGroup, an option group drawn after the ones Click Extra injects, ordered among them by its priority.

  • Align the columns of every option group by default, with align_option_groups now set to True.

  • Render the --config and --validate-config values as a LOCATION metavar, replacing CONFIG_PATH and FILE.

  • Show the --config default as the folder it searches, instead of the glob of every format the install enables. Pass show_file_patterns=True to keep advertising them.

  • Render the --table-format value as a FORMAT metavar, replacing the list of its fifty accepted values on the help screen.

  • Add a choices key to each option of the --help-format json export, and list the accepted values under an option whose metavar hides them in the man and markdown renders.

  • Match a configuration key against a parameter name whatever its case, so Foo-Bar and FOO_BAR both reach the foo_bar parameter. Adds canonical_param_name().

  • Report an unmatched argfile declaration under the name Click would derive from it, so --Unknown-Option is named unknown_option.

  • Disable the SQLITE configuration format on a Python whose sqlite3 bindings are missing, like FreeBSD’s, instead of breaking every CLI at import time.

  • Measure a styled string at the width a terminal draws it. cell_width counted the escape sequences instead, answering 16 cells for a colored apricot drawn in 7.

  • Draw overline in a capture, which reached the terminal and never the picture.

  • Fix a capture dropping the underline off a run that was also struck through.

  • Fix a capture drawing every tile of a rule one cell late when a label inside it fell on a chunk boundary.

  • Fix the Examples: block of every click-extra help screen drawing its raw escape sequences on the documentation site.

  • Fix stray backspace characters shipping in the Examples: block of seven click-extra help screens.

  • Fix record_command mangling a multi-byte glyph split across two pty reads into a replacement character.

  • Fix a drawn prompt dropping the quotes around an argument or environment value holding a space, so a captured command line pastes back as the command it pictures.

  • Fix a capture inheriting TERM_PROGRAM from the terminal it is taken from, which drew an emoji-bearing table wider on one machine than another.

  • Fix recorded screens dropping every line the command ended with \r\n, the form a pseudo-terminal substitutes for each newline.

  • Fix a printed CLI trace raising on a captured character the output encoding refuses, which failed the run instead of the command under test.

  • Fix a failing invocation leaving --no-color pinned process-wide, which stripped color from every later command run in the same process.

  • Stop {env_info} resolving the host’s name, which stalled every --verbosity DEBUG run for as long as the machine’s reverse DNS took to answer.

  • Fix an argument declared with a plain click.argument(help=...) drawing a blank Positional arguments entry on the help screen, while every other render carried its text.

  • Fix a deprecated command showing Cloup’s (Deprecated) prefix and dropping the reason string: it now carries Click’s own (DEPRECATED: reason) marker in every render.

  • Fix a MulticallGroup and a VersionOption failing to copy on Python 3.10 with Click 8.4, which raised ValueError: <object object> is not a valid Sentinel.

  • Paint the (DEPRECATED) label with the deprecated theme slot in --tree and the --params help column, as the help screen already does.

  • Fix --help-format carapace describing an option that computes its own help, like -v and -q, with an empty string.

  • List a subcommand’s aliases in the man page, the Markdown document and the JSON export, which named only its primary spelling. Each JSON entry gains an aliases array.

  • Carry an argument’s help into the completion spec, under the documentation block Carapace reserves for operands.

  • Mark a hidden option with Carapace’s & modifier and a required one with !, which the spec carried as indistinguishable from listed and optional ones.

  • Paint each value of a choice operand in --tree with the choice theme slot, the way the help screen paints it.

  • Draw a required {green|ripe} choice metavar on the help screen the way the optional [green|ripe] form is already drawn.

  • Reorganize the documentation sidebar into eight topical sections, grouping the documentation tooling together and splitting Development into Contributing, API reference and Project.

  • Split the configuration documentation into five pages, and move the python:* and matrix Sphinx directives to a page of their own.

  • Fix the dead API documentation links to the capture, theme, Carapace and --help-format pages.

  • Fix the documentation cross-references that did not jump to their section when a page is read on GitHub.

  • Repoint the install page at GitHub’s current artifact attestations guide.

  • Document how to search a platformdirs folder layout, by passing a computed pattern to --config’s default.

  • Lead the wrap documentation with the --params introspection example, its terminal capture and the uvx one-liner that produces it.

  • Pin --no-prefix on the git diff screenshot, so the picture no longer depends on the diff.noprefix setting of whoever builds the documentation.

9.0.0 (2026-08-29)ΒΆ

Note

9.0.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Breaking: Raise the Click floor from 8.3.1 to 8.4.1, dropping the compatibility shims the 8.3.x releases needed.

  • Breaking: Rename every camel-cased spinner preset to kebab case, so boxBounce is now box-bounce.

  • Breaking: Rename the solarized_dark theme to solarized-dark.

  • Breaking: Remove the timeTravel spinner preset, which is SPINNERS["clock"] with reverse=True.

  • Breaking: --man now typesets the manual and pages it, the way man does, instead of printing roff to stdout; the source moved to --help-format man.

  • Breaking: Remove click-extra wrap --carapace in favor of wrap --help-format carapace, one option carrying every rendering.

  • Breaking: Rename the click_extra.man_page module to click_extra.command_doc, after the model it is built around rather than one of the four formats it renders.

  • Breaking: Rename ManPage to CommandDoc, ManOptionItem to DocOptionItem, ManOptionGroup to DocOptionGroup and extract_manpage() to extract_command_doc().

  • Breaking: Remove every deprecated alias scheduled for removal in 9.0.0: the click_extra.test_plan module, the root-level test-plan and config-schema names, and the invocation and pre-baking helpers’ old homes.

  • Breaking: ConfigOption.search_and_read_file() yields (location, content, media_type) triples instead of (location, content) pairs.

  • Breaking: LazyGroup.lazy_subcommands holds LazySubcommand instances instead of import-path strings; the constructor still accepts either.

  • Deprecated: Rename the color_envvars and nocolor_theme constants to COLOR_ENVVARS and NOCOLOR_THEME, following the uppercase convention; the old names resolve until 10.0.0.

  • Deprecated: Move the generic patch_attr(), generator_tag() and missing_extra_message() helpers from click_extra.parameters to the new click_extra._utils module; the old homes resolve until 10.0.0.

  • Add a click-extra screenshot subcommand capturing any CLI’s colored output as an SVG image, an HTML document or raw escape sequences.

  • Add a click_extra.screenshot module rendering a capture on a character grid, needing no optional dependency for either format.

  • Draw a capture as a macOS, Windows, GNOME or plain terminal with --preset, each catalogued in the new click_extra.screenshot_presets module.

  • Restate the window a capture is drawn in with --background, --border, --border-width, --radius, --shadow, --margin, --padding, --opacity, --title and a --backdrop accepting a plain color or a CSS gradient.

  • Number and band a capture’s lines with --line-numbers and --emphasize-lines, and credit it with --watermark and --watermark-color.

  • Lay a capture out at the longest line it holds with an auto width, or emit it as a bare inline-styled HTML block with --fragment.

  • Add a --wrap option to click-extra screenshot, routing the target through the wrap subcommand so a foreign Click CLI is captured with its colors.

  • Tell a captured command its chrome through CLITHEME and COLORFGBG, so a CLI passing --theme auto renders for the window it lands in.

  • Add a click-extra snippet subcommand and a click_extra.snippet module coloring a source file with Pygments and drawing it in a screenshot’s window, painted by --syntax-style.

  • Capture a click:run block’s output, or a click:source or python:source block’s own code, beside the documentation with :screenshot:, every command option restated as :screenshot-*: and defaulted by click_extra_screenshot_* settings.

  • Add a :mirror: option to the click:run directive, keeping a Markdown link to that capture in the source, refreshed by refresh-directives.

  • Add a click_extra.recording module rebuilding a terminal’s screen from the stream a command writes at it, in-process with ScreenRecorder or from a Unix command with record_command.

  • Render an animated SVG capture from a sequence of frames, tuned by hold, blank, speed and quantize(), and fed by the new Spinner.frame_lines().

  • Animate a documented capture with :screenshot-animate:, :screenshot-interval: and :screenshot-record:, the last committing a recording once instead of rewriting it on every build.

  • Harden every SVG capture and brand asset against renderers ignoring <style> or resolving clips, filters and glyph widths differently, so an image draws the same outside a browser.

  • Add a --help-format FORMAT option on every command, rendering it as json, json-full, man, markdown, markdown-full or carapace.

  • Add a --help-format mode to click-extra wrap, rendering any foreign Click CLI in those same formats without running it.

  • Add render_help(), the HELP_FORMATS and INSTALLABLE_FORMATS registries, and the to_markdown(), to_dict(), to_json(), read_manpage(), format_manpage() and install_manpages() backends behind them.

  • Add --output-dir and --install to every installable wrap --help-format rendering, so a man page reaches your man directory the way a Carapace spec reaches Carapace’s.

  • Strip the man page’s overstrike emphasis under --accessible, which a screen reader voices instead of skipping.

  • Add an examples=[("description", "command")] parameter to @command and @group, rendered in help screens, man pages and every --help-format.

  • Add a sqlite configuration file format, reading a config table of dotted keys and JSON-encoded values from *.sqlite and *.sqlite3 databases with the built-in sqlite3 module. Closes #124.

  • Add a plist configuration file format, reading *.plist property lists in both their XML and binary variant through the built-in plistlib module, and dumping them with --export-config. Closes #123.

  • Add an argfile configuration file format, reading *.conf files as a plain-text list of command-line options, one per line, in the style of mpv and yt-dlp. Closes #340.

  • Add a cascade argument to @config_option, layering every discovered configuration file into the defaults, most-local first, and listing them in a new CONF_SOURCES context key. Closes #581.

  • Guess the format of a configuration downloaded over HTTP from the Content-Type the server advertises, resolved by the new format_from_mime() and per-format mime_types.

  • Add opt-in help and config_file columns to --params, naming a parameter’s help text and the configuration layer its value came from, backed by a new optional field on ColumnSpec.

  • Add sort_subcommands and subcommand_priorities to @group, plus a sort_subcommands context setting inherited by every subgroup, ordering subcommands by registration or priority. Closes #544.

  • Add an option_priorities argument to @command and @group, reordering the help screen without moving the order option callbacks run in, plus iter_params_for_display(). Closes #544.

  • Add LazySubcommand, declaring a lazy subcommand’s Cloup section and fallback_to_default_section beside its import path.

  • Add @multicall_group, BusyBox-style argv[0] dispatch: invoked under a subcommand’s name, the group runs as that subcommand, exposed as INVOCATION_NAME. Closes #1619.

  • Add the {build_time}, {build_os}, {build_target} and {build_target_arch} version template variables, baked by click-extra prebake all from SOURCE_DATE_EPOCH.

  • Add a VersionScreen drawing --version as a logo with facts beside it, mounted via @version_option(screen=…), plus a click_extra.logo module and VersionOption.field_style().

  • Add a machine-wide CLICK_EXTRA_THEME environment variable naming the help-screen palette of every Click Extra CLI at once, with auto now advertised in the help screen and in shell completion.

  • Add parse_envvar_flag() to click_extra.envvar, the one permissive boolean reading shared by the color, --accessible and --telemetry environment flags.

  • Add theme and prompt parameters to format_cli_prompt(), and a theme parameter to highlight_bin_name(), so a caller picks the palette and sigil it draws.

  • Add a --debug flag to every Click Extra CLI, shorthand for --verbosity DEBUG, which outranks --verbosity, -v and -q, and dump {env_info} as indented JSON in those logs.

  • Set or remove a test-suite case’s environment with env and unset_env, and run it elsewhere with --work-directory or the new cwd argument of run_cli().

  • Add :show-prompt: and :hide-prompt: options to the click:run Sphinx directive, drawing or dropping the invocation above the output it produced.

  • Count CPUs for --jobs with os.process_cpu_count() on Python 3.13+, honoring a container’s cgroup quota and affinity, and use both CPUs of a two-CPU host.

  • Align a table carrying an emoji-presentation sequence (⁉️) the way the running terminal advances and paints it, rather than assuming one column.

  • Split a test case’s cli_parameters string with the Windows tokenizer on Windows, so --city "San Francisco" stays one argument instead of three.

  • Render a click:run block’s environment variables as assignments on the invocation ($ WEATHER_UNITS=fahrenheit weather Paris) instead of a separate $ export line.

  • Deduplicate the Sphinx todolist page, which sphinx.ext.todo fills with one entry per rendering of a {todo} directive instead of one per directive.

  • Track Click 8.5.0: keep click_extra.testing.isolated_filesystem() alive, re-export custom_version_option, and keep get_binary_stream and get_text_stream bound by a star import.

  • Speed up ANSI tokenization, help-screen keyword highlighting and SVG grid layout.

  • Fix --version painting the program name and version from the dark palette whatever --theme was picked, and caching the first invocation’s name forever.

  • Fix --version rendering no version at all in a click:run documentation block, which resolved the CLI against the directive’s own runner instead of the documented command.

  • Fix a --theme resolved from the environment, or typed after --help, not reaching the screens that render and exit.

  • Fix options computing their help from the context (-v, -q) rendering blank in man pages and --params.

  • Fix --params resolving subcommand parameter values and sources against the root context, which left their Value and Source columns at the defaults.

  • Fix the configuration parse-error message leaving a dangling or when the --config option accepts a single format.

  • Fix --color=always leaving a wrapped CLI uncolored when its commands come from plain @click.command() decorators.

  • Fix --color and --no-color callbacks publishing the process-wide color state from resilient introspection contexts, pinning a NO_COLOR environment onto every CLI lacking its own color option.

  • Fix wrap naming a target after click-extra’s own launch mode in its usage line, and after the script path in a rendering, which produced a Carapace spec binding to nothing.

  • Fix env_copy() rejecting a None value instead of removing that variable, as its Mapping[str, str | None] type and click.testing.CliRunner both promise.

  • Fix HelpFormatter instances sharing one class-level keyword collection as their default.

  • Fix click_extra.sphinx refusing to import when myst-parser is not installed, which broke reST-only documentation builds.

  • Fix the source line a Sphinx warning reports when raised inside a block a click:* or python:* directive generates.

  • Fix the click:run directive handing Click only the last word of a multi-word prog_name, which made a wrapped CLI report a name its own prompt line contradicted.

  • Fix the gradient demo overflowing an 80-column terminal by one character, which wrapped every ramp onto a second line.

  • Escape quotes in an OSC 8 hyperlink’s URL when AnsiHtmlFormatter renders it, so a quote in the URL can no longer break out of the href attribute.

  • Trim the trailing space upstream pads its emoji spinner frames with, so a label sits one space from the glyph and a capture centers it.

  • Reword the --accessible help so cross-reference highlighting stops painting its plain as a --table-format choice.

  • Illustrate the readme and the documentation with live captures, superseding hand-drawn screenshots that still advertised the long-gone --show-params and -C, --config options.

  • Ship a subset of JuliaMono with the documentation, so box-drawing and Braille glyphs stop breaking the alignment of captured terminal tables.

  • Document CliRunner, the Pytest fixtures and helpers, and the parameter tree behind --params, replacing four placeholder sections.

  • Give the machine-readable renderings a page of their own, move the examples= guide beside the other command-authoring options, and trim the mechanics no reader acts on.

  • Illustrate how the --jobs default, auto and max resolve across CPU arrangements in a table on the parallel-jobs page.

  • Refresh the readme’s list of projects using Click Extra, split between those building a CLI on it and those rendering their documentation with it.

  • Collect this project’s scattered TODO and FIXME notes into {todo} admonitions, so the todolist page carries every planned change.

  • Replace the star-history.com embed on the benchmark page, broken by GitHub’s 2026 stargazer restriction, with a chart sampled weekly into the repository.

8.9.1 (2026-08-15)ΒΆ

Note

8.9.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix the man-page links of the click-extra-manpages directive, which pointed one directory too high on dirhtml and singlehtml builds.

  • Resolve man-page links against each rendered page, so they stay correct when builders share a doctree cache.

  • Stop resolving man-page links through a Sphinx API deprecated for removal in Sphinx 11.

  • Document the colon-grid table format.

  • Fix the Sphinx page’s click:run example, which reported the documentation build’s own Sphinx version instead of the CLI’s.

8.9.0 (2026-08-14)ΒΆ

Note

8.9.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add a transform argument to EnumChoice, reshaping the string produced by any choice source, so show_aliases can spell aliases in kebab-case instead of raw Python identifiers.

  • Reject a transform collapsing two EnumChoice members into the same choice string, instead of silently dropping one from the help screen.

  • Point the EnumChoice show_aliases error at transform and explain why ChoiceSource.STR and callable sources cannot see aliases.

  • Add a max_column_widths argument to render_table() and print_table(), and a max_width field to ColumnSpec, capping a column to a character count or to auto.

  • Wrap long cells in the vertical format, aligning continuation lines under the label gutter.

  • Add a WRAPPABLE_FORMATS registry and a TableFormat.is_wrappable property, so formats unable to render a wrapped cell drop column widths instead of corrupting their output.

  • Add wrap_ansi(), wrapping a string to a visible width without counting its ANSI escapes toward the line length, and keeping each line’s styling self-contained.

  • Read the input of run_jobs() and run_lanes() lazily, keeping a bounded window of tasks in flight instead of materializing the whole stream.

  • Stop scheduling the rest of a run_jobs() or run_lanes() stream when the caller breaks early, at any worker count and not only at --jobs 1.

  • Declare run_jobs() and run_lanes() as generators, so the early-exit close() they document is visible to type checkers.

  • Render the {matrix} python axis in three states: βœ… for a version a release declares, ❌ for one its requires-python rules out, and – for one it neither claimed nor forbade.

  • Split a Python matrix row when the declared requires-python changes, even if the set of supported versions does not.

  • Read a dependency’s requirement from a parsed pyproject.toml instead of a regex over its raw text, so {matrix} follows extras brackets, environment markers and Poetry’s inline-table form.

  • Match a tracked dependency on its normalized name, searching runtime and extra dependencies but no longer development dependency groups.

  • Drop the Codecov integration, its badge and its upload steps. Coverage is now gated by the [tool.coverage] report.fail_under ratchet.

  • Move every test job and the full matrix off the ubuntu-slim and ubuntu-24.04-arm runners onto the ubuntu-26.04 pair, and teach actionlint the new labels.

  • Exempt the inline repomatic pin and the test-package-install job from the supply-chain cooldown, so neither resolves to a missing or stale release.

  • Pin the uv version installed by astral-sh/setup-uv in the test workflow.

  • Enable ruff’s PLW1514 and disable its unsafe fixes.

  • Skip the test workflow on version-bump pushes again, whose commit titles gained a [changelog] prefix.

  • Cap a Poetry caret range at the component Poetry documents, so ^0.2.3 no longer claims the whole 0.x series instead of stopping at 0.3.0.

  • Translate Poetry’s major-only tilde (~1) and its wildcard ranges (*, 1.*, 1.2.*), which used to be unparsable and rendered an all-❌ row.

  • Give an exact == pin a column of its own precision, so the single release it accepts no longer renders as all-❌.

  • Fix the test workflow’s metadata job requesting coverage_cells, a key repomatic dropped, which failed the job and skipped every job below it.

  • Skip test_blocks_reexported_from_sphinx_package without the sphinx extra, instead of failing on an ImportError. It is the only test outside tests/sphinx/ importing that package.

  • Skip tests/sphinx/test_sphinx_matrix.py when no git binary is on PATH, instead of failing all 155 of its cases with an unexplained FileNotFoundError.

  • Bind the test suite’s local HTTP server to 127.0.0.1 instead of localhost, so the configuration tests serving a config file over HTTP no longer need a name resolver.

8.8.1 (2026-08-02)ΒΆ

Note

8.8.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Widen the [tool.uv] required-version to >=0.11.15 and the [build-system] uv-build floor to >=0.8, dropping the previous <0.13 upper cap.

8.8.0 (2026-07-31)ΒΆ

Note

8.8.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Breaking: OperationTrail now gates its per-item and finisher elapsed times on a new timer argument that defaults to None, following --time / --no-time; its finisher no longer always shows a clock (pass timer=True to restore it).

  • Add spinner and progress_bar arguments to OperationTrail to render its concurrent aggregate indicator as a spinner from the SPINNERS catalog or a determinate progress bar. Closes #1860.

  • Add a clock argument to OperationTrail ("elapsed" by default, or "eta"), choosing whether a running spinner or bar counts elapsed time up or estimated time remaining down.

  • Add an OperationTrail.operation() handle whose mark() records an outcome timed from when the operation began.

  • Render the OperationTrail sequential finish-line elapsed time in the compact clock format, so a run past a minute reads 1:15, not 75.3s.

  • Gate the estimated-time display of click_extra.progressbar on --time through a new tri-state show_eta argument (default None; Click’s own default is True).

  • Add a trail demo subcommand to the click-extra CLI, running a simulated batch behind an OperationTrail to showcase its sequential, spinner and progress-bar renderings in a real terminal.

  • Move the self-updating block primitives (update_blocks, marker_res, replace_region) to a new dependency-light click_extra.blocks module, importable without the sphinx extra; they stay re-exported from click_extra.sphinx.

  • Add a pad option to replace_region to keep the closing marker flush against the body, for regions constrained by mdformat-footnote.

  • Add a click_extra.humanize module with format_size and format_duration, rendering byte counts (IEC binary KiB/MiB, SI decimal kB/MB, or JEDEC KB/MB) and elapsed durations (2.3s, 1:05, 1:02:03) as compact strings.

  • Add parse_duration, parse_friendly_duration and parse_iso8601_duration to click_extra.types: soft, None-returning counterparts of the Duration parameter type, for parsing durations read from files or other machine sources.

  • Add a click_extra.output module with prep_path and is_stdout (and the STDOUT_SENTINEL constant): open an --output path for writing as UTF-8, treating - as stdout and creating missing parent directories.

  • Add config_table_to_flags to click_extra.config: translate a [tool.X]-style configuration table into long-form CLI flags for tools that mirror their config keys as options but cannot read the table themselves.

  • Work around pallets/click#3571 in click_extra.progressbar: a bar with show_pos=True and an update_min_steps that does not divide its length now renders its final position instead of freezing below it.

8.7.0 (2026-07-30)ΒΆ

Note

8.7.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add a <!-- mirror-src --> comment form of python:render :mirror:: the generator Python lives inside an HTML comment, so its output renders on GitHub and PyPI while the generator stays invisible.

  • Export update_blocks, marker_res, and a new replace_region helper from click_extra.sphinx for downstream self-updating documentation scripts.

  • Accept kebab-case keys in configuration files: dummy-flag and dummy_flag both address the --dummy-flag option, the last spelling winning on collision with a warning.

  • Scope the configuration strict check and merge to the app’s own section, ignoring other tools’ sections in shared files like pyproject.toml.

  • Honor legacy fallback_sections when merging configuration values into default_map, not only in the schema path.

  • Forward config_strict and additive excluded_params from @command/@group to the default --config option.

  • Load the configuration file before --params and --export-config render, so both reflect it whatever the order of the flags.

  • Export parameters without a value in --export-config: empty lists for multi-value options, null in YAML and JSON, commented-out keys in TOML.

  • Render --export-config keys in kebab-case, the canonical spelling for configuration files, matching the CLI flags.

  • Exclude --validate-config from configuration files, like the other self-referential config options.

  • Reword the unknown-configuration-key error, and report parameters blocked from configuration files as not allowed instead of unknown.

  • Fix DO_NOT_TRACK handling: a truthy value now forces --telemetry off; it previously fed the boolean flag verbatim and enabled telemetry.

  • Add an executables download table and a release-verification section to the installation guide.

  • Render the demo CLI help screen live in the installation guide, replacing captured output stuck on 7.2.0.

  • Add a CLI reference page rendering the command tree and the [tool.click-extra] configuration schema live.

  • Add cross-reference render tests asserting anchors and intersphinx links in the built documentation.

8.6.3 (2026-07-29)ΒΆ

Note

8.6.3 is available on 🐍 PyPI and πŸ™ GitHub.

  • Stop importing the test tooling at package import time: the click_extra.testing and click_extra.test_suite exports now resolve lazily, keeping Click’s debugger stack out of importing programs and compiled binaries.

  • Scrub the submodule objects star imports leaked into the package namespace: foreign modules like click_extra.core and click_extra.termui no longer hand out Click’s un-enhanced classes or shadow the globals builtin.

  • Pin [tool.repomatic] nuitka.nofollow-imports to its bare ["tkinter"] default, ahead of the repomatic release introducing the setting.

  • Fix the myst_docstrings MyST-to-reST converter mispairing inline-code backticks and emitting reST literals with illegal edge whitespace from padded code spans.

8.6.2 (2026-07-27)ΒΆ

Note

8.6.2 is available on 🐍 PyPI and πŸ™ GitHub.

  • Treat an unreaped zombie as a dead process in the run_cli process-group teardown tests, so they pass in a build sandbox with no init to reap orphans (like Alpine’s abuild container).

8.6.1 (2026-07-27)ΒΆ

Note

8.6.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Deprecated: ClickExtraConfig, PrebakeConfig and TestSuiteConfig resolve again from the top-level click_extra namespace, warning and redirecting to click_extra.config; removed in 9.0.0.

  • Deprecated: The click_extra.test_plan module and the top-level TestPlanConfig, parse_test_plan, run_test_plan and DEFAULT_TEST_PLAN names warn and resolve to their test_suite replacements; removed in 9.0.0.

  • Deprecated: prebake_dunder, prebake_version and discover_package_init_files resolve again from click_extra.version, warning and redirecting to click_extra.prebake; removed in 9.0.0.

  • Deprecated: Importing INDENT, PROMPT, args_cleanup or format_cli_prompt from click_extra.testing now warns and redirects to click_extra.execution; removed in 9.0.0.

  • Ship the test suite and the docs and CI files it reads in the PyPI sdist, so downstream packagers can build and test without a Git checkout.

  • Add a [tool.setuptools] shim so builds that fall back to setuptools still bundle the themes.toml and py.typed data files.

  • Fix the source line reported in click:run variable-conflict errors when a MyST directive’s body ends in blank lines.

  • Fix the MkDocs test tree erroring instead of self-skipping when mkdocs-click is absent but mkdocs and pymdown-extensions are present.

8.6.0 (2026-07-24)ΒΆ

Note

8.6.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add OperationTrail, the batch-reporting companion of run_jobs/run_lanes: each operation leaves a persistent βœ“/✘ line and the batch closes with a timed summary. Adds the trail_glyph and trail_line helpers.

  • Add column-order and row-order options to {matrix} blocks (newest-first/oldest-first), defaulting both axes to newest-first so the most recent compatibility information reads from the upper-left corner.

  • Refresh each python:render :mirror: block through click-extra refresh-directives with the source file’s directory on sys.path, so a block importing a sibling helper module resolves offline as it does at build time.

  • Fix test-suite --command resolving a venv’s symlinked Python interpreter (.venv/bin/python) to its base target, silently dropping the venv’s installed packages.

  • Upload coverage from the once-only test job to Codecov, and move the package-install CLI checks to a dedicated CI job skipped on pull requests.

8.5.0 (2026-07-22)ΒΆ

Note

8.5.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Breaking: Rename the --show-params flag to --params. Its parameter ID changes from show_params to params, its environment variable suffix from _SHOW_PARAMS to _PARAMS, and click-extra wrap --show-params becomes click-extra wrap --params. ShowParamsOption and @show_params_option keep their names.

  • Add the click_extra.sphinx.myst_docstrings Sphinx extension: write Python docstrings in MyST markdown, transparently converted to reST at build time, keeping sphinx.ext.autodoc and sphinx_autodoc_typehints unmodified. Absorbed from repomatic.myst_docstrings.

  • Add a convert-to-myst subcommand migrating a package’s reST docstrings and comments to MyST in place, idempotently: string literals and other runtime code pass through byte-for-byte. Absorbed from repomatic, along with the sphinx-apidoc stub converter click_extra.rst_to_myst and the public convert_source().

  • Add a :mirror: flag to the python:render Sphinx directive: the block’s generated Markdown is mirrored into the source .md between <!-- mirror --> markers, reviewable in raw diffs; builds regenerate it in memory, never writing to the source.

  • Extend click-extra refresh-directives to also refresh python:render :mirror: regions, alongside {matrix} blocks, by executing each mirror block’s Python.

  • Add a start_new_session option to run_cli(): the child leads its own POSIX session and process group, and every kill path signals the whole group, so grandchildren are reaped. Off by default to keep interactive prompts working; no-op on Windows.

  • Add a themes demo subcommand (click-extra themes) printing a sample help screen rendered under every built-in theme, for a quick terminal preview of all palettes.

  • Promote ctx.render_table and ctx.print_table to methods on click_extra.Context, reading the --table-format and --sort-by selections from the context’s shared meta so they work from any subcommand. TableFormatOption and SortByOption remain drop-ins on click and cloup commands; ctx.render_table now honors --sort-by.

  • Warn on configuration keys unknown to the config_schema when the section is schema-only, instead of dropping them silently; strict mode still raises, and sections mixing CLI parameters stay silent. Exposed as warn_unknown on make_schema_callable() and schema_warn_unknown on run_config_validation().

  • Convert all of click-extra’s own docstrings and comments from reST to MyST.

  • Fix a group-level --theme not reaching the CLI wrapped by click-extra wrap: the target’s help now renders in the chosen palette instead of falling back to the default dark theme.

  • Fix click-extra refresh-directives rewriting {matrix} examples nested inside longer code fences: documented illustrations are copied verbatim, never refreshed or executed.

8.4.0 (2026-07-16)ΒΆ

Note

8.4.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Breaking: Remove the historical from click_extra.version import prebake_* compatibility imports; the pre-baking helpers are only importable from click_extra.prebake.

  • Breaking: Remove the leaked annotations and warnings entries from the package’s public API: both were star-import artifacts, not Click, Cloup or Click Extra API.

  • Breaking: Move args_cleanup, format_cli_prompt, PROMPT and INDENT from click_extra.testing to click_extra.execution; all but PROMPT stay importable from their historical home.

  • Breaking: Remove the dead CarapaceCompletion.is_empty() method and the deprecated alert parser’s current_depth().

  • Add a --tree flag to the default option set: it prints the whole hierarchy of nested subcommands as a tree (names, aliases, operand metavars and one-line descriptions), then exits. The new click_extra.tree module exposes render_command_tree(), TreeOption and @tree_option.

  • Add a --tree mode to click-extra wrap: prints the subcommand tree of any foreign Click CLI without running it, with the same target resolution as --show-params and --man.

  • Help screens and the --tree view now style subcommand aliases with the alias theme slot and their parenthetical punctuation with alias_secondary; aliases used to take the subcommand slot and the punctuation stayed plain.

  • Table formats able to express styles natively (html, unsafehtml, mediawiki, textile, jira and the four latex* variants) now translate the ANSI codes carried by cells and headers to the format’s own styling markup instead of stripping them.

  • An explicit --color no longer injects raw ANSI codes into the markup formats supporting native styling; the raw passthrough escape hatch remains for the formats without.

  • Add split_ansi() and render_ansi() plus the ansi_to_html(), ansi_to_jira(), ansi_to_latex() and ansi_to_textile() converters to click_extra.styling.

  • Add run_cli(args) to click_extra.execution: a subprocess.run work-alike that logs the invocation as a copy-pasteable prompt line and streams the child’s output to the logger as it is produced; a per-call label tags each streamed record.

  • format_cli_prompt now styles each token family with the theme slot it holds elsewhere in a CLI’s output; the binary-path renderer behind it is public as highlight_bin_name(program).

  • Add the Duration parameter type to click_extra.types: parses a friendly duration (7 days, 12h), an ISO 8601 duration (P7D) or an RFC 3339 timestamp into a datetime.timedelta; zero, empty and future values parse to None.

  • One --sort-by can now serve subcommands rendering heterogeneous tables: SortByOption accepts bare column IDs resolved per table, print_table() and render_table() headers accept ColumnSpec instances and (label, column_id) pairs, and column_sort_key() is public. An explicit default=() declares no default sort.

  • Add the isolated_app_dir fixture to click_extra.pytest: repoints click.get_app_dir-based configuration discovery at a fresh per-test directory, so in-process CLI invocations never read the host’s real configuration folder.

  • Add install_interrupt_handler(ctx) and terminate_live_processes() to click_extra.execution: the first Ctrl+C now SIGTERMs every subprocess spawned through run_cli.

  • Log records emitted while a Spinner animates on the same stream are now printed through Spinner.echo(), on their own line above the animation, instead of garbling the in-progress frame. Adds active_spinner() to click_extra.spinner.

  • Add temporary_env() to click_extra.envvar: a context manager applying environment variable changes for the duration of a block, then restoring every touched variable.

  • Expose generator_tag() in click_extra.parameters: the provenance tag stamped into generated man pages and Carapace completion specs.

  • Unify the palettes materializing the 16 ANSI colors as concrete RGB: Style CSS output, contrast math and the first 16 slots of the indexed palette now share the palette the documentation renders terminal sessions with.

  • select_row accepts any Mapping, not just dict, so read-only row shapes project without a copy.

  • test-suite now runs its target binaries through run_cli: each invocation is disclosed as a themed prompt line and its output streams live to DEBUG logs.

  • print_table() now honors a --color forced on a parent group: the raw-ANSI escape hatch used to be ignored when the color option was not declared on the very command printing the table.

  • --color/--no-color now reach output produced from background threads: StreamHandler consults the process-wide invocation_color() instead of click.echo’s thread-local context lookup.

  • Formatter no longer mutates a record’s levelname in place: a record formatted several times no longer accumulates styling or glued labels.

  • Style.from_ansi() now parses the parameter-less reset escape (\x1b[m) and ignores all selective reset codes (22-29, 39, 49, 55), not just the full 0 reset.

  • ConfigOption.excluded_params now resolves the CLI’s --help option ID from Click at runtime instead of assuming it is named help; the option keeps being excluded from configuration files if Click ever renames it.

  • ExtraOption.handle_parse_result now pre-records the parameter source of every option, not just eager ones, so non-eager callbacks and types keep introspecting their provenance on Click 8.4.0.

  • The --jobs sequential-execution warning now fires only for an explicit auto/max request; the option’s own default logs it at info level.

  • test-suite no longer crashes on non-UTF-8 binary output: undecodable bytes are escaped into the captured stream, and the subprocess inherits PYTHONIOENCODING=utf8.

  • A test-suite case skipped by only_platforms now reports the platforms it requires; the message used to name the current platform.

  • regex_fullmatch_line_by_line now reports a regular line mismatch instead of crashing with an IndexError when the regex and the checked content do not have the same number of lines.

  • Add a binaries page to the documentation: a searchable, sortable catalog of every released standalone executable with download links, VirusTotal analyses and a detection trend chart.

  • Coverage now uploads to Codecov from one runner per OS and Python version, on released Click and Cloup only; the Test Analytics upload and its junit.xml artifact are dropped.

8.3.0 (2026-07-08)ΒΆ

Note

8.3.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add a click:config Sphinx directive documenting a CLI’s config_schema: a summary table plus one section per option, with docstring, type, default, and a TOML example. Adds schema_field_infos(), field_docstrings() and SchemaFieldInfo to the public API.

  • Disable mouse zoom on the class inheritance diagrams of the documentation’s API sections, so they no longer hijack page scrolling; the fullscreen viewer keeps zoom.

  • Add tests covering 256-color palette index 0 and empty-string colors in Style, gated on runtime probes of Click 8.5.0’s color validation.

8.2.0 (2026-07-01)ΒΆ

Note

8.2.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add a --export-config FORMAT option to every @command and @group: it renders the resolved configuration on <stdout> in any writable format (toml, yaml, json, json5, jsonc, hjson, xml), then exits. Adds ExportConfigOption, @export_config_option and SERIALIZABLE_FORMATS to the public API.

  • Add --theme=auto: it selects the dark or light palette from the terminal background, detected from CLITHEME, COLORFGBG or a live OSC 11 query; the default stays dark. Adds resolve_background and query_osc_background to click_extra.color, resolve_auto_theme and AUTO_THEME to click_extra.theme.

  • Add run_lanes(func, lanes) and resolve_jobs(ctx, count) to click_extra.execution: run each lane serially while distinct lanes run concurrently, sized by --jobs; expose the worker-count policy shared with run_jobs. A serial_at_debug keyword collapses both fan-outs to sequential at DEBUG verbosity.

  • Add the always-on matrix Sphinx directive, rendering a package’s release compatibility matrix from its git tags, for the Python interpreter ({matrix} python) or a dependency ({matrix} <distribution>) axis; a comment-marker form renders the embedded table on GitHub too.

  • Add the click-extra refresh-directives command (wrapping click_extra.sphinx.matrix.update_matrix_blocks) to regenerate the tables embedded in {matrix} directive blocks and <!-- matrix … --> marker regions; its --check mode flags stale tables in CI.

  • Publish format_cli_prompt in click_extra.testing (was the private _format_cli_prompt): render a themed, copy-pasteable prompt simulating a CLI invocation.

  • Fix Carapace dynamic completion: an option’s value or a subcommand argument with a custom shell_complete now resolves through the generated spec, instead of returning empty or root-level candidates.

  • Fix EnumChoice shell completion on Click 8.4.0: completion candidates are now normalized, so they match the option’s accepted values instead of appearing as raw uppercase enum names.

  • Fix run_jobs blocking on Ctrl+C during parallel execution: an interrupt now drops queued items and returns immediately, instead of waiting for every in-flight task to finish.

  • Add a documentation page on Typer compatibility, explaining why click-extra cannot be combined with Typer and how to get the same options natively.

8.1.4 (2026-06-27)ΒΆ

Note

8.1.4 is available on 🐍 PyPI and πŸ™ GitHub.

  • Skip the EnumChoice shell-completion case-folding test on Click 8.3.

8.1.3 (2026-06-27)ΒΆ

Note

8.1.3 is available on 🐍 PyPI and πŸ™ GitHub.

  • Mark test as network-dependent.

8.1.2 (2026-06-27)ΒΆ

Note

8.1.2 is available on 🐍 PyPI and πŸ™ GitHub.

  • The runner pytest fixture now pins HOME and its platform equivalents inside its isolated filesystem, making configuration-file discovery independent of the ambient environment.

  • The Sphinx, MkDocs and Carapace tests now self-skip when their optional dependencies are missing, so downstream packagers no longer need to --ignore them.

8.1.1 (2026-06-24)ΒΆ

Note

8.1.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix multiple and variadic (nargs=-1) options typed with EnumChoice: their tuple default was stringified as a whole (str((MyEnum.FOO,))) instead of per member, so the default tripped Click’s Value must be an iterable check when the option was left unset.

  • Fix decorator_factory leaking options across reuses of a pre-instantiated decorator: applying the same command() or group() decorator to several functions accumulated duplicate parameters, because Click extended its shared params list in place on each use.

8.1.0 (2026-06-24)ΒΆ

Note

8.1.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Breaking: Rename the test-plan subcommand to test-suite, its --plan-file/--plan-envvar options to --suite-file/--suite-envvar, its [tool.<cli>.test-plan] config section to [tool.<cli>.test-suite], the click_extra.test_plan module to click_extra.test_suite, and the TestPlanConfig/parse_test_plan/run_test_plan/DEFAULT_TEST_PLAN API to TestSuiteConfig/parse_test_suite/run_test_suite/DEFAULT_TEST_SUITE. The CLITestCase class and the [[cases]] file structure keep their names.

  • Breaking: Replace the test-suite config’s inline field with a native cases array under [tool.<cli>.test-suite.cases] (or set file to a suite path). Adds the cases field to TestSuiteConfig and the cases_from_data helper.

  • Breaking: ClickExtraConfig, TestSuiteConfig, and PrebakeConfig are no longer re-exported from the top-level click_extra namespace; import them from click_extra.config.

  • Add a Carapace completion exporter: the click_extra.carapace module serializes a Click command tree to carapace-spec YAML for native shell completion, behind a new carapace extra. The to_carapace_spec, dump_carapace_spec, write_carapace_spec and install_carapace_spec API answers click#3188.

  • Add a --carapace mode to the wrap command: click-extra wrap --carapace SCRIPT prints the target CLI’s spec, and --install writes it into Carapace’s user spec directory. Mutually exclusive with --man and --show-params.

  • The wrap command now accepts a local project directory, reading its console-script entry point from pyproject.toml or setup.cfg so a checked-out project can be wrapped without installing it first.

  • Add the @sort_by_option decorator for the --sort-by table option, composing with option groups and constraints; it accepts ColumnSpec definitions and a columns= registry so one column tuple drives both --columns and --sort-by. Closes click-extra#1777.

  • Decorators built by decorator_factory carry proper signatures: their option class’s constructor surfaces in help(), the REPL and autodoc, and overloaded type hints let basedpyright, pyright and mypy infer the produced command or decorated callback. Closes click-extra#1781.

  • @version_option accepts an explicit version string as its first positional argument (@version_option("1.2.3")), for drop-in compatibility with Click.

  • A test-suite file may now be in any list-capable config format detected from its extension: TOML and JSON (built-in), plus YAML, JSON5, JSONC and Hjson (with their extras). Adds the load_test_suite helper and SUITE_FORMATS constant.

  • Accept a bare integer timeout in a test-suite case, coercing it to a float instead of rejecting it.

  • Default the test-suite config file to ./tests/cli-test-suite.toml, which parses with the built-in tomllib and so needs no optional extra.

  • Add an all extra that pulls in every optional feature at once.

  • Centralize config format reading, serialization, and detection in click_extra.config with the new serialize_content, read_file, and format_from_path helpers, joining the existing parse_content.

  • Add iter_subcommands and make_resilient_context to click_extra.parameters for enumerating a group’s visible subcommands and building a parse-free introspection context.

  • Add the CONFIG_PATH_METADATA_KEY and NORMALIZE_KEYS_METADATA_KEY named constants for the schema field-metadata keys, alongside the existing EXTENSION_METADATA_KEY.

  • Man pages now render optional-value options like --color as --color[=auto|always|never] and drop the spurious value metavar on repeatable count options like -v/--verbose.

  • When introspection (--man, --show-params, --carapace) cannot find a Click command in the resolved module, the error now explains that an entry point importing its command lazily must be addressed with module:function notation.

  • Unify the β€œmissing optional dependency” error messages behind a shared missing_extra_message helper, pointing at the canonical pip install click-extra[<extra>] install target.

  • Restrict pytest collection to the tests folder and switch to importlib import mode, fixing import file mismatch errors when building from a packaged source tree alongside an installed copy. Closes click-extra#1779.

  • Show the same configuration across all eight supported formats (TOML, YAML, JSON, JSON5, JSONC, Hjson, INI, XML) in a tabbed block in the configuration docs.

  • Silence ambiguous cross-reference warnings in the Sphinx documentation build for the ColumnSpec, ConfigFormat, ConfigValidator and LogLevel classes re-exported at the package root.

8.0.1 (2026-06-22)ΒΆ

Note

8.0.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Redo a proper release.

8.0.0 (2026-06-22)ΒΆ

Note

8.0.0 is available on 🐍 PyPI.

Warning

8.0.0 is not available on πŸ™ GitHub.

  • Breaking: Drop the Extra prefix from public classes (ExtraCommand to Command, ExtraGroup to Group, ExtraContext to Context, ExtraVersionOption to VersionOption, and eight more); ExtraOption keeps its prefix.

  • Breaking: Remove the deprecated extra_command, extra_group and extra_version_option aliases; use command, group and version_option instead.

  • Breaking: VersionOption and @version_option now take fields={...} and styles={...} mappings instead of per-field value and *_style parameters; message/message_style are unchanged.

  • Breaking: Replace the --color/--no-color boolean with the GNU tri-state --color[=WHEN] (auto, always, never), defaulting to auto; a bare --color means always.

  • Breaking: Remove the --ansi/--no-ansi aliases of --color/--no-color.

  • Breaking: Remove the show-params and man subcommands; use click-extra wrap --show-params and click-extra wrap --man instead.

  • Breaking: Rename the click_extra.wrap module to click_extra.cli_wrapper; update any from click_extra.wrap import ... accordingly.

  • Breaking: Reorganize the configuration subsystem into a click_extra.config package with schema, formats, and option submodules; public symbols stay importable from click_extra.config.

  • Breaking: Split click_extra.colorize into click_extra.highlight (help-screen highlighting) and click_extra.color (color-mode resolution); root re-exports unchanged, update deeper imports.

  • Breaking: Split the theme palette and HTML renderer into click_extra.theme_docs and the spinner preset catalog into click_extra.spinner_presets; root re-exports unchanged, update deeper imports.

  • Breaking: Remove print_sorted_table; SortByOption now bakes the sort key into ctx.print_table for use with or without --sort-by.

  • Breaking: Remove dead ParamStructure internals: the unused flatten_tree_dict/_flatten_tree_dict_gen methods, the __init__, and the redundant SEP attribute (use the module-level click_extra.parameters.PARAM_PATH_SEP).

  • Breaking: Remove the unused click_extra.styling.cascade_fields helper.

  • Add a Spinner widget for long blocking work as a context manager or decorator, with 90 presets in SPINNERS and TTY auto-disable; includes a spinner demo subcommand on the click-extra CLI.

  • Add click_extra.test_plan and a click-extra test-plan subcommand for YAML-driven black-box subprocess testing of any CLI; YAML parsing needs the yaml extra.

  • Add --progress/--no-progress (ProgressOption) and click_extra.progressbar, a drop-in for click.progressbar that hides under --no-progress or --accessible.

  • Add -q/--quiet (QuietOption), the counterpart to -v/--verbose: each -q lowers the log level toward CRITICAL, the two cancelling out.

  • Under --accessible, click_extra.clear is a no-op and click_extra.echo_via_pager streams to stdout instead of spawning a pager.

  • Add no_color_option/NoColorOption, a standalone --no-color flag for plain click.command CLIs.

  • Add {author}, {license}, {git_distance}, and {git_dirty} version-string template variables; git ones support pre-baking via click-extra prebake all.

  • VersionOption git fields fall back to .git_archival.json when running from a git archive export without a .git directory.

  • --jobs (JobsOption) now accepts auto and max keywords in addition to an integer, with shell completion; run_jobs(func, items) executes items against the resolved count.

  • Add make_schema_callable(schema), a callable that coerces a raw config dict into a validated dataclass.

  • Add require_sibling_param and last_param helpers to click_extra.parameters for locating sibling and typed parameters at call time.

  • Re-type pass_context for the enhanced Context, so @pass_context def cmd(ctx: Context) type-checks.

  • Add click_extra.prebake hosting build-time version pre-baking helpers (prebake_version, prebake_dunder, discover_package_init_files); still importable from click_extra.version.

  • Speed up import click_extra by deferring heavy imports, cutting startup time by roughly a third.

  • Drop requests as a runtime dependency; the configuration-from-URL loader now uses urllib.request.

  • click-extra wrap honors the tri-state color resolution, colorizing the wrapped CLI under auto only when the output is a terminal.

  • --color and --no-color colorize eager --help and --version screens regardless of their position on the command line. Closes click-extra#137.

  • --color[=WHEN] accepts yes/force, no/none, and tty/if-tty as hidden aliases; configuration files also accept native booleans (true/false).

  • Under auto, a dumb or unknown TERM strips ANSI color even on a terminal; an explicit --color or FORCE_COLOR overrides.

  • Branded 24-bit themes (dracula, monokai, nord, solarized_dark) downsample to 256 colors when the terminal does not advertise truecolor.

  • click-extra wrap --show-params now reports the target’s environment variables and resolves parameter values and their source from arguments passed after SCRIPT.

  • Lower the Click floor from 8.4.1 to 8.3.1, restoring support for Click 8.3.1 and later.

  • The click:run and click:tree Sphinx directives now capture at the file-descriptor level by default (Click 8.4+); set click_extra_run_capture = "sys" to opt out.

  • Tolerate a missing click_extra/themes.toml data file: log a warning and fall back to the no-color theme.

  • Fix from click_extra import * raising AttributeError due to VersionOption missing from the bound namespace.

  • Fix the dim bracket styling of an IntRange option’s [x>=N] constraint leaking across the next option in colored help.

  • Fix inconsistent highlighting of the --jobs [auto|max|INTEGER] metavar in colored help.

  • Fix the assert_output_regex testing fixture raising TypeError on a failed match under pytest 9.

  • Fix context_settings={"show_choices": True} being ignored on a Command or Group.

  • Fix click-extra man and write_manpages author and version resolution when the import name differs from the installed distribution name.

  • --validate-config now raises RuntimeError instead of TypeError when used on a command with no sibling --config option, matching --no-config.

  • Fix broken documentation links for the GNU --color reference, click.Parameter API anchor, and parameters page cross-references.

7.20.1 (2026-06-18)ΒΆ

Note

7.20.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix the MkDocs plugin and Sphinx directives leaving Rich-based CLIs (such as rich-click) colorless in rendered documentation.

7.20.0 (2026-06-17)ΒΆ

Note

7.20.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add MultiChoice to click_extra.types: a Click ParamType for comma-separated multi-pick from a fixed set of values, the pick-many counterpart to click.Choice.

  • Extend the --show-params table with seven new columns (Is flag, Flag value, Is bool flag, Multiple, Nargs, Prompt, Confirmation prompt).

  • Add the --columns option (ColumnsOption, @columns_option) for SQL SELECT-style column selection on both --show-params and the standalone click-extra show-params subcommand.

  • Add a click:tree Sphinx directive that walks a Click command tree and expands into a summary table plus one {click:run} --help block per command. MyST-only.

  • Fix click-extra show-params ignoring the top-level --table-format option and rendering its default as the enum name instead of the kebab-case ID.

  • Fix click-extra show-params and click-extra man resolving auto-generated environment variables as empty; the envvars column now matches what Click reads at runtime.

  • Fix the MkDocs plugin stripping ANSI escape codes but rendering no colors: it now generates the ANSI Pygments stylesheet and registers it through extra_css, so the -Ansi-* classes it emits are styled.

  • Drop duplicate and dead CSS classes from ANSI HTML rendering: compound tokens like Token.Ansi.Bold.Cyan now emit -Ansi -Ansi-Bold -Ansi-Cyan instead of repeating -Ansi-Bold and adding an unstyled -Ansi-Bold-Cyan.

7.19.0 (2026-06-12)ΒΆ

Note

7.19.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add an --output-dir DIR option to click-extra man, writing one .1 file per command into DIR instead of printing a single page to stdout.

  • Add a click_extra_manpages Sphinx config value and a click-extra-manpages directive to emit Click command trees as roff .1 files (and browser-viewable .html siblings when mandoc or groff is available) on every HTML build.

  • Fix ExtraVersionOption.package_version resolving to None when the top-level module name differs from the installed distribution name (PIL vs Pillow); pass package_name explicitly to disambiguate.

7.18.0 (2026-05-29)ΒΆ

Note

7.18.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Breaking: Consolidate --time, --jobs, and -0/--zero-exit into a single click_extra.execution module; the click_extra.jobs and click_extra.timer submodules are removed (their decorators and classes remain importable from the click_extra root).

  • Breaking: Unify configuration-loading errors under ValidationError. Unknown CLI-parameter keys (strict=True) and unknown schema fields (schema_strict=True) now exit with code 1 instead of raising an uncaught ValueError; catch the SystemExit or use --validate-config / run_config_validation() to inspect errors.

  • Add a --man option to @extra_command and @extra_group (and the @man_option decorator) that prints the command’s man page to stdout and exits.

  • Add an --accessible option (and @accessible_option decorator, AccessibleOption class) to @extra_command and @extra_group; it or the ACCESSIBLE environment variable is equivalent to --no-color --table-format plain for screen readers. Explicit --color or --table-format keeps precedence.

  • Add a man subcommand to the click-extra CLI: click-extra man SCRIPT [SUBCOMMAND]... renders any external Click CLI’s man page. Both man and show-params now also accept .py file targets.

  • Add the click_extra.man_page module to generate man pages programmatically: render_manpage(), render_manpages(), and write_manpages().

  • Add a -0/--zero-exit option (@zero_exit_option decorator, ZeroExitOption class) that records intent in ctx.meta under the ZERO_EXIT key for downstream code to read.

  • Honor the standard POSIXLY_CORRECT environment variable: when present, ExtraContext forces allow_interspersed_args to False, stopping option parsing at the first positional argument.

  • Add run_config_validation() and the ValidationReport dataclass to click_extra.config, running the CLI-parameter check, schema build, and every registered ConfigValidator in one pass; collect_all toggles between gathering all errors or stopping at the first.

  • Fix schema_strict=True wrongly rejecting a configuration field marked with EXTENSION_METADATA_KEY when its Python type is not a mapping.

7.17.2 (2026-05-26)ΒΆ

Note

7.17.2 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add Mermaid diagrams throughout the documentation for configuration source selection and precedence, class layering and default-option bundles, --color/--no-color enablement, {version}/{exec_name} fallback chains, the decorator_factory guardrail, and environment-variable id resolution.

7.17.1 (2026-05-25)ΒΆ

Note

7.17.1 is available on πŸ™ GitHub.

Warning

7.17.1 is not available on 🐍 PyPI.

  • Fix the Nuitka standalone binaries aborting at startup with FileNotFoundError: themes.toml by bundling click_extra/themes.toml via a new [tool.nuitka] include-package-data setting.

7.17.0 (2026-05-25)ΒΆ

Note

7.17.0 is available on πŸ™ GitHub.

Warning

7.17.0 is not available on 🐍 PyPI.

  • Breaking: Bump the Click floor to 8.4.1, required for correct parameter-source detection in eager callbacks (ColorOption precedence, ConfigOption branching, ShowParamsOption’s Source column).

  • Breaking: Bump the requests floor to 2.34; it now ships inline type annotations, so the types-requests stub package is removed from the typing dependency group.

  • All built-in themes now follow the man-pages(7) font convention: literal tokens (commands, aliases, option flags, choice values) render bold and replaceable tokens (metavars, argument names) render italic. Declared by the new LITERAL_STYLES / REPLACEABLE_STYLES frozensets in click_extra.theme.

  • Add a colorless manpage built-in theme that renders the bold-literal / italic-replaceable convention with no color, selectable via --theme manpage.

  • HelpCommand now raises click.NoSuchCommand instead of click.UsageError for an unknown subcommand, so the user sees did-you-mean suggestions.

  • Remove the HelpExtraFormatter.write_usage override, no longer needed now that Click measures visible width when wrapping.

  • Drop the explicit type=UNPROCESSED from NoConfigOption.__init__, now auto-detected by Click for flag_value with non-basic types.

  • Bump the myst-parser floor in the docs dependency group to 5.1; doc builds now use its native "alert" syntax extension instead of the in-tree converter.

  • Drop the colorama test-matrix variation.

7.16.1 (2026-05-15)ΒΆ

Note

7.16.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix ConfigOption leaking keys from an earlier --config into later invocations of the same CLI in one process (Sphinx builds, test runners, REPLs).

7.16.0 (2026-05-14)ΒΆ

Note

7.16.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Breaking: Remove the click_extra.themes module and the per-theme constants DARK, DRACULA, LIGHT, MONOKAI, NORD, SOLARIZED_DARK; use BUILTIN_THEMES["<name>"] instead.

  • Breaking: Replace the default_theme module attribute with get_default_theme() / set_default_theme(theme) accessors that always observe the current value.

  • Breaking: Remove the pre-rendered OK and KO constants; use the raw OK_GLYPH / KO_GLYPH strings styled at the call site so they follow the active theme.

  • Breaking: theme_registry no longer accepts a Callable[[], HelpExtraTheme] value; only HelpExtraTheme instances are valid entries.

  • Breaking: Move telemetry storage to ctx.meta[context.TELEMETRY]; consumers reading ctx.telemetry must switch to context.get(ctx, context.TELEMETRY).

  • Add four branded built-in themes: solarized_dark, dracula, nord, and monokai. The full catalog now ships as click_extra/themes.toml; BUILTIN_THEMES is the single public {name: HelpExtraTheme} dict.

  • Add a ThemeChoice click.ParamType (no longer a click.Choice subclass) whose choices read the live registry, so themes loaded from --config appear as valid --theme choices and in the --help metavar.

  • Add the click_extra.styling module with a feature-rich Style subclass (hex constructor, a | b composition, cascade, to_dict/from_dict, to_css, from_ansi, WCAG contrast_ratio), exposed as from click_extra import Style.

  • Add to_dict() / from_dict() / cascade(base) to HelpExtraTheme for sparse theme overrides layered on a full palette.

  • Read user-defined theme palettes from the config file: every [<cli>.themes.<name>] table is parsed and available to --theme, cascading on the matching built-in or registered as a stand-alone theme, without mutating the global registry.

  • Add an app-defined configuration-validation hook: new ConfigValidator, ValidationError, and EXTENSION_METADATA_KEY types, registered via a config_validators= kwarg on ExtraCommand / ExtraGroup (and @command / @group / @config_option). --validate-config now collects every error before exiting.

  • Flip the AnsiColorLexer.true_color default to True: 24-bit RGB sequences render as inline style="color: #rrggbb" spans by default. Restore the old behavior with AnsiColorLexer(true_color=False).

  • Add the :emphasize-result-lines: option to the click:run and python:run Sphinx directives to highlight lines in the captured output.

  • Fix pyproject.toml CWD discovery skipping files lacking a [tool.<cli_name>] section, so an unrelated pyproject.toml no longer shadows the user’s app-dir config.

  • Fix ExtraVerbosity.set_level() changing the logger level during help rendering and shell completion, and fix reset_loggers double-registration when both --verbosity and -v are passed.

  • Inner bracket-field slots (envvar, default, required, range_label) now fall back to the bracket slot’s style, so a minimal palette colours the whole bracket field uniformly.

  • Deprecate click_extra.sphinx.alerts now that myst-parser 5.1.0 ships a native "alert" extension; the regex converter is registered only on older myst-parser.

7.15.0 (2026-05-03)ΒΆ

Note

7.15.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Breaking: Code importing theme symbols from click_extra.colorize must switch to click_extra.theme (the from click_extra import HelpExtraTheme path is unaffected).

  • Breaking: from click_extra.commands import ExtraContext and from click_extra import ctx_meta must become from click_extra.context import ExtraContext and from click_extra import context (the from click_extra import ExtraContext path is unaffected).

  • Breaking: Disable the click:* and python:* Sphinx directives by default, since they execute arbitrary Python at build time. Re-enable with click_extra_enable_exec_directives = True in conf.py.

  • Add opt-in 24-bit true-color rendering to the ANSI Pygments stack via true_color=True on AnsiColorLexer, AnsiFilter, or any session lexer; AnsiHtmlFormatter renders the preserved RGB tokens as inline style="color: #rrggbb" spans. Default 256-color quantization is unchanged.

  • Add a click_extra.theme module centralizing all theme machinery (HelpExtraTheme, ThemeOption, theme_option, theme_registry, register_theme(), …). Every command now accepts --theme [dark|light], extensible via register_theme(); the active theme is read with get_current_theme().

  • Add a click_extra.context module consolidating ExtraContext and a documented registry of every ctx.meta key, with get() / set() helpers. Replaces click_extra.ctx_meta.

  • Add python:source, python:run, python:render, python:render-myst, and python:render-rst Sphinx directives under a new python domain, mirroring click:source / click:run for arbitrary Python; the render family turns captured stdout into live document content.

  • Tighten the Click floor to 8.3.1, the minimum shipping the parameter-name fix this depends on.

7.14.1 (2026-04-26)ΒΆ

Note

7.14.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Relax the Click floor back to 8.1 by replacing ParameterSource ordered comparisons in ConfigOption with set membership.

  • Relax the tabulate floor back to 0.9 by aliasing colon_grid to grid when tabulate < 0.10 is installed.

7.14.0 (2026-04-24)ΒΆ

Note

7.14.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add a wrap subcommand: click-extra wrap SCRIPT [ARGS]... applies help colorization to any installed Click CLI without modifying it. Supports --theme and [tool.click-extra.wrap.<script>] config sections; unknown subcommands fall through to wrap automatically. run is kept as an alias.

  • Add a show-params subcommand: click-extra show-params SCRIPT [SUBCOMMAND]... introspects any external Click CLI’s parameters as a table, honoring all --table-format renderings and drilling into nested subcommands.

  • Add get_param_spec() and format_param_row() as public API in click_extra.parameters, the shared spec extractor and cell renderer for both --show-params and show-params.

  • Make ParamStructure.get_param_type() a @staticmethod that returns str for unrecognised custom types instead of raising.

  • Replace the render-matrix subcommand with individual colors, styles, palette, 8color, and gradient subcommands under a Demo section, and remove the click-extra-demo entry point.

  • Bump the Click floor to 8.3.3.

7.13.0 (2026-04-16)ΒΆ

Note

7.13.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add a MkDocs plugin for ANSI color rendering in code blocks: install with pip install click-extra[mkdocs], then add click-extra to your mkdocs.yml plugins list.

  • Automatically patch mkdocs-click code blocks to use the ansi-output lexer when the plugin is enabled, so CLI help text with ANSI codes renders with colors.

  • Fix API reference sections rendering as raw RST instead of formatted documentation by wrapping automodule and autoclasstree directives in eval-rst blocks.

  • Add OSC 8 hyperlink support to AnsiColorLexer and AnsiHtmlFormatter, rendering terminal hyperlinks as clickable HTML <a> tags; other OSC sequences are now fully stripped.

7.12.0 (2026-04-16)ΒΆ

Note

7.12.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Breaking: change render-matrix --matrix=<choice> to a positional argument render-matrix <choice>. Add palette, 8color, and gradient choices.

  • Add JobsOption and the @jobs_option decorator for parallel execution control. Defaults to available CPUs minus one, and warns when the count is clamped.

  • Improve error messages for single-dash multi-character tokens like -dbgwrong: report the full token with close-match suggestions instead of No such option: -d.

  • Replace the pygments-ansi-color dependency with an inline ANSI SGR parser, adding italic, underline, reverse video, strikethrough, and 24-bit RGB colors. The token namespace moves from Token.Color.*/Token.C.* to Token.Ansi.* and CSS classes from .-Color-*/.-C-* to .-Ansi-*.

  • Rename lexer_map to LEXER_MAP.

  • Fix render-matrix colors styling background color column headers as foreground colors.

7.11.0 (2026-04-13)ΒΆ

Note

7.11.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add serialize_data() and print_data() to serialize arbitrary nested Python data to JSON, HJSON, TOML, YAML, and XML, complementing render_table()/print_table().

  • Add a sort_key parameter to render_table() and print_table() for pre-render row sorting.

  • Catch ImportError from missing optional dependencies in print_table() and print_data(), emitting a clean one-line error instead of a traceback. print_data() takes a package parameter to customize install instructions.

  • Add print_sorted_table() and SortByOption, which generates a --sort-by CLI option from column definitions and wires ctx.print_table to the sorted variant.

  • Add an auto-injected help subcommand to ExtraGroup: mycli help [subcommand] shows help and --search term searches all subcommands. Disable with help_command=False.

  • Expose the HelpKeywords dataclass and collect_keywords() (renamed from _collect_keywords()) as public API for extending help-screen highlighting.

  • Add extra_keywords and excluded_keywords parameters to ExtraCommand and ExtraGroup to inject or suppress highlighted strings. Both accept a HelpKeywords instance.

  • Highlight manually-added deprecation markers like (Deprecated) or (deprecated: reason) alongside Click-native (DEPRECATED) markers.

  • Style individual choices inside their own metavar ([json|csv|xml]) as structural elements, always styled even when free-text highlighting is suppressed.

  • Propagate excluded_keywords from parent groups to subcommands.

  • Fix command aliases rendered by Cloup in parenthetical groups (like backup (save, freeze)) not being highlighted in help screens.

  • Fix choice cross-reference highlighting bleeding into bracket fields when a default value contained a choice keyword (like outline in rounded-outline).

  • Fix parent-context choice collection lowercasing case-insensitive choices that define a custom metavar.

7.10.1 (2026-04-07)ΒΆ

Note

7.10.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix the pipe and github table formats to produce mdformat-compatible separator rows, preventing a formatting cycle between tabulate and mdformat.

  • Compute the test matrix dynamically via repomatic metadata (OS, Python, and stability axes), with custom Click/Cloup version axes via [tool.repomatic.test-matrix]. PRs get a reduced matrix.

  • Replace {eval-rst}-wrapped automodule and autoclasstree directives with native MyST syntax in all docs.

7.10.0 (2026-04-02)ΒΆ

Note

7.10.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Highlight parent group names in subcommand help text even when interleaved with options.

  • Add range_label, required, and argument theme slots to HelpExtraTheme, styling argument metavars separately from option metavars.

  • Add a cross_ref_highlight flag to HelpExtraTheme. Set to False to disable free-text highlighting of options, choices, arguments, metavars, and CLI names; structural elements stay styled.

  • Add type-aware flattening, field metadata, and nested dataclass support to config_schema. flatten_config_keys() and normalize_config_keys() accept an opaque_keys parameter, and fields support click_extra.config_path and click_extra.normalize_keys metadata.

  • Fix help-text highlighting of hyphenated option names (like --table-format), argument names colliding with option keywords, and substring matches in compound keywords (like outline inside rounded-outline).

  • Fix enum coloring to use normalize_choice() so the metavar strings match instead of raw enum member names.

7.9.0 (2026-03-31)ΒΆ

Note

7.9.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add a flatten_config_keys() utility to flatten nested config dicts into a single level by joining keys with a separator.

  • Flatten nested config dicts before dataclass field matching in config_schema, so nested TOML sub-tables map to flat dataclass fields.

  • Add a schema_strict parameter to ConfigOption and ExtraCommand/ExtraGroup: when True, unknown config keys raise ValueError during schema validation instead of being dropped.

  • Auto-discover pyproject.toml by walking up from the working directory to the VCS root before falling back to the app config directory.

  • Instantiate config_schema defaults when no config file is found, so get_tool_config() never returns None when a schema is configured.

  • Forward included_params from ExtraCommand/ExtraGroup to ConfigOption, letting @group(included_params=()) disable merge_default_map when config keys are schema-only.

  • Move prebake_version(), prebake_dunder(), and discover_package_init_files() from ExtraVersionOption static methods to module-level functions in click_extra.version.

  • Add a git_tag template field, resolved from a __git_tag__ dunder or git describe --tags --exact-match HEAD at runtime.

  • Add a git_tag_sha template field, resolved from a __git_tag_sha__ dunder with a git subprocess fallback. Replaces the old __tag_sha__ convention.

  • Resolve git template fields (git_branch, git_long_hash, git_short_hash, git_date) from pre-baked __<field>__ dunders before falling back to subprocess calls, so compiled binaries can embed git metadata at build time.

  • Add a click-extra prebake CLI with all, version, and field subcommands to bake __version__ and git fields. Field names auto-wrap with __...__, and targets are auto-discovered from [project.scripts].

  • Add empty __git_*__ dunder placeholders to click_extra/__init__.py.

  • Pin image URLs in readme.md and docs/tutorial.md to the release tag at bump time, restoring them to main on the next dev bump.

7.8.0 (2026-03-09)ΒΆ

Note

7.8.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add config_schema parameter to ConfigOption and ExtraCommand/ExtraGroup for typed configuration access via dataclasses or custom callables.

  • Add fallback_sections parameter for legacy configuration section name migration with deprecation warnings.

  • Add normalize_config_keys() utility to convert kebab-case config keys to snake_case Python identifiers.

  • Add get_tool_config() helper to retrieve typed configuration from context.

  • Check more variations of local, stable and dev CLI invocations.

  • Adopt RUF022 rule to let ruff enforce __all__ sorting.

  • Fix ruff 0.15.5 lint errors.

7.7.0 (2026-03-07)ΒΆ

Note

7.7.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add version_fields parameter to ExtraCommand and ExtraGroup. Forwards any ExtraVersionOption template field (e.g. prog_name, version, git_branch) from the command decorator without replacing the default params list.

  • Lazily evaluate version metadata fields in ctx.meta.

  • Remove version parameter from ExtraCommand and ExtraGroup.

  • Add hjson, json, json5, jsonc, toml, xml and yaml table formats for --table-format.

  • Add TableFormat.is_markup property.

  • Strip ANSI color codes from markup table formats (csv, html, latex, rst, etc.) by default. Use --color to preserve them.

  • Add [toml] extra dependency group for TOML table output via tomlkit.

  • Emit native types (booleans, nulls, lists) in --show-params output for structured serialization formats (JSON, YAML, TOML, HJSON, XML).

  • Fix --show-params ignoring --table-format when it appears first on the command line.

  • Expand dotted keys in configuration files (e.g. "subcommand.option": value) into nested dicts before merging, to allow for mixing flat dot-notation and nested structures.

  • Only capture timer start time when --time is actually requested.

  • Add click-extra entry point so uvx click-extra works out of the box. The click-extra-demo alias is kept for backward compatibility.

7.6.5 (2026-03-05)ΒΆ

Note

7.6.5 is available on 🐍 PyPI and πŸ™ GitHub.

  • Bump tabulate requirement from >=0.9 to >=0.10.

  • Add new colon-grid table format.

  • Replace custom github table renderer with tabulate’s pipe format. Backport of python-tabulate#410.

7.6.4 (2026-03-04)ΒΆ

Note

7.6.4 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix ExtraVersionOption.cli_frame() crashing in Nuitka-compiled binaries where all stack frames belong to the Click ecosystem.

  • Fix ExtraVersionOption.module_version returning None in __main__ entry points by checking the parent package’s __version__.

  • Fix test plan for Nuitka-compiled binary.

  • Add @pytest.mark.once marker for platform-independent structural tests. Run them in a single CI job instead of across the full matrix.

7.6.3 (2026-03-02)ΒΆ

Note

7.6.3 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix test_default_pattern_roaming_force_posix test failures when XDG_CONFIG_HOME is set. Closes #1541.

7.6.2 (2026-02-27)ΒΆ

Note

7.6.2 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add ExtraVersionOption.prebake_version() static method to pre-bake __version__ strings with Git hashes at compile time, complementing the runtime version property for Nuitka/PyInstaller binaries.

7.6.1 (2026-02-27)ΒΆ

Note

7.6.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix test failures when optional config format dependencies are not installed. Closes #1538.

7.6.0 (2026-02-26)ΒΆ

Note

7.6.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add _default_subcommands reserved configuration key to auto-invoke subcommands when none are provided on the CLI. Closes #1405.

  • Add _prepend_subcommands reserved configuration key to always prepend subcommands to every invocation (requires chain=True). Closes #1405.

  • Add --validate-config option to validate configuration files.

  • Add ConfigFormat.PYPROJECT_TOML format for [tool.*] section support in pyproject.toml. Closes #1524.

  • Stop parent directory walk on inaccessible directories.

  • Add stop_at parameter to @config_option to limit parent directory walking. Defaults to VCS. Closes #651.

  • Add VCS sentinel and VCS_DIRS constant for VCS root detection.

  • Resolve relative paths to absolute in parent_patterns before yielding.

  • Add included_params allowlist to ConfigOption and @config_option, the inverse of excluded_params. Closes #1362.

  • Add human-friendly display labels to ConfigFormat.

  • Switch back from SPLIT to BRACE flag for multi-format config file patterns. Fixes a bug where only the first format received the directory prefix with SPLIT.

  • Hard code icon workaround for Sphinx index entries.

  • Automatically append Git short hash as a PEP 440 local version identifier to .dev versions (e.g., 1.2.3.dev0+abc1234).

  • Skip Git hash suffix for versions that already contain + (pre-baked local identifiers) to avoid invalid double-suffixed versions.

  • Recognize LLM environment variable to strip ANSI codes when running under an AI agent.

7.5.3 (2026-02-22)ΒΆ

Note

7.5.3 is available on 🐍 PyPI and πŸ™ GitHub.

  • Allow disabling of autodiscovery of configuration files by setting default=NO_CONFIG on @config_option. Closes #1495.

  • Implement resolve_any_xref in ClickDomain to prevent MyST-Parser warning. Closes #1502.

  • Fix subcommand conflict detection checking against root-level params instead of parent params. Closes #1286.

7.5.2 (2026-02-12)ΒΆ

Note

7.5.2 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix GitHub alerts converter mangling list-table directive content. Closes #1490.

  • Replace Dependabot by Renovate.

  • Move click_extra/docs_update.py to docs/docs_update.py.

  • Add pygments-ansi-color to docs dependency group for lexer table generation.

7.5.1 (2026-02-05)ΒΆ

Note

7.5.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add new aligned table format with single-space column separators and no borders.

  • Fix parallel mode support in Sphinx extension. Closes #1482.

7.5.0 (2026-02-03)ΒΆ

Note

7.5.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix TableFormat.GITHUB to render proper alignment hints in the separator row (:---, :---:, ---:).

  • Move auto-lock time from 8:43 to 4:43.

  • Set cooldown period via the pyproject.toml.

  • Add Download link to project metadata.

  • Include license file in package.

  • Replace deprecated codecov/test-results-action by codecov/codecov-action.

  • Remove utilization workaround for macos-15-intel.

  • Bump requirement of extra-platforms to 8.0.0.

7.4.0 (2025-12-08)ΒΆ

Note

7.4.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add cooldown period for dependabot and uv.lock updates.

  • Uncap all dependencies.

  • Replace tool.uv section by build-system.

  • Merge all label jobs into a single one.

  • Unlock a CPU core stuck at 100% utilization on macos-15-intel.

7.3.0 (2025-12-01)ΒΆ

Note

7.3.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add click:source directive as an alias to click:example directive in Sphinx extension.

  • Flag click:example directive as deprecated in favor of click:source.

  • Add support for nested GitHub alerts.

  • Fix fetching version when the CLI is implemented as a standalone script and not as a package module.

7.2.0 (2025-11-26)ΒΆ

Note

7.2.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add support for auto-conversion of GitHub alerts into MyST admonitions in Sphinx extension.

  • Rename click-extra demo CLI to click-extra-demo to avoid confusion with the package name.

  • Run tests on ubuntu-slim GitHub Actions runner.

  • Run docs update job on ubuntu-slim runner.

7.1.0 (2025-11-21)ΒΆ

Note

7.1.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add support for aliases in EnumChoice type.

  • Register pre-configured render_table() utility in the context when table_format is set, in the same spirit as print_table().

7.0.1 (2025-11-18)ΒΆ

Note

7.0.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Restore support for @extra_command, @extra_group and @extra_version_option, but mark them as deprecated.

7.0.0 (2025-11-18)ΒΆ

Note

7.0.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Allow parent directories search for configuration files. Adds search_parents argument on @config_file. Closes #651.

  • Allow fine-tuning of configuration file format pattern matching. Replaces formats argument on @config_file by file_format_patterns.

  • Adds search_pattern_flags and file_pattern_flags arguments on @config_file to allow user to tweak pattern matching behavior.

  • Use | as separator for multiple file patterns instead of {,} syntax. Replace glob.BRACE by glob.SPLIT for search pattern flags. Force glob.SPLIT for file pattern flags.

  • Remove glob.IGNORECASE flag to make case-sensitivity determined by the underlying platform at runtime.

  • Force glob.NODIR for search pattern flags to speed up search.

  • Rename click_extra.config.Formats enum to click_extra.config.ConfigFormat. Expose it at the root click_extra module.

  • Eat our own dog food: add a click-extra CLI to run self-tests.

  • Override base decorators and classes with Click Extra’s own variants:

    • @command now points to what was @extra_command.

    • @group now points to what was @extra_group.

    • Option class now points to click_extra.Option, which is a subclass of cloup.Option.

    • Argument class now points to click_extra.Argument, which is a subclass of cloup.Argument.

    • @option now instantiates click_extra.Option by default.

    • @argument now instantiates click_extra.Argument by default.

    • @version_option now points to what was @extra_version_option.

    • Now if you want to use the previous aliases to Click’s and Cloup’s originals, import them directly from click or cloup instead of click_extra, which makes origination clearer.

  • Remove @extra_command, @extra_group and @extra_version_option.

  • Remove no_redefined argument in click_extra.pytest.command_decorators() method.

  • Validates that classes passed to the cls parameter of decorators are subclasses of the expected base classes.

  • Normalize the default value of EnumChoice parameters to their string choice representation in help screens.

  • Run tests on Python 3.14t and 3.15t free-threaded variants.

6.2.0 (2025-11-04)ΒΆ

Note

6.2.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add new EnumChoice type for fine-tunable Enum-based choices. Expose EnumChoice and ChoiceSource at the root click_extra module.

  • Relax dependencies to support Python 3.10. Closes #1385.

  • Re-introduce tomli dependency for Python 3.10 users.

  • Skip tests on intermediate Python versions (3.11, 3.12 and 3.13) to reduce CI load.

6.1.0 (2025-10-29)ΒΆ

Note

6.1.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add support for JSON5, JSONC and HJSON configuration files.

  • YAML and XML configuration support is now optional. You need to install the click_extra[yaml] and click_extra[xml] extra dependency groups to enable it.

  • Add new @lazy_group decorator and LazyGroup class to create groups that only load their subcommands when invoked. Closes #1332.

  • Move all custom types to click_extra._types module.

  • Avoid importing all types at runtime to reduce startup time.

  • Upgrade tests runs from macos-13 to macos-15-intel, and from macos-15 to macos-26.

  • Use astral-sh/setup-uv action to install uv.

6.0.3 (2025-10-13)ΒΆ

Note

6.0.3 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix regex_fullmatch_line_by_line to accept compiled regex patterns as well as string patterns.

6.0.2 (2025-10-11)ΒΆ

Note

6.0.2 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add a new regex_fullmatch_line_by_line utility to compare a wall of text against a regex, line by line, and raise a custom RegexLineMismatch exception on the first mismatch.

6.0.1 (2025-10-08)ΒΆ

Note

6.0.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix @config_option to accept Path objects as default value. Closes #1356.

  • Add official support of Python 3.14.

  • Run tests on Python 3.15-dev.

6.0.0 (2025-09-25)ΒΆ

Note

6.0.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add new variables for version string template: {git_repo_path}, {git_branch}, {git_long_hash}, {git_short_hash} and {git_date}.

  • Add a new --no-config option on @extra_command and @extra_group to disable configuration files. Closes #750.

  • Add --table-format option by default on @extra_command and @extra_group.

  • Let --table-format and --no-color affect the rendering of --show-params table.

  • Swap Class and Spec. columns in --show-params output.

  • Remove the -C short option associated with --config.

  • Remove the -t short option associated with --table-format.

  • Classify table formats into two categories: markup formats and plain-text formats.

  • Rename all table format identifiers to use dashes instead of underscores:

    • double_grid β†’ double-grid

    • double_outline β†’ double-outline

    • fancy_grid β†’ fancy-grid

    • fancy_outline β†’ fancy-outline

    • heavy_grid β†’ heavy-grid

    • heavy_outline β†’ heavy-outline

    • latex_booktabs β†’ latex-booktabs

    • latex_longtable β†’ latex-longtable

    • latex_raw β†’ latex-raw

    • mixed_grid β†’ mixed-grid

    • mixed_outline β†’ mixed-outline

    • rounded_grid β†’ rounded-grid

    • rounded_outline β†’ rounded-outline

    • simple_grid β†’ simple-grid

    • simple_outline β†’ simple-outline

  • Fix display in --show-params for parameters sharing the same name.

  • Fix detection in the --version option of the module in which the user’s CLI is implemented.

  • Rename click_extra.tabulate namespace to click_extra.table.

  • Expose click._utils.UNSET and click.logging.LogLevel at the root click_extra module.

  • Replace unmaintained mergedeep dependency by deepmerge.

  • Remove maximum capped version of all dependencies (relax all ~= specifiers to >=). This gives more freedom to downstream and upstream packagers. Document each minimal version choice.

  • Add unit tests for Sphinx extension.

  • Render GitHub-Flavored Markdown admonitions in Sphinx.

5.1.1 (2025-08-24)ΒΆ

Note

5.1.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Relax Click dependency to account for yanked release. Closes #1307.

5.1.0 (2025-08-03)ΒΆ

Note

5.1.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add support for MyST Markdown syntax for click:example and click:run Sphinx directives.

  • Add support for all code-block options to click:example and click:run: :linenos:, :lineno-start:, :emphasize-lines:, :force:, :caption:, :name:, :class: and :dedent:.

  • Add new :show-source:/:hide-source:, :show-results:/:hide-results: and :language: options to click:example and click:run. Closes #719.

  • Support non-string choices in colored help screens. Closes #1284.

  • Replace LOG_LEVELS mapping with LogLevel enum.

  • Remove DEFAULT_LEVEL_NAME constants.

  • Fix rendering of default values in --show-params output.

  • Fix reconciliation of flags’ environment variables.

  • Force requirement on cloup >= 3.0.7.

  • Be more informative when error is found in click:example and click:run Sphinx directives by displaying the path of the original document and the line number of the error.

5.0.2 (2025-05-31)ΒΆ

Note

5.0.2 is available on 🐍 PyPI and πŸ™ GitHub.

  • Set ExtraCommand default prog_name to CLI’s name to avoid it to be named python -m <module_name> if invoked out of a module.

  • Tweak exit code rendering of CLI runs.

5.0.1 (2025-05-28)ΒΆ

Note

5.0.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix highlighting of deprecated messages.

  • Use ASCII characters instead of unicode for prompt rendering in messages.

5.0.0 (2025-05-13)ΒΆ

Note

5.0.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Upgrade to Click 8.2.0.

  • Add support for custom deprecated messages on commands and parameters.

  • Remove ExtraOption.get_help_default() and rely on new Option.get_help_extra().

  • Remove dependency on pallets-sphinx-themes.

  • Drop supports for Python 3.10.

  • Add windows-11-arm to the test matrix.

  • Remove tests on ubuntu-22.04-arm, ubuntu-22.04 and windows-2022 to keep matrix small.

4.15.0 (2025-03-05)ΒΆ

Note

4.15.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Regroup all envronment variables-related code.

  • Rename extend_envvars() to merge_envvar_ids() and allow it to merge arbitrary-nested structures. Normalize names to uppercase on Windows.

  • Rename normalize_envvar() to clean_envvar_id().

  • Rename all_envvars() to param_envvar_ids().

  • Rename auto_envvar() to param_auto_envvar_id().

  • Remove unused normalize parameter on all_envvars().

  • Add missing line returns in render_cli_run().

  • Prefix all types with capital-T.

4.14.2 (2025-02-23)ΒΆ

Note

4.14.2 is available on 🐍 PyPI and πŸ™ GitHub.

  • Extract rendering part of the print_cli_run() helper to render_cli_run().

  • Remove unused click_extra.testing.run_cmd.

  • Relax requirement on extra-platforms.

  • Add tests on windows-2025. Remove tests on windows-2019.

4.14.1 (2025-02-02)ΒΆ

Note

4.14.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix upload of Python package to GitHub release on tagging.

4.14.0 (2025-02-02)ΒΆ

Note

4.14.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add a new --verbose option on @extra_command and @extra_group to increase the verbosity level for each additional repetition.

  • Add new @verbose_option pre-configured decorator.

  • Reassign the short -v option from --verbosity to --verbose.

  • Improve logging documentation.

  • Align ExtraStreamHandler behavior to logging.StreamHandler.

  • Move stream_handler_class and formatter_class arguments from new_extra_logger to extraBasicConfig.

  • Add new file_handler_class argument to extraBasicConfig.

  • Fix upload of Python package to GitHub release on tagging.

  • Remove dependency on pytest-cases.

4.13.2 (2025-01-28)ΒΆ

Note

4.13.2 is available on 🐍 PyPI and πŸ™ GitHub.

  • Re-release to fix GitHub publishing.

  • Reactivates some color tests on Windows.

4.13.1 (2025-01-28)ΒΆ

Note

4.13.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Re-release to fix GitHub publishing.

4.13.0 (2025-01-28)ΒΆ

Note

4.13.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Revamps logging helpers and aligns them with Python’s logging module.

  • Remove extra_basic_config.

  • Adds new extraBasicConfig, and aligns it with Python’s basicConfig.

  • Replace ExtraLogFormatter with ExtraFormatter.

  • Replace ExtraLogHandler with ExtraStreamHandler.

  • Add new new_extra_logger helper.

  • Rewrite the logging documentation with all use-cases and custom configuration examples. Closes #989.

  • Removes old platforms page from documentation.

4.12.0 (2025-01-20)ΒΆ

Note

4.12.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Remove Click Extra’s own implementation of HelpOption class now that fixes have reached Click’s upstream.

  • Redefine @help_option decorator to default to --help/-h options.

  • Add more logging examples in documentation.

  • Add tests on ubuntu-24.04-arm and ubuntu-22.04-arm.

  • Use uv to install specific versions of Python.

4.11.7 (2024-12-01)ΒΆ

Note

4.11.7 is available on 🐍 PyPI and πŸ™ GitHub.

  • Remove support for comments in JSON configuration files. Remove dependency on unmaintained commentjson. Closes click-extra#1152.

4.11.6 (2024-11-29)ΒΆ

Note

4.11.6 is available on 🐍 PyPI and πŸ™ GitHub.

  • Make --timer option eager so it can jumps the queue of processing order.

  • Fix configuration of help option generated by the help_option_names context setting. Closes mail-deduplicate#762.

  • Fix eagerness of help option generated by help_option_names. Refs click#2811.

  • Display generated help option in --show-params results.

  • Force UTF-8 encoding everywhere.

4.11.5 (2024-11-18)ΒΆ

Note

4.11.5 is available on 🐍 PyPI and πŸ™ GitHub.

  • Allow replace_content() utility method to replace any content found after the start tag.

4.11.4 (2024-11-14)ΒΆ

Note

4.11.4 is available on 🐍 PyPI and πŸ™ GitHub.

  • Ignore hidden options when coloring help screen.

4.11.3 (2024-11-12)ΒΆ

Note

4.11.3 is available on 🐍 PyPI and πŸ™ GitHub.

  • Aligns dependencies.

4.11.2 (2024-11-11)ΒΆ

Note

4.11.2 is available on 🐍 PyPI and πŸ™ GitHub.

  • Aligns dependencies.

4.11.1 (2024-10-27)ΒΆ

Note

4.11.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix tests against development version of Click.

4.11.0 (2024-10-08)ΒΆ

Note

4.11.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add support for Python 3.13.

  • Drop supports for Python 3.9.

  • Run tests on Python 3.14-dev.

  • Add tests on ubuntu-24.04. Remove tests on ubuntu-20.04.

  • Upgrade tests from macos-14 to macos-15.

4.10.0 (2024-09-05)ΒΆ

Note

4.10.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Move all platform detection utilities to its own standalone Extra Platforms project.

  • Add dependency on extra-platforms.

4.9.0 (2024-07-25)ΒΆ

Note

4.9.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Switch from Poetry to uv.

  • Drop support for Python 3.8.

  • Mark Python 3.13-dev tests as stable.

  • Remove dependency on regex.

4.8.3 (2024-05-25)ΒΆ

Note

4.8.3 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix string interpolation in log message.

4.8.2 (2024-05-25)ΒΆ

Note

4.8.2 is available on 🐍 PyPI and πŸ™ GitHub.

  • Do not raise error if package version cannot be fetched.

4.8.1 (2024-05-23)ΒΆ

Note

4.8.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Do not fail on docs_update import if pygments is not installed.

4.8.0 (2024-05-23)ΒΆ

Note

4.8.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Slim down package by moving unit tests out of the main package.

  • Allow reuse of Pytest fixures and marks by other packages.

  • Move dependencies extending pygments, sphinx and pytest into optional extra dependencies. Closes #836.

  • Split dev dependency groups into optional test, typing and docs groups.

  • Remove direct dependency on mypy.

  • Allow running tests with Python 3.8 and 3.9 on macos-14 runners.

4.7.5 (2024-04-05)ΒΆ

Note

4.7.5 is available on 🐍 PyPI and πŸ™ GitHub.

  • Remove bypass of cloup.Color re-import.

4.7.4 (2024-02-23)ΒΆ

Note

4.7.4 is available on 🐍 PyPI and πŸ™ GitHub.

  • Allow standalone --version option to output its debug messages.

  • Force closing of context before exiting CLIs to provoque callback calls and prevent state leaks.

  • Run tests on macos-14. Remove tests on macos-12.

4.7.3 (2024-01-07)ΒΆ

Note

4.7.3 is available on 🐍 PyPI and πŸ™ GitHub.

  • Run tests on Python 3.13-dev branch.

4.7.2 (2023-11-08)ΒΆ

Note

4.7.2 is available on 🐍 PyPI and πŸ™ GitHub.

  • Run tests on released Python 3.12 version.

4.7.1 (2023-09-29)ΒΆ

Note

4.7.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Distinguish between parameter type and Python type in --show-params output.

  • Recognize custom parameter type as string-based. Closes #721.

  • Rely on bump-my-version to update citation file metadata.

4.7.0 (2023-09-04)ΒΆ

Note

4.7.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Switch to format string style for version template.

  • Add new variables for version string template: {module}, {module_name}, {module_file}, {module_version}, {package_version} and {exec_name}.

  • Remove support for Click-specific %(prog) and %(package) variables in version string.

  • Print all versions string variables in debug mode.

4.6.5 (2023-09-01)ΒΆ

Note

4.6.5 is available on 🐍 PyPI and πŸ™ GitHub.

  • Highlight required label and value range in option description. Closes #748.

4.6.4 (2023-08-23)ΒΆ

Note

4.6.4 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix collection of subcommand parameters in --show-params output. Closes #725.

  • Set %(package_name) in --version to file name for CLI that are standalone scripts and not packaged. Fix #729.

  • Allow standalone scripts to define a local __version__ variable to set the %(version) element in --version output.

  • Allow building of documentation with Sphinx 7.

  • Run tests on macos-13. Remove tests on macos-11.

  • Ignore unstable tests on upcoming Click 8.2.x / main branch.

4.6.3 (2023-07-16)ΒΆ

Note

4.6.3 is available on 🐍 PyPI and πŸ™ GitHub.

  • Forces ExtraContext to properly close itself before exiting the program, to trigger all callbacks.

4.6.2 (2023-07-15)ΒΆ

Note

4.6.2 is available on 🐍 PyPI and πŸ™ GitHub.

  • Remove workaround for Cloup handling of command_class default on custom groups.

  • Force @extra_group to produce sub-groups of the same class.

4.6.1 (2023-07-13)ΒΆ

Note

4.6.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Inspect in --version the whole execution stack to find the package in which the user’s CLI is implemented.

4.6.0 (2023-07-12)ΒΆ

Note

4.6.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Keep the promise of drop-in replacement for @version_option which is now a proxy to Click’s original.

  • Rename the colored, enhanced --version option to @extra_version_option for its decorator, and ExtraVersionOption for its class.

  • Activate colors on @extra_command and @extra_group by default, even if stripped of all their default parameters. Closes #534 and #543.

  • Expose location and content of user’s configuration file in the Context’s meta property. Closes #673.

  • Render specs of hidden parameters in --show-params output. Fixes #689.

  • Swap Exposed and Allowed in conf? columns in --show-params output.

  • Add a hidden column to --show-params output. Refs #689.

4.5.0 (2023-07-06)ΒΆ

Note

4.5.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Expose verbosity level name, table format ID and CLI start timestamp in the Context’s meta property.

  • Refactor VersionOption. Introduce internal caching.

  • Expose version string elements in the Context’s meta property. Closes #325.

  • Remove print_env_info option from VersionOption class and version_option decorators.

  • Add new %(env_info) element. Default value is the same as what the removed print_env_info produced (i.e. a JSON dump of the environment).

  • Allow %(env_info) value to be set by user on --version.

  • Rename in version string formatting the %(prog) element to %(prog_name), and %(package) to %(package_name).

  • Detect Click-specific %(prog) and %(package) and raise a deprecated warning.

  • Do not print environment info in --version by default. Change default message from %(prog)s, version %(version)s\n%(env_info) to %(prog_name)s, version %(version)s.

  • Automaticcaly augment version string with environment info in DEBUG log level.

  • Expose click_extra.search_params utility.

4.4.0 (2023-06-16)ΒΆ

Note

4.4.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add a reduce() utility to reduce a collection of Group and Platform to a minimal set.

  • Remove @destructive and @non_destructive pytest markers.

  • Rename the exclude_params argument of ParamStructure and ConfigOption to excluded_params.

  • Fix over-styling of usage heading in help screen.

  • Move bump-my-version configuration to pyproject.toml.

  • Remove bump2version from dev dependencies, and let the external workflows install it.

  • Remove workaround for pallets-sphinx-themes’s outdated reference to old click’s Python 2 compatibility hack.

4.3.0 (2023-06-02)ΒΆ

Note

4.3.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Colorize envvars and default values in --show-params option.

  • Keep <stdout> and <stderr> streams independent in ExtraCliRunner.

  • Always collect <stderr> output and never raise an exception.

  • Add a new <output> stream to simulate what the user sees in its terminal.

  • Only mix <stdout> and <stderr> in <output> when mix_stderr=True.

  • Print detailed CLI execution trace in logs.

  • Document inline tests in Sphinx CLI execution blocks.

  • Improve Pygments ANSI formatter and lexers documentation.

  • Document usage of pygmentize command line.

  • Regroup all parameter-related code.

  • Regroup all testing and CLI execution utilities.

  • Activate zoom on big Mermaid graphs.

4.2.0 (2023-05-24)ΒΆ

Note

4.2.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add support for dedicated styling of environment variables, defaults, command aliases, aliases punctuation, subcommands and deprecated tag in help screen.

  • Update default colors of help screen to improve readability.

  • Change default style of critical log messages’ prefix to bold red.

  • Document the full matrix of colors and styles.

  • Render bright variants of ANSI colors in documentation.

  • Dynamically patch the style provided to AnsiHtmlFormatter to augment it with ANSI colors.

  • Remove main dependency on furo, make it a development dependency.

  • Remove the custom ansi-click-extra-furo-style Pygments style for Furo and its AnsiClickExtraFuroStyle class.

4.1.0 (2023-05-12)ΒΆ

Note

4.1.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add new global show_envvar option to display all environment variables in help screens.

  • Global show_choices setting to show or hide choices when prompting a user for input.

  • Populate the Allowed in conf? column in --show-params output if there is a --config option in the command.

  • Print all modified loggers and their levels in DEBUG mode.

  • Directly download Pygments source code from GitHub to check for candidates for ANSI-coloring in unittests.

  • Test continuously against Click and Cloup development version. Closes #525.

  • Move click_extra.commands.TimerOption to click_extra.timer.TimerOption.

4.0.0 (2023-05-08)ΒΆ

Note

4.0.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Drop support for Python 3.7.

  • Add a simple --telemetry/--no-telemetry option flag which respects the DO_NOT_TRACK environment variable.

  • Add new populate_auto_envvars parameter to @extra_command/@extra_group decorators to allow auto-generated environment variables to be displayed in help screens.

  • Display all environment variables in --show-params output, including those auto-generated by the way of the auto_envvar_prefix context parameter.

  • Allow user to override hard-coded context defaults on @extra_command/@extra_group.

  • Change default log level from INFO to WARNING to aligns with Python’s global root logger.

  • Force resetting of log level on --verbosity’s context closing to the hard-coded default.

  • Use a dedicated click_extra logger for all internal messages, instead of sending them to the user-defined one.

  • Aligns click_extra logger level to --verbosity option level.

  • Set default logger of --verbosity to Python’s global root logger, instead a local wrapped logger. Closes #318.

  • Allow user to provide a string as the default logger to --verbosity that will be used to fetch the global logger singleton of that name. Closes #318.

  • Only colorize the %(levelname)s field during log record formatting, not the : message separator.

  • Prefix INFO-level log message with info: prefix by default.

  • Raise an error if multiple --version options are defined in the same command. Closes #317.

  • Remove dependency on click-log.

  • Remove supports for Pallets-Sphinx-Themes < 2.1.0.

  • Force closing of the context before stopping the execution flow, to make sure all callbacks are called.

  • Fix rendering of GitHub-Flavored Markdown tables in canonical format.

3.10.0 (2023-04-04)ΒΆ

Note

3.10.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Colorize help screens of subcommands spawned out of an @extra_group. Closes #479.

  • Remove deprecated click_extra.platform.

3.9.0 (2023-04-01)ΒΆ

Note

3.9.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Allow @color_option, @command, @config_option, @extra_command, @extra_group, @group, @help_option, @show_params_option, @table_format_option, @timer_option, @verbosity_option and @version_option decorators to be used without parenthesis.

  • Fix wrapping of Cloup decorators by @extra_group/@extra_command decorators. Closes #489.

  • Add main dependency on furo which is referenced in ANSI-aware Pygment styles.

  • Move all documentation assets to assets subfolder.

3.8.3 (2023-02-25)ΒΆ

Note

3.8.3 is available on 🐍 PyPI and πŸ™ GitHub.

  • Let --version option output system details when run on python >= 3.10.

3.8.2 (2023-02-20)ΒΆ

Note

3.8.2 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix overlapping detection of linux and wsl2 platforms.

  • Renders platform groups in documentation in Mermaid format instead of Graphviz. Add new dependency on sphinxcontrib-mermaid, removed dependency on graphviz.

  • Produce dependency graph in Mermaid instead of Graphviz.

3.8.1 (2023-02-15)ΒΆ

Note

3.8.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Code, comments and documentation style change to conform to new QA workflows based on ruff.

3.8.0 (2023-01-25)ΒΆ

Note

3.8.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Rename click_extra.platform to click_extra.platforms.

  • Refactor platforms and their groups with dataclasses instead of string IDs.

  • Add new LINUX_LAYERS, ALL_WINDOWS, BSD_WITHOUT_MACOS, EXTRA_GROUPS and ALL_GROUPS groups.

  • Add new dependency on graphviz.

  • Activate Graphviz extension in Sphinx.

  • Let Sphinx produce the dependency graph from Graphviz file.

  • Produce platform graph dynamically.

  • Rename docs.py to docs_update.py and allow this module to be called directly.

3.7.0 (2023-01-03)ΒΆ

Note

3.7.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add support for new ANSI-capable lexers: ansi-gap-console and ansi-gap-repl.

  • Auto-update table of supported lexers in documentation.

  • Add test to search in Pygments’ test data for REPL/terminal-like lexers, as candidates for ANSI-coloring.

  • Depends on importlib_metadata for Python < 3.8.

3.6.0 (2022-12-28)ΒΆ

Note

3.6.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add new constants to group platforms by family.

  • Add heuristics to recognize new platforms: IBM AIX, Cygwin, FreeBSD, GNU/Hurd, NetBSD, OpenBSD, Oracle Solaris, SunOS, Windows Subsystem for Linux v1 and v2.

  • Document version option usage.

  • Split version code to its own file and tests.

  • Run tests on Python 3.12-dev.

3.5.0 (2022-12-09)ΒΆ

Note

3.5.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Print fully qualified class of options in --show-params output.

  • Add new columns in --show-params table to show option specifications, configuration exclusion and exposed attribute.

  • Rename ignored_params argument to exclude_params on the ConfigOption class.

  • Blocking parameters from configuration files now requires the fully qualified ID. Which adds support for selectively blocking parameters at any subcommand level.

3.4.1 (2022-12-08)ΒΆ

Note

3.4.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix highlighting of +-prefixed options in help screens. Closes #316.

  • Fix highlighting of hard-coded deprecated labels in option help.

  • Document parameter introspection. Closes #319.

3.4.0 (2022-12-01)ΒΆ

Note

3.4.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Streamline setup of Sphinx extensions.

  • Document click:example and click:run Sphinx extensions.

3.3.4 (2022-11-14)ΒΆ

Note

3.3.4 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix some types.

3.3.3 (2022-11-14)ΒΆ

Note

3.3.3 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix release workflow.

3.3.2 (2022-11-14)ΒΆ

Note

3.3.2 is available on πŸ™ GitHub.

Warning

3.3.2 is not available on 🐍 PyPI.

  • Remove use of deprecated ::set-output directives and replace them by environment files.

3.3.1 (2022-11-11)ΒΆ

Note

3.3.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Keep a copy of the table format ID in the context when set.

3.3.0 (2022-11-11)ΒΆ

Note

3.3.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Use tabulate dependency instead of cli-helpers for all the table rendering utilities.

  • Remove dependency on cli-helpers.

  • Re-implement locally the vertical table rendering format from cli-helpers.

  • Add new table rendering formats: asciidoc, fancy_outline, heavy_grid, heavy_outline, latex_longtable, latex_raw, mixed_grid, mixed_outline, presto, pretty, unsafehtml and youtrack.

  • Remove minimal table rendering formats, which was an alias of plain.

  • Add new csv-excel, csv-excel-tab and csv-unix formats based on Python defaults dialects.

  • Remove csv-tab rendering format.

  • Make csv format an alias of csv-excel.

  • Deactivate number alignment and extra-spacing in table rendering by default.

  • Remove tests on Pypy. Nobody asked for it and I need to speed up tests.

3.2.5 (2022-09-30)ΒΆ

Note

3.2.5 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix argument’s property getter in --show-params.

  • Remove GitHub edit link workaround in documentation.

3.2.4 (2022-09-27)ΒΆ

Note

3.2.4 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add citation file.

  • Fix type casting.

3.2.3 (2022-09-27)ΒΆ

Note

3.2.3 is available on 🐍 PyPI and πŸ™ GitHub.

  • Increase type coverage.

3.2.2 (2022-09-26)ΒΆ

Note

3.2.2 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix bad typing import.

3.2.1 (2022-09-26)ΒΆ

Note

3.2.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Move some command utility from test machinery to run submodule.

3.2.0 (2022-09-25)ΒΆ

Note

3.2.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • New --show-params option to debug parameters defaults, values, environment variables and provenance.

  • Rename ignored_options to ignored_params on ConfigOption.

  • Highlight command’s metavars, default values and deprecated flag in help.

  • Finer highlighting of options, subcommands and their aliases in help screens.

  • Fix highlight of dynamic metavars and secondary option in help screen.

  • New custom ExtraContext which allows populating meta at instantiation.

  • Use the Formats enum to encode for default configuration file extensions.

  • Re-introduce *.yml as a possible extension for YAML files.

3.1.0 (2022-09-20)ΒΆ

Note

3.1.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add support for pattern matching to search for configuration file.

  • Add a new formats option to specify which dialects the configuration file is written in, regardless of its name or file extension. Closes #197.

  • Set default configuration folder according each OS preferred location. Closes #211.

  • Add roaming and force_posix option to influence default application directory of configuration file.

  • Add a ignored_options parameter to the configuration file instead of hard-coding them.

  • Add dependency on wcmatch.

  • Remove tests on deprecated ubuntu-18.04.

  • Document preset options overriding. Closes #232.

  • Document configuration option pattern matching and default folder. Closes #197 and #211.

3.0.1 (2022-08-07)ΒΆ

Note

3.0.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix wrong dependency bump on pytest-cov produced by major release.

3.0.0 (2022-08-07)ΒΆ

Note

3.0.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Make default extra features optional, so click_extra can act as a drop-in replacement for click and cloup (closes #173):

    • Rename click_extra.group to click_extra.extra_group.

    • Rename click_extra.command to click_extra.extra_command.

    • Alias click_extra.group to cloup.group.

    • Alias click_extra.command to cloup.group.

  • Use declarative params= argument to set defaults options on extra_command and extra_group.

  • Move the implementation of options to classes.

  • Hard-copy version_option code from click to allow for more flexibility. Addresses #176.

  • All custom options inherits from ExtraOption class.

  • New extra_option_at_end to extra_command to force position of all extra options (on by default).

  • Replace theme styles inherited from click-log by Python standard logging module. Adds info and removes exception styles.

  • Add a tutorial in documentation.

  • Add support for click:example and click:run directives in documentation.

  • Add ANSI session and console lexers for Pygments.

  • Add a Pygments filter to transform tokens into ANSI tokens.

  • Add custom Pygment style to render ANSI tokens in furo theme.

  • Add dependency on pygments, pygments-ansi-color and Pallets-Sphinx-Themes.

  • Allow translation of short help in extra options.

  • Add minimal type hints.

  • Pre-compute test matrix to allow for a subset of jobs to fail if flagged as unstable.

  • Run tests on ubuntu-22.04 and macos-12.

  • Remove tests on deprecated macos-10.15.

2.1.3 (2022-07-08)ΒΆ

Note

2.1.3 is available on 🐍 PyPI and πŸ™ GitHub.

  • Do not render None cells in tables with <null> string.

  • Disable workflow grouping and concurrency management.

2.1.2 (2022-06-27)ΒΆ

Note

2.1.2 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix auto-mapping and recognition of all missing Click option types in config module. Closes #170.

  • Fix CI workflow grouping.

2.1.1 (2022-05-22)ΒΆ

Note

2.1.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix compatibility with cloup >= 0.14.0.

  • Group workflow jobs so new commits cancels in-progress execution triggered by previous commits.

  • Run tests on early Python 3.11 releases.

2.1.0 (2022-04-22)ΒΆ

Note

2.1.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add a highlight utility to style substrings.

  • Add regex dependency.

2.0.2 (2022-04-14)ΒΆ

Note

2.0.2 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix and unittest derivation of configuration template and types from CLI options.

  • Fix dependency requirements induced by overzealous automatic post-release version bump workflow.

  • Replace sphinx_tabs by sphinx-design.

  • Add edit link to documentation pages.

2.0.1 (2022-04-13)ΒΆ

Note

2.0.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix mapping of file arguments in configuration files.

  • Fix Sphinx documentation update and publishing.

  • Run tests on pypy-3.7.

2.0.0 (2022-04-11)ΒΆ

Note

2.0.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add support for XML configuration file. Closes #122.

  • Add strict mode to fail on unrecognized configuration options.

  • Support the NO_COLOR environment variable convention from no-color.org.

  • Recognize a subset of (FORCE_)(CLI)(NO_)COLOR(S)(_FORCE) variations as color-sensitive environment variables.

  • Print version and environment details in logs at the DEBUG level.

  • Add Sphinx-based documentation.

  • Add a logo.

  • Outsource documentation publishing to external workflow.

1.9.0 (2022-04-08)ΒΆ

Note

1.9.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add supports for .ini configuration files.

  • Add supports for commented JSON configuration files.

  • Fix identification of TOML and JSON configuration files.

  • Fix leak of local environment variable update on extend_env() usage.

  • Ignore help boolean in configuration files.

  • Add new dependency on mergedeep.

1.8.0 (2022-04-03)ΒΆ

Note

1.8.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Split the print_cli_output method to expose the simpler format_cli utility.

1.7.0 (2022-03-31)ΒΆ

Note

1.7.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Refactor global logging management.

  • Remove click_extra.run.run and rebase all run utilities around subprocess.run.

  • Use the tomllib from the standard library starting with Python 3.11.

1.6.4 (2022-03-04)ΒΆ

Note

1.6.4 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix extension of default environment variables.

1.6.3 (2022-03-04)ΒΆ

Note

1.6.3 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add support for environment variables to run utilities.

1.6.2 (2022-03-03)ΒΆ

Note

1.6.2 is available on 🐍 PyPI and πŸ™ GitHub.

  • Temporarily skip displaying environment details in --version option results for python >= 3.10.

  • Reactivate all tests on Python 3.10.

1.6.1 (2022-03-02)ΒΆ

Note

1.6.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Expose some cloup versions of click utilities at the root of click_extra.

1.6.0 (2022-03-02)ΒΆ

Note

1.6.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Allow click_extra to be imported as a drop-in replacement for click.

  • Share the same set of default options between click_extra.command and click_extra.group.

  • Document default help screen comparison between simple click CLI and enhanced click-extra CLI.

1.5.0 (2022-02-21)ΒΆ

Note

1.5.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add support for JSON configuration file.

  • Search all supported formats in default location if configuration file not provided.

  • Print configuration file default location in help screens.

1.4.1 (2022-02-13)ΒΆ

Note

1.4.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add new external workflow to modernize Python code.

  • Use external workflow suite to manage changelog and build & publish packages on PyPI on release.

  • Use external workflow to label sponsored issues and PRs.

  • Replace local workflow by external one to label issues and PRs.

  • Reuse externnal workflow to produce dependency graph.

  • Remove dev dependencies on check-wheel-contents, graphviz, pipdeptree and twine.

1.4.0 (2022-01-08)ΒΆ

Note

1.4.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Allow downloading of a remote config URL.

  • Add new dependencies on requests and pytest-httpserver.

  • Fix inference of config file top-level section name.

  • Document usage of click_extra.config.config_option.

  • Use external workflows for GitHub actions.

  • Automate version and changelog management.

1.3.0 (2021-11-28)ΒΆ

Note

1.3.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add support for YAML configuration file. Closes #13.

  • Auto-detect configuration file on loading.

  • Add pyyaml dependency.

1.2.2 (2021-11-04)ΒΆ

Note

1.2.2 is available on 🐍 PyPI and πŸ™ GitHub.

  • Evaluate format option dynamically at use to let third-party register new rendering formats.

1.2.1 (2021-11-04)ΒΆ

Note

1.2.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix creation of post-release version bump PR on tagging.

1.2.0 (2021-11-03)ΒΆ

Note

1.2.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Extend cli-helper.TabularOutputFormatter with new formats: simple_grid, rounded_grid, double_grid, outline, simple_outline, rounded_outline and double_outline. Address https://github.com/astanin/python-tabulate/issues/151.

  • Add a new --table-format/-t option to select table format rendering mode.

  • Add new dependency on cli-helper and tabulate.

  • Automate post-release version bump.

1.1.1 (2021-11-01)ΒΆ

Note

1.1.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Fix printing of additional non-grouped default options in help screen.

1.1.0 (2021-10-28)ΒΆ

Note

1.1.0 is available on 🐍 PyPI and πŸ™ GitHub.

  • Add a --config/-C option to load CLI configuration from a TOML file.

1.0.1 (2021-10-27)ΒΆ

Note

1.0.1 is available on 🐍 PyPI and πŸ™ GitHub.

  • Re-release previous version with fixed dependency.

1.0.0 (2021-10-27)ΒΆ

Note

1.0.0 is available on πŸ™ GitHub.

Warning

1.0.0 is not available on 🐍 PyPI.

  • Add colorization of options, choices and metavars in help screens.

  • Add --color/--no-color option flag (aliased to --ansi/--no-ansi).

  • Add colored --version option.

  • Add colored --verbosity option and logs.

  • Add dependency on click-log.

  • --time/--no-time flag to measure duration of command execution.

  • Add platform recognition utilities.

  • Add new conditional markers for pytest: @skip_{linux,macos,windows}, @unless_{linux,macos,windows}, @destructive and @non_destructive.

0.0.1 (2021-10-18)ΒΆ

Note

0.0.1 is the first version available on 🐍 PyPI and πŸ™ GitHub.

  • Initial public release.