0
# PyDevD
1

2
A comprehensive Python debugger backend that serves as the core debugging engine for multiple popular IDEs including PyDev for Eclipse, PyCharm, and VSCode Python extensions. PyDevD provides advanced debugging capabilities including remote debugging, breakpoint management, variable inspection, step-by-step execution control, and frame evaluation with optimized performance through Cython speedups and Python 3.12 sys.monitoring support.
3

4
## Package Information
5

6
- **Package Name**: pydevd
7
- **Language**: Python
8
- **Installation**: `pip install pydevd`
9
- **License**: EPL (Eclipse Public License)
10
- **Python Versions**: 3.6+
11

12
## Core Imports
13

14
```python
15
import pydevd
16
```
17

18
For file utilities:
19

20
```python
21
import pydevd_file_utils
22
```
23

24
For interactive console:
25

26
```python
27
import pydevconsole
28
```
29

30
For programmatic API control:
31

32
```python
33
from _pydevd_bundle.pydevd_api import PyDevdAPI
34
```
35

36
## Basic Usage
37

38
### Remote Debugging Setup
39

40
```python
41
import pydevd
42

43
# Connect to debugger server (typically running in IDE)
44
pydevd.settrace('localhost', port=5678)
45

46
# Your code here - execution will pause at first line
47
x = 42
48
y = x * 2
49
print(f"Result: {y}")
50

51
# Stop debugging
52
pydevd.stoptrace()
53
```
54

55
### Configuration and Logging
56

57
```python
58
import pydevd
59

60
# Configure debugger protocol and logging
61
pydevd.config(protocol='http', debug_mode='True')
62
pydevd.log_to('/path/to/debugger.log', log_level=2)
63

64
# Start debugging with custom settings
65
pydevd.settrace(
66
    host='192.168.1.100',
67
    port=5678,
68
    suspend=True,
69
    trace_only_current_thread=False,
70
    patch_multiprocessing=True
71
)
72
```
73

74
## Architecture
75

76
PyDevD follows a modular architecture designed for flexibility and performance:
77

78
- **Core Debugger (`pydevd.py`)**: Main debugging session management and control interface
79
- **Communication Layer**: Handles protocol communication between debugger and IDE
80
- **Tracing Infrastructure**: Low-level Python tracing hooks and frame evaluation
81
- **File System Integration**: Cross-platform path handling and source file management
82
- **Plugin System**: Framework-specific debugging extensions (Django, Jinja2)
83
- **Performance Optimizations**: Cython extensions and sys.monitoring for Python 3.12+
84

85
This design enables PyDevD to serve as the universal debugging backend for Python development across different IDEs and environments.
86

87
## Capabilities
88

89
### Core Debugging Interface
90

91
Primary debugging functionality including session management, tracing control, configuration, and logging. These functions provide the main interface for starting, stopping, and configuring debugging sessions.
92

93
```python { .api }
94
def settrace(host=None, stdout_to_server=False, stderr_to_server=False, port=5678, suspend=True, trace_only_current_thread=False, overwrite_prev_trace=False, patch_multiprocessing=False, stop_at_frame=None, block_until_connected=True, wait_for_ready_to_run=True, dont_trace_start_patterns=(), dont_trace_end_patterns=(), access_token=None, client_access_token=None, notify_stdin=True, protocol=None, **kwargs): ...
95
def stoptrace(): ...
96
def config(protocol="", debug_mode="", preimport=""): ...
97
def log_to(log_file: str, log_level=3): ...
98
```
99

100
[Core Debugging](./core-debugging.md)
101

102
### File System Utilities
103

104
Cross-platform file path handling, normalization, and client-server path translation for remote debugging scenarios. Essential for handling source file references across different environments.
105

106
```python { .api }
107
def canonical_normalized_path(filename): ...
108
def absolute_path(filename): ...
109
def normcase(s): ...
110
def get_client_filename_source_reference(client_filename): ...
111
def get_server_filename_from_source_reference(source_reference): ...
112
```
113

114
[File System](./file-system.md)
115

116
### Interactive Console
117

