# Copyright (c) Microsoft Corporation. All rights reserved.
# Licensed under the MIT License. See LICENSE in the project root
# for license information.

from __future__ import absolute_import, division, print_function, unicode_literals

"""An implementation of the Debug Adapter Protocol (DAP) for Python.

https://microsoft.github.io/debug-adapter-protocol/
"""

# debugpy stable public API consists solely of members of this module that are
# enumerated below.
__all__ = [
    "__version__",
    "breakpoint",
    "configure",
    "connect",
    "debug_this_thread",
    "is_client_connected",
    "listen",
    "log_to",
    "trace_this_thread",
    "wait_for_client",
]

import codecs
import os

from debugpy import _version
from debugpy.common import compat


# Expose debugpy.server API from subpackage, but do not actually import it unless
# and until a member is invoked - we don't want the server package loaded in the
# adapter, the tests, or setup.py.

# Docstrings for public API members must be formatted according to PEP 8 - no more
# than 72 characters per line! - and must be readable when retrieved via help().


def log_to(path):
    """Generate detailed debugpy logs in the specified directory.

    The directory must already exist. Several log files are generated,
    one for every process involved in the debug session.
    """

    from debugpy.server import api

    return api.log_to(path)


def configure(properties=None, **kwargs):
    """Sets debug configuration properties that cannot be set in the
    "attach" request, because they must be applied as early as possible
    in the process being debugged.

    For example, a "launch" configuration with subprocess debugging
    disabled can be defined entirely in JSON::

        {
            "request": "launch",
            "subProcess": false,
            ...
        }

    But the same cannot be done with "attach", because "subProcess"
    must be known at the point debugpy starts tracing execution. Thus,
    it is not available in JSON, and must be omitted::

        {
            "request": "attach",
            ...
        }

    and set from within the debugged process instead::

        debugpy.configure(subProcess=False)
        debugpy.listen(...)

    Properties to set can be passed either as a single dict argument,
    or as separate keyword arguments::

        debugpy.configure({"subProcess": False})
    """

    from debugpy.server import api

    return api.configure(properties, **kwargs)


def listen(address):
    """Starts a debug adapter debugging this process, that listens for
    incoming socket connections from clients on the specified address.

    address must be either a (host, port) tuple, as defined by the
    standard socket module for the AF_INET address family, or a port
    number. If only the port is specified, host is "127.0.0.1".

    Returns the interface and the port on which the debug adapter is
    actually listening, in the same format as address. This may be
    different from address if port was 0 in the latter, in which case
    the adapter will pick some unused ephemeral port to listen on.

    This function does't wait for a client to connect to the debug
    adapter that it starts. Use wait_for_client() to block execution
    until the client connects.
    """

    from debugpy.server import api

    return api.listen(address)


@compat.kwonly
def connect(address, access_token=None):
    """Tells an existing debug adapter instance that is listening on the
    specified address to debug this process.

    address must be either a (host, port) tuple, as defined by the
    standard socket module for the AF_INET address family, or a port
    number. If only the port is specified, host is "127.0.0.1".

    access_token must be the same value that was passed to the adapter
    via the --server-access-token command-line switch.

    This function does't wait for a client to connect to the debug
    adapter that it connects to. Use wait_for_client() to block
    execution until the client connects.
    """

    from debugpy.server import api

    return api.connect(address, access_token=access_token)


def wait_for_client():
    """If there is a client connected to the debug adapter that is
    debugging this process, returns immediately. Otherwise, blocks
    until a client connects to the adapter.

    While this function is waiting, it can be canceled by calling
    wait_for_client.cancel() from another thread.
    """

    from debugpy.server import api

    return api.wait_for_client()


def is_client_connected():
    """True if a client is connected to the debug adapter that is
    debugging this process.
    """

    from debugpy.server import api

    return api.is_client_connected()


def breakpoint():
    """If a client is connected to the debug adapter that is debugging
    this process, pauses execution of all threads, and simulates a
    breakpoint being hit at the line following the call.

    On Python 3.7 and above, this is the same as builtins.breakpoint().
    """

    from debugpy.server import api

    return api.breakpoint()


def debug_this_thread():
    """Makes the debugger aware of the current thread.

    Must be called on any background thread that is started by means
    other than the usual Python APIs (i.e. the "threading" module),
    in order for breakpoints to work on that thread.
    """

    from debugpy.server import api

    return api.debug_this_thread()


def trace_this_thread(should_trace):
    """Tells the debug adapter to enable or disable tracing on the
    current thread.

    When the thread is traced, the debug adapter can detect breakpoints
    being hit, but execution is slower, especially in functions that
    have any breakpoints set in them. Disabling tracing when breakpoints
    are not anticipated to be hit can improve performance. It can also
    be used to skip breakpoints on a particular thread.

    Tracing is automatically disabled for all threads when there is no
    client connected to the debug adapter.
    """

    from debugpy.server import api

    return api.trace_this_thread(should_trace)


__version__ = _version.get_versions()["version"]

# Force absolute path on Python 2.
__file__ = os.path.abspath(__file__)

# Preload encodings that we're going to use to avoid import deadlocks on Python 2,
# before importing anything from debugpy.
map(codecs.lookup, ["ascii", "utf8", "utf-8", "latin1", "latin-1", "idna", "hex"])
