Metadata-Version: 2.4
Name: shtab
Version: 1.8.0
Summary: Automagic shell tab completion for Python CLI applications
Author-email: Casper da Costa-Luis <casper.dcl@physics.org>
Maintainer-email: Iterative <support@iterative.ai>
License-Expression: 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: 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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
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.9
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 <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

Installation
------------

Choose one of:

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

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

Usage
-----

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

Examples
--------

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

FAQs
----

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

Alternatives
------------

- `argcomplete <https://pypi.org/project/argcomplete>`_

  - executes the underlying script *every* time ``<TAB>`` is pressed (slow and
    has side-effects)

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

Contributions
-------------

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

- support ``fish`` (`#174 <https://github.com/iterative/shtab/pull/174>`_)
- support ``powershell``

See
`CONTRIBUTING.md <https://github.com/iterative/shtab/tree/main/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
