0
# Programmatic API Control
1

2
Advanced programmatic interface for controlling debugger behavior, managing breakpoints, and handling debugging events. This API provides fine-grained control over debugging sessions and is primarily used by IDEs and development tools that need programmatic access to debugger functionality.
3

4
## Capabilities
5

6
### Main API Interface
7

8
The primary class for programmatic debugger control, providing methods for breakpoint management, debugging session control, and IDE integration.
9

10
```python { .api }
11
class PyDevdAPI:
12
    """
13
    Main API class for programmatic debugger control.
14
    
15
    Provides methods for managing breakpoints, debugger configuration, and debugging behavior
16
    programmatically. Most methods require a py_db (PyDB instance) as the first parameter.
17
    """
18
    
19
    def run(self, py_db):
20
        """Initialize and run the debugger API."""
21
    
22
    def notify_initialize(self, py_db):
23
        """Notify that the debugger has been initialized."""
24
    
25
    def notify_configuration_done(self, py_db):
26
        """Notify that debugger configuration is complete."""
27
    
28
    def notify_disconnect(self, py_db):
29
        """Notify that debugger is disconnecting."""
30
    
31
    def set_protocol(self, py_db, seq, protocol):
32
        """Set the communication protocol (JSON, HTTP-JSON, etc)."""
33
```
34

35
### Breakpoint Management
36

37
Methods for adding, removing, and managing different types of breakpoints.
38

39
```python { .api }
40
class PyDevdAPI:
41
    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):
42
        """
43
        Add a breakpoint to the specified file and line.
44
        
45
        Parameters:
46
        - py_db: PyDB debugger instance
47
        - original_filename (str): Full path to the source file
48
        - breakpoint_type (str): Type of breakpoint ('python-line', 'django-line', 'jinja2-line')
49
        - breakpoint_id (int): Unique breakpoint identifier
50
        - line (int): Line number for the breakpoint (1-based)
51
        - condition (str): Conditional expression for breakpoint
52
        - func_name (str): Function name for breakpoint
53
        - expression (str): Expression to evaluate when breakpoint hits
54
        - suspend_policy (str): When to suspend execution
55
        - hit_condition (str): Hit count condition
56
        - is_logpoint (bool): Whether this is a logpoint (logs without suspending)
57
        - adjust_line (bool): Whether to adjust line number if invalid
58
        - on_changed_breakpoint_state: Callback for breakpoint state changes
59
        
60
        Returns:
61
        _AddBreakpointResult: Result object containing breakpoint information
62
        """
63
    
64
    def remove_breakpoint(self, py_db, received_filename, breakpoint_type, breakpoint_id):
65
        """
66
        Remove a breakpoint from the specified file.
67
        
68
        Parameters:
69
        - py_db: PyDB debugger instance
70
        - received_filename (str): Full path to the source file
71
        - breakpoint_type (str): Type of breakpoint to remove
72
        - breakpoint_id (int): Breakpoint identifier to remove
73
        
74
        Returns:
75
        None
76
        """
77
    
78
    def remove_all_breakpoints(self, py_db, received_filename):
79
        """Remove all breakpoints from the specified file."""
80
    
81
    def reapply_breakpoints(self, py_db):
82
        """Reapply all breakpoints (useful after code changes)."""
83
    
84
    def set_function_breakpoints(self, py_db, function_breakpoints):
85
        """Set function-based breakpoints."""
86
```
87

88
### Exception Handling
89

90
Methods for managing exception breakpoints and exception handling behavior.
91

92
```python { .api }
93
class PyDevdAPI:
94
    def add_plugins_exception_breakpoint(self, py_db, breakpoint_type, exception):
95
        """Add exception breakpoint for plugin frameworks (Django, Jinja2)."""
96
    
97
    def remove_python_exception_breakpoint(self, py_db, exception):
98
        """Remove Python exception breakpoint."""
99
    
100
    def remove_plugins_exception_breakpoint(self, py_db, exception_type, exception):
101
        """Remove plugin exception breakpoint."""
102
    
103
    def remove_all_exception_breakpoints(self, py_db):
104
        """Remove all exception breakpoints."""
105
```
106

107
### Thread Control and Execution
108

109
Methods for controlling thread execution, stepping, and suspension.
110

111
```python { .api }
112
class PyDevdAPI:
113
    def list_threads(self, py_db, seq):
114
        """List all active threads in the debugging session."""
115
    
116
    def request_suspend_thread(self, py_db, thread_id="*"):
117
        """Suspend execution of specified thread(s)."""
118
    
119
    def request_resume_thread(self, thread_id):
120
        """Resume execution of suspended thread."""
121
    
122
    def request_step(self, py_db, thread_id, step_cmd_id):
123
        """Execute stepping command (step into, over, return)."""
124
    
125
    def request_smart_step_into(self, py_db, seq, thread_id, offset, child_offset):
126
        """Smart step into specific function calls."""
127
    
128
    def request_smart_step_into_by_func_name(self, py_db, seq, thread_id, line, func_name):
129
        """Smart step into by function name."""
130
    
131
    def request_set_next(self, py_db, seq, thread_id, set_next_cmd_id, original_filename, line, func_name):
132
        """Set next execution line."""
133
```
134

