or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-interface.mdcolor-system.mdconfiguration.mdcore-formatting.mddefault-hooks.mdglobal-hooks.mdindex.mdprinting.mdutilities.md
tile.json

tessl/pypi-traceback-with-variables

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/traceback-with-variables@2.2.x

To install, run

npx @tessl/cli install tessl/pypi-traceback-with-variables@2.2.0

index.mddocs/

Traceback with Variables

A Python debugging library that enhances exception tracebacks by automatically including local variable values and contexts for each frame in the stack trace. Provides multiple output formats including colorful console printing, file logging, and integration with standard Python logging systems, with built-in support for Jupyter notebooks and IPython environments.

Package Information

  • Package Name: traceback-with-variables
  • Language: Python
  • Installation: pip install traceback-with-variables
  • Python Version: >=3.6
  • Dependencies: None (zero dependencies)

Core Imports

import traceback_with_variables

Common imports for direct usage:

from traceback_with_variables import print_exc, Format, printing_exc
from traceback_with_variables import default_format as fmt

The fmt alias provides convenient access to the global default format configuration:

from traceback_with_variables import fmt  # Short alias for default_format

# Modify global formatting for all subsequent traceback calls
fmt.max_value_str_len = 500
fmt.before = 1
fmt.after = 1

Auto-activation imports:

# Auto-activate in any environment
import traceback_with_variables.activate_by_import

# Auto-activate in Python (not Jupyter/IPython)  
import traceback_with_variables.activate_in_python_by_import

# Auto-activate in Jupyter/IPython only
import traceback_with_variables.activate_in_ipython_by_import

Basic Usage

Manual Exception Printing

from traceback_with_variables import print_exc

try:
    x = 42
    y = "hello"
    result = x / 0  # This will raise ZeroDivisionError
except Exception as e:
    print_exc(e)  # Print enhanced traceback with variables

Context Manager

from traceback_with_variables import printing_exc

x = 42
y = "hello"

with printing_exc():
    result = x / 0  # Enhanced traceback printed automatically

Global Hook Installation

from traceback_with_variables import global_print_exc

# Install global hook for all exceptions
global_print_exc()

# Now all unhandled exceptions show variables
x = 42
y = "hello"
result = x / 0  # Enhanced traceback displayed automatically

Simplest Usage (Auto-activation)

# Just import to auto-activate in any environment
import traceback_with_variables.activate_by_import

# All exceptions now show variables automatically
x = 42
y = "hello"  
result = x / 0  # Enhanced traceback displayed

Architecture

The library uses a modular architecture centered around formatting configuration:

  • Format: Central configuration class controlling all aspects of traceback formatting
  • Core Functions: Low-level traceback processing and formatting engine
  • Print Functions: High-level interfaces for different output scenarios
  • Global Hooks: Integration with Python's exception handling system
  • Color System: ANSI terminal color support with auto-detection
  • Auto-activation: Zero-configuration import-based activation

Capabilities

Core Formatting and Display

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

def format_exc(e=None, num_skipped_frames=0, fmt=None, for_file=None): ...
def format_cur_tb(num_skipped_frames=0, fmt=None, for_file=None): ...
def iter_exc_lines(e=None, num_skipped_frames=0, fmt=None, for_file=None): ...
def iter_cur_tb_lines(num_skipped_frames=0, fmt=None, for_file=None): ...
def skip(obj): ...
def hide(obj): ...
def show(obj): ...
default_format: Format

Core Formatting

Printing and Context Management

High-level printing functions and context managers for displaying enhanced tracebacks to various output destinations including files, loggers, and standard streams.

def print_exc(e=None, num_skipped_frames=0, fmt=None, file_=sys.stderr): ...
def print_cur_tb(num_skipped_frames=0, fmt=None, file_=sys.stderr): ...
def printing_exc(reraise=True, file_=sys.stderr, skip_cur_frame=False, fmt=None): ...
def prints_exc(func=None, file_=sys.stderr, fmt=None): ...

Printing and Context Management

Configuration and Formatting

Comprehensive formatting configuration system with customizable output options, color schemes, variable filtering, and display preferences.

