tessl/pypi-pydevd

Comprehensive Python debugger backend for IDEs with remote debugging, breakpoints, variable inspection, and performance optimizations

—

Pending

Overview

Eval results

Files

Programmatic API Control

Name: tessl/pypi-pydevd
Author: tessl

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.

Capabilities

Main API Interface

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

class PyDevdAPI:
    """
    Main API class for programmatic debugger control.
    
    Provides methods for managing breakpoints, debugger configuration, and debugging behavior
    programmatically. Most methods require a py_db (PyDB instance) as the first parameter.
    """
    
    def run(self, py_db):
        """Initialize and run the debugger API."""
    
    def notify_initialize(self, py_db):
        """Notify that the debugger has been initialized."""
    
    def notify_configuration_done(self, py_db):
        """Notify that debugger configuration is complete."""
    
    def notify_disconnect(self, py_db):
        """Notify that debugger is disconnecting."""
    
    def set_protocol(self, py_db, seq, protocol):
        """Set the communication protocol (JSON, HTTP-JSON, etc)."""

Breakpoint Management

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

class PyDevdAPI:
    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):
        """
        Add a breakpoint to the specified file and line.
        
        Parameters:
        - py_db: PyDB debugger instance
        - original_filename (str): Full path to the source file
        - breakpoint_type (str): Type of breakpoint ('python-line', 'django-line', 'jinja2-line')
        - breakpoint_id (int): Unique breakpoint identifier
        - line (int): Line number for the breakpoint (1-based)
        - condition (str): Conditional expression for breakpoint
        - func_name (str): Function name for breakpoint
        - expression (str): Expression to evaluate when breakpoint hits
        - suspend_policy (str): When to suspend execution
        - hit_condition (str): Hit count condition
        - is_logpoint (bool): Whether this is a logpoint (logs without suspending)
        - adjust_line (bool): Whether to adjust line number if invalid
        - on_changed_breakpoint_state: Callback for breakpoint state changes
        
        Returns:
        _AddBreakpointResult: Result object containing breakpoint information
        """
    
    def remove_breakpoint(self, py_db, received_filename, breakpoint_type, breakpoint_id):
        """
        Remove a breakpoint from the specified file.
        
        Parameters:
        - py_db: PyDB debugger instance
        - received_filename (str): Full path to the source file
        - breakpoint_type (str): Type of breakpoint to remove
        - breakpoint_id (int): Breakpoint identifier to remove
        
        Returns:
        None
        """
    
    def remove_all_breakpoints(self, py_db, received_filename):
        """Remove all breakpoints from the specified file."""
    
    def reapply_breakpoints(self, py_db):
        """Reapply all breakpoints (useful after code changes)."""
    
    def set_function_breakpoints(self, py_db, function_breakpoints):
        """Set function-based breakpoints."""

Exception Handling

Methods for managing exception breakpoints and exception handling behavior.

class PyDevdAPI:
    def add_plugins_exception_breakpoint(self, py_db, breakpoint_type, exception):
        """Add exception breakpoint for plugin frameworks (Django, Jinja2)."""
    
    def remove_python_exception_breakpoint(self, py_db, exception):
        """Remove Python exception breakpoint."""
    
    def remove_plugins_exception_breakpoint(self, py_db, exception_type, exception):
        """Remove plugin exception breakpoint."""
    
    def remove_all_exception_breakpoints(self, py_db):
        """Remove all exception breakpoints."""

Thread Control and Execution

Methods for controlling thread execution, stepping, and suspension.

class PyDevdAPI:
    def list_threads(self, py_db, seq):
        """List all active threads in the debugging session."""
    
    def request_suspend_thread(self, py_db, thread_id="*"):
        """Suspend execution of specified thread(s)."""
    
    def request_resume_thread(self, thread_id):
        """Resume execution of suspended thread."""
    
    def request_step(self, py_db, thread_id, step_cmd_id):
        """Execute stepping command (step into, over, return)."""
    
    def request_smart_step_into(self, py_db, seq, thread_id, offset, child_offset):
        """Smart step into specific function calls."""
    
    def request_smart_step_into_by_func_name(self, py_db, seq, thread_id, line, func_name):
        """Smart step into by function name."""
    
    def request_set_next(self, py_db, seq, thread_id, set_next_cmd_id, original_filename, line, func_name):
        """Set next execution line."""

