1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
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 <casper.dcl@physics.org>
Maintainer-email: Iterative <support@iterative.ai>
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 <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
|