118
Interactive debugging console interface for code evaluation and inspection during debugging sessions. Provides REPL-like functionality within the debugging context.
119

120
```python { .api }
121
class Command: ...
122
# Console classes from _pydevd_bundle.pydevconsole_code
123
```
124

125
[Interactive Console](./interactive-console.md)
126

127
### Programmatic API Control
128

129
Advanced programmatic interface for controlling debugger behavior, managing breakpoints, and handling debugging events. Used by IDEs and tools that need fine-grained control over debugging sessions.
130

131
```python { .api }
132
class PyDevdAPI:
133
    def add_breakpoint(self, py_db, original_filename, breakpoint_type, breakpoint_id, line, condition, func_name, expression, suspend_policy, hit_condition, is_logpoint, adjust_line=False, on_changed_breakpoint_state=None): ...
134
    def remove_breakpoint(self, py_db, received_filename, breakpoint_type, breakpoint_id): ...
135
    # Additional API methods for thread control, variable inspection, and debugging
136
```
137

138
[Programmatic API](./programmatic-api.md)
139

140
### Process Attachment
141

142
Remote process attachment and code injection capabilities for debugging already-running Python processes. Enables debugging scenarios where the target process wasn't started with debugging enabled.
143

144
```python { .api }
145
# Functions from pydevd_attach_to_process.add_code_to_python_process
146
def run_python_code(pid, python_code, connect_debugger_tracing=False, show_debug_info=0): ...
147
```
148

149
[Process Attachment](./process-attachment.md)
150

151
### Framework Integration
152

153
Plugin system for framework-specific debugging support including Django templates, Jinja2 templates, and custom debugging extensions. Provides specialized debugging capabilities for web frameworks and template engines.
154

155
```python { .api }
156
# Django debugging support
157
# Jinja2 template debugging support
158
# Custom plugin extension framework
159
```
160

161
[Framework Integration](./framework-integration.md)
162

163
### IPython Integration
164

165
Integration with IPython kernels and GUI toolkits for debugging interactive computing environments. Supports matplotlib, Qt applications, and other GUI frameworks commonly used in scientific computing.
166

167
```python { .api }
168
# IPython kernel integration
169
# GUI toolkit event loop management
170
# Matplotlib integration utilities
171
```
172

173
[IPython Integration](./ipython-integration.md)
174

175
## Types
176

177
### Core Types
178

179
```python { .api }
180
class PyDB:
181
    """Main debugging session management class."""
182
    def __init__(self, set_as_global=True): ...
183
    def trace_dispatch(self, frame, event, arg): ...
184
    def set_suspend(self, thread, stop_reason): ...
185
    def do_wait_suspend(self, thread, frame, event, arg): ...
186

187
class SetupHolder:
188
    """Debugger configuration holder."""
189
    setup: dict
190

191
class DebugInfoHolder:
192
    """Debug configuration and state container."""
193
    default_stop_on_unhandled_exception: bool
194
    default_stop_on_handled_exception: bool
195
```
196

197
### Breakpoint Types
198

199
```python { .api }
200
class ExceptionBreakpoint:
201
    """Exception breakpoint configuration."""
202
    def __init__(self, qname, condition, expression, notify_on_handled_exceptions, notify_on_unhandled_exceptions, notify_on_first_raise_only): ...
203

204
class LineBreakpoint:
205
    """Line-based breakpoint configuration."""
206
    def __init__(self, line, condition, expression, suspend_policy, hit_condition, is_logpoint): ...
207
```
208

209
### Constants
210

211
```python { .api }
212
# Debugger states
213
STATE_RUN = 1
214
STATE_SUSPEND = 2
215

216
# Suspend types
217
PYTHON_SUSPEND = 1
218
DJANGO_SUSPEND = 2
219
JINJA2_SUSPEND = 3
220

221
# Platform detection
222
IS_CPYTHON: bool
223
IS_IRONPYTHON: bool
224
IS_WINDOWS: bool
225
IS_LINUX: bool
226
IS_MAC: bool
227

228
# Configuration limits
229
MAXIMUM_VARIABLE_REPRESENTATION_SIZE = 1000
230
```