v8.1.0

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

Full changelog: v8.0.1...v8.1.0

---

🛡️ VirusTotal scans

Binary	Detections	Analysis
click-extra-8.1.0-linux-arm64.bin	0 / 61	View scan
click-extra-8.1.0-linux-x64.bin	1 / 62	View scan
click-extra-8.1.0-macos-arm64.bin	1 / 60	View scan
click-extra-8.1.0-macos-x64.bin	1 / 60	View scan
click-extra-8.1.0-windows-arm64.exe	2 / 68	View scan
click-extra-8.1.0-windows-x64.exe	14 / 67	View scan