#
#  Copyright © 2010—2023 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
from argparse import ArgumentParser

COMPLETION_ENABLED = False
"""
Dynamically set to `True` on load if argcomplete_ was successfully imported.
"""

try:
    import argcomplete
except ImportError:  # pragma: no cover
    argcomplete = None
else:
    COMPLETION_ENABLED = True  # pragma: no cover


__all__ = ["autocomplete", "COMPLETION_ENABLED"]


logger = logging.getLogger(__package__)


def autocomplete(parser: ArgumentParser) -> None:
    """
    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 is not available. Please install argcomplete.")
    else:
        pass