https://github.com/iterative/shtab
↔️ Automagic shell tab completion for Python CLI applications
https://github.com/iterative/shtab
argcomplete argopt argparse bash bash-completion cli completion developer-tools docopt documentation hacktoberfest pages python pyzshcomplete tab-completion tcsh zsh
Last synced: 6 months ago
JSON representation
↔️ Automagic shell tab completion for Python CLI applications
- Host: GitHub
- URL: https://github.com/iterative/shtab
- Owner: iterative
- License: other
- Created: 2020-06-13T23:34:04.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-03-03T18:21:07.000Z (9 months ago)
- Last Synced: 2025-04-01T10:36:02.909Z (8 months ago)
- Topics: argcomplete, argopt, argparse, bash, bash-completion, cli, completion, developer-tools, docopt, documentation, hacktoberfest, pages, python, pyzshcomplete, tab-completion, tcsh, zsh
- Language: Python
- Homepage: https://docs.iterative.ai/shtab
- Size: 943 KB
- Stars: 387
- Watchers: 17
- Forks: 34
- Open Issues: 32
-
Metadata Files:
- Readme: README.rst
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
- awesome-zsh-plugins - shtab - Automatically generate shell tab completion scripts for Python CLI apps, supports `zsh`, `bash` and `tcsh`. (Other Resources / ZSH Tools)
- fucking-awesome-zsh-plugins - shtab - Automatically generate shell tab completion scripts for Python CLI apps, supports `zsh`, `bash` and `tcsh`. (Other Resources / ZSH Tools)
README
|Logo|
shtab
=====
|PyPI-Downloads| |Tests| |Coverage| |PyPI| |Conda|
- 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}``)
------------------------------------------
.. contents:: Table of Contents
:backlinks: top
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,tcsh}``
- subparser mode: end-users execute ``your_cli_app completion {bash,zsh,tcsh}``
Examples
--------
See `the docs for usage examples `_.
FAQs
----
Not working? Check out `frequently asked questions `_.
Alternatives
------------
- `argcomplete `_
- executes the underlying script *every* time ```` is pressed (slow and
has side-effects)
- `pyzshcomplete `_
- executes the underlying script *every* time ```` 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.
|Hits|
.. |Logo| image:: https://github.com/iterative/shtab/raw/main/meta/logo.png
.. |Tests| image:: https://img.shields.io/github/actions/workflow/status/iterative/shtab/test.yml?logo=github&label=tests
:target: https://github.com/iterative/shtab/actions
:alt: Tests
.. |Coverage| image:: https://codecov.io/gh/iterative/shtab/branch/main/graph/badge.svg
:target: https://codecov.io/gh/iterative/shtab
:alt: Coverage
.. |Conda| image:: https://img.shields.io/conda/v/conda-forge/shtab.svg?label=conda&logo=conda-forge
:target: https://anaconda.org/conda-forge/shtab
:alt: conda-forge
.. |PyPI| image:: https://img.shields.io/pypi/v/shtab.svg?label=pip&logo=PyPI&logoColor=white
:target: https://pypi.org/project/shtab
:alt: PyPI
.. |PyPI-Downloads| image:: https://img.shields.io/pypi/dm/shtab.svg?label=pypi%20downloads&logo=PyPI&logoColor=white
:target: https://pepy.tech/project/shtab
:alt: Downloads
.. |Hits| image:: https://cgi.cdcl.ml/hits?q=shtab&style=social&r=https://github.com/iterative/shtab&a=hidden
:target: https://cgi.cdcl.ml/hits?q=shtab&a=plot&r=https://github.com/iterative/shtab&style=social
:alt: Hits