135
### Variable Inspection
136

137
Methods for inspecting variables, expressions, and runtime state.
138

139
```python { .api }
140
class PyDevdAPI:
141
    def request_stack(self, py_db, seq, thread_id, fmt=None, timeout=0.5, start_frame=0, levels=0):
142
        """Get stack trace for specified thread."""
143
    
144
    def request_get_variable(self, py_db, seq, thread_id, frame_id, scope, attrs):
145
        """Get variable value from specified scope."""
146
    
147
    def request_get_variable_json(self, py_db, request, thread_id):
148
        """Get variable value in JSON format."""
149
    
150
    def request_change_variable(self, py_db, seq, thread_id, frame_id, scope, attr, value):
151
        """Change variable value at runtime."""
152
    
153
    def request_change_variable_json(self, py_db, request, thread_id):
154
        """Change variable value using JSON request."""
155
    
156
    def request_get_array(self, py_db, seq, roffset, coffset, rows, cols, fmt, thread_id, frame_id, scope, attrs):
157
        """Get array/list slice for large data structures."""
158
    
159
    def request_load_full_value(self, py_db, seq, thread_id, frame_id, vars):
160
        """Load full value for truncated variables."""
161
    
162
    def request_get_description(self, py_db, seq, thread_id, frame_id, expression):
163
        """Get description/type information for expression."""
164
    
165
    def request_get_frame(self, py_db, seq, thread_id, frame_id):
166
        """Get frame information."""
167
```
168

169
### Code Execution and Evaluation
170

171
Methods for executing code and evaluating expressions in debugging context.
172

173
```python { .api }
174
class PyDevdAPI:
175
    def request_exec_or_evaluate(self, py_db, seq, thread_id, frame_id, expression, is_exec, trim_if_too_big, attr_to_set_result):
176
        """Execute code or evaluate expression in frame context."""
177
    
178
    def request_exec_or_evaluate_json(self, py_db, request, thread_id):
179
        """Execute/evaluate using JSON request format."""
180
    
181
    def request_set_expression_json(self, py_db, request, thread_id):
182
        """Set expression value using JSON format."""
183
    
184
    def request_console_exec(self, py_db, seq, thread_id, frame_id, expression):
185
        """Execute code in console context."""
186
    
187
    def request_completions(self, py_db, seq, thread_id, frame_id, act_tok, line=-1, column=-1):
188
        """Get code completion suggestions."""
189
```
190

191
### Source Code and File Operations
192

193
Methods for loading source code and handling file operations.
194

195
```python { .api }
196
class PyDevdAPI:
197
    def request_load_source(self, py_db, seq, filename):
198
        """Load source code for specified file."""
199
    
200
    def request_load_source_from_frame_id(self, py_db, seq, frame_id):
201
        """Load source code from frame information."""
202
    
203
    def get_decompiled_source_from_frame_id(self, py_db, frame_id):
204
        """Get decompiled source for compiled code."""
205
    
206
    def request_reload_code(self, py_db, seq, module_name, filename):
207
        """Reload modified source code during debugging."""
208
```
209

210
### Configuration and Settings
211

212
Methods for configuring debugger behavior and settings.
213

214
```python { .api }
215
class PyDevdAPI:
216
    def set_ide_os_and_breakpoints_by(self, py_db, seq, ide_os, breakpoints_by):
217
        """Configure IDE OS and breakpoint handling."""
218
    
219
    def set_gui_event_loop(self, py_db, gui_event_loop):
220
        """Set GUI event loop integration."""
221
    
222
    def set_show_return_values(self, py_db, show_return_values):
223
        """Configure whether to show function return values."""
224
    
225
    def set_enable_thread_notifications(self, py_db, enable):
226
        """Enable/disable thread creation notifications."""
227
    
228
    def set_project_roots(self, py_db, project_roots):
229
        """Set project root directories."""
230
    
231
    def set_stepping_resumes_all_threads(self, py_db, stepping_resumes_all_threads):
232
        """Configure whether stepping resumes all threads."""
233
    
234
    def set_exclude_filters(self, py_db, exclude_filters):
235
        """Set file/path exclusion filters."""
236
    
237
    def set_use_libraries_filter(self, py_db, use_libraries_filter):
238
        """Configure library filtering."""
239
    
240
    def set_dont_trace_start_end_patterns(self, py_db, start_patterns, end_patterns):
241
        """Set patterns for files to exclude from tracing."""
242
    
243
    def set_ignore_system_exit_codes(self, py_db, ignore_system_exit_codes):
244
        """Configure which system exit codes to ignore."""
245
    
246
    def set_source_mapping(self, py_db, source_filename, mapping):
247
        """Set source code mapping (for transpiled languages)."""
248
    
249
    def set_variable_presentation(self, py_db, variable_presentation):
250
        """Configure variable display presentation."""
251
```
252

253
### Process Management
254

255
Methods for managing debugger processes and cleanup.
256