Variable Inspection

Methods for inspecting variables, expressions, and runtime state.

class PyDevdAPI:
    def request_stack(self, py_db, seq, thread_id, fmt=None, timeout=0.5, start_frame=0, levels=0):
        """Get stack trace for specified thread."""
    
    def request_get_variable(self, py_db, seq, thread_id, frame_id, scope, attrs):
        """Get variable value from specified scope."""
    
    def request_get_variable_json(self, py_db, request, thread_id):
        """Get variable value in JSON format."""
    
    def request_change_variable(self, py_db, seq, thread_id, frame_id, scope, attr, value):
        """Change variable value at runtime."""
    
    def request_change_variable_json(self, py_db, request, thread_id):
        """Change variable value using JSON request."""
    
    def request_get_array(self, py_db, seq, roffset, coffset, rows, cols, fmt, thread_id, frame_id, scope, attrs):
        """Get array/list slice for large data structures."""
    
    def request_load_full_value(self, py_db, seq, thread_id, frame_id, vars):
        """Load full value for truncated variables."""
    
    def request_get_description(self, py_db, seq, thread_id, frame_id, expression):
        """Get description/type information for expression."""
    
    def request_get_frame(self, py_db, seq, thread_id, frame_id):
        """Get frame information."""

Code Execution and Evaluation

Methods for executing code and evaluating expressions in debugging context.

class PyDevdAPI:
    def request_exec_or_evaluate(self, py_db, seq, thread_id, frame_id, expression, is_exec, trim_if_too_big, attr_to_set_result):
        """Execute code or evaluate expression in frame context."""
    
    def request_exec_or_evaluate_json(self, py_db, request, thread_id):
        """Execute/evaluate using JSON request format."""
    
    def request_set_expression_json(self, py_db, request, thread_id):
        """Set expression value using JSON format."""
    
    def request_console_exec(self, py_db, seq, thread_id, frame_id, expression):
        """Execute code in console context."""
    
    def request_completions(self, py_db, seq, thread_id, frame_id, act_tok, line=-1, column=-1):
        """Get code completion suggestions."""

Source Code and File Operations

Methods for loading source code and handling file operations.

class PyDevdAPI:
    def request_load_source(self, py_db, seq, filename):
        """Load source code for specified file."""
    
    def request_load_source_from_frame_id(self, py_db, seq, frame_id):
        """Load source code from frame information."""
    
    def get_decompiled_source_from_frame_id(self, py_db, frame_id):
        """Get decompiled source for compiled code."""
    
    def request_reload_code(self, py_db, seq, module_name, filename):
        """Reload modified source code during debugging."""

Configuration and Settings

Methods for configuring debugger behavior and settings.

class PyDevdAPI:
    def set_ide_os_and_breakpoints_by(self, py_db, seq, ide_os, breakpoints_by):
        """Configure IDE OS and breakpoint handling."""
    
    def set_gui_event_loop(self, py_db, gui_event_loop):
        """Set GUI event loop integration."""
    
    def set_show_return_values(self, py_db, show_return_values):
        """Configure whether to show function return values."""
    
    def set_enable_thread_notifications(self, py_db, enable):
        """Enable/disable thread creation notifications."""
    
    def set_project_roots(self, py_db, project_roots):
        """Set project root directories."""
    
    def set_stepping_resumes_all_threads(self, py_db, stepping_resumes_all_threads):
        """Configure whether stepping resumes all threads."""
    
    def set_exclude_filters(self, py_db, exclude_filters):
        """Set file/path exclusion filters."""
    
    def set_use_libraries_filter(self, py_db, use_libraries_filter):
        """Configure library filtering."""
    
    def set_dont_trace_start_end_patterns(self, py_db, start_patterns, end_patterns):
        """Set patterns for files to exclude from tracing."""
    
    def set_ignore_system_exit_codes(self, py_db, ignore_system_exit_codes):
        """Configure which system exit codes to ignore."""
    
    def set_source_mapping(self, py_db, source_filename, mapping):
        """Set source code mapping (for transpiled languages)."""
    
    def set_variable_presentation(self, py_db, variable_presentation):
        """Configure variable display presentation."""

