Finish shell completion implementation

A whole lot of busywork:

- Poetry
- Tests
- Documentation
- Change log

Signed-off-by: Carmen Bianca BAKKER <carmenbianca@fsfe.org>

.github/workflows/test.yaml

@@ -37,7 +37,7 @@ jobs:
       - name: Install dependencies
         run: |
           pip install poetry~=1.3.0
-          poetry install --no-interaction --only main,test
+          poetry install --no-interaction --only main,test --all-extras
       - name: Run tests with pytest
         run: |
           poetry run pytest --cov=reuse
@@ -53,7 +53,6 @@ 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: |
@@ -87,7 +86,6 @@ 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: |

README.md

@@ -267,6 +267,16 @@ repos:
       - id: reuse-lint-file
 ```
 
+### Shell completion
+
+You can generate a shell completion script with `reuse --print-completion bash`.
+Replace 'bash' as needed. You must place the printed text in a file dictated by
+your shell to benefit from completions.
+
+This functionality depends on `shtab`, which is an optional dependency. To
+benefit from this feature, install reuse with the `completion` extra, like
+`pipx install reuse[completion]`.
+
 ## Maintainers
 
 - Carmen Bianca Bakker <carmenbianca@fsfe.org>

changelog.d/added/shtab.md

@@ -0,0 +1 @@
+- Added `--print-completion` using a new `shtab` optional dependency. (#1076)

docs/man/reuse.rst

@@ -80,9 +80,14 @@ Options
 
 .. 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.
+  Print a static shell completion script for the given shell and exit. You must
+  place the printed text in a file dictated by your shell before the completions
+  will function. For Bash, this file is
+  ``${XDG_DATA_HOME}/bash-completion/reuse``.
+
+  This option depends on ``shtab``, which is an optional dependency of
+  :program:`reuse`. The supported shells depend on your installed version of
+  ``shtab``.
 
 .. option:: -h, --help
 

pyproject.toml

@@ -60,6 +60,10 @@ license-expression = ">=1.0"
 python-debian = ">=0.1.34,!=0.1.45,!=0.1.46,!=0.1.47"
 tomlkit = ">=0.8"
 attrs = ">=21.3"
+shtab = { version = ">=1.4.0", optional = true }
+
+[tool.poetry.extras]
+completion = ["shtab"]
 
 [tool.poetry.group.test.dependencies]
 pytest = ">=6.0.0"

src/reuse/_main.py

@@ -10,12 +10,14 @@
 """Entry functions for reuse."""
 
 import argparse
+import contextlib
 import logging
 import os
 import sys
 import warnings
 from gettext import gettext as _
 from pathlib import Path
+from types import ModuleType
 from typing import IO, Callable, List, Optional, Type, cast
 
 from . import (
@@ -35,10 +37,9 @@
 from .project import GlobalLicensingConflict, GlobalLicensingFound, Project
 from .vcs import find_root
 
-try:
-    import shtab
-except ImportError:
-    shtab = None
+shtab: Optional[ModuleType] = None
+with contextlib.suppress(ImportError):
+    import shtab  # type: ignore[no-redef]
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -110,6 +111,7 @@ def parser() -> argparse.ArgumentParser:
         help=_("define root of project"),
     )
     if shtab:
+        # This is magic. Running `reuse -s bash` now prints bash completions.
         shtab.add_argument_to(parser, ["-s", "--print-completion"])
     parser.add_argument(
         "--version",

tests/test_main.py

@@ -29,7 +29,7 @@
 from freezegun import freeze_time
 
 from reuse import download
-from reuse._main import main
+from reuse._main import main, shtab
 from reuse._util import GIT_EXE, HG_EXE, JUJUTSU_EXE, PIJUL_EXE, cleandoc_nl
 from reuse.report import LINT_VERSION
 
@@ -88,6 +88,16 @@ def mock_put_license_in_file(monkeypatch):
     return result
 
 
+@pytest.mark.skipif(not shtab, reason="shtab required")
+def test_print_completion(capsys):
+    """shtab completions are printed."""
+    with pytest.raises(SystemExit) as error:
+        main(["--print-completion", "bash"])
+
+    assert error.value.code == 0
+    assert "AUTOMATICALLY GENERATED by `shtab`" in capsys.readouterr().out
+
+
 def test_lint(fake_repository, stringio, optional_git_exe, optional_hg_exe):
     """Run a successful lint. The optional VCSs are there to make sure that the
     test also works if these programs are not installed.