[PATCH b4 v2] b4: add shell completion via python-shtab

[PATCH b4 v2] b4: add shell completion via python-shtab

[Emil Velikov via B4 Relay]

From: Emil Velikov <emil.l.velikov@gmail.com>

The python-shtab module allows for static shell completion files,
whereas others like python-argcomplete, execute the underlying tool for
ever suggestion.

Static completion files are a cleaner solution and also faster to
execute. So we're going with them.

Currently python-shtab supports bash, zsh and tcsh - maintainer is open
to patches supporting fish.

Although currently there is no completion action, although that's rather
rare with b4 so we can live without out.

My completion action, we're talking about the automatic hints such as
folders (for example with `b4 sen -o some-folder/`) and alike.

To generate/install the zsh completion use:
 - ./b4.sh --print-completion zsh > _b4
 - mv _b4 /usr/share/zsh/site-functions/_b4

For more details, see the website https://github.com/iterative/shtab

Signed-off-by: Emil Velikov <emil.l.velikov@gmail.com>
---
Having a shell completion is cool way to ramp-up and improve your
workflow with any tool.

Initially I started off writing zsh completion by hand, although the
100+ options quickly made me reconsider my life choices :-D

Shortly afterwards, I found python-shtab which seems to work just fine.
Since it's effectively a zero maintenance I opted for that, instead of
completing the hand-written ones.

Both zsh and bash completions work fine in my testing, although YMMV.

Ideally, distro maintainers will generate those as part of the
packaging. Although if b4 devs prefer having those in-tree that's also
doable.

Happy to do so, of course - let me know either way.

Changes in v2:
- Fix typos and broken grammar
- Document in the README
- Link to v1: https://msgid.link/20240227-shell-completion-v1-1-a809aad38589@gmail.com
---
 README.rst        | 14 ++++++++++++++
 src/b4/command.py |  7 +++++++
 2 files changed, 21 insertions(+)

diff --git a/README.rst b/README.rst
index 20577e4..bd3d00b 100644
--- a/README.rst
+++ b/README.rst
@@ -44,6 +44,20 @@ following commands after the initial clone::
     git submodule update --init
     python3 -m pip install -r requirements.txt
 
+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 generate a completion file, install python-shtab and execute::
+
+    ./b4.sh --print-completion zsh > _b4
+    mv _b4 /usr/share/zsh/site-functions/_b4
+
+You may need to adjust the path and filename, depending on your distribution
+setup and shell used.
+
 Support
 -------
 For support or with any other questions, please email tools@kernel.org,
diff --git a/src/b4/command.py b/src/b4/command.py
index be0f033..10cb4d0 100644
--- a/src/b4/command.py
+++ b/src/b4/command.py
@@ -363,6 +363,13 @@ def setup_parser() -> argparse.ArgumentParser:
                           help='Submit the token received via verification email')
     sp_send.set_defaults(func=cmd_send)
 
+    try:
+        import shtab
+
+        shtab.add_argument_to(parser, ["-s", "--print-completion"])
+    except ImportError:
+        pass
+
     return parser
 
 

---
base-commit: 7f3284906e67f138eae82271a6c3bde1ebb30791
change-id: 20240227-shell-completion-060a610f5b20

Best regards,
-- 
Emil Velikov <emil.l.velikov@gmail.com>

Re: [PATCH b4 v2] b4: add shell completion via python-shtab

[Konstantin Ryabitsev]

On Fri, Mar 01, 2024 at 04:59:23PM +0000, Emil Velikov via B4 Relay wrote:
> From: Emil Velikov <emil.l.velikov@gmail.com>
> 
> The python-shtab module allows for static shell completion files,
> whereas others like python-argcomplete, execute the underlying tool for
> ever suggestion.

Thank you for the series! I hope to look at it very soon -- I just need to
wrap my head around the underlying concept.

Cheers,
-K

Re: [PATCH b4 v2] b4: add shell completion via python-shtab

[Konstantin Ryabitsev]

On Fri, Mar 01, 2024 at 04:59:23PM +0000, Emil Velikov via B4 Relay wrote:
> For more details, see the website https://github.com/iterative/shtab

Thank you for pointing me in that direction. I think I'd rather use their CLI
integration, what do you think? E.g. we can have misc/tc-generate.sh with the
following contents:

    #!/usr/bin/env bash
    if [[ -z $1 ]]; then
        echo "Specify the shell type as parameter (bash, zsh, tcsh)"
        exit 1
    fi
    if which shtab >/dev/null 2>&1; then
        PYTHONPATH="src${PYTHONPATH:+:$PYTHONPATH}" \
            exec shtab --shell=$1 -u b4.command.setup_parser
    fi

