click 8.4.0

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