class Format:
    def __init__(
        self,
        max_value_str_len=1000,
        ellipsis_rel_pos=0.7,
        max_exc_str_len=10000,
        objects_details=1,
        ellipsis_='...',
        before=0,
        after=0,
        color_scheme=None,
        skip_files_except=None,
        brief_files_except=None,
        custom_var_printers=None
    ): ...

Configuration and Formatting

Global Exception Hooks

System-level integration that replaces Python's default exception handling with enhanced traceback display, supporting both standard Python and IPython/Jupyter environments.

def global_print_exc(fmt=None): ...
def global_print_exc_in_ipython(fmt=None): ...
def in_ipython() -> bool: ...
def is_ipython_global(name: str, type_: Type, filename: str, is_global: bool) -> bool: ...

Global Exception Hooks

Color and Terminal Support

ANSI color system with automatic terminal capability detection and pre-defined color schemes for different environments and preferences.

class ColorScheme: ...
class ColorSchemes: ...
def supports_ansi(file_): ...

Color and Terminal Support

Default Global Hooks and Auto-activation

Pre-configured global exception hooks and auto-activation modules that provide zero-configuration enhanced tracebacks with sensible defaults including environment-appropriate variable filtering.

def default_global_print_exc() -> None: ...
def default_global_print_exc_in_ipython() -> None: ...
def default_global_print_exc_in_all() -> None: ...

Default Global Hooks and Auto-activation

Command Line Interface

Command-line tool for running Python scripts with enhanced traceback display, supporting all formatting options and providing a complete wrapper for script execution with variable contexts.

def run_script(path: Path, argv: List[str], fmt: Format) -> int: ...
def main() -> int: ...
def parse_args() -> Tuple[argparse.Namespace, Path, List[str]]: ...
class ParseError(RuntimeError): ...

Command Line Interface

Utilities and Aliases

Utility functions and module aliasing system for enhanced convenience, including filesystem-based module aliases for shorter imports and ANSI color code utilities.

def create_alias(alias: str, module_name: str) -> None: ...
def rm_alias(alias: str) -> None: ...
def create_tb_alias() -> None: ...
def rm_tb_alias() -> None: ...
def to_ansi(str_: str) -> str: ...

Utilities and Aliases

Types

# Type aliases for configuration
Patterns = Union[None, str, List[str]]  # File filter patterns
ShouldPrint = Callable[[str, Type, str, bool], bool]  # Variable filter function  
VarFilterItem = Union[str, Type, ShouldPrint]  # Single variable filter
VarFilter = Union[VarFilterItem, List[VarFilterItem]]  # Complete variable filter
Print = Callable[[Any], Optional[str]]  # Custom variable printer function
VarPrinters = List[Tuple[ShouldPrint, Print]]  # Filter-printer pairs

# Main configuration class
class Format:
    max_value_str_len: int
    ellipsis_rel_pos: float  
    max_exc_str_len: int
    objects_details: int
    ellipsis_: str
    before: int
    after: int
    color_scheme: Optional[ColorScheme]
    skip_files_except: List[re.Pattern]
    brief_files_except: List[re.Pattern]
    custom_var_printers: VarPrinters
    
    @classmethod
    def add_arguments(cls, parser: argparse.ArgumentParser) -> None: ...
    
    @classmethod  
    def parse(cls, ns: argparse.Namespace) -> 'Format': ...
    
    def replace(self, **kwargs) -> 'Format': ...

# Color system classes
class ColorScheme:
    def __init__(
        self,
        common: str,
        file_: str, 
        line_num: str,
        func_name: str,
        func_snippet: str,
        name: str,
        value: str,
        exc_class: str,
        exc_text: str,
        end: str
    ): ...

class ColorSchemes:
    auto: None
    none: ColorScheme
    common: ColorScheme  
    synthwave: ColorScheme
    nice: ColorScheme

# Logger adapter for file-like interface
class LoggerAsFile:
    def __init__(self, logger: logging.Logger, separate_lines: bool = False): ...
    def write(self, text: str) -> None: ...
    def flush(self) -> None: ...