brentyi / shtab

↔️ Automagic shell tab completion for Python CLI applications

shtab

• 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})

---

Table of Contents

• shtab
  • Features
  • Installation
  • Usage
  • Examples
  • FAQs
  • Alternatives
  • Contributions

Installation

Choose one of:

• pip install shtab, or
• conda install -c conda-forge shtab

See operating system-specific instructions in the docs.

Usage

There are two ways of using shtab:

• 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: 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}
  • subparser mode: end-users execute your_cli_app completion {bash,zsh}

Examples

See the docs for usage examples.

FAQs

Not working? Check out frequently asked questions.

Alternatives

• argcomplete
  • executes the underlying script every time <TAB> is pressed (slow and has side-effects)
  • only provides bash completion
• 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
• support powershell

See CONTRIBUTING.md for more guidance.