Merge branch 'main' into split-help-extra-generation

.github/workflows/publish.yaml

@@ -10,7 +10,7 @@ jobs:
       hash: ${{ steps.hash.outputs.hash }}
     steps:
       - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9
-      - uses: actions/setup-python@bd6b4b6205c4dbad673328db7b31b7fab9e241c0
+      - uses: actions/setup-python@61a6322f88396a6271a6ee3565807d608ecaddd1
         with:
           python-version: '3.x'
           cache: 'pip'
@@ -62,10 +62,10 @@ jobs:
       id-token: write
     steps:
       - uses: actions/download-artifact@9bc31d5ccc31df68ecc42ccf4149144866c47d8a
-      - uses: pypa/gh-action-pypi-publish@f5622bde02b04381239da3573277701ceca8f6a0
+      - uses: pypa/gh-action-pypi-publish@f8c70e705ffc13c3b4d1221169b84f12a75d6ca8
         with:
           repository_url: https://test.pypi.org/legacy/
           packages_dir: artifact/
-      - uses: pypa/gh-action-pypi-publish@f5622bde02b04381239da3573277701ceca8f6a0
+      - uses: pypa/gh-action-pypi-publish@f8c70e705ffc13c3b4d1221169b84f12a75d6ca8
         with:
           packages-dir: artifact/

.github/workflows/tests.yaml

@@ -31,12 +31,11 @@ jobs:
           - {name: '3.10', python: '3.10', os: ubuntu-latest, tox: py310}
           - {name: '3.9', python: '3.9', os: ubuntu-latest, tox: py39}
           - {name: '3.8', python: '3.8', os: ubuntu-latest, tox: py38}
-          - {name: '3.7', python: '3.7', os: ubuntu-latest, tox: py37}
           - {name: 'PyPy', python: 'pypy-3.10', os: ubuntu-latest, tox: pypy310}
           - {name: Typing, python: '3.11', os: ubuntu-latest, tox: typing}
     steps:
       - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9
-      - uses: actions/setup-python@bd6b4b6205c4dbad673328db7b31b7fab9e241c0
+      - uses: actions/setup-python@61a6322f88396a6271a6ee3565807d608ecaddd1
         with:
           python-version: ${{ matrix.python }}
           cache: 'pip'

.pre-commit-config.yaml

@@ -3,21 +3,21 @@ ci:
   autoupdate_schedule: monthly
 repos:
   - repo: https://github.com/asottile/pyupgrade
-    rev: v3.8.0
+    rev: v3.10.1
     hooks:
       - id: pyupgrade
-        args: ["--py37-plus"]
+        args: ["--py38-plus"]
   - repo: https://github.com/asottile/reorder-python-imports
     rev: v3.10.0
     hooks:
       - id: reorder-python-imports
         args: ["--application-directories", "src"]
   - repo: https://github.com/psf/black
-    rev: 23.3.0
+    rev: 23.7.0
     hooks:
       - id: black
   - repo: https://github.com/PyCQA/flake8
-    rev: 6.0.0
+    rev: 6.1.0
     hooks:
       - id: flake8
         additional_dependencies:

CHANGES.rst

@@ -5,14 +5,61 @@ 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:`326`
 -   Use ``flit_core`` instead of ``setuptools`` as build backend.
+-   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`
 -   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`
 
 
+Version 8.1.7
+-------------
+
+Released 2023-08-17
+
+-   Fix issue with regex flags in shell completion. :issue:`2581`
+-   Bash version detection issues a warning instead of an error. :issue:`2574`
+-   Fix issue with completion script for Fish shell. :issue:`2567`
+
+
+Version 8.1.6
+-------------
+
+Released 2023-07-18
+
+-   Fix an issue with type hints for ``@click.group()``. :issue:`2558`
+
+
+Version 8.1.5
+-------------
+
+Released 2023-07-13
+
+-   Fix an issue with type hints for ``@click.command()``, ``@click.option()``, and
+    other decorators. Introduce typing tests. :issue:`2558`
+
+
 Version 8.1.4
 -------------
 
@@ -910,12 +957,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.
 

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.