Merge pull request #1084 from carmenbianca/click

Implement click, remove argparse

.github/workflows/gettext.yaml

@@ -25,6 +25,9 @@ jobs:
           token: ${{ secrets.FSFE_SYSTEM_TOKEN }}
       - name: Install gettext and wlc
         run: sudo apt-get install -y gettext wlc
+      # We mostly install reuse to install the click dependency.
+      - name: Install reuse
+        run: poetry install --no-interaction --only main
       - name: Lock Weblate
         run: |
           wlc --url https://hosted.weblate.org/api/ --key ${{secrets.WEBLATE_KEY }} lock fsfe/reuse-tool
@@ -34,7 +37,7 @@ jobs:
       - name: Pull Weblate translations
         run: git pull origin main
       - name: Create .pot file
-        run: make create-pot
+        run: poetry run make create-pot
       # Normally, POT-Creation-Date changes in two locations. Check if the diff
       # includes more than just those two lines.
       - name: Check if sufficient lines were changed

.gitignore

@@ -147,7 +147,6 @@ dmypy.json
 
 # End of https://www.gitignore.io/api/linux,python
 
-po/reuse.pot
 *.mo
 docs/api/
 docs/history.md

Makefile

@@ -67,8 +67,8 @@ dist: clean-build clean-pyc clean-docs ## builds source and wheel package
 .PHONY: create-pot
 create-pot:  ## generate .pot file
 	xgettext --add-comments --from-code=utf-8 --output=po/reuse.pot src/reuse/**.py
-	xgettext --add-comments --output=po/argparse.pot /usr/lib*/python3*/argparse.py
-	msgcat --output=po/reuse.pot po/reuse.pot po/argparse.pot
+	xgettext --add-comments --output=po/click.pot "${VIRTUAL_ENV}"/lib/python*/*-packages/click/**.py
+	msgcat --output=po/reuse.pot po/reuse.pot po/click.pot
 	for name in po/*.po; do \
 		msgmerge --output=$${name} $${name} po/reuse.pot; \
 	done

README.md

@@ -270,13 +270,18 @@ repos:
 
 ### 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.
+In order to enable shell completion, you need to generate the shell completion
+script. You do this with `_REUSE_COMPLETE=bash_source reuse`. Replace `bash`
+with `zsh` or `fish` as needed, or any other shells supported by the
+Python`click` library. You can then source the output in your shell rc file,
+like so (e.g.`~/.bashrc`):
 
-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]`.
+```bash
+eval "$(_REUSE__COMPLETE=bash_source reuse)"
+```
+
+Alternatively, you can place the generated completion script in
+`${XDG_DATA_HOME}/bash-completion/completions/reuse`.
 
 ## Maintainers
 

changelog.d/added/completion.md

@@ -0,0 +1 @@
+- Added shell completion via `click`. (#1084)

changelog.d/changed/click.md

@@ -0,0 +1,17 @@
+- Switched from `argparse` to `click` for handling the CLI. The CLI should still
+  handle the same, with identical options and arguments, but some stuff changed
+  under the hood. (#1084)
+
+  Find here a small list of differences:
+
+  - `-h` is no longer shorthand for `--help`.
+  - `--version` now outputs "reuse, version X.Y.Z", followed by a licensing
+    blurb on different paragraphs.
+  - Some options are made explicitly mutually exclusive, such as `annotate`'s
+    `--skip-unrecognised` and `--style`, and `download`'s `--output` and
+    `--all`.
+  - Subcommands which take a list of things (files, license) as arguments, such
+    as `annotate`, `lint-file`, or `download`, now also allow zero arguments.
+    This will do nothing, but can be useful in scripting.
+  - `annotate` and `lint-file` now also take directories as arguments. This will
+    do nothing, but can be useful in scripting.

docs/conf.py

@@ -62,7 +62,7 @@
 
 apidoc_module_dir = str(ROOT_DIR / "src/reuse")
 # apidoc_output_dir = "api"
-# apidoc_excluded_paths = []
+apidoc_excluded_paths = ["cli"]
 apidoc_separate_modules = True
 apidoc_toc_file = False
 apidoc_extra_args = ["--maxdepth", "2"]

docs/man/reuse-annotate.rst

@@ -46,22 +46,22 @@ Mandatory options
 -----------------
 
 At least *one* among the following options is required. They contain the
-information which the tool will add to the file(s).
+information which the tool will add to the file(s). You can repeat these
+options.
 
 .. option:: -c, --copyright COPYRIGHT
 
   A copyright holder. This does not contain the year or the copyright prefix.
   See :option:`--year` and :option:`--copyright-prefix` for the year and prefix.
-  This option can be repeated.
 
 .. option:: -l, --license LICENSE
 
-  An SPDX license identifier. This option can be repeated.
+  An SPDX license identifier.
 
 .. option:: --contributor CONTRIBUTOR
 
   A name of a contributor. The contributor will be added via the
-  ``SPDX-FileContributor:`` tag. This option can be repeated.
+  ``SPDX-FileContributor:`` tag.
 
 Other options
 -------------
@@ -143,7 +143,7 @@ Other options
   Instead of aborting when a file extension does not have an associated comment
   style, skip those files.
 
-.. option:: -h, --help
+.. option:: --help
 
   Display help and exit.
 

docs/man/reuse-convert-dep5.rst

@@ -21,7 +21,7 @@ functionally equivalent ``REUSE.toml`` file in the root of the project. The
 Options
 -------
 
-.. option:: -h, --help
+.. option:: --help
 
   Display help and exit.
 

docs/man/reuse-download.rst

@@ -36,11 +36,11 @@ Options
   If downloading a single file, output it to a specific file instead of putting
   it in a detected ``LICENSES/`` directory.
 
-.. option:: --source SOURCE
+.. option:: --source PATH
 
   Specify a source from which to copy custom ``LicenseRef-`` files. This can be
   a directory containing such file, or a path to the file itself.
 
-.. option:: -h, --help
+.. option:: --help
 
   Display help and exit.

docs/man/reuse-lint-file.rst

@@ -45,6 +45,6 @@ Options
   Output one line per error, prefixed by the file path. This option is the
   default.
 
-.. option:: -h, --help
+.. option:: --help
 
   Display help and exit.

docs/man/reuse-lint.rst

@@ -97,6 +97,6 @@ Options
 
   Output one line per error, prefixed by the file path.
 
-.. option:: -h, --help
+.. option:: --help
 
   Display help and exit.

docs/man/reuse-spdx.rst

@@ -41,6 +41,6 @@ Options
 
   Name of the creator (organization) of the bill of materials.
 
-.. option:: -h, --help
+.. option:: --help
 
   Display help and exit.

docs/man/reuse-supported-licenses.rst

@@ -25,6 +25,6 @@ full name of the license, and an URL to the license.
 Options
 -------
 
-.. option:: -h, --help
+.. option:: --help
 
   Display help and exit.

docs/man/reuse.rst

@@ -78,18 +78,7 @@ 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
+.. option::  --help
 
   Display help and exit. If no command is provided, this option is implied.
 
@@ -112,6 +101,9 @@ Commands
 :manpage:`reuse-lint(1)`
   Verify whether a project is compliant with the REUSE Specification.
 
+:manpage:`reuse-lint-file(1)`
+  Verify whether individual files are compliant with the REUSE Specification.
+
 :manpage:`reuse-spdx(1)`
   Generate SPDX bill of materials.
 

pyproject.toml

@@ -62,10 +62,7 @@ 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"]
+click = ">=8.0"
 
 [tool.poetry.group.test.dependencies]
 pytest = ">=6.0.0"
@@ -98,7 +95,7 @@ pyls-isort = "*"
 python-lsp-black = "*"
 
 [tool.poetry.scripts]
-reuse = 'reuse._main:main'
+reuse = "reuse.cli.main:main"
 
 [tool.poetry.build]
 generate-setup-file = false

src/reuse/__main__.py

@@ -4,9 +4,8 @@
 
 """Entry module for reuse."""
 
-import sys
-
 if __name__ == "__main__":
-    from ._main import main
+    from .cli.main import main
 
-    sys.exit(main())
+    # pylint: disable=no-value-for-parameter
+    main()