API Reference

Overview

API	Description
breakpoint()	Break on the next line when connected to client.
configure()	TBD
debug_this_thread()	Used to identify python threads created using native APIs.
is_client_connected()	Check if IDE or Debug Adapter Protocol (DAP) Client is connected.
listen()	Recommended way to run the debug server.
log_to()	Turn on logging and configure logging path.
trace_this_thread()	Enable or Disable tracing on a per thread basis.
wait_for_client()	Block running user code until DAP client or IDE is connected.

API Usage with examples

Debugging a simple script

Consider the following script:

print('Hello World')

First let us import debugpy and start the debug server. The code below load the debugger and ster the debug server. But it will not block until you connect to it. this means if you run it by the time you attach using your IDE of choice it will probably already finish and exit.

import debugpy
debugpy.listen(5678) # Loads the debugger and starts the debug server at 127.0.0.1:5678.

print('Hello World')

Let us add wait_for_client() to block your code from running until you have connected to the debug server.

import debugpy
debugpy.listen(("localhost", 5678)) # Loads the debugger and starts the debug server.

debugpy.wait_for_client() # Blocks until you have connected to the debug server.

print('Hello World')

API reference

List ordered by most frequently used to lest frequently used.

listen(address)

Loads the debugger and starts the debug server at the specified port.

• 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 defaults to "127.0.0.1".

Returns a tuple (host interface, port) on which the debug server is actually listening.

Usage

debugpy.listen(5678)
debugpy.listen(('localhost', 5678))

# See how to secure this option if you are using it with remote.
debugpy.listen(('0.0.0.0', 5678))

# if you don't want to select the port yourself
debugpy.listen(0)
debugpy.listen(('localhost', 0))

wait_for_client()

Blocks execution of your code until you connect to the debug server with a Debug Adapter Protocol client. If a client is connected, the function returns immediately. While this function is waiting, it can be canceled by calling wait_for_client.cancel() from another thread.

Usage

debugpy.wait_for_client()

To cancel, you wil have to run wait_for_client.cancel() for another thread. cancel() can only be called after wait_for_client is called at least once.

debugpy.wait_for_client.cancel()

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.

Usage

debugpy.debug_this_thread()

Example

import debugpy

def foo(x):
    debugpy.debug_this_thread()
    print('set breakpoint here')

    return 0

from ctypes import CFUNCTYPE, c_void_p, c_size_t, c_uint32, windll

event = threading.Event()

thread_func_p = CFUNCTYPE(c_uint32, c_void_p)
thread_func = thread_func_p(foo)
assert windll.kernel32.CreateThread(c_void_p(0), c_size_t(0), thread_func, c_void_p(0), c_uint32(0), c_void_p(0))

event.wait()

breakpoint()

Returns immediately if no DAP client is connected. If a client is connected, then it simulates a breakpoint on the next line. On Python 3.7 and above, this is the same as builtins.breakpoint().

Usage

debugpy.breakpoint()
print('debugger stops here')

Example

import debugpy

def foo():
    debugpy.breakpoint()
    print('here')        # Debugger stops here
    debugpy.breakpoint() # Debugger won't stop since there is no next line in this block

foo()

log_to(path)

Sets a directory to write detailed debugpy logs. Several log files are generated, one for every process involved in the debug session.

• path : Path to the directory where the logs should be written. The directory must already exist.

Usage

debugpy.log_to("~/logs")

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.

• should_trace : True to enable tracing. False to disable tracing.

Usage

debugpy.trace_this_thread(True)

Example

import debugpy

def foo():
    debugpy.trace_this_thread(True)

    # Some performance intensive operation.

    debugpy.trace_this_thread(False)

foo()

configure()

TBD