0
# IPDB
1

2
IPython-enabled pdb debugger that provides enhanced debugging capabilities with tab completion, syntax highlighting, better tracebacks, and improved introspection while maintaining full compatibility with the standard pdb module API.
3

4
## Package Information
5

6
- **Package Name**: ipdb
7
- **Language**: Python
8
- **Installation**: `pip install ipdb`
9

10
## Core Imports
11

12
```python
13
import ipdb
14
```
15

16
For individual function imports:
17

18
```python
19
from ipdb import set_trace, post_mortem, pm, run, runcall, runeval
20
from ipdb import launch_ipdb_on_exception, iex
21
```
22

23
For version information:
24

25
```python
26
from ipdb.__main__ import __version__
27
```
28

29
For stdout-safe debugging (when using tools like nose):
30

31
```python
32
from ipdb import sset_trace, spost_mortem, spm, slaunch_ipdb_on_exception
33
from ipdb.stdout import update_stdout
34
```
35

36
For configuration functions (internal module access):
37

38
```python
39
from ipdb.__main__ import get_context_from_config, get_config, wrap_sys_excepthook, main
40
```
41

42
## Basic Usage
43

44
```python
45
import ipdb
46

47
def problematic_function(data):
48
    result = []
49
    for item in data:
50
        # Set a breakpoint to inspect variables
51
        ipdb.set_trace()
52
        processed = item * 2
53
        result.append(processed)
54
    return result
55

56
# Example usage
57
data = [1, 2, 3, 4, 5]
58
output = problematic_function(data)
59
```
60

61
Exception debugging:
62

63
```python
64
import ipdb
65

66
def risky_operation():
67
    try:
68
        result = 10 / 0  # This will raise an exception
69
    except Exception:
70
        # Start post-mortem debugging
71
        ipdb.post_mortem()
72

73
# Or use context manager for automatic exception debugging
74
from ipdb import launch_ipdb_on_exception
75

76
with launch_ipdb_on_exception():
77
    risky_operation()
78
```
79

80
## Architecture
81

82
IPDB bridges the standard Python pdb module with IPython's enhanced debugging capabilities:
83

84
- **Debugger Integration**: Uses IPython's debugger classes for enhanced features while maintaining pdb compatibility
85
- **Configuration System**: Supports multiple configuration sources (.ipdb, setup.cfg, pyproject.toml, environment variables)
86
- **Stdout Handling**: Provides special functions for tools that manipulate stdout (like testing frameworks)
87
- **Exception Handling**: Enhanced exception hook integration for better debugging workflows
88

89
## Capabilities
90

91
### Interactive Debugging
92

93
Core debugging functions that set breakpoints and start the interactive IPython debugger with enhanced features like tab completion, syntax highlighting, and better introspection.
94

95
```python { .api }
96
def set_trace(frame=None, context=None, cond=True):
97
    """
98
    Set a breakpoint and start the IPython debugger.
99
    
100
    Parameters:
101
    - frame: Frame object to debug (optional, defaults to current frame)
102
    - context: Number of lines to show around breakpoint (optional, defaults to config value)
103
    - cond: Boolean condition for conditional breakpoint (optional, defaults to True)
104
    """
105

106
def post_mortem(tb=None):
107
    """
108
    Start post-mortem debugging on a traceback.
109
    
110
    Parameters:
111
    - tb: Traceback object (optional, defaults to current exception traceback)
112
    """
113

114
def pm():
115
    """
116
    Start post-mortem debugging on the last traceback.
117
    """
118
```
119

120
### Code Execution Under Debugger
121

122
Functions that execute Python statements, expressions, or function calls under debugger control, allowing step-by-step execution and variable inspection.
123

