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 <[email protected]>

.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

@@ -39,6 +39,7 @@ Contributors
 - Dimitris Apostolou <[email protected]>
 - Dirk Brömmel <[email protected]>
 - Dmitry Bogatov <[email protected]>
+- Emil Velikov <[email protected]>
 - Ethan Kerrick <[email protected]>
 - FeRD (Frank Dana) <[email protected]>
 - FestplattenSchnitzel <[email protected]>

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 <[email protected]>
 
   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 <[email protected]>
 # SPDX-FileCopyrightText: © 2020 Liferay, Inc. <https://liferay.com>
 # SPDX-FileCopyrightText: 2024 Kerry McAdams <github@klmcadams>
+# SPDX-FileCopyrightText: 2024 Emil Velikov <[email protected]>
 #
 # SPDX-License-Identifier: GPL-3.0-or-later
 
@@ -103,6 +104,12 @@ def parser() -> argparse.ArgumentParser:
         type=PathType("r", force_directory=True),
         help=_("define root of project"),
     )
+    try:
+        import shtab
+
+        shtab.add_argument_to(parser, ["-s", "--print-completion"])
+    except ImportError:
+        pass
     parser.add_argument(
         "--version",
         action="store_true",