Merge branch 'main' into bugfix/OptionsAutoCompletion

.github/workflows/pre-commit.yaml

@@ -0,0 +1,16 @@
+name: pre-commit
+on:
+  pull_request:
+  push:
+    branches: [main, stable]
+jobs:
+  main:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+    - uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0
+      with:
+        python-version: 3.x
+    - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
+    - uses: pre-commit-ci/lite-action@9d882e7a565f7008d4faf128f27d1cb6503d4ebf # v1.0.2
+      if: ${{ !cancelled() }}

.github/workflows/tests.yaml

@@ -21,7 +21,6 @@ jobs:
           - {python: '3.10'}
           - {python: '3.9'}
           - {python: '3.8'}
-          - {python: '3.7'}
           - {name: PyPy, python: 'pypy-3.10', tox: pypy310}
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

.gitignore

@@ -2,6 +2,8 @@
 .vscode/
 .venv*/
 venv*/
+.env*/
+env*/
 __pycache__/
 dist/
 .coverage*

CHANGES.rst

@@ -1,5 +1,104 @@
 .. currentmodule:: click
 
+Version 8.2.0
+-------------
+
+Unreleased
+
+-   Drop support for Python 3.7. :pr:`2588`
+-   Use modern packaging metadata with ``pyproject.toml`` instead of ``setup.cfg``.
+    :pr:`2438`
+-   Use ``flit_core`` instead of ``setuptools`` as build backend. :pr:`2543`
+-   Deprecate the ``__version__`` attribute. Use feature detection, or
+    ``importlib.metadata.version("click")``, instead. :issue:`2598`
+-   ``BaseCommand`` is deprecated. ``Command`` is the base class for all
+    commands. :issue:`2589`
+-   ``MultiCommand`` is deprecated. ``Group`` is the base class for all group
+    commands. :issue:`2590`
+-   The current parser and related classes and methods, are deprecated.
+    :issue:`2205`
+
+    -   ``OptionParser`` and the ``parser`` module, which is a modified copy of
+        ``optparse`` in the standard library.
+    -   ``Context.protected_args`` is unneeded. ``Context.args`` contains any
+        remaining arguments while parsing.
+    -   ``Parameter.add_to_parser`` (on both ``Argument`` and ``Option``) is
+        unneeded. Parsing works directly without building a separate parser.
+    -   ``split_arg_string`` is moved from ``parser`` to ``shell_completion``.
+
+-   Enable deferred evaluation of annotations with
+    ``from __future__ import annotations``. :pr:`2270`
+-   When generating a command's name from a decorated function's name, the
+    suffixes ``_command``, ``_cmd``, ``_group``, and ``_grp`` are removed.
+    :issue:`2322`
+-   Show the ``types.ParamType.name`` for ``types.Choice`` options within
+    ``--help`` message if ``show_choices=False`` is specified.
+    :issue:`2356`
+-   Do not display default values in prompts when ``Option.show_default`` is
+    ``False``. :pr:`2509`
+-   Add ``get_help_extra`` method on ``Option`` to fetch the generated extra
+    items used in ``get_help_record`` to render help text. :issue:`2516`
+    :pr:`2517`
+-   Keep stdout and stderr streams independent in ``CliRunner``. Always
+    collect stderr output and never raise an exception. Add a new
+    output stream to simulate what the user sees in its terminal. Removes
+    the ``mix_stderr`` parameter in ``CliRunner``. :issue:`2522` :pr:`2523`
+-   ``Option.show_envvar`` now also shows environment variable in error messages.
+    :issue:`2695` :pr:`2696`
+-   ``Context.close`` will be called on exit. This results in all
+    ``Context.call_on_close`` callbacks and context managers added via
+    ``Context.with_resource`` to be closed on exit as well. :pr:`2680`
+-   Add ``ProgressBar(hidden: bool)`` to allow hiding the progressbar. :issue:`2609`
+-   A ``UserWarning`` will be shown when multiple parameters attempt to use the
+    same name. :issue:`2396`
+-   When using ``Option.envvar`` with ``Option.flag_value``, the ``flag_value``
+    will always be used instead of the value of the environment variable.
+    :issue:`2746` :pr:`2788`
+-   Add ``Choice.get_invalid_choice_message`` method for customizing the
+    invalid choice message. :issue:`2621` :pr:`2622`
+-   If help is shown because ``no_args_is_help`` is enabled (defaults to ``True``
+    for groups, ``False`` for commands), the exit code is 2 instead of 0.
+    :issue:`1489` :pr:`1489`
+-   Contexts created during shell completion are closed properly, fixing
+    a ``ResourceWarning`` when using ``click.File``. :issue:`2644` :pr:`2800`
+    :pr:`2767`
+-   ``click.edit(filename)`` now supports passing an iterable of filenames in
+    case the editor supports editing multiple files at once. Its return type
+    is now also typed: ``AnyStr`` if ``text`` is passed, otherwise ``None``.
+    :issue:`2067` :pr:`2068`
+-   Specialized typing of ``progressbar(length=...)`` as ``ProgressBar[int]``.
+    :pr:`2630`
+-   Improve ``echo_via_pager`` behaviour in face of errors.
+    :issue:`2674`
+
+    -   Terminate the pager in case a generator passed to ``echo_via_pager``
+        raises an exception.
+    -   Ensure to always close the pipe to the pager process and wait for it
+        to terminate.
+    -   ``echo_via_pager`` will not ignore ``KeyboardInterrupt`` anymore. This
+        allows the user to search for future output of the generator when
+        using less and then aborting the program using ctrl-c.
+
+-   ``deprecated: bool | str`` can now be used on options and arguments. This
+    previously was only available for ``Command``. The message can now also be
+    customised by using a ``str`` instead of a ``bool``. :issue:`2263` :pr:`2271`
+
+    -   ``Command.deprecated`` formatting in ``--help`` changed from
+        ``(Deprecated) help`` to ``help (DEPRECATED)``.
+    -   Parameters cannot be required nor prompted or an error is raised.
+    -   A warning will be printed when something deprecated is used.
+
+-   Add a ``catch_exceptions`` parameter to ``CliRunner``. If
+    ``catch_exceptions`` is not passed to ``CliRunner.invoke``,
+    the value from ``CliRunner``. :issue:`2817` :pr:`2818`
+-   ``Option.flag_value`` will no longer have a default value set based on
+    ``Option.default`` if ``Option.is_flag`` is ``False``. This results in
+    ``Option.default`` not needing to implement `__bool__`. :pr:`2829`
+-   Incorrect ``click.edit`` typing has been corrected. :pr:`2804`
+-   ``Choice`` is now generic and supports any iterable value.
+    This allows you to use enums and other non-``str`` values. :pr:`2796`
+    :issue:`605`
+
 Version 8.1.8
 -------------
 