I believe running ./misc/tc-generate.sh from the toplevel dir should
get us the exact same result as your patch below, no?

My preference would be to go this route, because it doesn't create a new
dependency on shtab but still lets packagers generate and ship the
tab-completion content.

-K

Re: [PATCH b4 v2] b4: add shell completion via python-shtab

[Emil Velikov]

On Tue, 5 Mar 2024 at 20:53, Konstantin Ryabitsev
<konstantin@linuxfoundation.org> wrote:
>
> On Fri, Mar 01, 2024 at 04:59:23PM +0000, Emil Velikov via B4 Relay wrote:
> > For more details, see the website https://github.com/iterative/shtab
>
> Thank you for pointing me in that direction. I think I'd rather use their CLI
> integration, what do you think? E.g. we can have misc/tc-generate.sh with the
> following contents:
>
>     #!/usr/bin/env bash
>     if [[ -z $1 ]]; then
>         echo "Specify the shell type as parameter (bash, zsh, tcsh)"
>         exit 1
>     fi
>     if which shtab >/dev/null 2>&1; then
>         PYTHONPATH="src${PYTHONPATH:+:$PYTHONPATH}" \
>             exec shtab --shell=$1 -u b4.command.setup_parser
>     fi
>
> I believe running ./misc/tc-generate.sh from the toplevel dir should
> get us the exact same result as your patch below, no?
>
> My preference would be to go this route, because it doesn't create a new
> dependency on shtab but still lets packagers generate and ship the
> tab-completion content.
>

The above solution can break in a number of cases and since there's no
CI, it can lurk broken for a while.
- path changes from src/b4/ to ...
- parser function is moved from command.py, or command.py itself is renamed
- parser function is renamed

Does that seem like a reasonable argument, or do you prefer the
standalone script approach?

Thanks
Emil

Re: [PATCH b4 v2] b4: add shell completion via python-shtab

[Konstantin Ryabitsev]

On Wed, Mar 06, 2024 at 12:03:31PM +0000, Emil Velikov wrote:
> > My preference would be to go this route, because it doesn't create a new
> > dependency on shtab but still lets packagers generate and ship the
> > tab-completion content.
> >
> 
> The above solution can break in a number of cases and since there's no
> CI, it can lurk broken for a while.

Yes, but the same is true for any number of other things. Since this is an
auxiliary feature, it's not really critical in my view.

> - path changes from src/b4/ to ...

I doubt this will change again -- I just did this as a large breaking feature
to make pyproject.toml look less insane and I don't expect to do this again.

> - parser function is moved from command.py, or command.py itself is renamed
> - parser function is renamed

These are possible, of course, but I doubt they are likely to happen. Even if
it does, since it's an auxiliary feature, I don't really worry too much about
introducing this regression.

> Does that seem like a reasonable argument, or do you prefer the
> standalone script approach?

I still prefer to go with the CLI solution. I'm going to commit the script to
misc (giving you proper attribution) and we'll try it out.

-K

Re: [PATCH b4 v2] b4: add shell completion via python-shtab

[Emil Velikov]

On Wed, 6 Mar 2024 at 19:35, Konstantin Ryabitsev
<konstantin@linuxfoundation.org> wrote:
>
> On Wed, Mar 06, 2024 at 12:03:31PM +0000, Emil Velikov wrote:
> > > My preference would be to go this route, because it doesn't create a new
> > > dependency on shtab but still lets packagers generate and ship the
> > > tab-completion content.
> > >
> >
> > The above solution can break in a number of cases and since there's no
> > CI, it can lurk broken for a while.
>
> Yes, but the same is true for any number of other things. Since this is an
> auxiliary feature, it's not really critical in my view.
>
> > - path changes from src/b4/ to ...
>
> I doubt this will change again -- I just did this as a large breaking feature
> to make pyproject.toml look less insane and I don't expect to do this again.
>
> > - parser function is moved from command.py, or command.py itself is renamed
> > - parser function is renamed
>
> These are possible, of course, but I doubt they are likely to happen. Even if
> it does, since it's an auxiliary feature, I don't really worry too much about
> introducing this regression.
>
> > Does that seem like a reasonable argument, or do you prefer the
> > standalone script approach?
>
> I still prefer to go with the CLI solution. I'm going to commit the script to
> misc (giving you proper attribution) and we'll try it out.
>

Ack, thanks for the patience and for landing upstream o/

-Emil