[PATCH b4] b4: support optional shell completion

[PATCH b4] b4: support optional shell completion

[Brandon Maier]

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 <brandon.maier@collins.com>
---
 README.rst                      | 18 ++++++++++++++++++
 misc/requirements-completion.in |  1 +
 pyproject.toml                  |  3 +++
 src/b4/command.py               |  7 +++++++
 4 files changed, 29 insertions(+)

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

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

Best regards,
-- 
Brandon Maier <brandon.maier@collins.com>

Re: [PATCH b4] b4: support optional shell completion

[cdwhite3]

[-- Attachment #1: Type: text/plain, Size: 1188 bytes --]

> 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].

I would recommend using a `completion` command instead of
`--print-completion` to generate the completion scripts. E.g., 

    b4 completion bash

This is a more common pattern and is used by many other tools.

> +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``.

While this works, the more common pattern is to echo the output to a
completion directory which is auto sourced, for example (bash):

For global installation:
    b4 completion bash > /etc/bash_completion.d/b4

For user installation:
    mkdir -p ~/.local/share/bash-completion/completions
    b4 completion bash > ~/.local/share/bash-completion/completions/b4

Best,


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 509 bytes --]

Re: [PATCH b4] b4: support optional shell completion

[Emil Velikov]

On Thu, 10 Oct 2024 at 18:12, <cdwhite3@pm.me> wrote:
>
> > 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].
>
> I would recommend using a `completion` command instead of
> `--print-completion` to generate the completion scripts. E.g.,
>
>     b4 completion bash
>
> This is a more common pattern and is used by many other tools.
>
> > +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``.
>
> While this works, the more common pattern is to echo the output to a
> completion directory which is auto sourced, for example (bash):
>
> For global installation:
>     b4 completion bash > /etc/bash_completion.d/b4
>
> For user installation:
>     mkdir -p ~/.local/share/bash-completion/completions
>     b4 completion bash > ~/.local/share/bash-completion/completions/b4
>

^^ please, or the equivalent I had in the original patch. Better yet,
if anyone has a nice reference to explain these kinds of things, just
use that.

Mind you, I never fully understood what the dependency concern was,
considering it was optional since day one.
Then again, it was never a hill to die on. Plus b4 is an awesome tool
- thanks again Konstantin.

HTH
Emil

Re: [PATCH b4] b4: support optional shell completion

[Brandon Maier]

Hi Emil, Caleb,

On Fri Oct 11, 2024 at 4:39 PM UTC, Emil Velikov wrote:
> On Thu, 10 Oct 2024 at 18:12, <cdwhite3@pm.me> wrote:
> >
> > > 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].
> >
> > I would recommend using a `completion` command instead of
> > `--print-completion` to generate the completion scripts. E.g.,
> >
> >     b4 completion bash
> >
> > This is a more common pattern and is used by many other tools.
> >
> > > +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``.
> >
> > While this works, the more common pattern is to echo the output to a
> > completion directory which is auto sourced, for example (bash):
> >
> > For global installation:
> >     b4 completion bash > /etc/bash_completion.d/b4
> >
> > For user installation:
> >     mkdir -p ~/.local/share/bash-completion/completions
> >     b4 completion bash > ~/.local/share/bash-completion/completions/b4
> >
>
> ^^ please, or the equivalent I had in the original patch. Better yet,
> if anyone has a nice reference to explain these kinds of things, just
> use that.

I haven't seen any good reference docs for this design pattern. All the
tools I've run across document this manually using either the `eval` or
bash-completion methods. Same with arguments, `b4 --completion` or `b4
completion`.

The shtab project also doesn't have any opinions and supports both
approaches for arguments.
https://github.com/iterative/shtab

I have no strong preferences either way, I can resubmit with these
changes.

>
> Mind you, I never fully understood what the dependency concern was,
> considering it was optional since day one.
> Then again, it was never a hill to die on. Plus b4 is an awesome tool
> - thanks again Konstantin.

Agreed, b4 makes managing patch-based workflows much easier!

Thanks,
Brandon

>
> HTH
> Emil

Re: [PATCH b4] b4: support optional shell completion

[Caleb White]

On Fri Oct 11, 2024 at 12:00 PM CDT, Brandon Maier wrote:
> Hi Emil, Caleb,
>
> On Fri Oct 11, 2024 at 4:39 PM UTC, Emil Velikov wrote:
>> On Thu, 10 Oct 2024 at 18:12, <cdwhite3@pm.me> wrote:
>> > I would recommend using a `completion` command instead of
>> > `--print-completion` to generate the completion scripts. E.g.,
>> >
>> >     b4 completion bash
>> >
>> > This is a more common pattern and is used by many other tools.
>> >
>> > > +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``.
>> >
>> > While this works, the more common pattern is to echo the output to a
>> > completion directory which is auto sourced, for example (bash):
>> >
>> > For global installation:
>> >     b4 completion bash > /etc/bash_completion.d/b4
>> >
>> > For user installation:
>> >     mkdir -p ~/.local/share/bash-completion/completions
>> >     b4 completion bash > ~/.local/share/bash-completion/completions/b4
>> >
>
> I haven't seen any good reference docs for this design pattern. All the
> tools I've run across document this manually using either the `eval` or
> bash-completion methods. Same with arguments, `b4 --completion` or `b4
> completion`.
>
> The shtab project also doesn't have any opinions and supports both
> approaches for arguments.
> https://github.com/iterative/shtab
>
> I have no strong preferences either way, I can resubmit with these
> changes.

Some programs that follow the `<program> completion` pattern are:
pip, kubectl, helm, composer, npm, himalaya (Rust email client),
the GitHub `gh` CLI, etc. Ultimately, it's up to you and it and it's not
the biggest thing either way, but this is the first thing I look for
when I'm trying to figure out how to get completion for a new tool.

Usually, installation docs will show both the eval and the completion
directory methods. The completion directory method allows for lazy
loading of completions, which can speed up shell startup time, but
it could just depend on your shell.

Best,

Re: [PATCH b4] b4: support optional shell completion

[Konstantin Ryabitsev]

On Wed, 09 Oct 2024 19:38:58 +0000, Brandon Maier wrote:
> 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.
> 
> [...]

Applied, thanks!

[1/1] b4: support optional shell completion
      commit: 13d5dc723d93d783c67932c61e12bbcd56598179

Best regards,
-- 
Konstantin Ryabitsev <konstantin@linuxfoundation.org>