You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Fix Fish shell completion broken in 8.4.0 by {pr}3126. Newlines and
tabs in option help text are now escaped, keeping the original completion
format while still supporting multi-line help. {issue}3502
{issue}3043 {pr}3504 {pr}3508
Deprecated commands and options with empty or missing help text no longer
render a stray leading space before the (DEPRECATED) label. {pr}3509
A {class}Group with invoke_without_command=True marks its subcommand as
optional in the usage help, showing [COMMAND] instead of COMMAND.
{issue}3059 {pr}3507
echo_via_pager flushes after each write, so passing a generator streams
output to the pager incrementally instead of staying hidden until the pipe
buffer fills. {issue}3242 {issue}2542 {pr}3534
echo_via_pager and get_pager_file no longer close a borrowed stdout
stream when no external pager runs, completing the partial I/O operation on closed file fix from {pr}3482. {issue}3449
{pr}3533
:class:ParamType is now a generic abstract base class,
parameterized by its converted value type.
:meth:~ParamType.convert return types are narrowed on all
concrete types (str for :class:STRING, int for
:class:INT, etc.).
:meth:~ParamType.to_info_dict returns specific
:class:~typing.TypedDict subclasses instead of dict[str, Any].
:class:CompositeParamType and the number-range base are now
generic with abstract methods.
Refactor convert_type to extract type inference into a private _guess_type helper, and add :func:typing.overload signatures.
:pr:3372
:class:Parameter typing improvements. :pr:2805
:class:Parameter is now an abstract base class, making explicit
that it cannot be instantiated directly.
:attr:Parameter.name is now str instead of str | None.
When expose_value=False, the name is set to "" instead
of None.
The ctx parameter of :meth:Parameter.get_error_hint is now
typed as Context | None, matching the runtime behavior.
Split string values from default_map for parameters with nargs > 1
or :class:Tuple type, matching environment variable behavior.
:issue:2745 :pr:3364
Auto-detect type=UNPROCESSED for flag_value of non-basic types
(not str, int, float, or bool), so programmer-provided
Python objects like classes and enum members are passed through unchanged
instead of being stringified. Previously type=click.UNPROCESSED had
to be set explicitly. :issue:2012 :pr:3363
The error hint now uses :meth:Command.get_help_option_names to pick
non-shadowed help option names, so Try '... -h' no longer points to a
subcommand option that shadows -h. The longest surviving name is
shown (--help over -h) for readability. :issue:2790 :pr:3208
Fix readline functionality on non-Windows platforms. Prompt text is now
passed directly to readline instead of being printed separately, allowing
proper backspace, line editing, and line wrapping behavior. :issue:2968
:pr:2969
Use :func:os.startfile on Windows to open URLs in :func:open_url,
replacing the start built-in which cannot be invoked without shell=True. :issue:3164 :pr:3186
Fix Fish shell completion errors when option help text contains newlines.
:issue:3043 :pr:3126
Add :class:NoSuchCommand exception with suggestions for misspelled
commands. :issue:3107 :pr:3228
Use :class:ValueError message when conversion in :class:FuncParamType would
fail. :issue:3105 :pr:3211
Add click.get_pager_file for file-like access to an output
pager. :pr:1572 :pr:3405
:func:~click.formatting.wrap_text now measures line width in visible
characters, ignoring ANSI escape sequences. :pr:3420
Fix :meth:HelpFormatter.write_usage emitting only a blank line when
called without args. The usage prefix and program name are now
written even when no arguments follow, and the trailing separator
space is stripped so the line ends at the program name.
:issue:3360 :pr:3434
Show custom error messages from types when :func:prompt with hide_input=True fails validation, instead of always showing a
generic message. Built-in type messages mask the input value.
:issue:2809 :pr:3256
Add capture parameter to :class:CliRunner with two modes: sys
(default) and fd. fd redirects file descriptors 1 and 2
via :func:os.dup2 so output that bypasses sys.stdout (stale stream
references, C extensions, subprocesses, faulthandler) is captured
with proper isolation. :issue:854 :issue:2412 :issue:2468
:issue:2497 :issue:2761 :issue:2827 :issue:2865 :pr:3391
Revert the 8.3.3 change that exposed the original file descriptor
via fileno() on the redirected CliRunner streams in the default
capture mode. os.dup2(w, sys.stdout.fileno()) calls inside a CLI no
longer mutate the host runner's stdout, which broke Pytest's fd-level
capture teardown. C-level consumers that need a real fd should use capture="fd". :issue:3384 :pr:3391
Mark additional built-in strings with gettext() to extend translation
coverage. :pr:2902
Fix feature switch groups (several flag_value options sharing one
parameter name) silently dropping an explicit default when a sibling
option without an explicit default was declared first. Arbitration is now
source-aware: a more explicit :class:ParameterSource always wins, and
within ParameterSource.DEFAULT, an option that received an explicit default= keyword wins over a sibling whose default was auto-derived.
The 8.3.x first-wins fallback for remaining ties was reverted to the
pre-8.3.x last-wins fallback. :issue:3403 :pr:3404
Fix missing space between option help text and the (DEPRECATED)
label, and localize the option label so it matches the command label.
The label and the DeprecationWarning reason suffix are now produced
by shared helpers. :pr:3423
Document short option stacking (-abc is parsed as -a -b -c) and
clarify that multi-character short option names are not supported.
:issue:2779 :pr:3431
Fix handling of flag_value when is_flag=False to allow such options to be
used without an explicit value. :issue:3084 :pr:3152
Hide Sentinel.UNSET values as None when using lookup_default().
:issue:3136 :pr:3199 :pr:3202 :pr:3209 :pr:3212 :pr:3224
Prevent _NamedTextIOWrapper from closing streams owned by StreamMixer.
:issue:824 :issue:2991 :issue:2993 :issue:3110 :pr:3139 :pr:3140
Add comprehensive tests for CliRunner stream lifecycle, covering
logging interaction, multi-threaded safety, and sequential invocation
isolation. Add high-iteration stress tests behind a stress marker
with a dedicated CI job. :pr:3139
Fix callable flag_value being instantiated when used as a default via default=True. :issue:3121 :pr:3201 :pr:3213 :pr:3225
Don't discard pager arguments by correctly using subprocess.Popen. :issue:3039
:pr:3055
Replace Sentinel.UNSET default values by None as they're passed through
the Context.invoke() method. :issue:3066 :issue:3065 :pr:3068
Fix conversion of Sentinel.UNSET happening too early, which caused incorrect
behavior for multiple parameters using the same name. :issue:3071 :pr:3079
Hide Sentinel.UNSET values as None when looking up for other parameters
through the context inside parameter callbacks. :issue:3136 :pr:3137
Fix rendering when prompt and confirm parameter prompt_suffix is
empty. :issue:3019 :pr:3021
When Sentinel.UNSET is found during parsing, it will skip calls to type_cast_value. :issue:3069 :pr:3090
Fix reconciliation of default, flag_value and type parameters for
flag options, as well as parsing and normalization of environment variables.
:issue:2952 :pr:2956
Fix typing issue in BadParameter and MissingParameter exceptions for the
parameter param_hint that did not allow for a sequence of string where the
underlying function _join_param_hints allows for it. :issue:2777 :pr:2990
Use the value of Enum choices to render their default value in help
screen. Refs :issue:2911 :pr:3004
Fix completion for the Z shell (zsh) for completion items containing
colons. :issue:2703 :pr:2846
Don't include envvar in error hint when not configured. :issue:2971 :pr:2972
Fix a rare race in click.testing.StreamMixer's finalization that manifested
as a ValueError on close in a multi-threaded test session.
:issue:2993 :pr:2991
Configuration
📅 Schedule: (UTC)
Branch creation
At any time (no schedule defined)
Automerge
At any time (no schedule defined)
🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.
♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.
🔕 Ignore: Close this PR and you won't be reminded about this update again.
If you want to rebase/retry this PR, check this box
Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>
Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%
NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer TIP This summary will be updated as you push new changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR contains the following updates:
<8.3→<8.5Release Notes
pallets/click (click)
v8.4.2Compare Source
Unreleased
8.4.0by {pr}3126. Newlines andtabs in option help text are now escaped, keeping the original completion
format while still supporting multi-line help. {issue}
3502{issue}
3043{pr}3504{pr}3508render a stray leading space before the
(DEPRECATED)label. {pr}3509Groupwithinvoke_without_command=Truemarks its subcommand asoptional in the usage help, showing
[COMMAND]instead ofCOMMAND.{issue}
3059{pr}3507echo_via_pagerflushes after each write, so passing a generator streamsoutput to the pager incrementally instead of staying hidden until the pipe
buffer fills. {issue}
3242{issue}2542{pr}3534echo_via_pagerandget_pager_fileno longer close a borrowed stdoutstream when no external pager runs, completing the partial
I/O operation on closed filefix from {pr}3482. {issue}3449{pr}
3533v8.4.1Compare Source
Released 2026-05-21
get_parameter_source()is available during eager callbacks and typeconversion again. :issue:
3458:issue:34843277:pr:3466ChoiceEnumvalues produces a valid completionresult. :issue:
30153487echo_via_pager. :issue:3449v8.4.0Compare Source
Released 2026-05-17
:class:
ParamTypetyping improvements. :pr:3371ParamTypeis now a generic abstract base class,parameterized by its converted value type.
~ParamType.convertreturn types are narrowed on allconcrete types (
strfor :class:STRING,intfor:class:
INT, etc.).~ParamType.to_info_dictreturns specific:class:
~typing.TypedDictsubclasses instead ofdict[str, Any].CompositeParamTypeand the number-range base are nowgeneric with abstract methods.
Refactor
convert_typeto extract type inference into a private_guess_typehelper, and add :func:typing.overloadsignatures.:pr:
3372:class:
Parametertyping improvements. :pr:2805Parameteris now an abstract base class, making explicitthat it cannot be instantiated directly.
Parameter.nameis nowstrinstead ofstr | None.When
expose_value=False, the name is set to""insteadof
None.ctxparameter of :meth:Parameter.get_error_hintis nowtyped as
Context | None, matching the runtime behavior.Split string values from
default_mapfor parameters withnargs > 1or :class:
Tupletype, matching environment variable behavior.:issue:
2745:pr:3364Auto-detect
type=UNPROCESSEDforflag_valueof non-basic types(not
str,int,float, orbool), so programmer-providedPython objects like classes and enum members are passed through unchanged
instead of being stringified. Previously
type=click.UNPROCESSEDhadto be set explicitly. :issue:
2012:pr:3363The error hint now uses :meth:
Command.get_help_option_namesto picknon-shadowed help option names, so
Try '... -h'no longer points to asubcommand option that shadows
-h. The longest surviving name isshown (
--helpover-h) for readability. :issue:2790:pr:3208Fix readline functionality on non-Windows platforms. Prompt text is now
passed directly to readline instead of being printed separately, allowing
proper backspace, line editing, and line wrapping behavior. :issue:
2968:pr:
2969Use :func:
os.startfileon Windows to open URLs in :func:open_url,replacing the
startbuilt-in which cannot be invoked withoutshell=True. :issue:3164:pr:3186Fix Fish shell completion errors when option help text contains newlines.
:issue:
3043:pr:3126Add :class:
NoSuchCommandexception with suggestions for misspelledcommands. :issue:
3107:pr:3228Use :class:
ValueErrormessage when conversion in :class:FuncParamTypewouldfail. :issue:
3105:pr:3211Add
click.get_pager_filefor file-like access to an outputpager. :pr:
1572:pr:3405:func:
~click.formatting.wrap_textnow measures line width in visiblecharacters, ignoring ANSI escape sequences. :pr:
3420Fix :meth:
HelpFormatter.write_usageemitting only a blank line whencalled without
args. The usage prefix and program name are nowwritten even when no arguments follow, and the trailing separator
space is stripped so the line ends at the program name.
:issue:
3360:pr:3434Show custom error messages from types when :func:
promptwithhide_input=Truefails validation, instead of always showing ageneric message. Built-in type messages mask the input value.
:issue:
2809:pr:3256Add
captureparameter to :class:CliRunnerwith two modes:sys(default) and
fd.fdredirects file descriptors1and2via :func:
os.dup2so output that bypassessys.stdout(stale streamreferences, C extensions, subprocesses,
faulthandler) is capturedwith proper isolation. :issue:
854:issue:2412:issue:2468:issue:
2497:issue:2761:issue:2827:issue:2865:pr:3391Revert the
8.3.3change that exposed the original file descriptorvia
fileno()on the redirectedCliRunnerstreams in the defaultcapture mode.
os.dup2(w, sys.stdout.fileno())calls inside a CLI nolonger mutate the host runner's stdout, which broke Pytest's
fd-levelcapture teardown. C-level consumers that need a real
fdshould usecapture="fd". :issue:3384:pr:3391Mark additional built-in strings with
gettext()to extend translationcoverage. :pr:
2902Fix feature switch groups (several
flag_valueoptions sharing oneparameter name) silently dropping an explicit
defaultwhen a siblingoption without an explicit default was declared first. Arbitration is now
source-aware: a more explicit :class:
ParameterSourcealways wins, andwithin
ParameterSource.DEFAULT, an option that received an explicitdefault=keyword wins over a sibling whose default was auto-derived.The 8.3.x first-wins fallback for remaining ties was reverted to the
pre-8.3.x last-wins fallback. :issue:
3403:pr:3404Fix missing space between option help text and the
(DEPRECATED)label, and localize the option label so it matches the command label.
The label and the
DeprecationWarningreason suffix are now producedby shared helpers. :pr:
3423Document short option stacking (
-abcis parsed as-a -b -c) andclarify that multi-character short option names are not supported.
:issue:
2779:pr:3431v8.3.3Compare Source
v8.3.2Compare Source
Released 2026-04-02
flag_valuewhenis_flag=Falseto allow such options to beused without an explicit value. :issue:
3084:pr:3152Sentinel.UNSETvalues asNonewhen usinglookup_default().:issue:
3136:pr:3199:pr:3202:pr:3209:pr:3212:pr:3224_NamedTextIOWrapperfrom closing streams owned byStreamMixer.:issue:
824:issue:2991:issue:2993:issue:3110:pr:3139:pr:3140CliRunnerstream lifecycle, coveringlogging interaction, multi-threaded safety, and sequential invocation
isolation. Add high-iteration stress tests behind a
stressmarkerwith a dedicated CI job. :pr:
3139flag_valuebeing instantiated when used as a default viadefault=True. :issue:3121:pr:3201:pr:3213:pr:3225v8.3.1Compare Source
Released 2025-11-15
subprocess.Popen. :issue:3039:pr:
3055Sentinel.UNSETdefault values byNoneas they're passed throughthe
Context.invoke()method. :issue:3066:issue:3065:pr:3068Sentinel.UNSEThappening too early, which caused incorrectbehavior for multiple parameters using the same name. :issue:
3071:pr:3079Sentinel.UNSETvalues asNonewhen looking up for other parametersthrough the context inside parameter callbacks. :issue:
3136:pr:3137promptandconfirmparameterprompt_suffixisempty. :issue:
3019:pr:3021Sentinel.UNSETis found during parsing, it will skip calls totype_cast_value. :issue:3069:pr:3090v8.3.0Compare Source
Released 2025-09-17
Improved flag option handling: Reworked the relationship between
flag_valueand
defaultparameters for better consistency:defaultparameter value is now preserved as-is and passed directlyto CLI functions (no more unexpected transformations)
default=Truemaintain backward compatibilityby defaulting to their
flag_valuedefaultparameter can now be any type (bool,None, etc.)1992:issue:2514:issue:2610:issue:
3024:pr:3030Allow
defaultto be set onArgumentfornargs = -1. :issue:2164:pr:
3030Show correct auto complete value for
nargsoption in combination with flagoption :issue:
2813Fix handling of quoted and escaped parameters in Fish autocompletion. :issue:
2995:pr:3013Lazily import
shutil. :pr:3023Properly forward exception information to resources registered with
click.core.Context.with_resource(). :issue:2447:pr:3058Fix regression related to EOF handling in CliRunner. :issue:
2939:pr:2940v8.2.2Compare Source
Released 2025-07-31
default,flag_valueandtypeparameters forflag options, as well as parsing and normalization of environment variables.
:issue:
2952:pr:2956BadParameterandMissingParameterexceptions for theparameter
param_hintthat did not allow for a sequence of string where theunderlying function
_join_param_hintsallows for it. :issue:2777:pr:2990Enumchoices to render their default value in helpscreen. Refs :issue:
2911:pr:3004zsh) for completion items containingcolons. :issue:
2703:pr:28462971:pr:2972click.testing.StreamMixer's finalization that manifestedas a
ValueErroron close in a multi-threaded test session.:issue:
2993:pr:2991Configuration
📅 Schedule: (UTC)
🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.
♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.
🔕 Ignore: Close this PR and you won't be reminded about this update again.
This PR was generated by Mend Renovate. View the repository job log.