offline-debug 0.1.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: Exception, file_path: str): Serializes an exception, its traceback, and all picklable local/global variables to a binary file.
• load_traceback(file_path: str) -> typing.Never: Loads the serialized state, reconstructs the exception and its full traceback chain (including __cause__ and __context__), and raises it.

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

Usage Example

from offline_debug import save_traceback, load_traceback

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

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