@@ -957,12 +1056,10 @@ Released 2014-08-22
     function.
 -   Fixed default parameters not being handled properly by the context
     invoke method. This is a backwards incompatible change if the
-    function was used improperly. See :ref:`upgrade-to-3.2` for more
-    information.
+    function was used improperly.
 -   Removed the ``invoked_subcommands`` attribute largely. It is not
     possible to provide it to work error free due to how the parsing
-    works so this API has been deprecated. See :ref:`upgrade-to-3.2` for
-    more information.
+    works so this API has been deprecated.
 -   Restored the functionality of ``invoked_subcommand`` which was
     broken as a regression in 3.1.
 

CONTRIBUTING.rst

@@ -107,12 +107,6 @@ First time setup
 
         > env\Scripts\activate
 
--   Upgrade pip and setuptools.
-
-    .. code-block:: text
-
-        $ python -m pip install --upgrade pip setuptools
-
 -   Install the development dependencies, then install Click in
     editable mode.
 

docs/advanced.rst

@@ -7,67 +7,74 @@ In addition to common functionality that is implemented in the library
 itself, there are countless patterns that can be implemented by extending
 Click.  This page should give some insight into what can be accomplished.
 
+
 .. _aliases:
 
 Command Aliases
 ---------------
 
-Many tools support aliases for commands (see `Command alias example
-<https://github.com/pallets/click/tree/main/examples/aliases>`_).
-For instance, you can configure ``git`` to accept ``git ci`` as alias for
-``git commit``.  Other tools also support auto-discovery for aliases by
-automatically shortening them.
-
-Click does not support this out of the box, but it's very easy to customize
-the :class:`Group` or any other :class:`MultiCommand` to provide this
-functionality.
+Many tools support aliases for commands. For example, you can configure
+``git`` to accept ``git ci`` as alias for ``git commit``. Other tools also
+support auto-discovery for aliases by automatically shortening them.
 
