Metadata-Version: 2.1 Name: argcomplete Version: 2.1.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 Project-URL: Documentation, https://kislyuk.github.io/argcomplete Project-URL: Source Code, https://github.com/kislyuk/argcomplete Project-URL: Issue Tracker, https://github.com/kislyuk/argcomplete/issues Project-URL: Change Log, https://github.com/kislyuk/argcomplete/blob/master/Changes.rst 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 :: 3 Classifier: Programming Language :: Python :: 3.6 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 :: 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 Requires-Python: >=3.6 License-File: LICENSE.rst Requires-Dist: importlib-metadata (<6,>=0.23) ; python_version == "3.6" Requires-Dist: importlib-metadata (<6,>=0.23) ; python_version == "3.7" Provides-Extra: lint Requires-Dist: flake8 ; extra == 'lint' Requires-Dist: mypy ; extra == 'lint' Provides-Extra: test Requires-Dist: coverage ; extra == 'test' Requires-Dist: pexpect ; extra == 'test' Requires-Dist: wheel ; extra == 'test' Requires-Dist: flake8 ; extra == 'test' Requires-Dist: mypy ; extra == 'test' argcomplete - Bash/zsh 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 or zsh as your shell * You're using `argparse `_ 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 ------------ :: pip3 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``): .. 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)" 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 ```` (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. For dynamic completers, this can be used to reduce the work required to generate possible completions. * ``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(**kwargs): return os.environ 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 = choices def __call__(self, **kwargs): return self.choices 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=`` 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 `_ uses ``parsed_args`` and `Requests `_ 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 `_ like this:: ./describe_github_user.py --organization heroku --member If you have a useful completer to add to the `completer library `_, 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/3/library/readline.html .. _rlcompleter: http://docs.python.org/3/library/rlcompleter.html#completer-objects .. _IPython: http://ipython.org/ .. code-block:: python import IPython parser.add_argument("--python-name").completer = IPython.core.completer.Completer() ``argcomplete.CompletionFinder.rl_complete`` can also be used to plug in an 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 ````, 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(completion_candidate, current_input): """Complete non-prefix substring matches.""" return current_input in completion_candidate 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. Additionally, completion is activated for scripts run as ``python