257
```python { .api }
258
class PyDevdAPI:
259
    def request_disconnect(self, py_db, resume_threads):
260
        """Request debugger disconnection."""
261
    
262
    def request_terminate_process(self, py_db):
263
        """Request process termination."""
264
    
265
    def terminate_process(self, py_db):
266
        """Terminate the debugging process."""
267
    
268
    def set_terminate_child_processes(self, py_db, terminate_child_processes):
269
        """Configure child process termination behavior."""
270
    
271
    def set_terminate_keyboard_interrupt(self, py_db, terminate_keyboard_interrupt):
272
        """Configure keyboard interrupt handling."""
273
    
274
    def setup_auto_reload_watcher(self, py_db, enable_auto_reload, watch_dirs, poll_target_time, exclude_patterns, include_patterns):
275
        """Setup automatic code reload watching."""
276
```
277

278
## Breakpoint Configuration Classes
279

280
Classes for representing different types of breakpoints and their configurations.
281

282
```python { .api }
283
class LineBreakpoint:
284
    """Represents a line breakpoint configuration."""
285
    def __init__(self, line, condition, expression, suspend_policy, hit_condition, is_logpoint):
286
        """
287
        Initialize line breakpoint.
288
        
289
        Parameters:
290
        - line (int): Line number
291
        - condition (str): Breakpoint condition
292
        - expression (str): Expression to evaluate
293
        - suspend_policy (str): Suspension policy
294
        - hit_condition (str): Hit count condition
295
        - is_logpoint (bool): Whether this is a logpoint
296
        """
297
```
298

299
## Usage Examples
300

301
### Basic API Usage
302

303
```python
304
from _pydevd_bundle.pydevd_api import PyDevdAPI
305
import pydevd
306

307
# Start debugger and get PyDB instance
308
pydevd.settrace('localhost', port=5678, suspend=False)
309
py_db = pydevd.get_global_debugger()
310

311
# Create API instance
312
api = PyDevdAPI()
313

314
# Add a breakpoint
315
result = api.add_breakpoint(
316
    py_db=py_db,
317
    original_filename="/path/to/file.py",
318
    breakpoint_type="python-line",
319
    breakpoint_id=1,
320
    line=10,
321
    condition=None,
322
    func_name=None,
323
    expression=None,
324
    suspend_policy="ALL",
325
    hit_condition=None,
326
    is_logpoint=False
327
)
328

329
print(f"Breakpoint added: {result.breakpoint_id}")
330
```
331

332
### Thread Control
333

334
```python
335
from _pydevd_bundle.pydevd_api import PyDevdAPI
336
import pydevd
337

338
py_db = pydevd.get_global_debugger()
339
api = PyDevdAPI()
340

341
# List all threads
342
api.list_threads(py_db, seq=1)
343

344
# Suspend all threads
345
api.request_suspend_thread(py_db, thread_id="*")
346

347
# Resume specific thread
348
api.request_resume_thread(thread_id="MainThread")
349

350
# Step into next line
351
api.request_step(py_db, thread_id="MainThread", step_cmd_id=pydevd.CMD_STEP_INTO)
352
```
353

354
### Variable Inspection
355

356
```python
357
from _pydevd_bundle.pydevd_api import PyDevdAPI
358
import pydevd
359

360
py_db = pydevd.get_global_debugger()
361
api = PyDevdAPI()
362

363
# Get stack trace
364
api.request_stack(py_db, seq=1, thread_id="MainThread")
365

366
# Get variable value
367
api.request_get_variable(
368
    py_db=py_db,
369
    seq=2,
370
    thread_id="MainThread",
371
    frame_id=0,
372
    scope="FRAME",
373
    attrs=["my_variable"]
374
)
375

376
# Change variable value
377
api.request_change_variable(
378
    py_db=py_db,
379
    seq=3,
380
    thread_id="MainThread",
381
    frame_id=0,
382
    scope="FRAME",
383
    attr="my_variable",
384
    value="new_value"
385
)
386
```
387

388
### Exception Handling
389

390
```python
391
from _pydevd_bundle.pydevd_api import PyDevdAPI
392
import pydevd
393

394
py_db = pydevd.get_global_debugger()
395
api = PyDevdAPI()
396

397
# Add exception breakpoint for ValueError
398
api.add_plugins_exception_breakpoint(
399
    py_db=py_db,
400
    breakpoint_type="python",
401
    exception="ValueError"
402
)
403

404
# Remove all exception breakpoints
405
api.remove_all_exception_breakpoints(py_db)
406
```
407

408
## Implementation Notes
409

410
- **PyDB Instance Required**: Most API methods require a `py_db` parameter (PyDB debugger instance)
411
- **Sequence Numbers**: Many methods use sequence numbers (`seq`) for request tracking
412
- **Thread Safety**: The API is designed to work with multi-threaded applications
413
- **IDE Integration**: This API is primarily designed for IDE integration rather than direct user code
414
- **Protocol Support**: Supports both XML and JSON communication protocols
415
- **Framework Support**: Includes specific support for Django and Jinja2 template debugging