●Change8

8.2.0

Breaking Changes
📦 clickView on GitHub →
⚠ 8 breaking✨ 21 features🐛 4 fixes⚡ 7 deprecations🔧 21 symbols

Summary

Click 8.2.0 introduces numerous new features, deprecates legacy APIs, drops Python 3.7‑3.9 support, and removes several breaking symbols such as `click.HelpOption` and `mix_stderr`.

⚠️ Breaking Changes

  • Dropped support for Python 3.7, 3.8, and 3.9. Projects must run on Python >=3.10.
  • Removed `click.HelpOption` API; importing it will raise ImportError. Use the built‑in help handling instead.
  • Removed the `mix_stderr` parameter from `CliRunner`; code that passes this argument will raise a TypeError and must be updated to rely on the independent stdout/stderr streams.
  • Removed the `parser` module and `OptionParser` class; any imports from `click.parser` will break. Switch to Click's built‑in parsing (no external parser needed).
  • Removed `Context.protected_args`; use `Context.args` for remaining arguments.
  • Removed `Parameter.add_to_parser`; custom parser hooks must be refactored to use Click's automatic parsing.
  • `Option.flag_value` no longer defaults based on `Option.default` when `is_flag` is false; code that relied on that implicit default must set `flag_value` explicitly.
  • When `no_args_is_help` triggers help, the exit code is now 2 instead of 0; scripts or tests expecting exit code 0 need to be adjusted.

Migration Steps

  1. Replace any usage of `click.__version__` with `importlib.metadata.version("click")`.
  2. Swap `BaseCommand` subclasses for `Command` and `MultiCommand` subclasses for `Group`.
  3. Remove imports of `click.parser`, `OptionParser`, and any references to `Context.protected_args` or `Parameter.add_to_parser`; use the new APIs instead.
  4. If you passed `mix_stderr` to `CliRunner`, delete that argument and rely on the independent stdout/stderr streams.
  5. Update code that relied on `Option.flag_value` defaulting from `Option.default` when `is_flag` is false by explicitly setting `flag_value` where needed.
  6. Adjust test expectations for help output triggered by `no_args_is_help` to expect exit code 2.
  7. If you used `click.HelpOption`, remove it and rely on Click's built‑in `--help` handling.
  8. Review any custom deprecation messages; you can now pass a string to `deprecated` on options/arguments.
  9. If you used `click.edit` with a single filename, you can now also pass an iterable of filenames; update type hints accordingly.

✨ New Features

  • Enabled deferred evaluation of annotations with `from __future__ import annotations`.
  • When generating a command name from a function, suffixes `_command`, `_cmd`, `_group`, and `_grp` are stripped.
  • `types.ParamType.name` is shown for `types.Choice` options in `--help` when `show_choices=False`.
  • `Option.show_default=False` now hides default values in prompts.
  • Added `Option.get_help_extra` method to retrieve extra help items for rendering.
  • `CliRunner` now keeps stdout and stderr independent, always captures stderr, and no longer raises on mixed streams.
  • `Option.show_envvar` now displays the environment variable in error messages as well.
  • `Context.close` is called automatically on exit, invoking `Context.call_on_close` callbacks and resources added via `Context.with_resource`.
  • Added `ProgressBar(hidden: bool)` parameter to hide the progress bar.
  • A `UserWarning` is emitted when multiple parameters share the same name.
  • `Option.envvar` combined with `Option.flag_value` now always prefers the flag value over the environment variable.
  • Added `Choice.get_invalid_choice_message` for custom invalid‑choice messages.
  • Help shown via `no_args_is_help` now exits with code 2.
  • `click.edit` now accepts an iterable of filenames and its return type is correctly typed (`AnyStr` when `text` is passed, otherwise `None`).
  • Specialized typing for `progressbar(length=…)` as `ProgressBar[int]`.
  • Improved `echo_via_pager` to terminate the pager on generator errors, always close the pipe, and no longer ignore `KeyboardInterrupt`.
  • `deprecated` can now be a `bool` or `str` on options and arguments, allowing custom deprecation messages.
  • Added `catch_exceptions` parameter to `CliRunner` to control exception handling during invocation.
  • `Option.flag_value` no longer inherits a default from `Option.default` when `is_flag` is false.
  • `Choice` is now generic, supporting any iterable value (e.g., enums).
  • Removed `click.HelpOption` introduced in 8.1.8 due to API incompatibility.

🐛 Bug Fixes

  • Contexts created during shell completion are now closed properly, fixing a `ResourceWarning` when using `click.File`.
  • `echo_via_pager` now correctly terminates the pager process on generator exceptions and handles `KeyboardInterrupt`.
  • Corrected the typing of `click.edit` return value.
  • Fixed several resource‑leak warnings related to progress bar and pager handling.

🔧 Affected Symbols

__version__BaseCommandMultiCommandOptionParserparserContext.protected_argsParameter.add_to_parsersplit_arg_stringOption.show_defaultOption.show_envvarContext.closeProgressBarChoiceclick.editecho_via_pagerOption.deprecatedCommand.deprecatedCliRunnerCliRunner.mix_stderrclick.HelpOptionOption.flag_value

⚡ Deprecations

  • `__version__` attribute is deprecated; use `importlib.metadata.version("click")` instead.
  • `BaseCommand` is deprecated; use `Command` as the base class.
  • `MultiCommand` is deprecated; use `Group` as the base class for groups.
  • The legacy parser (`OptionParser` and the `parser` module) is deprecated and will be removed in a future release.
  • `Context.protected_args` is deprecated; `Context.args` provides the same information.
  • `Parameter.add_to_parser` is deprecated; parsing now works without building a separate parser.
  • `split_arg_string` has been moved to `click.shell_completion`; the old location is deprecated.