tessl/pypi-traceback-with-variables

Adds variables to python traceback with simple, lightweight, controllable debugging capabilities.

Overview

Eval results

Files

Core Formatting and Display

Name: tessl/pypi-traceback-with-variables
Author: tessl

Central formatting engine that processes Python tracebacks and displays variable contexts. Provides low-level functions for creating formatted traceback strings and iterating through traceback lines with comprehensive variable information.

Capabilities

Exception Formatting

Format complete exception tracebacks as strings with variable contexts for each frame.

def format_exc(
    e: Optional[Exception] = None,
    num_skipped_frames: int = 0,
    fmt: Optional[Format] = None,
    for_file: Optional[TextIO] = None,
) -> str:
    """
    Format exception traceback as a string with variable contexts.
    
    Parameters:
    - e: Exception to format (uses current exception if None)
    - num_skipped_frames: Number of frames to skip from the bottom of the stack
    - fmt: Format configuration (uses default_format if None)
    - for_file: Target file for color detection (uses stderr if None)
    
    Returns:
    Complete formatted traceback string with variables
    """

Current Traceback Formatting

Format the current call stack as a traceback string with variable contexts.

def format_cur_tb(
    num_skipped_frames: int = 0,
    fmt: Optional[Format] = None,
    for_file: Optional[TextIO] = None,
) -> str:
    """
    Format current traceback as a string with variable contexts.
    
    Parameters:
    - num_skipped_frames: Number of frames to skip from the bottom of the stack
    - fmt: Format configuration (uses default_format if None)  
    - for_file: Target file for color detection (uses stderr if None)
    
    Returns:
    Complete formatted traceback string with variables
    """

Exception Line Iteration

Iterate through formatted exception traceback lines for streaming or custom processing.

def iter_exc_lines(
    e: Optional[Exception] = None,
    num_skipped_frames: int = 0,
    fmt: Optional[Format] = None,
    for_file: Optional[TextIO] = None,
) -> Iterator[str]:
    """
    Iterate through exception traceback lines with variable contexts.
    
    Parameters:
    - e: Exception to format (uses current exception if None)
    - num_skipped_frames: Number of frames to skip from the bottom of the stack
    - fmt: Format configuration (uses default_format if None)
    - for_file: Target file for color detection (uses stderr if None)
    
    Yields:
    Individual formatted traceback lines with variables
    """

Current Traceback Line Iteration

Iterate through current call stack lines for streaming or custom processing.

def iter_cur_tb_lines(
    num_skipped_frames: int = 0,
    fmt: Optional[Format] = None,
    for_file: Optional[TextIO] = None,
) -> Iterator[str]:
    """
    Iterate through current traceback lines with variable contexts.
    
    Parameters:
    - num_skipped_frames: Number of frames to skip from the bottom of the stack
    - fmt: Format configuration (uses default_format if None)
    - for_file: Target file for color detection (uses stderr if None)
    
    Yields:
    Individual formatted traceback lines with variables
    """

Variable Display Control

Functions to control how variables are displayed in tracebacks.

def skip(obj: Any) -> Optional[str]:
    """
    Variable printer that skips displaying the variable.
    
    Parameters:
    - obj: Variable object (ignored)
    
    Returns:
    None (variable will not be displayed)
    """

def hide(obj: Any) -> Optional[str]:  
    """
    Variable printer that hides variable value with placeholder.
    
    Parameters:
    - obj: Variable object (ignored)
    
    Returns:
    String '...hidden...' as placeholder
    """

def show(obj: Any) -> Optional[str]:
    """
    Default variable printer marker (never called directly).
    
    Parameters:
    - obj: Variable object (ignored)
    
    Raises:
    NotImplementedError (used only for comparison)
    """

Default Format Configuration

Global default format instance with sensible defaults and security-conscious variable filtering.

default_format: Format

The default_format is a pre-configured Format instance used when no explicit format is provided. It includes built-in security filtering to hide sensitive variables like passwords, tokens, and API keys.

Usage Examples

Basic Exception Formatting

from traceback_with_variables import format_exc

try:
    x = 42
    y = "hello" 
    result = x / 0
except Exception as e:
    formatted = format_exc(e)
    print(formatted)

Custom Formatting with Configuration

from traceback_with_variables import format_exc, Format, ColorSchemes

# Create custom format
fmt = Format(
    max_value_str_len=500,
    color_scheme=ColorSchemes.synthwave,
    before=2,  # Show 2 lines before error
    after=1    # Show 1 line after error
)

try:
    data = {"key": "value", "number": 123}
    result = data["missing_key"]
except Exception as e:
    formatted = format_exc(e, fmt=fmt)
    print(formatted)

Streaming Traceback Processing

from traceback_with_variables import iter_exc_lines

try:
    items = [1, 2, 3]
    index = 5
    value = items[index]
except Exception as e:
    # Process traceback line by line
    for line in iter_exc_lines(e):
        # Custom processing (e.g., logging, filtering)
        if "items" in line:
            print(f"IMPORTANT: {line}")
        else:
            print(line)

Current Traceback Capture

from traceback_with_variables import format_cur_tb

def debug_function():
    local_var = "debug_value"
    nested_data = {"a": 1, "b": [1, 2, 3]}
    
    # Capture current call stack
    traceback_str = format_cur_tb(num_skipped_frames=0)
    print("Current call stack:")
    print(traceback_str)

debug_function()

Install with Tessl CLI

npx tessl i tessl/pypi-traceback-with-variables

docs