From 300b52b6f2ded97d385088bb9c8f48b76892b8b0 Mon Sep 17 00:00:00 2001 From: Itai Elidan Date: Wed, 15 Apr 2026 15:20:34 +0300 Subject: [PATCH 1/2] updated readme --- README.md | 63 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 40 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 1336a2c..04335ae 100644 --- a/README.md +++ b/README.md @@ -4,43 +4,60 @@ [![Tests](https://github.com/INTODAN/offline-debug/actions/workflows/ci.yml/badge.svg)](https://github.com/INTODAN/offline-debug/actions) [![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/INTODAN/offline-debug) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) -[![Ty checked](https://img.shields.io/badge/ty-checked-blue.svg)](https://github.com/intodan/ty) +[![Ty checked](https://img.shields.io/badge/ty-checked-blue.svg)](https://github.com/astral-sh/ty) ## 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. + +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 ` - - Run tests: `uv run pytest` +- `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` + ```python +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, "crash_report.dump") + save_traceback(e, Path("crash_report.dump")) # To debug or re-examine later: -load_traceback("crash_report.dump") +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 ` + - Run tests: `uv run pytest` + + From f1ec3b2ad5322aedaf9ea75fe7ae9cea93a51936 Mon Sep 17 00:00:00 2001 From: Itai Elidan Date: Wed, 15 Apr 2026 15:21:29 +0300 Subject: [PATCH 2/2] major version bump --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index d0c6bad..8408381 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "offline-debug" -version = "0.1.1" +version = "0.2.0" description = "Debug exceptions offline by saving them to a dump and raising them at a later point." readme = "README.md" authors = [