Add shell completion via python-shtab

Having a shell completion improves developers' workflow and makes it
easier for everyone to notice as the program gains new options.

This commit adds support for generatic static completion files via
python-shtab. Unlike other solutions which repeatedly invoke the
underlying program, to retrieve the next suggestion, shtab parses
argparse options and produces a complete static file.

It currently supports bash, tcsh and bash with PR opened for fish
support. For example, to generate zsh completion use:
 - reuse --print-completion zsh > /usr/share/zsh/site-functions/_reuse

This can be done by the reuse project itself, the package maintainer or
end-user.

For more details, see https://github.com/iterative/shtab

Closes: #629
Signed-off-by: Emil Velikov <emil.l.velikov@gmail.com>

.github/workflows/test.yaml

@@ -53,6 +53,7 @@ jobs:
       - name: Install dependencies
         run: |
           pip install poetry~=1.3.0
+          pip install shtab
           poetry install --no-interaction --only main,dev,test
       - name: Lint with Pylint
         run: |
@@ -86,6 +87,7 @@ jobs:
       - name: Install dependencies
         run: |
           pip install poetry~=1.3.0
+          pip install shtab
           poetry install --no-interaction --only main,dev,test
       - name: Test typing with mypy
         run: |

AUTHORS.rst

@@ -142,3 +142,4 @@ Contributors
 - Сергій <sergiy.goncharuk.1@gmail.com>
 - Mersho <code.rezaei@gmail.com>
 - Skyler Grey <sky@a.starrysky.fyi>
+- Emil Velikov <emil.l.velikov@gmail.com>

docs/man/reuse.rst

@@ -1,6 +1,7 @@
 ..
   SPDX-FileCopyrightText: 2019 Free Software Foundation Europe e.V. <https://fsfe.org>
   SPDX-FileCopyrightText: © 2020 Liferay, Inc. <https://liferay.com>
+  SPDX-FileCopyrightText: 2024 Emil Velikov <emil.l.velikov@gmail.com>
 
   SPDX-License-Identifier: CC-BY-SA-4.0
 
@@ -77,6 +78,12 @@ Options
   current working directory's VCS repository, or to the current working
   directory.
 
+.. option:: -s, --print-completion SHELL
+
+  Print a static shell completion file, for the given shell. This option depends
+  on python-shtab and as such defines which shells are supported. Presently this
+  includes bash, tcsh and zsh, with fish support being proposed.
+
 .. option:: -h, --help
 
   Display help and exit. If no command is provided, this option is implied.

src/reuse/_main.py

@@ -3,6 +3,7 @@
 # SPDX-FileCopyrightText: 2024 Carmen Bianca BAKKER <carmenbianca@fsfe.org>
 # SPDX-FileCopyrightText: © 2020 Liferay, Inc. <https://liferay.com>
 # SPDX-FileCopyrightText: 2024 Kerry McAdams <github@klmcadams>
+# SPDX-FileCopyrightText: 2024 Emil Velikov <emil.l.velikov@gmail.com>
 #
 # SPDX-License-Identifier: GPL-3.0-or-later
 
@@ -34,6 +35,11 @@
 from .project import GlobalLicensingConflict, GlobalLicensingFound, Project
 from .vcs import find_root
 
+try:
+    import shtab
+except ImportError:
+    shtab = None
+
 _LOGGER = logging.getLogger(__name__)
 
 _DESCRIPTION_LINES = [
@@ -103,6 +109,8 @@ def parser() -> argparse.ArgumentParser:
         type=PathType("r", force_directory=True),
         help=_("define root of project"),
     )
+    if shtab:
+        shtab.add_argument_to(parser, ["-s", "--print-completion"])
     parser.add_argument(
         "--version",
         action="store_true",