●Change8

8.4.0

Breaking Changes
📦 clickView on GitHub →
⚠ 2 breaking✨ 15 features🐛 9 fixes🔧 27 symbols

Summary

Click 8.4.0 is a feature release introducing significant typing improvements across ParamType and Parameter, alongside various bug fixes related to readline, URL opening, and output capturing.

⚠️ Breaking Changes

  • :class:`Parameter.name` is now strictly typed as ``str`` instead of ``str | None``. When ``expose_value=False``, the name is set to ``""`` instead of ``None``.
  • The default behavior of :class:`CliRunner` capture mode has been reverted regarding stream mutation. C-level consumers relying on the original file descriptor being exposed via ``fileno()`` on redirected streams in default capture mode must now use ``capture=\"fd\"`` to achieve that behavior.

Migration Steps

  1. If you subclassed :class:`ParamType`, ensure your implementation handles the generic typing, especially in :meth:`~ParamType.convert` return types.
  2. If you relied on ``Parameter.name`` being ``None`` when ``expose_value=False``, update code to check for ``""`` instead.
  3. Consumers of :class:`CliRunner` that need access to the original file descriptor via ``fileno()`` on redirected streams must now use ``capture=\"fd\"``.

✨ New Features

  • :class:`ParamType` is now a generic abstract base class, parameterized by its converted value type.
  • Return types of :meth:`~ParamType.convert` are narrowed on all concrete types (e.g., ``str`` for :class:`STRING`, ``int`` for :class:`INT`).
  • :meth:`~ParamType.to_info_dict` returns specific :class:`~typing.TypedDict` subclasses instead of ``dict[str, Any]``.
  • :class:`CompositeParamType` and the number-range base are now generic with abstract methods.
  • Added :func:`typing.overload` signatures for type inference in ``convert_type``.
  • :class:`Parameter` is now explicitly an abstract base class.
  • The ``ctx`` parameter of :meth:`Parameter.get_error_hint` is now typed as ``Context | None``.
  • Split string values from ``default_map`` for parameters with ``nargs > 1`` or :class:`Tuple` type, matching environment variable behavior.
  • Auto-detect ``type=UNPROCESSED`` for ``flag_value`` of non-basic types (not ``str``, ``int``, ``float``, or ``bool``), allowing programmer-provided Python objects to pass through unchanged.
  • Error hint uses `Command.get_help_option_names` to pick non-shadowed help option names.
  • Added :class:`NoSuchCommand` exception with suggestions for misspelled commands.
  • Added :class:`click.get_pager_file` for file-like access to an output pager.
  • :class:`~click.formatting.TextWrapper` and :func:`~click.formatting.wrap_text` now measure line width in visible characters, ignoring ANSI escape sequences.
  • Added ``capture`` parameter to :class:`CliRunner` with modes ``sys`` (default) and ``fd`` for improved output capturing isolation.
  • Marked additional built-in strings with ``gettext()`` for extended translation coverage.

🐛 Bug Fixes

  • Fixed readline functionality on non-Windows platforms by passing prompt text directly to readline.
  • Used :func:`os.startfile` on Windows to open URLs in :func:`open_url`, replacing the ``start`` built-in.
  • Fixed Fish shell completion errors when option help text contains newlines.
  • Used :class:`ValueError` message when conversion in :class:`FuncParamType` would fail.
  • Fixed :meth:`HelpFormatter.write_usage` emitting only a blank line when called without ``args``; usage prefix/program name are now written correctly.
  • Show custom error messages from types when :func:`prompt` with ``hide_input=True`` fails validation, instead of a generic message.
  • Reverted the change that exposed the original file descriptor via ``fileno()`` on redirected :class:`CliRunner` streams in default capture mode, preventing mutation of host runner's stdout.
  • Fixed feature switch groups silently dropping an explicit ``default`` when a sibling option without an explicit default was declared first, by implementing source-aware arbitration.
  • Fixed missing space between option help text and the ``(DEPRECATED)`` label, and localized the option label.

Affected Symbols

ParamTypeParamType.convertParamType.to_info_dictSTRINGINTCompositeParamTypeconvert_type_guess_typeParameterParameter.nameParameter.get_error_hintContextdefault_mapTupleflag_valueclick.UNPROCESSEDCommand.get_help_option_namesopen_urlCliRunnerNoSuchCommandFuncParamTypeclick.get_pager_fileclick.formatting.TextWrapperclick.formatting.wrap_textHelpFormatter.write_usagepromptParameterSource