Merge pull request #1076 from evelikov/shell-completion

Add shell completion support

.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

AUTHORS.rst

@@ -142,3 +142,4 @@ Contributors
 - Сергій <[email protected]>
 - Mersho <[email protected]>
 - Skyler Grey <[email protected]>
+- Emil Velikov <[email protected]>

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

changelog.d/added/shtab.md

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

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,17 @@ Options
   current working directory's VCS repository, or to the current working
   directory.
 
+.. option:: -s, --print-completion SHELL
+
+  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
 
   Display help and exit. If no command is provided, this option is implied.

pyproject.toml

@@ -62,6 +62,10 @@ python-debian = ">=0.1.34,!=0.1.45,!=0.1.46,!=0.1.47"
 # Python 3.10.
 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

@@ -3,18 +3,21 @@
 # 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
 
 """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, Optional, Type, cast
 
 from . import (
@@ -34,6 +37,10 @@
 from .project import GlobalLicensingConflict, Project
 from .vcs import find_root
 
+shtab: Optional[ModuleType] = None
+with contextlib.suppress(ImportError):
+    import shtab  # type: ignore[no-redef,import-not-found]
+
 _LOGGER = logging.getLogger(__name__)
 
 _DESCRIPTION_LINES = [
@@ -103,6 +110,9 @@ def parser() -> argparse.ArgumentParser:
         type=PathType("r", force_directory=True),
         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",
         action="store_true",

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.