124
```python { .api }
125
def run(statement, globals=None, locals=None):
126
    """
127
    Run a statement under debugger control.
128
    
129
    Parameters:
130
    - statement: Python statement to execute
131
    - globals: Global namespace (optional)
132
    - locals: Local namespace (optional)
133
    """
134

135
def runcall(*args, **kwargs):
136
    """
137
    Call a function under debugger control.
138
    
139
    Parameters:
140
    - *args: Function and its arguments
141
    - **kwargs: Keyword arguments
142
    
143
    Returns:
144
    Function return value
145
    """
146

147
def runeval(expression, globals=None, locals=None):
148
    """
149
    Evaluate an expression under debugger control.
150
    
151
    Parameters:
152
    - expression: Python expression to evaluate
153
    - globals: Global namespace (optional)
154
    - locals: Local namespace (optional)
155
    
156
    Returns:
157
    Expression result
158
    """
159
```
160

161
### Exception Context Management
162

163
Context managers and decorators that automatically launch the debugger when exceptions occur, providing seamless debugging workflows for exception handling.
164

165
```python { .api }
166
def launch_ipdb_on_exception():
167
    """
168
    Context manager that launches debugger on exception.
169
    
170
    Usage:
171
    with launch_ipdb_on_exception():
172
        # Code that might raise exceptions
173
        pass
174
        
175
    Returns:
176
    Context manager object
177
    """
178

179
# Alias for launch_ipdb_on_exception - pre-instantiated context manager
180
iex = launch_ipdb_on_exception()
181
```
182

183
### Stdout-Safe Debugging
184

185
Special debugging functions designed for tools that manipulate stdout (like nose testing framework), ensuring proper output handling while maintaining all debugging capabilities.
186

187
```python { .api }
188
def sset_trace(frame=None, context=3):
189
    """
190
    Stdout-safe version of set_trace.
191
    
192
    Parameters:
193
    - frame: Frame object to debug (optional)
194
    - context: Number of lines to show (defaults to 3)
195
    """
196

197
def spost_mortem(tb=None):
198
    """
199
    Stdout-safe version of post_mortem.
200
    
201
    Parameters:
202
    - tb: Traceback object (optional)
203
    """
204

205
def spm():
206
    """
207
    Stdout-safe version of pm().
208
    """
209

210
def slaunch_ipdb_on_exception():
211
    """
212
    Stdout-safe version of launch_ipdb_on_exception.
213
    
214
    Usage:
215
    with slaunch_ipdb_on_exception():
216
        # Code that might raise exceptions
217
        pass
218
        
219
    Returns:
220
    Context manager object
221
    """
222

223
def update_stdout():
224
    """
225
    Update stdout to ensure output is available with testing frameworks.
226
    
227
    Specifically designed for tools like nose that manipulate stdout.
228
    Sets stdout to sys.__stdout__ for proper output handling.
229
    """
230
```
231

232
### Configuration Management
233

234
Functions for managing IPDB configuration from various sources including environment variables, configuration files, and runtime settings.
235

236
```python { .api }
237
def get_context_from_config():
238
    """
239
    Get context size from configuration files.
240
    
241
    Returns:
242
    int: Context size (number of lines), defaults to 3
243
    
244
    Raises:
245
    ValueError: If configuration value cannot be converted to integer
246
    """
247

248
def get_config():
249
    """
250
    Get complete ipdb configuration from all available sources.
251
    
252
    Reads configuration from multiple sources in priority order:
253
    1. Environment variables (IPDB_CONFIG path)
254
    2. Home directory .ipdb file  
255
    3. Project files (setup.cfg, .ipdb, pyproject.toml)
256
    
257
    Returns:
258
    configparser.ConfigParser: Configuration object
259
    """
260
```
261

262
### Internal Utilities
263

264
System-level functions for debugger initialization and exception handling integration.
265

266
```python { .api }
267
def wrap_sys_excepthook():
268
    """
269
    Wrap system exception hook for better IPython debugger integration.
270
    
271
    Ensures BdbQuit_excepthook is properly installed without creating cycles.
272
    """
273
```
274

275
## Configuration
276