Process Management

Methods for managing debugger processes and cleanup.

class PyDevdAPI:
    def request_disconnect(self, py_db, resume_threads):
        """Request debugger disconnection."""
    
    def request_terminate_process(self, py_db):
        """Request process termination."""
    
    def terminate_process(self, py_db):
        """Terminate the debugging process."""
    
    def set_terminate_child_processes(self, py_db, terminate_child_processes):
        """Configure child process termination behavior."""
    
    def set_terminate_keyboard_interrupt(self, py_db, terminate_keyboard_interrupt):
        """Configure keyboard interrupt handling."""
    
    def setup_auto_reload_watcher(self, py_db, enable_auto_reload, watch_dirs, poll_target_time, exclude_patterns, include_patterns):
        """Setup automatic code reload watching."""

Breakpoint Configuration Classes

Classes for representing different types of breakpoints and their configurations.

class LineBreakpoint:
    """Represents a line breakpoint configuration."""
    def __init__(self, line, condition, expression, suspend_policy, hit_condition, is_logpoint):
        """
        Initialize line breakpoint.
        
        Parameters:
        - line (int): Line number
        - condition (str): Breakpoint condition
        - expression (str): Expression to evaluate
        - suspend_policy (str): Suspension policy
        - hit_condition (str): Hit count condition
        - is_logpoint (bool): Whether this is a logpoint
        """

Usage Examples

Basic API Usage

from _pydevd_bundle.pydevd_api import PyDevdAPI
import pydevd

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

# Create API instance
api = PyDevdAPI()

# Add a breakpoint
result = api.add_breakpoint(
    py_db=py_db,
    original_filename="/path/to/file.py",
    breakpoint_type="python-line",
    breakpoint_id=1,
    line=10,
    condition=None,
    func_name=None,
    expression=None,
    suspend_policy="ALL",
    hit_condition=None,
    is_logpoint=False
)

print(f"Breakpoint added: {result.breakpoint_id}")

Thread Control

from _pydevd_bundle.pydevd_api import PyDevdAPI
import pydevd

py_db = pydevd.get_global_debugger()
api = PyDevdAPI()

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

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

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

# Step into next line
api.request_step(py_db, thread_id="MainThread", step_cmd_id=pydevd.CMD_STEP_INTO)

Variable Inspection

from _pydevd_bundle.pydevd_api import PyDevdAPI
import pydevd

py_db = pydevd.get_global_debugger()
api = PyDevdAPI()

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

# Get variable value
api.request_get_variable(
    py_db=py_db,
    seq=2,
    thread_id="MainThread",
    frame_id=0,
    scope="FRAME",
    attrs=["my_variable"]
)

# Change variable value
api.request_change_variable(
    py_db=py_db,
    seq=3,
    thread_id="MainThread",
    frame_id=0,
    scope="FRAME",
    attr="my_variable",
    value="new_value"
)

Exception Handling

from _pydevd_bundle.pydevd_api import PyDevdAPI
import pydevd

py_db = pydevd.get_global_debugger()
api = PyDevdAPI()

# Add exception breakpoint for ValueError
api.add_plugins_exception_breakpoint(
    py_db=py_db,
    breakpoint_type="python",
    exception="ValueError"
)

# Remove all exception breakpoints
api.remove_all_exception_breakpoints(py_db)

Implementation Notes

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