DAP Client reference

Notes for DAP Clients

DAP Implementation details

Clients should use "Late case", (see here) when communicating with debugpy.

Extension to DAP

We added some extension to DAP to support Multi-process debugging.

debugpyAttach Event

The event body is a fully formed attach debug configuration that can be used to start a separate debug session. This is generated when the debugger detects a subprocess. See DAP Specifcation for Event object.

interface DebugpyAttachEvent extends Event {
  event: "debugpyAttach";

  body: {
    /**
     * Fully formed attach configuration that can be used with VS Code 'debug.startDebugging' API.
     */
  };
}

Starting debugpy for Launch Scenario.

Debugpy uses stdin/stdout to send and receive DAP messages. All you need to do to start the debug adapter is run this command:

python ~/debugpy/adapter

Follow the instructions here on how to implement a DAP client.

Starting debugpy for Attach scenario.

This assumes debugpy is already started using the CLI debugging or via import debugpy (see here). In this mode you can send and receive DAP messages over the socket. Everything else is same as the launch scenario.

VS Code DebugAdapterDescriptor

This is a sample implementation of how the debug adapter can be invoked in a VS Code extension.

public async createDebugAdapterDescriptor(session: DebugSession, executable: DebugAdapterExecutable | undefined): Promise<DebugAdapterDescriptor> {
    const configuration = session.
    const isAttach = configuration.request === 'attach';
    const port = configuration.port ?? 0;
    // When processId is provided we may have to inject the debugger into the process.
    // This is done by the debug adapter, so we need to start it. The adapter will handle
    // injecting the debugger when it receives the attach request.
    const processId = configuration.processId ?? 0;

     if (isAttach && processId === 0) {
        return new DebugAdapterServer(port, configuration.host);
    }

    const pythonPath = '<Path to python executable>';
    // If logToFile is set in the debug config then pass --log-dir <path-to-extension-dir> when launching the debug adapter.
    const logArgs = configuration.logToFile ? ['--log-dir', EXTENSION_ROOT_DIR] : [];

    return new DebugAdapterExecutable(pythonPath, [ 'C:\\debugpy\\adapter',...logArgs]);
}