Changelog History
Page 1
-
v8.2.0 Changes
๐ Unreleased
-
v8.1.3 Changes
๐ Released 2022-04-28
- Use verbose form of
typing.Callable
for@command
and@group
. :issue:2255
- Show error when attempting to create an option with
multiple=True, is_flag=True
. Usecount
instead. :issue:2246
- Use verbose form of
-
v8.1.2 Changes
๐ Released 2022-03-31
- Fix error message for readable path check that was mixed up with the
executable check. :pr:
2236
- โช Restore parameter order for
Path
, placing theexecutable
parameter at the end. It is recommended to use keyword arguments instead of positional arguments. :issue:2235
- Fix error message for readable path check that was mixed up with the
executable check. :pr:
-
v8.1.1 Changes
๐ Released 2022-03-30
- Fix an issue with decorator typing that caused type checking to
report that a command was not callable. :issue:
2227
- Fix an issue with decorator typing that caused type checking to
report that a command was not callable. :issue:
-
v8.1.0 Changes
๐ Released 2022-03-28
- ๐ Drop support for Python 3.6. :pr:
2129
๐ Remove previously deprecated code. :pr:
2130
-
Group.resultcallback
is renamed toresult_callback
. -
autocompletion
parameter toCommand
is renamed toshell_complete
. -
get_terminal_size
is removed, useshutil.get_terminal_size
instead. -
get_os_args
is removed, usesys.argv[1:]
instead.
-
Rely on :pep:
538
and :pep:540
to handle selecting UTF-8 encoding instead of ASCII. Click's locale encoding detection is removed. :issue:2198
0๏ธโฃ Single options boolean flags with
show_default=True
only show the default if it isTrue
. :issue:1971
The
command
andgroup
decorators can be applied with or without parentheses. :issue:1359
The
Path
type can check whether the target is executable. :issue:1961
0๏ธโฃ
Command.show_default
overridesContext.show_default
, instead of the other way around. :issue:1963
Parameter decorators and
@group
handlescls=None
the same as not passingcls
.@option
handleshelp=None
the same as not passinghelp
. :issue:#1959
A flag option with
required=True
requires that the flag is passed instead of choosing the implicit default value. :issue:1978
Indentation in help text passed to
Option
andCommand
is cleaned the same as using the@option
and@command
decorators does. A command'sepilog
andshort_help
are also processed. :issue:1985
Store unprocessed
Command.help
,epilog
andshort_help
strings. Processing is only done when formatting help text for output. :issue:2149
Allow empty str input for
prompt()
whenconfirmation_prompt=True
anddefault=""
. :issue:2157
๐ Windows glob pattern expansion doesn't fail if a value is an invalid pattern. :issue:
2195
It's possible to pass a list of
params
to@command
. Any params defined with decorators are appended to the passed params. :issue:2131
.@command
decorator is annotated as returning the correct type if acls
argument is used. :issue:2211
A
Group
withinvoke_without_command=True
andchain=False
will invoke its result callback with the group function's return value. :issue:2124
to_info_dict
will not fail if aParamType
doesn't define aname
. :issue:2168
๐ Shell completion prioritizes option values with option prefixes over new options. :issue:
2040
Options that get an environment variable value using
autoenvvar_prefix
treat an empty value asNone
, consistent with a directenvvar
. :issue:2146
- ๐ Drop support for Python 3.6. :pr:
-
v8.0.4 Changes
๐ Released 2022-02-18
-
open_file
recognizesPath("-")
as a standard stream, the same as the string"-"
. :issue:2106
- The
option
andargument
decorators preserve the type annotation of the decorated function. :pr:2155
- 0๏ธโฃ A callable default value can customize its help text by overriding
__str__
instead of always showing(dynamic)
. :issue:2099
- Fix a typo in the Bash completion script that affected file and
directory completion. If this script was generated by a previous
version, it should be regenerated. :issue:
2163
- Fix typing for
echo
andsecho
file argument. :issue:2174, 2185
-
-
v8.0.3 Changes
๐ Released 2021-10-10
- Fix issue with
Path(resolve_path=True)
type creating invalid paths. :issue:2088
- Importing
readline
does not cause theconfirm()
prompt to disappear when pressing backspace. :issue:2092
- 0๏ธโฃ Any default values injected by
invoke()
are cast to the corresponding parameter's type. :issue:2089, 2090
- Fix issue with
-
v8.0.2 Changes
๐ Released 2021-10-08
-
is_bool_flag
is not set toTrue
ifis_flag
isFalse
. :issue:1925
- Bash version detection is locale independent. :issue:
1940
- 0๏ธโฃ Empty
default
value is not shown formultiple=True
. :issue:1969
- Fix shell completion for arguments that start with a forward slash
such as absolute file paths. :issue:
1929
-
Path
type withresolve_path=True
resolves relative symlinks to be relative to the containing directory. :issue:1921
- Completion does not skip Python's resource cleanup when exiting,
avoiding some unexpected warning output. :issue:
1738, 2017
- Fix type annotation for
type
argument inprompt
function. :issue:2062
- ๐
Fix overline and italic styles, which were incorrectly added when
adding underline. :pr:
2058
- An option with
count=True
will not show "[x>=0]" in help text. :issue:2072
- 0๏ธโฃ Default values are not cast to the parameter type twice during
processing. :issue:
2085
- Options with
multiple
andflag_value
use the flag value instead of leaving an internal placeholder. :issue:2001
-
-
v8.0.1 Changes
๐ Released 2021-05-19
- Mark top-level names as exported so type checking understand imports
in user projects. :issue:
1879
- Annotate
Context.obj
asAny
so type checking allows all operations on the arbitrary object. :issue:1885
- Fix some types that weren't available in Python 3.6.0. :issue:
1882
- Fix type checking for iterating over
ProgressBar
object. :issue:1892
- ๐ The
importlib_metadata
backport package is installed on Python < 3.8. :issue:1889
- Arguments with
nargs=-1
only use env var value if no command line values are given. :issue:1903
- Flag options guess their type from
flag_value
if given, like regular options do fromdefault
. :issue:1886
- ๐ Added documentation that custom parameter types may be passed
already valid values in addition to strings. :issue:
1898
- Resolving commands returns the name that was given, not
command.name
, fixing an unintended change to help text anddefault_map
lookups. When using patterns likeAliasedGroup
, overrideresolve_command
to change the name that is returned if needed. :issue:1895
- 0๏ธโฃ If a default value is invalid, it does not prevent showing help
text. :issue:
1889
- Pass
windows_expand_args=False
when calling the main command to disable pattern expansion on Windows. There is no way to escape patterns in CMD, so if the program needs to pass them on as-is then expansion must be disabled. :issue:1901
- Mark top-level names as exported so type checking understand imports
in user projects. :issue:
-
v8.0 Changes
๐ Unreleased
- ๐ Drop support for Python 2 and 3.5.
- ๐
Colorama is always installed on Windows in order to provide style
and color support. :pr:
1784
- Adds a repr to Command, showing the command name for friendlier
debugging. :issue:
1267
, :pr:1295
- ๐ Add support for distinguishing the source of a command line
parameter. :issue:
1264
, :pr:1329
- โก๏ธ Add an optional parameter to
ProgressBar.update
to set thecurrent_item
. :issue:1226
, :pr:1332
- ๐
version_option
usesimportlib.metadata
(or theimportlib_metadata
backport) instead ofpkg_resources
. :issue:1582
- If validation fails for a prompt with
hide_input=True
, the value is not shown in the error message. :issue:1460
- An
IntRange
orFloatRange
option shows the accepted range in its help text. :issue:1525
, :pr:1303
-
IntRange
andFloatRange
bounds can be open (<
) instead of closed (<=
) by settingmin_open
andmax_open
. Error messages have changed to reflect this. :issue:1100
- An option defined with duplicate flag names (
"--foo/--foo"
) raises aValueError
. :issue:1465
- โ
echo()
will not fail when using pytest'scapsys
fixture on Windows. :issue:1590
- Resolving commands returns the canonical command name instead of the
matched name. This makes behavior such as help text and
Context.invoked_subcommand
consistent when using patterns likeAliasedGroup
. :issue:1422
- The
BOOL
type accepts the values "on" and "off". :issue:1629
- A
Group
withinvoke_without_command=True
will always invoke its result callback. :issue:1178
- ๐
nargs == -1
andnargs > 1
is parsed and validated for values from environment variables and defaults. :issue:729
- ๐ฆ Detect the program name when executing a module or package with
python -m name
. :issue:1603
- Include required parent arguments in help synopsis of subcommands.
:issue:
1475
- 0๏ธโฃ Help for boolean flags with
show_default=True
shows the flag name instead ofTrue
orFalse
. :issue:1538
- ๐
Non-string objects passed to
style()
andsecho()
will be converted to string. :pr:1146
-
edit(require_save=True)
will detect saves for editors that exit very fast on filesystems with 1 second resolution. :pr:1050
New class attributes make it easier to use custom core objects throughout an entire application. :pr:
938
-
Command.context_class
controls the context created when running the command. -
Context.invoke
creates new contexts of the same type, so a custom type will persist to invoked subcommands. -
Context.formatter_class
controls the formatter used to generate help and usage. -
Group.command_class
changes the default type for subcommands with@group.command()
. -
Group.group_class
changes the default type for subgroups with@group.group()
. Setting it totype
will create subgroups of the same type as the group itself. - Core objects use
super()
consistently for better support of subclassing.
-
Use
Context.with_resource()
to manage resources that would normally be used in awith
statement, allowing them to be used across subcommands and callbacks, then cleaned up when the context ends. :pr:1191
โ The result object returned by the test runner's
invoke()
method has areturn_value
attribute with the value returned by the invoked command. :pr:1312
Required arguments with the
Choice
type show the choices in curly braces to indicate that one is required ({a|b|c}
). :issue:1272
If only a name is passed to
option()
, Click suggests renaming it to--name
. :pr:1355
0๏ธโฃ A context's
show_default
parameter defaults to the value from the parent context. :issue:1565
๐
click.style()
can output 256 and RGB color codes. Most modern terminals support these codes. :pr:1429
When using
CliRunner.invoke()
, the replacedstdin
file hasname
andmode
attributes. This letsFile
options with the-
value match non-testing behavior. :issue:1064
When creating a
Group
, allow passing a list of commands instead of a dict. :issue:1339
๐ When a long option name isn't valid, use
difflib
to make better suggestions for possible corrections. :issue:1446
Core objects have a
to_info_dict()
method. This gathers information about the object's structure that could be useful for a tool generating user-facing documentation. To get the structure of an entire CLI, useContext(cli).to_info_dict()
. :issue:461
Redesign the shell completion system. :issue:
1484
, :pr:1622
- Support Bash >= 4.4, Zsh, and Fish, with the ability for extensions to add support for other shells.
- Allow commands, groups, parameters, and types to override their completions suggestions.
- Groups complete the names commands were registered with, which can differ from the name they were created with.
- The
autocompletion
parameter for options and arguments is renamed toshell_complete
. The function must takectx, param, incomplete
, must do matching rather than return all values, and must return a list of strings or a list ofShellComplete
. The old name and behavior is deprecated and will be removed in 8.1. - The env var values used to start completion have changed order.
The shell now comes first, such as
{shell}_source
rather thansource_{shell}
, and is always required.
๐ Completion correctly parses command line strings with incomplete quoting or escape sequences. :issue:
1708
Extra context settings (
obj=...
, etc.) are passed on to the completion system. :issue:942
Include
--help
option in completion. :pr:1504
ParameterSource
is anenum.Enum
subclass. :issue:1530
Boolean and UUID types strip surrounding space before converting. :issue:
1605
Adjusted error message from parameter type validation to be more consistent. Quotes are used to distinguish the invalid value. :issue:
1605
0๏ธโฃ The default value for a parameter with
nargs
> 1 andmultiple=True
must be a list of tuples. :issue:1649
0๏ธโฃ When getting the value for a parameter, the default is tried in the same section as other sources to ensure consistent processing. :issue:
1649
All parameter types accept a value that is already the correct type. :issue:
1649
For shell completion, an argument is considered incomplete if its value did not come from the command line args. :issue:
1649
Added
ParameterSource.PROMPT
to track parameter values that were prompted for. :issue:1649
0๏ธโฃ Options with
nargs
> 1 no longer raise an error if a default is not given. Parameters withnargs
> 1 default toNone
, and parameters withmultiple=True
ornargs=-1
default to an empty tuple. :issue:472
Handle empty env vars as though the option were not passed. This extends the change introduced in 7.1 to be consistent in more cases. :issue:
1285
0๏ธโฃ
Parameter.get_default()
checksContext.default_map
to handle overrides consistently in help text,invoke()
, and prompts. :issue:1548
Add
prompt_required
param toOption
. When set toFalse
, the user will only be prompted for an input if no value was passed. :issue:736
Providing the value to an option can be made optional through
is_flag=False
, and the value can instead be prompted for or passed in as a default value. :issue:549, 736, 764, 921, 1015, 1618
Fix formatting when
Command.options_metavar
is empty. :pr:1551
โช Revert adding space between option help text that wraps. :issue:
1831
0๏ธโฃ The default value passed to
prompt
will be cast to the correct type like an input value would be. :pr:1517
Automatically generated short help messages will stop at the first ending of a phrase or double linebreak. :issue:
1082
Skip progress bar render steps for efficiency with very fast iterators by setting
update_min_steps
. :issue:676
Respect
case_sensitive=False
when doing shell completion forChoice
:issue:1692
Use
mkstemp()
instead ofmktemp()
in pager implementation. :issue:1752
0๏ธโฃ If
Option.show_default
is a string, it is displayed even ifdefault
isNone
. :issue:1732
click.get_terminal_size()
is deprecated and will be removed in 8.1. Use :func:shutil.get_terminal_size
instead. :issue:1736
Control the location of the temporary directory created by
CLIRunner.isolated_filesystem
by passingtemp_dir
. A custom directory will not be removed automatically. :issue:395
click.confirm()
will prompt until input is given if called withdefault=None
. :issue:1381
Option prompts validate the value with the option's callback in addition to its type. :issue:
457
confirmation_prompt
can be set to a custom string. :issue:723
๐ Allow styled output in Jupyter on Windows. :issue:
1271
๐
style()
supports thestrikethrough
,italic
, andoverline
styles. :issue:805, 1821
๐ Multiline marker is removed from short help text. :issue:
1597
โช Restore progress bar behavior of echoing only the label if the file is not a TTY. :issue:
1138
Progress bar output is shown even if execution time is less than 0.5 seconds. :issue:
1648
๐ Progress bar
item_show_func
shows the current item, not the previous item. :issue:1353
The
Path
param type can be passedpath_type=pathlib.Path
to return a path object instead of a string. :issue:405
TypeError
is raised when parameter withmultiple=True
ornargs > 1
has non-iterable default. :issue:1749
Add a
pass_meta_key
decorator for passing a key fromContext.meta
. This is useful for extensions usingmeta
to store information. :issue:1739
๐
Path
resolve_path
resolves symlinks on Windows Python < 3.8. :issue:1813
๐ Command deprecation notice appears at the start of the help text, as well as in the short help. The notice is not in all caps. :issue:
1791
๐ When taking arguments from
sys.argv
on Windows, glob patterns, user dir, and env vars are expanded. :issue:1096
Marked messages shown by the CLI with
gettext()
to allow applications to translate Click's built-in strings. :issue:303
โ Writing invalid characters to
stderr
when using the test runner does not raise aUnicodeEncodeError
. :issue:848
Fix an issue where
readline
would clear the entireprompt()
line instead of only the input when pressing backspace. :issue:665
Add all kwargs passed to
Context.invoke()
toctx.params
. Fixes an inconsistency when nestingContext.forward()
calls. :issue:1568
The
MultiCommand.resultcallback
decorator is renamed toresult_callback
. The old name is deprecated. :issue:1160
Fix issues with
CliRunner
output when usingecho_stdin=True
. :issue:1101
0๏ธโฃ Fix a bug of
click.utils.make_default_short_help
for which the returned string could be as long asmax_width + 3
. :issue:1849
0๏ธโฃ When defining a parameter,
default
is validated withmultiple
andnargs
. More validation is done for values being processed as well. :issue:1806