offline-debug 0.2.0

Debug exceptions offline by saving them to a dump and raising them at a later point.

Traceback Serializer Project (offline-debug)

Overview

A Python package for high-fidelity serialization and deserialization of exceptions and their complete tracebacks. Unlike other solutions, offline-debug reconstructs actual types.FrameType objects using the Python C API, ensuring that re-raised exceptions look and feel genuine to debuggers and introspection tools.

Core Functions

• save_traceback(exc: BaseException, file: Path | BytesIO): Serializes an exception, its traceback, and all picklable local/global variables to a binary file or buffer.
• load_traceback(file: Path | BytesIO) -> Never: Loads the serialized state, reconstructs the exception and its full traceback chain (including __cause__ and __context__), and raises it.

Usage Example

to get started, install with:
pip install offline-debug or uv add offline-debug

from pathlib import Path
from offline_debug import save_traceback, load_traceback

try:
    # Code that might fail
    some_complex_operation()
except Exception as e:
    save_traceback(e, Path("crash_report.dump"))

# To debug or re-examine later:
load_traceback(Path("crash_report.dump"))

Technical Implementation

• True Frame Reconstruction: Uses ctypes to call PyFrame_New from the Python C API. This creates real frame objects which are required for a valid types.TracebackType.
• Python 3.13 Compatibility: Leverages PEP 667 features where f_locals is a write-through proxy, allowing for accurate local variable restoration.
• Support python 3.12 as well
• Robust Serialization:
  • pickle is used for exceptions and variables.
  • marshal is used for code objects.
  • Non-picklable items are gracefully handled by storing their repr.

Development & Tooling

• Package Manager: uv
• Minimum Python: 3.12
• Testing: pytest
• Commands:
  • Add dependencies: uv add <package>
  • Run tests: uv run pytest