●Change8

8.5.0

Breaking Changes
📦 clickView on GitHub →
⚠ 4 breaking✨ 8 features🐛 10 fixes⚡ 3 deprecations🔧 26 symbols

Summary

Click 8.5.0 introduces built-in PowerShell completion, improves ANSI support on Windows, and refines help option handling. It also deprecates several utility functions and the `isolated_filesystem` method.

⚠️ Breaking Changes

  • The automatic help option now stores its value under the reserved name `_click_default_help` instead of `help`. This means a parameter named `help` will no longer break parsing. If you have a parameter named `help`, it will now be treated as a regular parameter and the automatic help option will be disabled for that command.
  • Invalid color arguments passed to `style()` and `secho()` now raise a `ValueError` instead of a `TypeError`. Ensure that color arguments are valid.
  • The `click.utils` names `LazyFile`, `KeepOpenFile`, `make_default_short_help`, `PacifyFlushWrapper`, and `safecall` are now private (`_`-prefixed). While they remain available with a `DeprecationWarning` until Click 9.0, you should update your code to use the private versions or alternative implementations.
  • The `CliRunner.isolated_filesystem` method is deprecated. It relies on `os.chdir`, which is not thread-safe and mutates global state. Use `tempfile.TemporaryDirectory` or pytest's `tmp_path` fixture with absolute paths instead.

Migration Steps

  1. If you have a parameter named `help`, it will now be treated as a regular parameter and the automatic help option will be disabled for that command. Consider renaming your parameter.
  2. Update code that uses `click.utils.LazyFile`, `click.utils.KeepOpenFile`, `click.utils.make_default_short_help`, `click.utils.PacifyFlushWrapper`, or `click.utils.safecall` to use their private (`_`-prefixed) versions or alternative implementations.
  3. Replace usage of `CliRunner.isolated_filesystem` with `tempfile.TemporaryDirectory` or pytest's `tmp_path` fixture and absolute paths.

✨ New Features

  • Added built-in shell completion support for PowerShell (Windows PowerShell 5.1+ and pwsh 7+).
  • Supported versions of Windows enable ANSI terminal styles by default, removing the Colorama dependency.
  • `Argument` now accepts a `help` parameter, and help output includes a `Positional arguments` section when argument help is available.
  • Added `custom_version_option`, a `--version` option whose output is produced by a callback.
  • `prompt()` is now generically typed and returns the type produced by `type`, `value_proc`, or a matching `default` instead of `Any`. `ParamType` takes an optional second type parameter for the input value.
  • `Command.get_help_option_names` returns the help option names in the order they were declared.
  • The temporary file pager backend forwards any parameters set in `PAGER` to the pager command.
  • `edit` accepts `os.PathLike` values for `filename`.

🐛 Bug Fixes

  • `confirm()` and `prompt()` now strip ANSI color and style codes from the prompt when the output stream does not support them, fixing a regression from 8.4.0.
  • `Path` with `allow_dash=True` no longer triggers a `BytesWarning` when checking a value against the `-` convention.
  • The automatic help option now stores its value under the reserved name `_click_default_help` instead of `help`, preventing conflicts with parameters named `help`.
  • Unstyle and ANSI handling now strip the full CSI escape-sequence grammar.
  • Runtime behavior of `Option` flag handling is unchanged, but `Parameter.to_info_dict` now resolves `default=True` on a feature switch to its `flag_value`.
  • `get_pager_file` yields a text stream on Windows again, fixing a regression from 8.4.0 where writing `str` raised `TypeError`.
  • `progressbar` now settles on its final position when `update_min_steps` does not divide the total.
  • An error raised while writing to the pager no longer gets replaced by `PermissionError: [WinError 32]` on Windows.
  • The temporary file pager backend on Windows is opened with the correct encoding and `errors="replace"`.
  • Improved raw mode detection by parsing option tokens.

Affected Symbols

click.shell_completionclick.Commandclick.Argumentclick.confirmclick.promptclick.echoclick.Pathclick.custom_version_optionclick.version_optionclick.styleclick.sechoclick.Command.to_info_dictclick.Parameter.to_info_dictclick.get_binary_streamclick.get_text_streamclick.utils.LazyFileclick.utils.KeepOpenFileclick.utils.make_default_short_helpclick.utils.PacifyFlushWrapperclick.utils.safecallclick.CliRunner.isolated_filesystemclick.ParamTypeclick.Command.get_help_option_namesclick.get_pager_fileclick.progressbarclick.edit

⚡ Deprecations

  • `get_binary_stream` and `get_text_stream` are deprecated and will be removed in Click 9.0.
  • The `CliRunner.isolated_filesystem` method is deprecated. It relies on `os.chdir`, which is not thread-safe and mutates global state. Use `tempfile.TemporaryDirectory` or pytest's `tmp_path` fixture with absolute paths instead.
  • The `click.utils` names `LazyFile`, `KeepOpenFile`, `make_default_short_help`, `PacifyFlushWrapper`, and `safecall` are now private (`_`-prefixed). While they remain available with a `DeprecationWarning` until Click 9.0, you should update your code to use the private versions or alternative implementations.