[b4] b4: support optional shell completion

Commit Message

Brandon Maier Oct. 9, 2024, 7:38 p.m. UTC

Shell completion support was added in commit 333189c by using a shell
script to generate the completion files with python-shtab. This script
can be run by distribution packagers to include shell completion.
However this does not support the use case of installing b4 with pip
from PyPi[1], because PyPi doesn't support distributing shell completion
scripts.

Many tools support this by having a command line flag that can generate
the completion scripts. In the original version of the shell completion
by Emil Velikov this was supported with `b4 --print-completion bash`,
but it was decided against to avoid bringing in more dependencies[2].

This restores Emil's work, but using a Python optional-dependency. This
way the base install for b4 is unchanged, but PyPi users that want shell
completion can install it with `pip install b4[completion]`.

[1] https://github.com/mricon/b4/issues/47
[2] https://lore.kernel.org/tools/20240305-obedient-centipede-of-finesse-a35a86@lemur/

Signed-off-by: Brandon Maier <[e-mail]>
---
 README.rst                      | 18 ++++++++++++++++++
 misc/requirements-completion.in |  1 +
 pyproject.toml                  |  3 +++
 src/b4/command.py               |  7 +++++++
 4 files changed, 29 insertions(+)


---
base-commit: 2a6338e451a0c1e81f214f48c820c1e52d76b2f1
change-id: 20241009-pypi-completion-83f2e22ff0d9

Best regards,

Patch

diff --git a/README.rst b/README.rst
index 20577e447b002b3837866bc8a007db95ef7ab301..b1db598dfa12115c226452ff5e086ac3c4662c37 100644
--- a/README.rst
+++ b/README.rst
@@ -20,6 +20,24 @@  Or to install the latest master (warning, maybe broken!)::
 
     python3 -m pip install git+https://git.kernel.org/pub/scm/utils/b4/b4.git@master
 
+Shell completion
+----------------
+b4 makes use of the python-shtab module to provide static shell completion
+files. Currently python-shtab supports bash, zsh and tcsh, where others may be
+added in the future.
+
+To install b4 with pip and shell completion use::
+
+    python3 -m pip install b4[completion]
+
+Shell completion is provided by the command ``b4 --print-completion
+{bash,zsh,tcsh}``. To enable shell completion run::
+
+    eval $(b4 --print-completion bash)
+
+To make it permanent on new shells, add that command to your ``$HOME/.bashrc``
+or ``$HOME/.zshrc``.
+
 Upgrading
 ---------
 If you previously installed from pypi::
diff --git a/misc/requirements-completion.in b/misc/requirements-completion.in
new file mode 100644
index 0000000000000000000000000000000000000000..a5993fffe28875b84c0480c83a850b496cdd10c1
--- /dev/null
+++ b/misc/requirements-completion.in
@@ -0,0 +1 @@ 
+shtab>=1.7
diff --git a/pyproject.toml b/pyproject.toml
index 31bfe3033650b2b251fcdcbab0456f4a67e914df..4914b0aa13b1ceab4a622c03c94587aac2441017 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -27,6 +27,9 @@  dynamic = ["dependencies", "optional-dependencies"]
 [tool.setuptools.dynamic]
 dependencies = { file = ["requirements.in"] }
 
+[tool.setuptools.dynamic.optional-dependencies]
+completion = { file = ["misc/requirements-completion.in"] }
+
 [tool.setuptools.packages.find]
 where = ['src']
 exclude = ['tests*']
diff --git a/src/b4/command.py b/src/b4/command.py
index 5d90b4f52b4f3bd84f8660c26fc005af98309c26..2bdd785d90004bc0be9c839fe50938dc9cbbe207 100644
--- a/src/b4/command.py
+++ b/src/b4/command.py
@@ -162,6 +162,13 @@  def setup_parser() -> argparse.ArgumentParser:
                         value to the empty string. Using NAME and omitting
                         =VALUE will set the value to "true".''')
 
+    try:
+        import shtab
+
+        shtab.add_argument_to(parser, ["--print-completion"])
+    except ImportError:
+        pass
+
     subparsers = parser.add_subparsers(help='sub-command help', dest='subcmd')
 
     # b4 mbox