277
IPDB supports configuration through multiple sources, with precedence from highest to lowest:
278

279
### Environment Variables
280

281
```python
282
import os
283

284
# Set context size globally
285
os.environ['IPDB_CONTEXT_SIZE'] = '5'
286

287
# Set custom config file path
288
os.environ['IPDB_CONFIG'] = '/path/to/custom/.ipdb'
289
```
290

291
### Configuration Files
292

293
**setup.cfg** (project-level):
294
```ini
295
[ipdb]
296
context=5
297
```
298

299
**.ipdb** (user or project-level):
300
```ini
301
context=5
302
```
303

304
**pyproject.toml** (modern Python projects):
305
```toml
306
[tool.ipdb]
307
context = 5
308
```
309

310

311
### Command Line Interface
312

313
Main entry point function for command-line debugging with full argument parsing and debugger initialization.
314

315
```python { .api }
316
def main():
317
    """
318
    Main entry point for command-line ipdb debugging.
319
    
320
    Parses command-line arguments and starts debugging session.
321
    Supports script debugging, module debugging, and various options.
322
    
323
    Command line options:
324
    - -c/--command: Execute debugger command at startup
325
    - -m: Run library module as a script (Python 3.7+)
326
    - -h/--help: Show help message
327
    
328
    Usage examples:
329
    python -m ipdb script.py
330
    python -m ipdb -c "continue" script.py
331
    python -m ipdb -m module_name  (Python 3.7+)
332
    """
333
```
334

335
## Command Line Usage
336

337
IPDB provides command-line debugging capabilities similar to pdb but with IPython enhancements:
338

339
```bash
340
# Debug a Python script (Python 2)
341
ipdb script.py
342

343
# Debug a Python script (Python 3)  
344
ipdb3 script.py
345

346
# Module-based debugging
347
python -m ipdb script.py
348

349
# With command-line options
350
python -m ipdb -c "continue" script.py  # Run until exception
351
python -m ipdb -c "until 25" script.py  # Run until line 25
352
python -m ipdb -m module_name  # Debug a module (Python 3.7+)
353
```
354

355
### Command Line Options
356

357
- `-c command`: Execute debugger command at startup
358
- `-m`: Run library module as a script (Python 3.7+)  
359
- `-h, --help`: Show help message
360

361
## Types
362

363
Since ipdb maintains full compatibility with Python's standard pdb module, it uses the same base types and interfaces. All function parameters and return values are standard Python types (frames, tracebacks, strings, etc.).
364

365
## Constants
366

367
```python { .api }
368
__version__ = "0.13.13"  # Package version string
369
```
370

371
## Error Handling
372

373
IPDB integrates with Python's exception handling system and provides enhanced error reporting:
374

375
- **BdbQuit_excepthook**: IPython's exception hook for better debugger integration
376
- **Restart**: Exception class for debugger restart functionality (when available)
377
- **Configuration Errors**: ValueError raised for invalid configuration values
378

379
Common error scenarios:
380

381
```python
382
# Invalid configuration value
383
# ValueError: In /path/to/config, context value [invalid] cannot be converted into an integer.
384

385
# Missing traceback for post_mortem
386
# No traceback available - use within exception handler
387

388
# File not found for command-line debugging  
389
# Error: script.py does not exist
390
```
391

392
## Compatibility
393

394
- **Python 2.7**: Supported with IPython 5.1.0-6.0.0
395
- **Python 3.4+**: Supported with version-specific IPython dependencies
396
- **Python 3.11+**: Supported with IPython 7.31.1+
397
- **Standard pdb**: Full API compatibility maintained
398
- **IPython Integration**: Seamless integration with IPython shells and Jupyter notebooks
399

400
## Dependencies
401

402
- **IPython**: Core dependency for enhanced debugging features
403
- **decorator**: Context manager functionality
404
- **toml/tomli/tomllib**: Configuration file parsing (version-dependent)
405
- **configparser**: Configuration management