/usr/lib/python3/dist-packages/argcomplete-1.8.1.egg-info/PKG-INFO is in python3-argcomplete 1.8.1-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 | Metadata-Version: 1.1
Name: argcomplete
Version: 1.8.1
Summary: Bash tab completion for argparse
Home-page: https://github.com/kislyuk/argcomplete
Author: Andrey Kislyuk
Author-email: kislyuk@gmail.com
License: Apache Software License
Description: argcomplete - Bash tab completion for argparse
==============================================
*Tab complete all the things!*
Argcomplete provides easy, extensible command line tab completion of arguments for your Python script.
It makes two assumptions:
* You're using bash as your shell (limited support for zsh and tcsh is available)
* You're using `argparse <http://docs.python.org/2.7/library/argparse.html>`_ to manage your command line arguments/options
Argcomplete is particularly useful if your program has lots of options or subparsers, and if your program can
dynamically suggest completions for your argument/option values (for example, if the user is browsing resources over
the network).
Installation
------------
::
pip install argcomplete
activate-global-python-argcomplete
See `Activating global completion`_ below for details about the second step (or if it reports an error).
Refresh your bash environment (start a new shell or ``source /etc/profile``).
Synopsis
--------
Python code (e.g. ``my-awesome-script.py``):
.. code-block:: python
#!/usr/bin/env python
# PYTHON_ARGCOMPLETE_OK
import argcomplete, argparse
parser = argparse.ArgumentParser()
...
argcomplete.autocomplete(parser)
args = parser.parse_args()
...
Shellcode (only necessary if global completion is not activated - see `Global completion`_ below), to be put in e.g. ``.bashrc``::
eval "$(register-python-argcomplete my-awesome-script.py)"
Note that the script name is passed directly to ``complete``, meaning it is only tab completed when invoked exactly
as it was registered. The above line will **not** allow you to complete ``./my-awesome-script.py``, or
``/path/to/my-awesome-script.py``.
argcomplete.autocomplete(*parser*)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This method is the entry point to the module. It must be called **after** ArgumentParser construction is complete, but
**before** the ``ArgumentParser.parse_args()`` method is called. The method looks for an environment variable that the
completion hook shellcode sets, and if it's there, collects completions, prints them to the output stream (fd 8 by
default), and exits. Otherwise, it returns to the caller immediately.
.. admonition:: Side effects
Argcomplete gets completions by running your program. It intercepts the execution flow at the moment
``argcomplete.autocomplete()`` is called. After sending completions, it exits using ``exit_method`` (``os._exit``
by default). This means if your program has any side effects that happen before ``argcomplete`` is called, those
side effects will happen every time the user presses ``<TAB>`` (although anything your program prints to stdout or
stderr will be suppressed). For this reason it's best to construct the argument parser and call
``argcomplete.autocomplete()`` as early as possible in your execution flow.
.. admonition:: Performance
If the program takes a long time to get to the point where ``argcomplete.autocomplete()`` is called, the tab completion
process will feel sluggish, and the user may lose confidence in it. So it's also important to minimize the startup time
of the program up to that point (for example, by deferring initialization or importing of large modules until after
parsing options).
Specifying completers
---------------------
You can specify custom completion functions for your options and arguments. Two styles are supported: callable and
readline-style. Callable completers are simpler. They are called with the following keyword arguments:
* ``prefix``: The prefix text of the last word before the cursor on the command line. All returned completions should begin with this prefix.
* ``action``: The ``argparse.Action`` instance that this completer was called for.
* ``parser``: The ``argparse.ArgumentParser`` instance that the action was taken by.
* ``parsed_args``: The result of argument parsing so far (the ``argparse.Namespace`` args object normally returned by
``ArgumentParser.parse_args()``).
Completers should return their completions as a list of strings. An example completer for names of environment
variables might look like this:
.. code-block:: python
def EnvironCompleter(prefix, **kwargs):
return (v for v in os.environ if v.startswith(prefix))
To specify a completer for an argument or option, set the ``completer`` attribute of its associated action. An easy
way to do this at definition time is:
.. code-block:: python
from argcomplete.completers import EnvironCompleter
parser = argparse.ArgumentParser()
parser.add_argument("--env-var1").completer = EnvironCompleter
parser.add_argument("--env-var2").completer = EnvironCompleter
argcomplete.autocomplete(parser)
If you specify the ``choices`` keyword for an argparse option or argument (and don't specify a completer), it will be
used for completions.
A completer that is initialized with a set of all possible choices of values for its action might look like this:
.. code-block:: python
class ChoicesCompleter(object):
def __init__(self, choices=[]):
self.choices = [str(choice) for choice in choices]
def __call__(self, prefix, **kwargs):
return (c for c in self.choices if c.startswith(prefix))
The following two ways to specify a static set of choices are equivalent for completion purposes:
.. code-block:: python
from argcomplete.completers import ChoicesCompleter
parser.add_argument("--protocol", choices=('http', 'https', 'ssh', 'rsync', 'wss'))
parser.add_argument("--proto").completer=ChoicesCompleter(('http', 'https', 'ssh', 'rsync', 'wss'))
Note that if you use the ``choices=<completions>`` option, argparse will show
all these choices in the ``--help`` output by default. To prevent this, set
``metavar`` (like ``parser.add_argument("--protocol", metavar="PROTOCOL",
choices=('http', 'https', 'ssh', 'rsync', 'wss'))``).
The following `script <https://raw.github.com/kislyuk/argcomplete/master/docs/examples/describe_github_user.py>`_ uses
``parsed_args`` and `Requests <http://python-requests.org/>`_ to query GitHub for publicly known members of an
organization and complete their names, then prints the member description:
.. code-block:: python
#!/usr/bin/env python
# PYTHON_ARGCOMPLETE_OK
import argcomplete, argparse, requests, pprint
def github_org_members(prefix, parsed_args, **kwargs):
resource = "https://api.github.com/orgs/{org}/members".format(org=parsed_args.organization)
return (member['login'] for member in requests.get(resource).json() if member['login'].startswith(prefix))
parser = argparse.ArgumentParser()
parser.add_argument("--organization", help="GitHub organization")
parser.add_argument("--member", help="GitHub member").completer = github_org_members
argcomplete.autocomplete(parser)
args = parser.parse_args()
pprint.pprint(requests.get("https://api.github.com/users/{m}".format(m=args.member)).json())
`Try it <https://raw.github.com/kislyuk/argcomplete/master/docs/examples/describe_github_user.py>`_ like this::
./describe_github_user.py --organization heroku --member <TAB>
If you have a useful completer to add to the `completer library
<https://github.com/kislyuk/argcomplete/blob/master/argcomplete/completers.py>`_, send a pull request!
Readline-style completers
~~~~~~~~~~~~~~~~~~~~~~~~~
The readline_ module defines a completer protocol in rlcompleter_. Readline-style completers are also supported by
argcomplete, so you can use the same completer object both in an interactive readline-powered shell and on the bash
command line. For example, you can use the readline-style completer provided by IPython_ to get introspective
completions like you would get in the IPython shell:
.. _readline: http://docs.python.org/2/library/readline.html
.. _rlcompleter: http://docs.python.org/2/library/rlcompleter.html#completer-objects
.. _IPython: http://ipython.org/
.. code-block:: python
import IPython
parser.add_argument("--python-name").completer = IPython.core.completer.Completer()
You can also use `argcomplete.CompletionFinder.rl_complete <https://argcomplete.readthedocs.org/en/latest/#argcomplete.CompletionFinder.rl_complete>`_
to plug your entire argparse parser as a readline completer.
Printing warnings in completers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Normal stdout/stderr output is suspended when argcomplete runs. Sometimes, though, when the user presses ``<TAB>``, it's
appropriate to print information about why completions generation failed. To do this, use ``warn``:
.. code-block:: python
from argcomplete import warn
def AwesomeWebServiceCompleter(prefix, **kwargs):
if login_failed:
warn("Please log in to Awesome Web Service to use autocompletion")
return completions
Using a custom completion validator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, argcomplete validates your completions by checking if they start with the prefix given to the completer. You
can override this validation check by supplying the ``validator`` keyword to ``argcomplete.autocomplete()``:
.. code-block:: python
def my_validator(current_input, keyword_to_check_against):
# Pass through ALL options even if they don't all start with 'current_input'
return True
argcomplete.autocomplete(parser, validator=my_validator)
Global completion
-----------------
In global completion mode, you don't have to register each argcomplete-capable executable separately. Instead, bash
will look for the string **PYTHON_ARGCOMPLETE_OK** in the first 1024 bytes of any executable that it's running
completion for, and if it's found, follow the rest of the argcomplete protocol as described above.
.. admonition:: Bash version compatibility
Global completion requires bash support for ``complete -D``, which was introduced in bash 4.2. On OS X or older Linux
systems, you will need to update bash to use this feature. Check the version of the running copy of bash with
``echo $BASH_VERSION``. On OS X, install bash via `Homebrew <http://brew.sh/>`_ (``brew install bash``), add
``/usr/local/bin/bash`` to ``/etc/shells``, and run ``chsh`` to change your shell.
Global completion is not currently compatible with zsh.
.. note:: If you use setuptools/distribute ``scripts`` or ``entry_points`` directives to package your module,
argcomplete will follow the wrapper scripts to their destination and look for ``PYTHON_ARGCOMPLETE_OK`` in the
destination code.
Activating global completion
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The script ``activate-global-python-argcomplete`` will try to install the file
``bash_completion.d/python-argcomplete.sh`` (`see on GitHub`_) into an appropriate location on your system
(``/etc/bash_completion.d/`` or ``~/.bash_completion.d/``). If it
fails, but you know the correct location of your bash completion scripts directory, you can specify it with ``--dest``::
activate-global-python-argcomplete --dest=/path/to/bash_completion.d
Otherwise, you can redirect its shellcode output into a file::
activate-global-python-argcomplete --dest=- > file
The file's contents should then be sourced in e.g. ``~/.bashrc``.
.. _`see on GitHub`: https://github.com/kislyuk/argcomplete/blob/master/argcomplete/bash_completion.d/python-argcomplete.sh
Tcsh Support
------------
To activate completions for tcsh use::
eval `register-python-argcomplete --shell tcsh my-awesome-script.py`
The ``python-argcomplete-tcsh`` script provides completions for tcsh.
The following is an example of the tcsh completion syntax for
``my-awesome-script.py`` emitted by ``register-python-argcomplete``::
complete my-awesome-script.py 'p@*@`python-argcomplete-tcsh my-awesome-script.py`@'
Debugging
---------
Set the ``_ARC_DEBUG`` variable in your shell to enable verbose debug output every time argcomplete runs. Alternatively,
you can bypass the bash completion shellcode altogether, and interact with the Python code directly with something like
this::
PROGNAME=./{YOUR_PY_SCRIPT} TEST_ARGS='some_arguments with autocompl' _ARC_DEBUG=1 COMP_LINE="$PROGNAME $TEST_ARGS" COMP_POINT=31 _ARGCOMPLETE=1 $PROGNAME 8>&1 9>>~/autocomplete_debug.log
Then tail::
tail -f ~/autocomplete_debug.log
Acknowledgments
---------------
Inspired and informed by the optcomplete_ module by Martin Blais.
.. _optcomplete: http://pypi.python.org/pypi/optcomplete
Links
-----
* `Project home page (GitHub) <https://github.com/kislyuk/argcomplete>`_
* `Documentation (Read the Docs) <https://argcomplete.readthedocs.org/en/latest/>`_
* `Package distribution (PyPI) <https://pypi.python.org/pypi/argcomplete>`_
* `Change log <https://github.com/kislyuk/argcomplete/blob/master/Changes.rst>`_
Bugs
~~~~
Please report bugs, issues, feature requests, etc. on `GitHub <https://github.com/kislyuk/argcomplete/issues>`_.
License
-------
Licensed under the terms of the `Apache License, Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0>`_.
.. image:: https://travis-ci.org/kislyuk/argcomplete.png
:target: https://travis-ci.org/kislyuk/argcomplete
.. image:: https://codecov.io/github/kislyuk/argcomplete/coverage.svg?branch=master
:target: https://codecov.io/github/kislyuk/argcomplete?branch=master
.. image:: https://img.shields.io/pypi/v/argcomplete.svg
:target: https://pypi.python.org/pypi/argcomplete
.. image:: https://img.shields.io/pypi/l/argcomplete.svg
:target: https://pypi.python.org/pypi/argcomplete
.. image:: https://readthedocs.org/projects/argcomplete/badge/?version=latest
:target: https://argcomplete.readthedocs.org/
Platform: MacOS X
Platform: Posix
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Development Status :: 5 - Production/Stable
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Shells
Classifier: Topic :: Terminals
|