Skip to content

Home

shtab

Tests Coverage Quality PyPI Conda Downloads LICENCE

  • What: Automatically generate shell tab completion scripts for Python CLI apps
  • Why: Speed & correctness. Alternatives like argcomplete and pyzshcomplete are slow and have side-effects
  • How: shtab processes an argparse.ArgumentParser object to generate a tab completion script for your shell

Features#

  • Outputs tab completion scripts for multiple shells
    • bash, zsh, fish, tcsh, powershell
  • Supports
  • <arguments>, --options and sub commands
  • Choices (--say={hello,goodbye})
  • Paths (--file={*.y*ml,*.toml}, --dir=*/)
  • Dynamic shell commands (--branch=$(git branch))

Installation#

scripts#

Tip

TL;DR where to save a completion script for a program called NAME

shell location
bash /etc/bash_completion.d/NAME
zsh /usr/local/share/zsh/site-functions/_NAME
tcsh /etc/profile.d/completion_NAME.csh, source in ~/.cshrc or ~/.tcshrc
fish ~/.config/fish/completions/NAME.fish
powershell ~\.config\powershell\completions\NAME.ps1, source in $PROFILE

For more information, click on the shells above, and/or see CLI Usage.

shtab#

pip install shtab

conda install -c conda-forge shtab

bash users who have never used any kind of tab completion before should also follow the OS-specific instructions below.

Recent versions should have completion already enabled. For older versions, first run sudo apt install --reinstall bash-completion, then make sure these lines appear in ~/.bashrc:

# enable bash completion in interactive shells
if ! shopt -oq posix; then
  if [ -f /usr/share/bash-completion/bash_completion ]; then
    . /usr/share/bash-completion/bash_completion
  elif [ -f /etc/bash_completion ]; then
    . /etc/bash_completion
  fi
fi

First run brew install bash-completion, then add the following to ~/.bash_profile:

if [ -f $(brew --prefix)/etc/bash_completion ]; then
  . $(brew --prefix)/etc/bash_completion
fi

FAQs#

  • Ensure that shtab and the application you're trying to complete are both accessible from your environment.
  • Ensure that prog matches the executable name:
    • if using project.scripts.MY-PROG=..., then
      • set the main parser's name (argparse.ArgumentParser(prog="MY-PROG"), argopt(prog="MY-PROG"), click.group("MY-PROG"), click.command("MY-PROG"), etc)
      • or override it using shtab MY_PROG.get_main_parser --prog=MY-PROG
    • if executing a script file ./MY_PROG.py (with a shebang #!/usr/bin/env python) directly, then use prog="MY_PROG.py"
  • Any suppressed argument (help=argparse.SUPPRESS, click hidden=True/deprecated=True) is skipped.
  • Default completion (when no choices are specified) is disabled. Enable it explicitly via e.g. parser.add_argument('positional').complete = shtab.FILE.
  • Some shells (e.g. zsh, fish) print information during tab completion:
    • subparser description takes precedence over help
    • argument metavar takes precedence over dest
  • Ask a general question on StackOverflow.
  • Report bugs and open feature requests on GitHub.

Alternatives#

All these execute the underlying script every time <TAB> is pressed (slow and have side-effects):

Contributions#

Please do open issues & pull requests!

See CONTRIBUTING.md for more guidance.

git-fame

Hits