-As explained in :ref:`custom-multi-commands`, a multi command can provide
-two methods: :meth:`~MultiCommand.list_commands` and
-:meth:`~MultiCommand.get_command`.  In this particular case, you only need
-to override the latter as you generally don't want to enumerate the
-aliases on the help page in order to avoid confusion.
+It's possible to customize :class:`Group` to provide this functionality. As
+explained in :ref:`custom-groups`, a group provides two methods:
+:meth:`~Group.list_commands` and :meth:`~Group.get_command`. In this particular
+case, you only need to override the latter as you generally don't want to
+enumerate the aliases on the help page in order to avoid confusion.
 
-This following example implements a subclass of :class:`Group` that
-accepts a prefix for a command.  If there were a command called ``push``,
-it would accept ``pus`` as an alias (so long as it was unique):
+The following example implements a subclass of :class:`Group` that accepts a
+prefix for a command. If there was a command called ``push``, it would accept
+``pus`` as an alias (so long as it was unique):
 
 .. click:example::
 
     class AliasedGroup(click.Group):
         def get_command(self, ctx, cmd_name):
-            rv = click.Group.get_command(self, ctx, cmd_name)
+            rv = super().get_command(ctx, cmd_name)
+
             if rv is not None:
                 return rv
-            matches = [x for x in self.list_commands(ctx)
-                       if x.startswith(cmd_name)]
+
+            matches = [
+                x for x in self.list_commands(ctx)
+                if x.startswith(cmd_name)
+            ]
+
             if not matches:
                 return None
-            elif len(matches) == 1:
+
+            if len(matches) == 1:
                 return click.Group.get_command(self, ctx, matches[0])
+
             ctx.fail(f"Too many matches: {', '.join(sorted(matches))}")
 
         def resolve_command(self, ctx, args):
             # always return the full command name
             _, cmd, args = super().resolve_command(ctx, args)
             return cmd.name, cmd, args
 
-And it can then be used like this:
+It can be used like this:
 
 .. click:example::
 
-    @click.command(cls=AliasedGroup)
+    @click.group(cls=AliasedGroup)
     def cli():
         pass
 
-    @cli.command()
+    @cli.command
     def push():
         pass
 
-    @cli.command()
+    @cli.command
     def pop():
         pass
 
+See the `alias example`_ in Click's repository for another example.
+
+.. _alias example: https://github.com/pallets/click/tree/main/examples/aliases
+
+
 Parameter Modifications
 -----------------------
 
@@ -266,7 +273,7 @@ triggering a parsing error.
 This can generally be activated in two different ways:
 
 1.  It can be enabled on custom :class:`Command` subclasses by changing
-    the :attr:`~BaseCommand.ignore_unknown_options` attribute.
+    the :attr:`~Command.ignore_unknown_options` attribute.
 2.  It can be enabled by changing the attribute of the same name on the
     context class (:attr:`Context.ignore_unknown_options`).  This is best
     changed through the ``context_settings`` dictionary on the command.
@@ -487,3 +494,8 @@ cleanup function.
             db.record_use()
             db.save()
             db.close()
+
+
+.. versionchanged:: 8.2 ``Context.call_on_close`` and context managers registered
+    via ``Context.with_resource`` will be closed when the CLI exits. These were
+    previously not called on exit.

docs/api.rst

@@ -113,6 +113,7 @@ Context
     :members:
     :member-order: bysource
 
+.. _click-api-types:
 
 Types
 -----
@@ -134,6 +135,7 @@ Types
 .. autoclass:: Path
 
 .. autoclass:: Choice
+   :members:
 
 .. autoclass:: IntRange