|Logo|

shtab

What: Automatically generate shell tab completion scripts for Python CLI apps
Why: Speed & correctness. Alternatives like argcomplete <https://pypi.org/project/argcomplete> and pyzshcomplete <https://pypi.org/project/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 <https://docs.python.org/library/argparse>_
- docopt <https://pypi.org/project/docopt> (via argopt <https://pypi.org/project/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})

.. contents:: Table of Contents :backlinks: top

Choose one of:

See operating system-specific instructions in the docs <https://docs.iterative.ai/shtab/#installation>_.

There are two ways of using shtab:

CLI Usage <https://docs.iterative.ai/shtab/use/#cli-usage>_: shtab's own CLI interface for external applications
- may not require any code modifications whatsoever
- end-users execute shtab your_cli_app.your_parser_object
Library Usage <https://docs.iterative.ai/shtab/use/#library-usage>_: as a library integrated into your CLI application
- adds a couple of lines to your application
- argument mode: end-users execute your_cli_app --print-completion {bash,zsh,tcsh}
- subparser mode: end-users execute your_cli_app completion {bash,zsh,tcsh}

See the docs for usage examples <https://docs.iterative.ai/shtab/use/#main.py>_.

Not working? Check out frequently asked questions <https://docs.iterative.ai/shtab/#faqs>_.

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

Please do open issues <https://github.com/iterative/shtab/issues> & pull requests <https://github.com/iterative/shtab/pulls>! Some ideas:

See CONTRIBUTING.md <https://github.com/iterative/shtab/tree/main/CONTRIBUTING.md>_ for more guidance.

|Hits|