offline-debug 0.1.1__tar.gz → 0.2.1__tar.gz

{offline_debug-0.1.1 → offline_debug-0.2.1}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.3
 Name: offline-debug
-Version: 0.1.1
+Version: 0.2.1
 Summary: Debug exceptions offline by saving them to a dump and raising them at a later point.
 Author: Itai Elidan
 Author-email: Itai Elidan <itaielidan@gmail.com>
 Requires-Dist: typing-extensions>=4.15.0
-Requires-Python: >=3.12
+Requires-Python: >=3.12, <3.14
 Project-URL: Homepage, https://github.com/INTODAN/offline-debug
 Project-URL: Repository, https://github.com/INTODAN/offline-debug
 Description-Content-Type: text/markdown
@@ -16,43 +16,60 @@ Description-Content-Type: text/markdown
 [![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 <package>`
-  - 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 <package>`
+    - Run tests: `uv run pytest`
+
+

{offline_debug-0.1.1 → offline_debug-0.2.1}/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 <package>`
-  - 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 <package>`
+    - Run tests: `uv run pytest`
+
+

offline_debug-0.2.1/offline_debug/__init__.py

@@ -0,0 +1,7 @@
+"""Tool for serializing and reconstructing Python exceptions with full stack traces."""
+
+from ._inner.load_traceback import load_traceback, parse_traceback
+from ._inner.models import ExceptionData, FrameData
+from ._inner.save_traceback import save_traceback
+
+__all__ = ["ExceptionData", "FrameData", "load_traceback", "parse_traceback", "save_traceback"]

{offline_debug-0.1.1 → offline_debug-0.2.1}/offline_debug/_inner/load_traceback.py

@@ -7,19 +7,18 @@ import types
 from io import BytesIO
 from pathlib import Path
 from types import CodeType
-from typing import Never
 
 from offline_debug._inner.c_api import (
     create_frame,
     link_frame,
 )
 from offline_debug._inner.models import (
-    _ExceptionData,
-    _FrameData,
+    ExceptionData,
+    FrameData,
 )
 
 
-def _reconstruct_exc_data(data: _ExceptionData) -> BaseException:
+def _reconstruct_exc_data(data: ExceptionData) -> BaseException:
     """
     Recursively reconstruct an exception from its serialized data.
 
@@ -37,26 +36,25 @@ def _reconstruct_exc_data(data: _ExceptionData) -> BaseException:
         msg = f"Expected BaseException, but got {type(exc).__name__}"
         raise TypeError(msg)
 
-    reconstructed_frames: list[tuple[types.FrameType, _FrameData]] = []
+    reconstructed_frames: list[tuple[types.FrameType, FrameData]] = []
     for f_data in data.tb_frames:
         code: CodeType = marshal.loads(f_data.code)  # noqa: S302
 
-        # In Python 3.11 and 3.12, accessing f_locals on a frame created via
+        # In Python 3.11+, accessing f_locals on a frame created via
         # PyFrame_New for optimized code (functions) causes a segmentation fault
         # because the internal 'fast' locals array is not initialized.
         # As a workaround, we create a 'non-optimized' version of the code object
         # by compiling a dummy string. This ensures the bytecode is safe
         # (no LOAD_FAST) while preserving metadata like name and filename.
-        if sys.version_info < (3, 13):
-            # A simple module-level code object never has fast locals.
-            # Since the source is empty, no optimized locals will be created.
-            # Instead, python will go to the unoptimized dictionary we set under frame_locals later.
-            unoptimized_code = compile("", code.co_filename, "exec")
-            code = unoptimized_code.replace(
-                co_name=code.co_name,
-                co_firstlineno=code.co_firstlineno,
-                co_qualname=code.co_qualname,
-            )
+        # A simple module-level code object never has fast locals.
+        # Since the source is empty, no optimized locals will be created.
+        # Instead, python will go to the unoptimized dictionary we set under frame_locals later.
+        unoptimized_code = compile("", code.co_filename, "exec")
+        code = unoptimized_code.replace(
+            co_name=code.co_name,
+            co_firstlineno=code.co_firstlineno,
+            co_qualname=code.co_qualname,
+        )
 
         # PyFrame_New returns a new reference to a PyFrameObject.
         if f_data.module_name:
@@ -92,17 +90,22 @@ def _reconstruct_exc_data(data: _ExceptionData) -> BaseException:
     return exc
 
 
-def load_traceback(file: Path | BytesIO) -> Never:
-    """Load an exception and its traceback from a file and raise it."""
+def parse_traceback(file: Path | BytesIO) -> ExceptionData:
     if isinstance(file, Path):
         with file.open("rb") as f:
             data = pickle.load(f)  # noqa: S301
     else:
         data = pickle.load(file)  # noqa: S301
 
-    if not isinstance(data, _ExceptionData):
+    if not isinstance(data, ExceptionData):
         msg = f"Expected _ExceptionData, but got {type(data).__name__}"
         raise TypeError(msg)
+    return data
+
+
+def load_traceback(file: Path | BytesIO, should_raise: bool = True) -> BaseException:  # noqa: FBT001, FBT002
+    """Load an exception and its traceback from a file and raise it."""
+    data = parse_traceback(file)
 
     exc = _reconstruct_exc_data(data)
 
@@ -126,4 +129,6 @@ def load_traceback(file: Path | BytesIO) -> Never:
         )
 
     exc = exc.with_traceback(tb_chain)
-    raise exc
+    if should_raise:
+        raise exc
+    return exc

{offline_debug-0.1.1 → offline_debug-0.2.1}/offline_debug/_inner/models.py

@@ -7,7 +7,7 @@ from typing import Any
 
 
 @dataclass
-class _FrameData:
+class FrameData:
     """Serialized data for a single stack frame."""
 
     code: bytes
@@ -20,10 +20,10 @@ class _FrameData:
 
 
 @dataclass
-class _ExceptionData:
+class ExceptionData:
     """Serialized data for an exception and its traceback."""
 
     exc_pickle: bytes
-    tb_frames: list[_FrameData]
-    cause: _ExceptionData | None = None
-    context: _ExceptionData | None = None
+    tb_frames: list[FrameData]
+    cause: ExceptionData | None = None
+    context: ExceptionData | None = None

{offline_debug-0.1.1 → offline_debug-0.2.1}/offline_debug/_inner/save_traceback.py

@@ -6,7 +6,7 @@ import types
 from io import BytesIO
 from pathlib import Path
 
-from offline_debug._inner.models import _ExceptionData, _FrameData
+from offline_debug._inner.models import ExceptionData, FrameData
 
 # Internal attributes that are either unpicklable or redundant in a new process.
 # We exclude these specifically because they are automatically recreated
@@ -41,9 +41,9 @@ def _filter_dict(d: dict) -> dict:
     return result
 
 
-def _serialize_exc_data(exc: BaseException) -> _ExceptionData:
+def _serialize_exc_data(exc: BaseException) -> ExceptionData:
     """Recursively serialize exception data into dataclasses."""
-    tb_frames: list[_FrameData] = []
+    tb_frames: list[FrameData] = []
     curr_tb = exc.__traceback__
     while curr_tb:
         f = curr_tb.tb_frame
@@ -58,7 +58,7 @@ def _serialize_exc_data(exc: BaseException) -> _ExceptionData:
                 mod_name = spec.name
 
         tb_frames.append(
-            _FrameData(
+            FrameData(
                 code=marshal.dumps(f.f_code),
                 globals=_filter_dict(f.f_globals),
                 locals=_filter_dict(f.f_locals),
@@ -77,7 +77,7 @@ def _serialize_exc_data(exc: BaseException) -> _ExceptionData:
             RuntimeError(f"Unpicklable exception {type(exc).__name__}: {exc!s}")
         )
 
-    return _ExceptionData(
+    return ExceptionData(
         exc_pickle=exc_pickle,
         tb_frames=tb_frames,
         cause=_serialize_exc_data(exc.__cause__) if exc.__cause__ else None,
@@ -85,9 +85,12 @@ def _serialize_exc_data(exc: BaseException) -> _ExceptionData:
     )
 
 
-def save_traceback(exc: BaseException, file: Path | BytesIO) -> None:
+def save_traceback(exc: BaseException, file: Path | BytesIO | None) -> ExceptionData:
     """Serialize an exception and its traceback to a file."""
     data = _serialize_exc_data(exc)
+    if file is None:
+        return data
+
     if isinstance(file, Path):
         with file.open("wb") as f:
             pickle.dump(data, f)
@@ -96,3 +99,4 @@ def save_traceback(exc: BaseException, file: Path | BytesIO) -> None:
     else:
         msg = f"Unexpected type for file {type(file).__name__}"
         raise TypeError(msg)
+    return data

{offline_debug-0.1.1 → offline_debug-0.2.1}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "offline-debug"
-version = "0.1.1"
+version = "0.2.1"
 description = "Debug exceptions offline by saving them to a dump and raising them at a later point."
 readme = "README.md"
 authors = [
     { name = "Itai Elidan", email = "itaielidan@gmail.com" }
 ]
-requires-python = ">=3.12"
+requires-python = ">=3.12, <3.14"
 dependencies = [
     "typing-extensions>=4.15.0",
 ]

offline_debug-0.1.1/offline_debug/__init__.py

@@ -1,6 +0,0 @@
-"""Tool for serializing and reconstructing Python exceptions with full stack traces."""
-
-from ._inner.load_traceback import load_traceback
-from ._inner.save_traceback import save_traceback
-
-__all__ = ["load_traceback", "save_traceback"]