Mercurial > repos > shellac > sam_consensus_v3

comparison env/lib/python3.9/site-packages/argcomplete-1.12.2.dist-info/METADATA @ 0:4f3585e2f14b draft default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
"planemo upload commit 60cee0fc7c0cda8592644e1aad72851dec82c959"
author shellac
date Mon, 22 Mar 2021 18:12:50 +0000
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:4f3585e2f14b
1 Metadata-Version: 2.1
2 Name: argcomplete
3 Version: 1.12.2
4 Summary: Bash tab completion for argparse
5 Home-page: https://github.com/kislyuk/argcomplete
6 Author: Andrey Kislyuk
7 Author-email: kislyuk@gmail.com
8 License: Apache Software License
9 Project-URL: Documentation, https://kislyuk.github.io/argcomplete
10 Project-URL: Source Code, https://github.com/kislyuk/argcomplete
11 Project-URL: Issue Tracker, https://github.com/kislyuk/argcomplete/issues
12 Project-URL: Change Log, https://github.com/kislyuk/argcomplete/blob/master/Changes.rst
13 Platform: MacOS X
14 Platform: Posix
15 Classifier: Environment :: Console
16 Classifier: Intended Audience :: Developers
17 Classifier: License :: OSI Approved :: Apache Software License
18 Classifier: Operating System :: MacOS :: MacOS X
19 Classifier: Operating System :: POSIX
20 Classifier: Programming Language :: Python
21 Classifier: Programming Language :: Python :: 2
22 Classifier: Programming Language :: Python :: 2.7
23 Classifier: Programming Language :: Python :: 3
24 Classifier: Programming Language :: Python :: 3.5
25 Classifier: Programming Language :: Python :: 3.6
26 Classifier: Programming Language :: Python :: 3.7
27 Classifier: Programming Language :: Python :: 3.8
28 Classifier: Programming Language :: Python :: Implementation :: CPython
29 Classifier: Programming Language :: Python :: Implementation :: PyPy
30 Classifier: Development Status :: 5 - Production/Stable
31 Classifier: Topic :: Software Development
32 Classifier: Topic :: Software Development :: Libraries :: Python Modules
33 Classifier: Topic :: System :: Shells
34 Classifier: Topic :: Terminals
35 Requires-Dist: importlib-metadata (<4,>=0.23) ; python_version == "2.7"
36 Requires-Dist: importlib-metadata (<4,>=0.23) ; python_version == "3.5"
37 Requires-Dist: importlib-metadata (<4,>=0.23) ; python_version == "3.6"
38 Requires-Dist: importlib-metadata (<4,>=0.23) ; python_version == "3.7"
39 Provides-Extra: test
40 Requires-Dist: coverage ; extra == 'test'
41 Requires-Dist: flake8 ; extra == 'test'
42 Requires-Dist: pexpect ; extra == 'test'
43 Requires-Dist: wheel ; extra == 'test'
44
45 argcomplete - Bash tab completion for argparse
46 ==============================================
47 *Tab complete all the things!*
48
49 Argcomplete provides easy, extensible command line tab completion of arguments for your Python script.
50
51 It makes two assumptions:
52
53 * You're using bash as your shell (limited support for zsh, fish, and tcsh is available)
54 * You're using `argparse <http://docs.python.org/3/library/argparse.html>`_ to manage your command line arguments/options
55
56 Argcomplete is particularly useful if your program has lots of options or subparsers, and if your program can
57 dynamically suggest completions for your argument/option values (for example, if the user is browsing resources over
58 the network).
59
60 Installation
61 ------------
62 ::
63
64 pip install argcomplete
65 activate-global-python-argcomplete
66
67 See `Activating global completion`_ below for details about the second step (or if it reports an error).
68
69 Refresh your bash environment (start a new shell or ``source /etc/profile``).
70
71 Synopsis
72 --------
73 Python code (e.g. ``my-awesome-script``):
74
75 .. code-block:: python
76
77 #!/usr/bin/env python
78 # PYTHON_ARGCOMPLETE_OK
79 import argcomplete, argparse
80 parser = argparse.ArgumentParser()
81 ...
82 argcomplete.autocomplete(parser)
83 args = parser.parse_args()
84 ...
85
86 Shellcode (only necessary if global completion is not activated - see `Global completion`_ below), to be put in e.g. ``.bashrc``::
87
88 eval "$(register-python-argcomplete my-awesome-script)"
89
90 argcomplete.autocomplete(*parser*)
91 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
92 This method is the entry point to the module. It must be called **after** ArgumentParser construction is complete, but
93 **before** the ``ArgumentParser.parse_args()`` method is called. The method looks for an environment variable that the
94 completion hook shellcode sets, and if it's there, collects completions, prints them to the output stream (fd 8 by
95 default), and exits. Otherwise, it returns to the caller immediately.
96
97 .. admonition:: Side effects
98
99 Argcomplete gets completions by running your program. It intercepts the execution flow at the moment
100 ``argcomplete.autocomplete()`` is called. After sending completions, it exits using ``exit_method`` (``os._exit``
101 by default). This means if your program has any side effects that happen before ``argcomplete`` is called, those
102 side effects will happen every time the user presses ``<TAB>`` (although anything your program prints to stdout or
103 stderr will be suppressed). For this reason it's best to construct the argument parser and call
104 ``argcomplete.autocomplete()`` as early as possible in your execution flow.
105
106 .. admonition:: Performance
107
108 If the program takes a long time to get to the point where ``argcomplete.autocomplete()`` is called, the tab completion
109 process will feel sluggish, and the user may lose confidence in it. So it's also important to minimize the startup time
110 of the program up to that point (for example, by deferring initialization or importing of large modules until after
111 parsing options).
112
113 Specifying completers
114 ---------------------
115 You can specify custom completion functions for your options and arguments. Two styles are supported: callable and
116 readline-style. Callable completers are simpler. They are called with the following keyword arguments:
117
118 * ``prefix``: The prefix text of the last word before the cursor on the command line.
119 For dynamic completers, this can be used to reduce the work required to generate possible completions.
120 * ``action``: The ``argparse.Action`` instance that this completer was called for.
121 * ``parser``: The ``argparse.ArgumentParser`` instance that the action was taken by.
122 * ``parsed_args``: The result of argument parsing so far (the ``argparse.Namespace`` args object normally returned by
123 ``ArgumentParser.parse_args()``).
124
125 Completers should return their completions as a list of strings. An example completer for names of environment
126 variables might look like this:
127
128 .. code-block:: python
129
130 def EnvironCompleter(**kwargs):
131 return os.environ
132
133 To specify a completer for an argument or option, set the ``completer`` attribute of its associated action. An easy
134 way to do this at definition time is:
135
136 .. code-block:: python
137
138 from argcomplete.completers import EnvironCompleter
139
140 parser = argparse.ArgumentParser()
141 parser.add_argument("--env-var1").completer = EnvironCompleter
142 parser.add_argument("--env-var2").completer = EnvironCompleter
143 argcomplete.autocomplete(parser)
144
145 If you specify the ``choices`` keyword for an argparse option or argument (and don't specify a completer), it will be
146 used for completions.
147
148 A completer that is initialized with a set of all possible choices of values for its action might look like this:
149
150 .. code-block:: python
151
152 class ChoicesCompleter(object):
153 def __init__(self, choices):
154 self.choices = choices
155
156 def __call__(self, **kwargs):
157 return self.choices
158
159 The following two ways to specify a static set of choices are equivalent for completion purposes:
160
161 .. code-block:: python
162
163 from argcomplete.completers import ChoicesCompleter
164
165 parser.add_argument("--protocol", choices=('http', 'https', 'ssh', 'rsync', 'wss'))
166 parser.add_argument("--proto").completer=ChoicesCompleter(('http', 'https', 'ssh', 'rsync', 'wss'))
167
168 Note that if you use the ``choices=<completions>`` option, argparse will show
169 all these choices in the ``--help`` output by default. To prevent this, set
170 ``metavar`` (like ``parser.add_argument("--protocol", metavar="PROTOCOL",
171 choices=('http', 'https', 'ssh', 'rsync', 'wss'))``).
172
173 The following `script <https://raw.github.com/kislyuk/argcomplete/master/docs/examples/describe_github_user.py>`_ uses
174 ``parsed_args`` and `Requests <http://python-requests.org/>`_ to query GitHub for publicly known members of an
175 organization and complete their names, then prints the member description:
176
177 .. code-block:: python
178
179 #!/usr/bin/env python
180 # PYTHON_ARGCOMPLETE_OK
181 import argcomplete, argparse, requests, pprint
182
183 def github_org_members(prefix, parsed_args, **kwargs):
184 resource = "https://api.github.com/orgs/{org}/members".format(org=parsed_args.organization)
185 return (member['login'] for member in requests.get(resource).json() if member['login'].startswith(prefix))
186
187 parser = argparse.ArgumentParser()
188 parser.add_argument("--organization", help="GitHub organization")
189 parser.add_argument("--member", help="GitHub member").completer = github_org_members
190
191 argcomplete.autocomplete(parser)
192 args = parser.parse_args()
193
194 pprint.pprint(requests.get("https://api.github.com/users/{m}".format(m=args.member)).json())
195
196 `Try it <https://raw.github.com/kislyuk/argcomplete/master/docs/examples/describe_github_user.py>`_ like this::
197
198 ./describe_github_user.py --organization heroku --member <TAB>
199
200 If you have a useful completer to add to the `completer library
201 <https://github.com/kislyuk/argcomplete/blob/master/argcomplete/completers.py>`_, send a pull request!
202
203 Readline-style completers
204 ~~~~~~~~~~~~~~~~~~~~~~~~~
205 The readline_ module defines a completer protocol in rlcompleter_. Readline-style completers are also supported by
206 argcomplete, so you can use the same completer object both in an interactive readline-powered shell and on the bash
207 command line. For example, you can use the readline-style completer provided by IPython_ to get introspective
208 completions like you would get in the IPython shell:
209
210 .. _readline: http://docs.python.org/3/library/readline.html
211 .. _rlcompleter: http://docs.python.org/3/library/rlcompleter.html#completer-objects
212 .. _IPython: http://ipython.org/
213
214 .. code-block:: python
215
216 import IPython
217 parser.add_argument("--python-name").completer = IPython.core.completer.Completer()
218
219 ``argcomplete.CompletionFinder.rl_complete`` can also be used to plug in an argparse parser as a readline completer.
220
221 Printing warnings in completers
222 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
223 Normal stdout/stderr output is suspended when argcomplete runs. Sometimes, though, when the user presses ``<TAB>``, it's
224 appropriate to print information about why completions generation failed. To do this, use ``warn``:
225
226 .. code-block:: python
227
228 from argcomplete import warn
229
230 def AwesomeWebServiceCompleter(prefix, **kwargs):
231 if login_failed:
232 warn("Please log in to Awesome Web Service to use autocompletion")
233 return completions
234
235 Using a custom completion validator
236 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
237 By default, argcomplete validates your completions by checking if they start with the prefix given to the completer. You
238 can override this validation check by supplying the ``validator`` keyword to ``argcomplete.autocomplete()``:
239
240 .. code-block:: python
241
242 def my_validator(current_input, keyword_to_check_against):
243 # Pass through ALL options even if they don't all start with 'current_input'
244 return True
245
246 argcomplete.autocomplete(parser, validator=my_validator)
247
248 Global completion
249 -----------------
250 In global completion mode, you don't have to register each argcomplete-capable executable separately. Instead, bash
251 will look for the string **PYTHON_ARGCOMPLETE_OK** in the first 1024 bytes of any executable that it's running
252 completion for, and if it's found, follow the rest of the argcomplete protocol as described above.
253
254 Additionally, completion is activated for scripts run as ``python <script>`` and ``python -m <module>``.
255 This also works for alternate Python versions (e.g. ``python3`` and ``pypy``), as long as that version of Python has
256 argcomplete installed.
257
258 .. admonition:: Bash version compatibility
259
260 Global completion requires bash support for ``complete -D``, which was introduced in bash 4.2. On OS X or older Linux
261 systems, you will need to update bash to use this feature. Check the version of the running copy of bash with
262 ``echo $BASH_VERSION``. On OS X, install bash via `Homebrew <http://brew.sh/>`_ (``brew install bash``), add
263 ``/usr/local/bin/bash`` to ``/etc/shells``, and run ``chsh`` to change your shell.
264
265 Global completion is not currently compatible with zsh.
266
267 .. note:: If you use setuptools/distribute ``scripts`` or ``entry_points`` directives to package your module,
268 argcomplete will follow the wrapper scripts to their destination and look for ``PYTHON_ARGCOMPLETE_OK`` in the
269 destination code.
270
271 If you choose not to use global completion, or ship a bash completion module that depends on argcomplete, you must
272 register your script explicitly using ``eval "$(register-python-argcomplete my-awesome-script)"``. Standard bash
273 completion registration roules apply: namely, the script name is passed directly to ``complete``, meaning it is only tab
274 completed when invoked exactly as it was registered. In the above example, ``my-awesome-script`` must be on the path,
275 and the user must be attempting to complete it by that name. The above line alone would **not** allow you to complete
276 ``./my-awesome-script``, or ``/path/to/my-awesome-script``.
277
278
279 Activating global completion
280 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
281 The script ``activate-global-python-argcomplete`` will try to install the file
282 ``bash_completion.d/python-argcomplete`` (`see on GitHub`_) into an appropriate location on your system
283 (``/etc/bash_completion.d/`` or ``~/.bash_completion.d/``). If it
284 fails, but you know the correct location of your bash completion scripts directory, you can specify it with ``--dest``::
285
286 activate-global-python-argcomplete --dest=/path/to/bash_completion.d
287
288 Otherwise, you can redirect its shellcode output into a file::
289
290 activate-global-python-argcomplete --dest=- > file
291
292 The file's contents should then be sourced in e.g. ``~/.bashrc``.
293
294 .. _`see on GitHub`: https://github.com/kislyuk/argcomplete/blob/master/argcomplete/bash_completion.d/python-argcomplete
295
296 Zsh Support
297 ------------
298 To activate completions for zsh you need to have ``bashcompinit`` enabled in zsh::
299
300 autoload -U bashcompinit
301 bashcompinit
302
303 Afterwards you can enable completion for your scripts with ``register-python-argcomplete``::
304
305 eval "$(register-python-argcomplete my-awesome-script)"
306
307 Tcsh Support
308 ------------
309 To activate completions for tcsh use::
310
311 eval `register-python-argcomplete --shell tcsh my-awesome-script`
312
313 The ``python-argcomplete-tcsh`` script provides completions for tcsh.
314 The following is an example of the tcsh completion syntax for
315 ``my-awesome-script`` emitted by ``register-python-argcomplete``::
316
317 complete my-awesome-script 'p@*@`python-argcomplete-tcsh my-awesome-script`@'
318
319 Fish Support
320 ------------
321 To activate completions for fish use::
322
323 register-python-argcomplete --shell fish my-awesome-script | source
324
325 or create new completion file, e.g::
326
327 register-python-argcomplete --shell fish ~/.config/fish/completions/my-awesome-script.fish
328
329 Completion Description For Fish
330 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
331 By default help string is added as completion description.
332
333 .. image:: docs/fish_help_string.png
334
335 You can disable this feature by removing ``_ARGCOMPLETE_DFS`` variable, e.g::
336
337 register-python-argcomplete --shell fish my-awesome-script | grep -v _ARGCOMPLETE_DFS | .
338
339 Git Bash Support
340 ----------------
341 Due to limitations of file descriptor inheritance on Windows,
342 Git Bash not supported out of the box. You can opt in to using
343 temporary files instead of file descriptors for for IPC
344 by setting the environment variable ``ARGCOMPLETE_USE_TEMPFILES``,
345 e.g. by adding ``export ARGCOMPLETE_USE_TEMPFILES=1`` to ``~/.bashrc``.
346
347 For full support, consider using Bash with the
348 Windows Subsystem for Linux (WSL).
349
350 External argcomplete script
351 ---------------------------
352 To register an argcomplete script for an arbitrary name, the ``--external-argcomplete-script`` argument of the ``register-python-argcomplete`` script can be used::
353
354 eval "$(register-python-argcomplete --external-argcomplete-script /path/to/script arbitrary-name)"
355
356 This allows, for example, to use the auto completion functionality of argcomplete for an application not written in Python.
357 The command line interface of this program must be additionally implemented in a Python script with argparse and argcomplete and whenever the application is called the registered external argcomplete script is used for auto completion.
358
359 This option can also be used in combination with the other supported shells.
360
361 Python Support
362 --------------
363 Argcomplete requires Python 2.7 or 3.5+.
364
365 Common Problems
366 ---------------
367 If global completion is not completing your script, bash may have registered a
368 default completion function::
369
370 $ complete | grep my-awesome-script
371 complete -F _minimal my-awesome-script
372
373 You can fix this by restarting your shell, or by running
374 ``complete -r my-awesome-script``.
375
376 Debugging
377 ---------
378 Set the ``_ARC_DEBUG`` variable in your shell to enable verbose debug output every time argcomplete runs. This will
379 disrupt the command line composition state of your terminal, but make it possible to see the internal state of the
380 completer if it encounters problems.
381
382 Acknowledgments
383 ---------------
384 Inspired and informed by the optcomplete_ module by Martin Blais.
385
386 .. _optcomplete: http://pypi.python.org/pypi/optcomplete
387
388 Links
389 -----
390 * `Project home page (GitHub) <https://github.com/kislyuk/argcomplete>`_
391 * `Documentation <https://kislyuk.github.io/argcomplete/>`_
392 * `Package distribution (PyPI) <https://pypi.python.org/pypi/argcomplete>`_
393 * `Change log <https://github.com/kislyuk/argcomplete/blob/master/Changes.rst>`_
394 * `xontrib-argcomplete <https://github.com/anki-code/xontrib-argcomplete>`_ - support argcomplete in `xonsh <https://github.com/xonsh/xonsh>`_ shell
395
396 Bugs
397 ~~~~
398 Please report bugs, issues, feature requests, etc. on `GitHub <https://github.com/kislyuk/argcomplete/issues>`_.
399
400 License
401 -------
402 Licensed under the terms of the `Apache License, Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0>`_.
403
404 .. image:: https://github.com/kislyuk/argcomplete/workflows/Python%20package/badge.svg
405 :target: https://github.com/kislyuk/argcomplete/actions
406 .. image:: https://codecov.io/github/kislyuk/argcomplete/coverage.svg?branch=master
407 :target: https://codecov.io/github/kislyuk/argcomplete?branch=master
408 .. image:: https://img.shields.io/pypi/v/argcomplete.svg
409 :target: https://pypi.python.org/pypi/argcomplete
410 .. image:: https://img.shields.io/pypi/l/argcomplete.svg
411 :target: https://pypi.python.org/pypi/argcomplete
412
413