index.md

• 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
  • bash
  • zsh
  • tcsh
• Supports
  • argparse
  • docopt (via argopt)
• Supports arguments, options and subparsers
• Supports choices (e.g. --say={hello,goodbye})
• Supports file and directory path completion
• Supports custom path completion (e.g. --file={*.txt})

---

Installation

=== "pip"

```sh
pip install shtab
```

=== "conda"

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

=== "Ubuntu/Debian"

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`:

```sh
# 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
```

=== "MacOS"

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

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

FAQs

Not working?

• Make sure that shtab and the application you're trying to complete are both accessible from your environment.
• Make sure that prog is set:
  • if using options.entry_points.console_scripts=MY_PROG=..., then ensure the main parser's prog matches argparse.ArgumentParser(prog="MY_PROG") 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 argparse.ArgumentParser(prog="MY_PROG.py") or override it using shtab MY_PROG.get_main_parser --prog=MY_PROG.py.
• Make sure that all arguments have help messages (parser.add_argument('positional', help="documented; i.e. not hidden")).
• Ask a general question on StackOverflow.
• Report bugs and open feature requests on GitHub.

"Eager" installation (completions are re-generated upon login/terminal start) is recommended. Naturally, shtab and the CLI application to complete should be accessible/importable from the login environment. If installing shtab in a different virtual environment, you'd have to add a line somewhere appropriate (e.g. $CONDA_PREFIX/etc/conda/activate.d/env_vars.sh).

By default, shtab will silently do nothing if it cannot import the requested application. Use -u, --error-unimportable to noisily complain.

Alternatives

• argcomplete
  • executes the underlying script every time <TAB> is pressed (slow and has side-effects)
• pyzshcomplete
  • executes the underlying script every time <TAB> is pressed (slow and has side-effects)
  • only provides zsh completion
• click
  • different framework completely replacing the builtin argparse
  • solves multiple problems (rather than POSIX-style "do one thing well")

Contributions

Please do open issues & pull requests! Some ideas:

• support fish (#174)
• support powershell

See CONTRIBUTING.md for more guidance.