8.3.0

This is the Click 8.3.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.

PyPI: https://pypi.org/project/click/8.3.0/
Changes: https://click.palletsprojects.com/page/changes/#version-8-3-0
Milestone https://github.com/pallets/click/milestone/27

• Improved flag option handling: Reworked the relationship between flag_value
  and default parameters for better consistency:

  • The default parameter value is now preserved as-is and passed directly
    to CLI functions (no more unexpected transformations)
  • Exception: flag options with default=True maintain backward compatibility
    by defaulting to their flag_value
  • The default parameter can now be any type (bool, None, etc.)
  • Fixes inconsistencies reported in: #1992 #2514 #2610
    #3024 #3030

• Allow default to be set on Argument for nargs = -1. #2164
  #3030

• Show correct auto complete value for nargs option in combination with flag
  option #2813

• Show correct auto complete value for nargs option in combination with flag option #2813

• Fix handling of quoted and escaped parameters in Fish autocompletion. #2995 #3013

• Lazily import shutil. #3023

• Properly forward exception information to resources registered with
  click.core.Context.with_resource(). #2447 #3058

• Fix regression related to EOF handling in CliRunner. #2939 #2940

8.2.2

This is the Click 8.2.2 fix release, which fixes bugs but does not otherwise change behavior and should not result in breaking changes compared to the latest feature release.

PyPI: https://pypi.org/project/click/8.2.2/
Changes: https://click.palletsprojects.com/page/changes/#version-8-2-2
Milestone: https://github.com/pallets/click/milestone/25

• Fix reconciliation of default, flag_value and type parameters for
  flag options, as well as parsing and normalization of environment variables.
  #2952 #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 functino _join_param_hints allows for it. #2777 #2990
• Use the value of Enum choices to render their default value in help
  screen. #2911 #3004
• Fix completion for the Z shell (zsh) for completion items containing
  colons. #2703 #2846
• Don't include envvar in error hint when not configured. #2971 #2972
• Fix a rare race in click.testing.StreamMixer's finalization that manifested
  as a ValueError on close in a multi-threaded test session.
  #2993 #2991

8.2.1

This is the Click 8.2.1 fix release, which fixes bugs but does not otherwise change behavior and should not result in breaking changes compared to the latest feature release.

PyPI: https://pypi.org/project/click/8.2.1/
Changes: https://click.palletsprojects.com/page/changes/#version-8-2-1
Milestone: https://github.com/pallets/click/milestone/24?closed=1

• Fix flag value handling for flag options with a provided type. #2894 #2897
• Fix shell completion for nested groups. #2906
• Flush sys.stderr at the end of CliRunner.invoke. #2682
• Fix EOF handling for stdin input in CliRunner. #2787

8.2.0

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.

PyPI: https://pypi.org/project/click/8.2.0/
Changes: https://click.palletsprojects.com/en/stable/changes/
Milestone https://github.com/pallets/click/milestone/15

• 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. Command is the base class for all commands. #2589
• 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.

8.1.8

This is the Click 8.1.8 fix release, which fixes bugs but does not otherwise change behavior and should not result in breaking changes compared to the latest feature release.

PyPI: https://pypi.org/project/click/8.1.8/
Changes: https://click.palletsprojects.com/en/stable/changes/#version-8-1-8
Milestone https://github.com/pallets/click/milestones/23?closed=1

• Fix an issue with type hints for click.open_file(). #2717
• Fix issue where error message for invalid click.Path displays on
  multiple lines. #2697
• Fixed issue that prevented a default value of "" from being displayed in
  the help for an option. #2500
• The test runner handles stripping color consistently on Windows. #2705
• Show correct value for flag default when using default_map. #2632
• Fix click.echo(color=...) passing color to coloroma so it can be
  forced on Windows. #2606.
• More robust bash version check, fixing problem on Windows with git-bash. #2638
• Cache the help option generated by the help_option_names setting to
  respect its eagerness. #2811
• Replace uses of os.system with subprocess.Popen. #1476
• Exceptions generated during a command will use the context's color
  setting when being displayed. #2193
• Error message when defining option with invalid name is more descriptive. #2452
• Refactor code generating default --help option to deduplicate code. #2563
• Test CLIRunner resets patched _compat.should_strip_ansi. #2732

8.1.7

This is a fix release for the 8.1.x feature branch.

• Changes: https://click.palletsprojects.com/en/8.1.x/changes/#version-8-1-7
• Milestone: https://github.com/pallets/click/milestone/22?closed=1

8.1.6

This is a fix release for the 8.1.x feature branch. If you were having issues with type checking tools like pyright or mypy not accepting uses of Click's decorators, this should fix that.

• Changes: https://click.palletsprojects.com/en/8.1.x/changes/#version-8-1-6
• Milestone: https://github.com/pallets/click/milestone/21?closed=1

8.1.5

This is a fix release for the 8.1.x feature branch. This fixes an issue with decorator type annotations that caused type checkers to fail for valid code. There are no runtime behavior changes.

• Changes: https://click.palletsprojects.com/en/8.1.x/changes/#version-8-1-5
• Milestone: https://github.com/pallets/click/milestone/20?closed=1

8.1.4

This is a fix release for the 8.1.x feature branch.

• Changes: https://click.palletsprojects.com/en/8.1.x/changes/#version-8-1-4
• Milestone: https://github.com/pallets/click/milestone/19?closed=1

8.1.3

This is a fix release for the 8.1.0 feature release.

• Changes: https://click.palletsprojects.com/en/8.1.x/changes/#version-8-1-3
• Milestone: https://github.com/pallets/click/milestone/18?closed=1