click 8.4.0

on Python PyPI

This is the Click 8.4.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.4.0/
Changes: https://click.palletsprojects.com/page/changes/#version-8-4-0
Milestone https://github.com/pallets/click/milestone/30

• ParamType typing improvements. #3371

  • :class:ParamType is now a generic abstract base class,
    parameterized by its converted value type.
  • :meth:~ParamType.convert return types are narrowed on all
    concrete types (str for :class:STRING, int for
    :class:INT, etc.).
  • :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.

• Refactor convert_type to extract type inference into a private
  _guess_type helper, and add :func:typing.overload signatures.
  #3372

• Parameter typing improvements. #2805

  • :class:Parameter is now an abstract base class, making explicit
    that it cannot be instantiated directly.
  • :attr:Parameter.name is now str instead of str | None.
    When expose_value=False, the name is set to "" instead
    of None.
  • The ctx parameter of :meth:Parameter.get_error_hint is now
    typed as Context | None, matching the runtime behavior.

• Split string values from default_map for parameters with nargs > 1
  or :class:Tuple type, matching environment variable behavior.
  #2745 #3364

• Auto-detect type=UNPROCESSED for flag_value of non-basic types
  (not str, int, float, or bool), so programmer-provided
  Python objects like classes and enum members are passed through unchanged
  instead of being stringified. Previously type=click.UNPROCESSED had
  to be set explicitly. #2012 #3363

• The error hint now uses Command.get_help_option_names to pick
  non-shadowed help option names, so Try '... -h' no longer points to a
  subcommand option that shadows -h. All surviving names are shown
  (-h/--help). #2790 #3208

• Fix readline functionality on non-Windows platforms. Prompt text is now
  passed directly to readline instead of being printed separately, allowing
  proper backspace, line editing, and line wrapping behavior. #2968
  #2969

• Use :func:os.startfile on Windows to open URLs in :func:open_url,
  replacing the start built-in which cannot be invoked without
  shell=True. #3164 #3186

• Fix Fish shell completion errors when option help text contains newlines.
  #3043 #3126

• Add :class:NoSuchCommand exception with suggestions for misspelled
  commands. #3107 #3228

• Use :class:ValueError message when conversion in :class:FuncParamType would
  fail. #3105 #3211

• Add click.get_pager_file for file-like access to an output
  pager. #1572 #3405

• :class:~click.formatting.TextWrapper and
  :func:~click.formatting.wrap_text now measure line width in visible
  characters, ignoring ANSI escape sequences. #3420

• Fix :meth:HelpFormatter.write_usage emitting only a blank line when
  called without args. The usage prefix and program name are now
  written even when no arguments follow, and the trailing separator
  space is stripped so the line ends at the program name.
  #3360 #3434

• Show custom error messages from types when :func:prompt with
  hide_input=True fails validation, instead of always showing a
  generic message. Built-in type messages mask the input value.
  #2809 #3256

• Add capture parameter to :class:CliRunner with two modes: sys
  (default) and fd. fd redirects file descriptors 1 and 2
  via :func:os.dup2 so output that bypasses sys.stdout (stale stream
  references, C extensions, subprocesses, faulthandler) is captured
  with proper isolation. #854 #2412 #2468
  #2497 #2761 #2827 #2865

• Revert the 8.3.3 change that exposed the original file descriptor
  via fileno() on the redirected CliRunner streams in the default
  capture mode. os.dup2(w, sys.stdout.fileno()) calls inside a CLI no
  longer mutate the host runner's stdout, which broke Pytest's fd-level
  capture teardown. C-level consumers that need a real fd should use
  capture="fd". #3384 #3391

• Mark additional built-in strings with gettext() to extend translation
  coverage. #2902

• Fix feature switch groups (several flag_value options sharing one
  parameter name) silently dropping an explicit default when a sibling
  option without an explicit default was declared first. Arbitration is now
  source-aware: a more explicit :class:ParameterSource always wins, and
  within ParameterSource.DEFAULT, an option that received an explicit
  default= keyword wins over a sibling whose default was auto-derived.
  The 8.3.x first-wins fallback for remaining ties was reverted to the
  pre-8.3.x last-wins fallback. #3403 #3404

• Fix missing space between option help text and the (DEPRECATED)
  label, and localize the option label so it matches the command label.
  The label and the DeprecationWarning reason suffix are now produced
  by shared helpers. #3423

• Document short option stacking (-abc is parsed as -a -b -c) and
  clarify that multi-character short option names are not supported.
  #2779 #3431