0
# Core Debugging Interface
1

2
Primary debugging functionality that provides the main interface for starting, stopping, and configuring debugging sessions. These functions handle debugger lifecycle, communication with IDE clients, and core debugging behavior configuration.
3

4
## Capabilities
5

6
### Session Management
7

8
Core functions for starting and stopping debugging sessions with full control over connection parameters and debugging behavior.
9

10
```python { .api }
11
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):
12
    """
13
    Start debugging session and connect to debugger server.
14
    
15
    Parameters:
16
    - host (str, optional): Debugger server hostname/IP (default: localhost)
17
    - stdout_to_server (bool): Redirect stdout to debugger server
18
    - stderr_to_server (bool): Redirect stderr to debugger server  
19
    - port (int): Debugger server port (default: 5678)
20
    - suspend (bool): Suspend execution immediately after connecting
21
    - trace_only_current_thread (bool): Only trace current thread
22
    - overwrite_prev_trace (bool): Replace existing trace function (deprecated)
23
    - patch_multiprocessing (bool): Enable debugging in child processes
24
    - stop_at_frame: Frame to stop at (internal use)
25
    - block_until_connected (bool): Block until debugger client connects
26
    - wait_for_ready_to_run (bool): Wait for ready signal before continuing
27
    - dont_trace_start_patterns (tuple): Filename patterns to skip tracing at start
28
    - dont_trace_end_patterns (tuple): Filename patterns to skip tracing at end
29
    - access_token (str, optional): Client access token for authentication
30
    - client_access_token (str, optional): Server access token for authentication
31
    - notify_stdin (bool): Notify about stdin redirections
32
    - protocol (str, optional): Communication protocol to use
33
    - **kwargs: Additional keyword arguments
34
    
35
    Returns:
36
    None
37
    """
38

39
def stoptrace():
40
    """
41
    Stop active debugging session and disconnect from debugger server.
42
    
43
    Returns:
44
    None
45
    """
46
```
47

48
### Configuration
49

50
Global debugger configuration functions for setting protocol, debug modes, and behavior options.
51

52
```python { .api }
53
def config(protocol="", debug_mode="", preimport=""):
54
    """
55
    Configure global debugger settings.
56
    
57
    Parameters:
58
    - protocol (str): Communication protocol ('', 'http', 'json')
59
    - debug_mode (str): Debug mode settings
60
    - preimport (str): Modules to preimport
61
    
62
    Returns:
63
    None
64
    """
65
```
66

67
### Logging
68

69
Debugger logging configuration for troubleshooting and development.
70

71
```python { .api }
72
def log_to(log_file: str, log_level=3):
73
    """
74
    Configure debugger logging output.
75
    
76
    Parameters:
77
    - log_file (str): Path to log file
78
    - log_level (int): Logging level (0=None, 1=Critical, 2=Error, 3=Warning, 4=Info, 5=Debug)
79
    
80
    Returns:
81
    None
82
    """
83
```
84

85
### Process Management
86

87
Functions for handling forked processes and multiprocessing scenarios.
88

89
```python { .api }
90
def settrace_forked(setup_tracing=True):
91
    """
92
    Setup debugger for forked child processes.
93
    
94
    Parameters:
95
    - setup_tracing (bool): Whether to setup tracing in child process
96
    
97
    Returns:
98
    None
99
    """
100
```
101

102
### Utility Functions
103

104
Helper functions for debugging session management and troubleshooting.
105

106
```python { .api }
107
def patch_stdin():
108
    """
109
    Patch stdin for debugging input handling.
110
    
111
    Returns:
112
    None
113
    """
114

115
def enable_qt_support(qt_support_mode):
116
    """
117
    Enable Qt application debugging support.
118
    
119
    Parameters:
120
    - qt_support_mode: Qt support mode configuration
121
    
122
    Returns:
123
    None
124
    """
125

126
def dump_threads(stream=None):
127
    """
128
    Utility function to dump thread information for debugging.
129
    
130
    Parameters:
131
    - stream: Output stream (default: stdout)
132
    
133
    Returns:
134
    None
135
    """
136

137
def main():
138
    """
139
    Command-line entry point for standalone debugging.
140
    
141
    Returns:
142
    None
143
    """
144
```
145

146
### Command Dispatch
147

148
Internal command dispatching for handling debugger protocol messages.
149

150
```python { .api }
151
def dispatch():
152
    """
153
    Dispatch debugger commands from IDE client.
154
    
155
    Returns:
156
    None
157
    """
158
```
159

160
## Usage Examples
161

162
### Basic Remote Debugging
163

164
```python
165
import pydevd
166

167
# Connect to IDE debugger on localhost
168
pydevd.settrace('localhost', port=5678)
169

170
# Your application code
171
def calculate_result():
172
    x = 10
173
    y = 20
174
    return x + y
175

176
result = calculate_result()
177
print(f"Result: {result}")
178

179
# Stop debugging when done
180
pydevd.stoptrace()
181
```
182

183
### Advanced Configuration
184

185
```python
186
import pydevd
187

188
# Configure debugger protocol and logging
189
pydevd.config(protocol='http', debug_mode='True')
190
pydevd.log_to('/tmp/pydevd.log', log_level=4)
191

192
# Start debugging with multiprocessing support
193
pydevd.settrace(
194
    host='192.168.1.100',
195
    port=5678,
196
    suspend=False,  # Don't suspend immediately
197
    trace_only_current_thread=False,
198
    patch_multiprocessing=True,  # Debug child processes
199
    stdout_to_server=True,
200
    stderr_to_server=True
201
)
202
```
203

204
### Debugging Forked Processes
205

206
```python
207
import os
208
import pydevd
209

210
# Start debugging in parent process
211
pydevd.settrace('localhost', port=5678)
212

213
pid = os.fork()
214
if pid == 0:
215
    # Child process - setup debugging for fork
216
    pydevd.settrace_forked()
217
    # Child process code here
218
    print("In child process")
219
else:
220
    # Parent process continues with debugging
221
    print("In parent process")
222
    os.waitpid(pid, 0)
223
```
224

225
### Qt Application Debugging
226

227
```python
228
import pydevd
229
from PyQt5.QtWidgets import QApplication, QMainWindow
230

231
# Enable Qt support before starting debugging
232
pydevd.enable_qt_support('auto')
233
pydevd.settrace('localhost', port=5678)
234

235
app = QApplication([])
236
window = QMainWindow()
237
window.show()
238

239
# Qt event loop will work properly with debugger
240
app.exec_()
241
```
242

243
## Constants
244

245
```python { .api }
246
# Connection dispatch modes
247
DISPATCH_APPROACH_NEW_CONNECTION = 1
248
DISPATCH_APPROACH_EXISTING_CONNECTION = 2
249

250
# Package version
251
__version__: str
252
```