You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
94 lines
2.9 KiB
94 lines
2.9 KiB
# coding: utf-8
|
|
#
|
|
# Copyright © 2010—2014 Andrey Mikhaylenko and contributors
|
|
#
|
|
# This file is part of Argh.
|
|
#
|
|
# Argh is free software under terms of the GNU Lesser
|
|
# General Public License version 3 (LGPLv3) as published by the Free
|
|
# Software Foundation. See the file README.rst for copying conditions.
|
|
#
|
|
"""
|
|
Shell completion
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
Command and argument completion is a great way to reduce the number of
|
|
keystrokes and improve user experience.
|
|
|
|
To display suggestions when you press :kbd:`tab`, a shell must obtain choices
|
|
from your program. It calls the program in a specific environment and expects
|
|
it to return a list of relevant choices.
|
|
|
|
`Argparse` does not support completion out of the box. However, there are
|
|
3rd-party apps that do the job, such as argcomplete_ and
|
|
python-selfcompletion_.
|
|
|
|
`Argh` supports only argcomplete_ which doesn't require subclassing
|
|
the parser and monkey-patches it instead. Combining `Argh`
|
|
with python-selfcompletion_ isn't much harder though: simply use
|
|
`SelfCompletingArgumentParser` instead of vanilla `ArgumentParser`.
|
|
|
|
See installation details and gotchas in the documentation of the 3rd-party app
|
|
you've chosen for the completion backend.
|
|
|
|
`Argh` automatically enables completion if argcomplete_ is available
|
|
(see :attr:`COMPLETION_ENABLED`). If completion is undesirable in given app by
|
|
design, it can be turned off by setting ``completion=False``
|
|
in :func:`argh.dispatching.dispatch`.
|
|
|
|
Note that you don't *have* to add completion via `Argh`; it doesn't matter
|
|
whether you let it do it for you or use the underlying API.
|
|
|
|
.. _argcomplete: https://github.com/kislyuk/argcomplete
|
|
.. _python-selfcompletion: https://github.com/dbarnett/python-selfcompletion
|
|
|
|
Argument-level completion
|
|
-------------------------
|
|
|
|
Argcomplete_ supports custom "completers". The documentation suggests adding
|
|
the completer as an attribute of the argument parser action::
|
|
|
|
parser.add_argument("--env-var1").completer = EnvironCompleter
|
|
|
|
However, this doesn't fit the normal `Argh`-assisted workflow.
|
|
It is recommended to use the :func:`~argh.decorators.arg` decorator::
|
|
|
|
@arg('--env-var1', completer=EnvironCompleter)
|
|
def func(...):
|
|
...
|
|
|
|
"""
|
|
import logging
|
|
import os
|
|
|
|
|
|
COMPLETION_ENABLED = False
|
|
"""
|
|
Dynamically set to `True` on load if argcomplete_ was successfully imported.
|
|
"""
|
|
|
|
try:
|
|
import argcomplete
|
|
except ImportError:
|
|
pass
|
|
else:
|
|
COMPLETION_ENABLED = True
|
|
|
|
|
|
__all__ = ['autocomplete', 'COMPLETION_ENABLED']
|
|
|
|
|
|
logger = logging.getLogger(__package__)
|
|
|
|
|
|
def autocomplete(parser):
|
|
"""
|
|
Adds support for shell completion via argcomplete_ by patching given
|
|
`argparse.ArgumentParser` (sub)class.
|
|
|
|
If completion is not enabled, logs a debug-level message.
|
|
"""
|
|
if COMPLETION_ENABLED:
|
|
argcomplete.autocomplete(parser)
|
|
elif 'bash' in os.getenv('SHELL', ''):
|
|
logger.debug('Bash completion not available. Install argcomplete.')
|