A Python debugging library for detailed code execution tracing. This library provides utilities for tracing Python code execution with detailed information about variables, function calls, and execution flow.

• Line-by-line execution tracing: See exactly which lines are being executed
• Function/method call tracing: Trace only function and method calls without line details
• Return event tracing: Track function return values and completion
• Exception event tracing: Monitor exception raising and handling
• Variable value inspection: View the values of variables at each execution step
• Module filtering: Trace only specific modules or all modules
• Context manager support: Use with with statements for automatic cleanup
• Lightweight: Minimal overhead and dependencies

Note: Implemented to avoid using pdb manual effort. This is not going to replace pyinstrument, py-spy, and several other performance and profiling debugging tools. This is a simple tool just to counter manual effort of pdb, and it can go deep inside the dependency and print those traces in a basic format which can be done by pyinstrument and other profiling tools as well, but again this is targeting a basic pdb flaw of manual inspection. This is just an inspection tool.

pip install spewer

git clone https://github.com/Agent-Hellboy/spewer.git
cd spewer
pip install -e .

from spewer import spew, unspew

# Start tracing
spew(show_values=True)

# Your code here
def my_function():
    x = 10
    y = 20
    return x + y

result = my_function()

# Stop tracing
unspew()

from spewer import SpewContext

# Automatic start/stop of tracing
with SpewContext(show_values=True):
    def my_function():
        x = 10
        y = 20
        return x + y

    result = my_function()

from spewer import spew, unspew

# Only trace specific modules
spew(trace_names=['my_module'], show_values=True)

# Your code here
import my_module
my_module.some_function()

unspew()

from spewer import SpewContext

# Trace execution without showing variable values
with SpewContext(show_values=False):
    def my_function():
        x = 10
        y = 20
        return x + y

    result = my_function()

from spewer import SpewContext

# Trace only function/method calls without line details
with SpewContext(functions_only=True, show_values=True):
    def my_function(x, y):
        result = x + y
        return result

    result = my_function(10, 20)

This will output:

__main__:15: my_function()
    args: x=10, y=20
__main__:17: my_function() -> 30

from spewer import SpewContext

# Trace function calls and returns
with SpewContext(functions_only=True, show_values=True, trace_returns=True):
    def calculate(x, y):
        return x * y + 10

    result = calculate(5, 3)

This will output:

__main__:15: calculate()
    args: x=5, y=3
__main__:16: calculate() -> 25

from spewer import SpewContext

# Trace function calls and exceptions
with SpewContext(functions_only=True, show_values=True, trace_exceptions=True):
    def risky_function(x, y):
        if y == 0:
            raise ValueError("Cannot divide by zero")
        return x / y

    try:
        result = risky_function(10, 0)
    except ValueError as e:
        print(f"Caught: {e}")

This will output:

__main__:15: risky_function()
    args: x=10, y=0
__main__:16: risky_function() -> ValueError('Cannot divide by zero')

from spewer import SpewContext

# Only trace function calls, not returns or exceptions
with SpewContext(functions_only=True, trace_returns=False, trace_exceptions=False):
    def my_function():
        return 42

    result = my_function()

This will output:

__main__:15: my_function()
# No return event traced

Install a trace hook which writes detailed logs about code execution.

Parameters:

• trace_names (Optional[List[str]]): List of module names to trace. If None, traces all modules.
• show_values (bool): Whether to show variable values during tracing. Default: False.
• functions_only (bool): Whether to trace only function/method calls instead of line-by-line execution. Default: False.
• trace_returns (bool): Whether to trace function return events. Default: False.
• trace_exceptions (bool): Whether to trace exception events. Default: False.

Remove the trace hook installed by spew().

Context manager for automatic spew/unspew operations.

Parameters:

• trace_names (Optional[List[str]]): List of module names to trace. If None, traces all modules.
• show_values (bool): Whether to show variable values during tracing. Default: False.
• functions_only (bool): Whether to trace only function/method calls instead of line-by-line execution. Default: False.
• trace_returns (bool): Whether to trace function return events. Default: False.
• trace_exceptions (bool): Whether to trace exception events. Default: False.

Configuration class for spewer debugging. Provides validation and centralized configuration management.

Parameters:

• trace_names (Optional[List[str]]): List of module names to trace. If None, traces all modules.
• show_values (bool): Whether to show variable values during tracing. Default: True.
• functions_only (bool): Whether to trace only function/method calls instead of line-by-line execution. Default: False.
• trace_returns (bool): Whether to trace function return events. Default: False.
• trace_exceptions (bool): Whether to trace exception events. Default: False.

Core trace hook implementation. This is the low-level class that handles the actual tracing logic.

Parameters:

• config (SpewConfig): Configuration object for the trace hook.

When tracing with show_values=True, you'll see output like:

__main__:15: x = 10
    x=10
__main__:16: y = 20
    y=20
__main__:17: result = x + y
    x=10 y=20 result=30
__main__:18: print(f"Result: {result}")
    result=30

When tracing with functions_only=True, show_values=True, trace_returns=True, trace_exceptions=True:

__main__:15: calculate()
    args: x=10, y=5
__main__:16: calculate() -> 15

__main__:20: risky_function()
    args: x=10, y=0
__main__:22: risky_function() -> ValueError('division by zero')

• The library uses Python's sys.settrace() which can impact performance
• Only one trace hook can be active at a time
• The context manager automatically handles cleanup even if exceptions occur
• Variable inspection works best with simple variable names (avoid complex expressions)

This library is based on the Gunicorn debug module released under the MIT license. The original Gunicorn debug module is Copyright (c) 2009-2024 Benoît Chesneau and Copyright (c) 2009-2015 Paul J. Davis.

This project builds upon the excellent debugging utilities from the Gunicorn web server project. The core tracing functionality was adapted from Gunicorn's debug module, which provides robust execution tracing capabilities. We've enhanced the original implementation with:

• Type hints for better IDE support
• Context manager integration for automatic cleanup
• Enhanced error handling for problematic objects
• Improved documentation and examples
• Modern Python packaging structure

The original Gunicorn debug module can be found at: https://github.com/benoitc/gunicorn/blob/master/gunicorn/debug.py

Future Enhancements: We plan to further enhance this library with additional features to improve usability, including more output formats, advanced filtering options, and better integration with existing debugging workflows.

git clone https://github.com/Agent-Hellboy/spewer.git
cd spewer
python3 -m pip install -e ".[dev]"

This project uses pre-commit hooks to ensure code quality. The hooks will automatically run on every commit and include:

• Ruff linting: Code linting and auto-fixing
• Ruff formatting: Code formatting
• File checks: Trailing whitespace, end-of-file, YAML validation, etc.
• Security checks: Private key detection, merge conflicts, etc.

To install the pre-commit hooks:

pre-commit install

To run the hooks manually:

pre-commit run --all-files

Note: The examples directory is excluded from pre-commit checks to avoid issues with example files.