This is the Click 8.2.0 feature release. A feature release may include new features, remove previously deprecated code, add new deprecation, or introduce potentially breaking changes.
We encourage everyone to upgrade. You can read more about our Version Support Policy on our website.
Drop support for Python 3.7, 3.8,and 3.9. #2588, #2893
Use modern packaging metadata with pyproject.toml instead of setup.cfg. #2438
Use flit_core instead of setuptools as build backend. #2543
Deprecate the __version__ attribute. Use feature detection, or importlib.metadata.version("click"), instead. #2598
BaseCommand is deprecated. is the base class for all commands. #2589
Command
MultiCommand is deprecated. Group is the base class for all group commands. #2590
The current parser and related classes and methods, are deprecated.
#2205
OptionParser and the parser module, which is a modified copy of optparse in the standard library.
Context.protected_args is unneeded. Context.args contains any remaining arguments while parsing.
Parameter.add_to_parser (on both Argument and Option) is unneeded. Parsing works directly without building a separate parser.
split_arg_string is moved from parser to shell_completion.
Enable deferred evaluation of annotations with from __future__ import annotations. #2270
When generating a command's name from a decorated function's name, the suffixes _command, _cmd, _group, and _grp are removed. #2322
Show the types.ParamType.name for types.Choice options within --help message if show_choices=False is specified. #2356
Do not display default values in prompts when Option.show_default is False. #2509
Add get_help_extra method on Option to fetch the generated extra items used in get_help_record to render help text. #2516 #2517
Keep stdout and stderr streams independent in CliRunner. Always collect stderr output and never raise an exception. Add a new output stream to simulate what the user sees in its terminal. Removes the mix_stderr parameter in CliRunner. #2522 #2523
Option.show_envvar now also shows environment variable in error messages. #2695 #2696
Context.close will be called on exit. This results in all Context.call_on_close callbacks and context managers added via Context.with_resource to be closed on exit as well. #2680
Add ProgressBar(hidden: bool) to allow hiding the progressbar. #2609
A UserWarning will be shown when multiple parameters attempt to use the same name. #2396
When using Option.envvar with Option.flag_value, the flag_value will always be used instead of the value of the environment variable. #2746 #2788
Add Choice.get_invalid_choice_message method for customizing the invalid choice message. #2621 #2622
If help is shown because no_args_is_help is enabled (defaults to True for groups, False for commands), the exit code is 2 instead of 0. #1489 #1489
Contexts created during shell completion are closed properly, fixing a ResourceWarning when using click.File. #2644 #2800 #2767
click.edit(filename) now supports passing an iterable of filenames in case the editor supports editing multiple files at once. Its return type is now also typed: AnyStr if text is passed, otherwise None. #2067 #2068
Specialized typing of progressbar(length=...) as ProgressBar[int]. #2630
Improve echo_via_pager behaviour in face of errors. #2674
Terminate the pager in case a generator passed to echo_via_pager raises an exception.
Ensure to always close the pipe to the pager process and wait for it to terminate.
echo_via_pager will not ignore KeyboardInterrupt anymore. This allows the user to search for future output of the generator when using less and then aborting the program using ctrl-c.
deprecated: bool | str can now be used on options and arguments. This previously was only available for Command. The message can now also be customised by using a str instead of a bool. #2263 #2271
Command.deprecated formatting in --help changed from (Deprecated) help to help (DEPRECATED).
Parameters cannot be required nor prompted or an error is raised.
A warning will be printed when something deprecated is used.
Add a catch_exceptions parameter to CliRunner. If catch_exceptions is not passed to CliRunner.invoke, the value from CliRunner is used. #2817 #2818
Option.flag_value will no longer have a default value set based on Option.default if Option.is_flag is False. This results in Option.default not needing to implement __bool__. #2829
Incorrect click.edit typing has been corrected. #2804
Choice is now generic and supports any iterable value. This allows you to use enums and other non-str values. #2796 #605
Remove click.HelpOption that was introduced in 8.1.8 due to api incompatibility. #2832
Please remember, applications must lock their full dependency tree to control when updates are installed and ensure reproducible deployments. Use one of the various project management or lock tools available in the Python ecosystem. Test with warnings treated as errors to be able to adapt to deprecation warnings early.