Metadata-Version: 2.4 Name: shtab Version: 1.7.2 Summary: Automagic shell tab completion for Python CLI applications Author-email: Casper da Costa-Luis Maintainer-email: Iterative License: Apache-2.0 Project-URL: documentation, https://docs.iterative.ai/shtab Project-URL: repository, https://github.com/iterative/shtab Project-URL: changelog, https://github.com/iterative/shtab/releases Keywords: tab,complete,completion,shell,bash,zsh,argparse Classifier: Development Status :: 5 - Production/Stable Classifier: Environment :: Console Classifier: Environment :: MacOS X Classifier: Environment :: Other Environment Classifier: Intended Audience :: Developers Classifier: Intended Audience :: Education Classifier: Intended Audience :: End Users/Desktop Classifier: Intended Audience :: Other Audience Classifier: Intended Audience :: System Administrators Classifier: License :: OSI Approved :: Apache Software License Classifier: Operating System :: MacOS Classifier: Operating System :: MacOS :: MacOS X Classifier: Operating System :: POSIX Classifier: Operating System :: POSIX :: BSD Classifier: Operating System :: POSIX :: BSD :: FreeBSD Classifier: Operating System :: POSIX :: Linux Classifier: Operating System :: POSIX :: SunOS/Solaris Classifier: Operating System :: Unix Classifier: Programming Language :: Other Scripting Engines Classifier: Programming Language :: Python Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.7 Classifier: Programming Language :: Python :: 3.8 Classifier: Programming Language :: Python :: 3.9 Classifier: Programming Language :: Python :: 3.10 Classifier: Programming Language :: Python :: 3.11 Classifier: Programming Language :: Python :: 3.12 Classifier: Programming Language :: Python :: 3 :: Only Classifier: Programming Language :: Python :: Implementation Classifier: Programming Language :: Python :: Implementation :: IronPython Classifier: Programming Language :: Python :: Implementation :: PyPy Classifier: Programming Language :: Unix Shell Classifier: Topic :: Desktop Environment Classifier: Topic :: Education :: Computer Aided Instruction (CAI) Classifier: Topic :: Education :: Testing Classifier: Topic :: Office/Business Classifier: Topic :: Other/Nonlisted Topic Classifier: Topic :: Software Development Classifier: Topic :: Software Development :: Build Tools Classifier: Topic :: Software Development :: Libraries Classifier: Topic :: Software Development :: Libraries :: Python Modules Classifier: Topic :: Software Development :: Pre-processors Classifier: Topic :: Software Development :: User Interfaces Classifier: Topic :: System Classifier: Topic :: System :: Installation/Setup Classifier: Topic :: System :: Shells Classifier: Topic :: System :: System Shells Classifier: Topic :: Terminals Classifier: Topic :: Utilities Requires-Python: >=3.7 Description-Content-Type: text/x-rst License-File: LICENCE Provides-Extra: dev Requires-Dist: pytest>=6; extra == "dev" Requires-Dist: pytest-cov; extra == "dev" Requires-Dist: pytest-timeout; extra == "dev" Dynamic: license-file |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