forked from microsoft/debugpy
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy path__init__.py
More file actions
214 lines (145 loc) · 6.34 KB
/
__init__.py
File metadata and controls
214 lines (145 loc) · 6.34 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
# 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"])