or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/pypi-ipdb

IPython-enabled pdb debugger with enhanced features including tab completion, syntax highlighting, and better tracebacks

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/ipdb@0.13.x

To install, run

npx @tessl/cli install tessl/pypi-ipdb@0.13.0

index.mddocs/

IPDB

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.

Package Information

  • Package Name: ipdb
  • Language: Python
  • Installation: pip install ipdb

Core Imports

import ipdb

For individual function imports:

from ipdb import set_trace, post_mortem, pm, run, runcall, runeval
from ipdb import launch_ipdb_on_exception, iex

For version information:

from ipdb.__main__ import __version__

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

from ipdb import sset_trace, spost_mortem, spm, slaunch_ipdb_on_exception
from ipdb.stdout import update_stdout

For configuration functions (internal module access):

from ipdb.__main__ import get_context_from_config, get_config, wrap_sys_excepthook, main

Basic Usage

import ipdb

def problematic_function(data):
    result = []
    for item in data:
        # Set a breakpoint to inspect variables
        ipdb.set_trace()
        processed = item * 2
        result.append(processed)
    return result

# Example usage
data = [1, 2, 3, 4, 5]
output = problematic_function(data)

Exception debugging:

import ipdb

def risky_operation():
    try:
        result = 10 / 0  # This will raise an exception
    except Exception:
        # Start post-mortem debugging
        ipdb.post_mortem()

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

with launch_ipdb_on_exception():
    risky_operation()

Architecture

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

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

Capabilities

Interactive Debugging

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

def set_trace(frame=None, context=None, cond=True):
    """
    Set a breakpoint and start the IPython debugger.
    
    Parameters:
    - frame: Frame object to debug (optional, defaults to current frame)
    - context: Number of lines to show around breakpoint (optional, defaults to config value)
    - cond: Boolean condition for conditional breakpoint (optional, defaults to True)
    """

def post_mortem(tb=None):
    """
    Start post-mortem debugging on a traceback.
    
    Parameters:
    - tb: Traceback object (optional, defaults to current exception traceback)
    """

def pm():
    """
    Start post-mortem debugging on the last traceback.
    """

Code Execution Under Debugger

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

def run(statement, globals=None, locals=None):
    """
    Run a statement under debugger control.
    
    Parameters:
    - statement: Python statement to execute
    - globals: Global namespace (optional)
    - locals: Local namespace (optional)
    """

def runcall(*args, **kwargs):
    """
    Call a function under debugger control.
    
    Parameters:
    - *args: Function and its arguments
    - **kwargs: Keyword arguments
    
    Returns:
    Function return value
    """

def runeval(expression, globals=None, locals=None):
    """
    Evaluate an expression under debugger control.
    
    Parameters:
    - expression: Python expression to evaluate
    - globals: Global namespace (optional)
    - locals: Local namespace (optional)
    
    Returns:
    Expression result
    """

Exception Context Management

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

def launch_ipdb_on_exception():
    """
    Context manager that launches debugger on exception.
    
    Usage:
    with launch_ipdb_on_exception():
        # Code that might raise exceptions
        pass
        
    Returns:
    Context manager object
    """

# Alias for launch_ipdb_on_exception - pre-instantiated context manager
iex = launch_ipdb_on_exception()

Stdout-Safe Debugging

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

def sset_trace(frame=None, context=3):
    """
    Stdout-safe version of set_trace.
    
    Parameters:
    - frame: Frame object to debug (optional)
    - context: Number of lines to show (defaults to 3)
    """

def spost_mortem(tb=None):
    """
    Stdout-safe version of post_mortem.
    
    Parameters:
    - tb: Traceback object (optional)
    """

def spm():
    """
    Stdout-safe version of pm().
    """

def slaunch_ipdb_on_exception():
    """
    Stdout-safe version of launch_ipdb_on_exception.
    
    Usage:
    with slaunch_ipdb_on_exception():
        # Code that might raise exceptions
        pass
        
    Returns:
    Context manager object
    """

def update_stdout():
    """
    Update stdout to ensure output is available with testing frameworks.
    
    Specifically designed for tools like nose that manipulate stdout.
    Sets stdout to sys.__stdout__ for proper output handling.
    """

Configuration Management

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

def get_context_from_config():
    """
    Get context size from configuration files.
    
    Returns:
    int: Context size (number of lines), defaults to 3
    
    Raises:
    ValueError: If configuration value cannot be converted to integer
    """

def get_config():
    """
    Get complete ipdb configuration from all available sources.
    
    Reads configuration from multiple sources in priority order:
    1. Environment variables (IPDB_CONFIG path)
    2. Home directory .ipdb file  
    3. Project files (setup.cfg, .ipdb, pyproject.toml)
    
    Returns:
    configparser.ConfigParser: Configuration object
    """

Internal Utilities

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

def wrap_sys_excepthook():
    """
    Wrap system exception hook for better IPython debugger integration.
    
    Ensures BdbQuit_excepthook is properly installed without creating cycles.
    """

Configuration

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

Environment Variables

import os

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

# Set custom config file path
os.environ['IPDB_CONFIG'] = '/path/to/custom/.ipdb'

Configuration Files

setup.cfg (project-level):

[ipdb]
context=5

.ipdb (user or project-level):

context=5

pyproject.toml (modern Python projects):

[tool.ipdb]
context = 5

Command Line Interface

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

def main():
    """
    Main entry point for command-line ipdb debugging.
    
    Parses command-line arguments and starts debugging session.
    Supports script debugging, module debugging, and various options.
    
    Command line options:
    - -c/--command: Execute debugger command at startup
    - -m: Run library module as a script (Python 3.7+)
    - -h/--help: Show help message
    
    Usage examples:
    python -m ipdb script.py
    python -m ipdb -c "continue" script.py
    python -m ipdb -m module_name  (Python 3.7+)
    """

Command Line Usage

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

# Debug a Python script (Python 2)
ipdb script.py

# Debug a Python script (Python 3)  
ipdb3 script.py

# Module-based debugging
python -m ipdb script.py

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

Command Line Options

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

Types

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.).

Constants

__version__ = "0.13.13"  # Package version string

Error Handling

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

  • BdbQuit_excepthook: IPython's exception hook for better debugger integration
  • Restart: Exception class for debugger restart functionality (when available)
  • Configuration Errors: ValueError raised for invalid configuration values

Common error scenarios:

# Invalid configuration value
# ValueError: In /path/to/config, context value [invalid] cannot be converted into an integer.

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

# File not found for command-line debugging  
# Error: script.py does not exist

Compatibility

  • Python 2.7: Supported with IPython 5.1.0-6.0.0
  • Python 3.4+: Supported with version-specific IPython dependencies
  • Python 3.11+: Supported with IPython 7.31.1+
  • Standard pdb: Full API compatibility maintained
  • IPython Integration: Seamless integration with IPython shells and Jupyter notebooks

Dependencies

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