b4: add shell completion via python-shtab

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

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

---
 README.rst        | 14 ++++++++++++++
 src/b4/command.py |  7 +++++++
 2 files changed, 21 insertions(+)

index 20577e4..bd3d00b 100644
@@ -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 [email protected],

index be0f033..10cb4d0 100644
@@ -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 <[email protected]>

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

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

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

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.

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.

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.

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

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

-Emil