Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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: 24 days 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 4 years ago)
Default Branch: main
Last Pushed: 2024-09-02T19:51:53.000Z (2 months ago)
Last Synced: 2024-09-27T23:20:57.509Z (about 1 month 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: 937 KB
Stars: 366
Watchers: 19
Forks: 34
Open Issues: 28
Metadata Files:
- Readme: README.rst
- Contributing: CONTRIBUTING.md

Awesome Lists containing this project

README

|Logo|

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

------------------------------------------

.. 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)
- only provides ``bash`` completion

- `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``
- 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://caspersci.uk.to/cgi-bin/hits.cgi?q=shtab&style=social&r=https://github.com/iterative/shtab&a=hidden
:target: https://caspersci.uk.to/cgi-bin/hits.cgi?q=shtab&a=plot&r=https://github.com/iterative/shtab&style=social
:alt: Hits