Repository navigation
v10.0.0
- 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 to4.0.0, tabulate to0.10and extra-platforms to14.0.0, dropping the shims older releases needed. - Breaking: Regroup the modules into the
captureandmarkdownpackages and split the largest ones. Every name the package root exported in9.xstill imports from it, so prefer it to module paths. - Breaking: Move
screenshot,screenshot_svg,screenshot_html,screenshot_presets,snippetandrecordingintoclick_extra.capture, asscreenshot,svg,html,presets,snippetandrecording. - Breaking: Move
Chrome, its defaults and the paint constants likeNO_PAINTtocapture.presets, andparse_hold()andparse_pause()tocapture.svg. The captureformat_from_path()becomesCaptureFormat.from_path(). - Breaking: Move
blockstoclick_extra.markdown.blocks, mergemyst_converterandrst_to_mystintoclick_extra.markdown.myst, and movetheme_docstoclick_extra.sphinx.theme_docs. - Breaking:
FenceSpangains anendfield, so it no longer builds from two arguments or unpacks into two values. - Breaking: Move the helpers of
click_extra.parameters, likeParamStructureandsearch_params(), toparam_tools, andShowParamsOptionwithrender_params_table()toshow_params. - Breaking: Move
ContextandPOSIXLY_CORRECT_ENVVARfromclick_extra.contexttoclick_extra.commands, and the table options,ColumnsTypeandcolumn_sort_key()fromclick_extra.tabletoclick_extra.table_options. - Breaking: Move
JobsOption,JobCount,resolve_jobs(),run_jobs()andrun_lanes()toclick_extra.jobs, and the version resolvers likeenv_summary()toclick_extra.version_facts. - Breaking: Move
OperationTrailandtrail_line()toclick_extra.trailandprogressbar()toclick_extra.progress, out ofclick_extra.spinner. - Breaking: Split
config.optionintoconfig.discoveryandconfig.export, andsphinx.clickintosphinx.click_runnerandsphinx.click_reference. - Breaking: Move
open_ansi()fromclick_extra.stylingto the newclick_extra.ansimodule, along with the escape and palette helpersstylingkept private. - Breaking: Move
read_project_scripts(),entry_point_package(),locate_package_root(),discover_package_init_files()anddetect_source_package()toclick_extra.project.detect_source_package()now takes the project directory. - Breaking: Remove the module aliases deprecated in
9.x, liketheme.nocolor_themeandtable.select_columns. Import each name from the module its warning named. - Breaking: Remove the deprecated
allow_query,merge_streams,uniqueandenabledarguments,color="forced", and the window arguments ofrender_html(). - Breaking: Remove the
is_root,default_optsandinherited_optsarguments ofextract_carapace_command(), which had no effect. - Breaking: Remove the public compiled patterns
blocks.OPTION_LINE_RE, the*_REconstants ofmyst_converter,myst_converter.FENCE_OPEN_REandcommand_doc.OVERSTRIKE_RE, whichstrip_overstrike()replaces. - Breaking: Remove
MAN_INSTALL_DIR,CARAPACE_SPECS_DIR,PARSER_SUPPORTandSQLITE_SUPPORT: install directories resolve when called, andConfigFormat.enabledprobes a parser on first use. - Breaking: Remove
pytest.skip_naked,command_doc.CLICK_EXTRA_URL,credit_segments(),run_paint(),preset_palette()and theCAPTURE_BACKGROUND-style color constants, and makeformat_param_row()private. - Breaking:
click_extra.sphinxno longer re-exports theblockshelpers and the capture configuration names, andclick_extra.configno longer re-exportsClickExtraConfig,TestSuiteConfigandPrebakeConfig. - Breaking: Remove
click_extra.sphinx.alertsandMYST_NATIVE_ALERTS_VERSION. Thesphinxextra now requiresmyst-parser5.1: listalertinmyst_enable_extensionsto render GitHub alerts. - Breaking: Remove the
jsoncextra and thejson-with-commentsdependency behind it:JSONCis now built in, its comments and trailing commas stripped in-house beforejsonreads the file. - Breaking: Remove the
xmlextra and thexmltodictdependency behind it:XMLis now built in, read with the standard library'sexpatparser and written in-house, with the same@attribute,#textand repeated-element conventions. - Breaking: Remove
click_extra/themes.toml: built-in themes live intheme.pyand build on first lookup, soBUILTIN_THEMESandget_theme_registry()return mappings, notdictinstances. - Breaking: Merge
color.COLOR_WHENandspinner.LIVE_MODESintocolor.WHEN, and renameCaptureBackgroundtocolor.TerminalBackground, aStrEnumwhose members equal"dark"and"light". - Breaking: Replace
MAN_FORMATTERSandsphinx.manpages.HTML_RENDERERSwith onecommand_doc.MAN_TYPESETTERStable. - Breaking: The capture functions take one
chrome=Chrome(...)instead of its fields, andCHROME_FIELDSandfold_chrome_arguments()are gone. - Breaking:
render_html()takes a resolvedpalettelikerender_svg(), and no longer takeswatermark_url. - Breaking: Table headers and
--sort-bycolumn definitions no longer accept a(label, column_id)tuple. Pass aColumnSpecinstead. - Breaking:
ColumnsTypetakes its column IDs aschoices, likeMultiChoice, whoseget_metavar()now takes Click's(param, ctx)signature. - Breaking:
TimerOption.print_timer()takes the start time of the run it reports, andVersionOptionraisesTypeErrorinstead ofValueErrorfor an unknown key infieldsorstyles. - Breaking:
print_table()andprint_data()raiseoutput.MissingExtraError, aClickException, instead ofSystemExitwhen an optional dependency is missing. - Breaking:
convert-to-mystanddetect_source_package()refuse a console script naming several functions, aswrapdoes. - 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_themeandinvalid_theme_shapecodes, in snake case like the other validation codes. - Breaking:
ctx.meta["click_extra.conf_source"]and the locations ofclick_extra.conf_sourceshold a remote configuration's URL as astr, instead of aboltonsURLobject. - Breaking: Remove the
{env_info}version field, itsclick_extra.env_infocontext key and its JSON dump in--verbosity DEBUGlogs. Appendenv_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()toclick_extra.ansi, which removes every ANSI escape sequence from a string or bytes, andtemplate_segments()toclick_extra.version. - Add
get_cache_dir(), which locates the user cache directory of a CLI, and export it withxdg_dir()from the package root. - Export from the package root the helpers other projects import from submodules, like
env_summary(),default_facts(),KO_GLYPHandcell_width(). - Add
CSV_FORMATStoclick_extra.table: the table formats Python'scsvmodule renders. - Add
symbol,styleandcolorarguments totrail_glyph(), which now also draws the marker ofSpinner.ok()andSpinner.fail(). - Add
iter_subcommand_contexts()toclick_extra.param_tools, the walk every command-tree renderer shares. - Add
resolve_entry_point()toclick_extra.project, andwalk_fences(),rewrite_fences()andrewrite_file()toclick_extra.markdown.blocks. - Read and write each page once in
click-extra refresh-directives, which composes the now publicrewrite_screenshot_regions(),rewrite_matrix_blocks()andrewrite_mirrors(). - Add
machine_envvars_apply()toclick_extra.envvar, which tells an option callback whether a machine-wide variable likeCLICK_EXTRA_THEMEmay set its value. - Add
setdefault()toclick_extra.context, andis_dumb_terminal()toclick_extra.color. - Add
find_git_root(),GIT_TIMEOUTand thecheckandtimeoutarguments ofrun_git(), which now removes only the final newline of an output. - Add
short_helptoLazySubcommand, to list a lazy subcommand without importing it. - Add a
click_extra.config_docstring_headingSphinx warning for each Markdown heading in an option docstring thatclick:configrenders. - Accept any mapping in
env_copy(), not only adict. ValidationErrorsubclassesValueError, and a newinvalid_keycode joinsunknown_parameterandschema_error.- Add a
config_cascadeargument to@commandand@group, which turns on the cascade of the default--configoption without replacing it. - Draw the
Config filecolumn of--paramsby default when the--configoption cascades. - Add a
--wrap-markeroption to thescreenshotandsnippetcommands, which closes each row a fold cut short on↵or a chosen character. - Drop the
boltonsanddeepmergedependencies, replaced by in-house code and the standard library. - The
tomlextra installstomlrtin place oftomlkitto 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--jobscount, likerun_jobs()runs a single item.- List the injected
personalitiessubcommand after the author's own undersort_subcommands=False, likehelp. prebake versionprints the baked__version__the wayprebake alldoes.- The
CLICK_EXTRA_THEMEwarning listsautoamong the accepted palettes. - Let
<CLI>_ACCESSIBLEoutrank the machine-wideACCESSIBLEvariable, andACCESSIBLE=0turn off the accessible mode a configuration file turns on. - Ignore the blanks around the value of
ACCESSIBLEandDO_NOT_TRACK, soDO_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. --paramsno longer prompts for an option declaring aprompt, and keeps its rows in parameter path order whichever column--columnsputs first.- The
-v/-qdebug trace says "by 1 level", not "by 1 levels". - Add the
3.15release date toPYTHON_RELEASE_DATES, so thematrixdirective caps a floor-onlyrequires-pythoncorrectly. - 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 loadssubprocess,termios,tty,tomllib, the converters, the trail and progress-bar code or the optional configuration parsers. - Build the default options of
@commandand@grouponce instead of twice. - Run a CLI without a configuration file without importing
extra_platformsorwcmatch, and find the module behind--versionwithout scanning all loaded modules. - Start the
click-extraCLI faster, by loading itstest-suite,screenshot,snippetandprebakecommands on first use. - Draw an SVG still about twice as fast, and import
click_extra.pygmentsfour 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: testingwhen a subcommand or subgroup carries its own--versionoption outside a test runner. - Fix
--versionprinting Click Extra's version for a CLI started with no frame under it, like from anatexithook or a C host. - Fix
--versionprintingNonefor a CLI started from a thread or an executor, like withthreading.Thread(target=cli.main). - Fix
MulticallGrouppersonalities losing the version fields pinned withfieldsorversion_fields. - Fix registering a
personalitiessubcommand on aMulticallGroup, and a personality whose subcommand is a plain Click command. - Fix
--timeof 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
RuntimeErroronstderrinstead of quitting. - Raise a Ctrl+C that a free-threaded Python turns into
RuntimeError: release unlocked lockwithinrun_jobs()orrun_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 anauto-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
rootlogger 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 owncatch_exceptionssetting when a call leaves the argument out. - Fix
CLITestCaseacceptingexecution_traceas 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 theESC ( Boftput 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_coloroption of the ANSI lexers reading-O true_color=falseas true, and their subclasses doubling their name prefix. - Fix
--helpcrashing on a plaincloup.HelpThemein thethemeformatter 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 likeNO_COLOR. - Reject malformed hex colors like
#-1-1-1or##abcin styles and themes, instead of reading negative or shifted channels. - Fix
Style.to_dict()writing anIntEnumpalette index as its member name, andHelpTheme.with_()reporting unknown slots unsorted. - Fix
ctx.metaafter--version:len(), iteration, views,copy(),pop()andsetdefault()now see its lazy fields. - Fix
--paramsdrawing a cross for a customconfirmation_promptstring, and the grammar of its warning on a plain Click command. - Fix
print_table()padding markup formats by terminal emoji width, and theverticalformat misaligning styled, wide or missing labels. - Fix
EnumChoiceraisingAssertionErrororAttributeErroron bad input: it raisesTypeErrorandValueError. - Fix
--validate-configandconfig_strictrejecting the keys a dataclassconfig_schemareads: 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=Truerejecting an extension point, like the built-inthemestable. - Fix an
INIsection 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 emptyapp_name, which now reads the whole document. - Report a missing PyYAML for
--help-format carapaceasError:with exit code 1, not a traceback. - Fix the
EXAMPLESsection of generated man pages, which showed a backslash before each dash of an example command. - Fix
render_help()ignoring a passedprog_namewhen it names a Carapace spec. - Fix
wrap --paramsignoring the context settings of its target and of its subcommands, like theirauto_envvar_prefix. - Fix
help NAMEsuggestions leaving out lazy subcommands, andhelp --searchlisting hidden ones. - Fix
click:treemissing lazy subcommands and ignoring thelist_commands()order: it walks like--treeand skips hidden subcommands. - Fix a
click:runprompt reading past the end of its input, which raisedIndexErrorinstead of aborting like Click. - Fix
:screenshot:captures written again on every build when unchanged, and a pipe splitting a row of theclick:treesummary table. - Fix the MyST docstring converter separating directive options from their directive, and rewriting the content of code blocks.
- Fix
refresh-directivesdeleting 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, andreplace_region()rewriting markers quoted in a fence. - Fix the dependency
matrixmissing theuv.lockversion of a dependency spelled with capitals, underscores or dots. - Fix
refresh-directivesrewriting form feeds and failing on a tag name that is not UTF-8, and stop its tag listing after 5 seconds. - Fix the
screenshotcommand reporting an--emphasize-linespast the end of the capture as a traceback. - Fix
prebakemangling a value holding a quote or a backslash, and misplacing a placeholder that follows non-ASCII text on its line. - Draw the
autotruncation 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
mandocandgroffman-page renderers as UTF-8 on every platform. - Name
--syntax-style, which colors the code, in thesnippethelp example, instead of the help screen's--theme. - Document the
click_extra.sphinx.pythonmodule in the API reference.
Full changelog: v9.5.1...v10.0.0