CLI tab-complete
Meltano uses the Python package Click for its CLI, which provides tab-complete/autocomplete as described here: https://click.palletsprojects.com/en/7.x/bashcomplete/
In particular, completion is provided for bash, zsh, and fish.
First, generate the shell-specific meltano-complete
script (using bash as an example):
_MELTANO_COMPLETE=source_bash meltano > meltano-complete.sh
This script can be generated by us in CI, and included in the Meltano wheels or sdist. When Meltano is run, it should check if the completions have been installed by verifying that the completions file exists in the installation location. If they have not been installed, then it should install them (see below).
Installing shell completions
fish
The Meltano completion script should be placed in ~/.config/fish/completions/
. From there it will be sourced automatically when a fish shell starts.
bash
The situation around per-user tab-completion in bash is a bit messier. There are standard locations to add completion scripts for system-wide packages (installed as root), but we cannot use those without root permissions. The bash-completion faq has this to say:
Q. Where should I install my own local completions?
A. Put them in the
completions
subdir of$BASH_COMPLETION_USER_DIR
(defaults to$XDG_DATA_HOME/bash-completion
or~/.local/share/bash-completion
if$XDG_DATA_HOME
is not set) to have them loaded automatically on demand when the respective command is being completed. See also the next question's answer for considerations for these files' names, they apply here as well. Alternatively, you can write them directly in~/.bash_completion
which is loaded eagerly by our main script.
$BASH_COMPLETION_USER_DIR
may not be defined. $XDG_DATA_HOME
may also not be defined. The directory ~/.local/share/bash-completion
may not exist. I have confirmed that the following two commands results in the shell providing completions for the meltano
command:
mkdir -p ${BASH_COMPLETION_USER_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion}/completions
mv meltano-complete.sh ${BASH_COMPLETION_USER_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/bash-completion}/completions/meltano
Now we more-or-less just need to translate the above two commands into Python.
zsh
I'm not yet sure how to handle this for zsh. We may have to put the file into /usr/local/share/zsh-completions
, or some other directory listed in $fpath
. I do have zsh available, but I do not have macOS running on any of my devices, so testing zsh completions in a realistic manner is a bit tricky. For instance, the default permissions of /usr/local/share/zsh-completions
will be important for how we decide to handle this.
Upgrading shell completions
The shell completions provided by Click are dynamic, which is to say switching to different versions of Meltano requires no changes to the installed completions. As an example, if a new (sub-)command or flag is added, it'll automatically be picked up by the tab-completer.
This has obvious advantages, but is noticeably slow, and we may want to change how the completions work in the future e.g. if we switch from Click to something else.
To support changing how the completion script works, we can make it so that the installed completion script is a thin wrapper that locates the currently activate meltano
installation (i.e. where the wheel was installed into), then sources a completion script from that location. Like that, one could upgrade Meltano, or switch virtual environments, and get all-new tab-completions.