offline-debug 0.1.0b1__tar.gz → 0.2.0__tar.gz

offline_debug-0.2.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.3
+Name: offline-debug
+Version: 0.2.0
+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
+Project-URL: Homepage, https://github.com/INTODAN/offline-debug
+Project-URL: Repository, https://github.com/INTODAN/offline-debug
+Description-Content-Type: text/markdown
+
+# Traceback Serializer Project (`offline-debug`)
+
+[![PyPI version](https://img.shields.io/pypi/v/offline-debug.svg)](https://pypi.org/project/offline-debug/)
+[![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/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.
+
+## 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`
+
+```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, 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`
+
+

offline_debug-0.2.0/README.md

@@ -0,0 +1,63 @@
+# Traceback Serializer Project (`offline-debug`)
+
+[![PyPI version](https://img.shields.io/pypi/v/offline-debug.svg)](https://pypi.org/project/offline-debug/)
+[![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/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.
+
+## 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`
+
+```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, 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`
+
+

offline_debug-0.2.0/offline_debug/__init__.py

@@ -0,0 +1,6 @@
+"""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"]

offline_debug-0.2.0/offline_debug/_inner/c_api/__init__.py

@@ -0,0 +1,4 @@
+from ._create_frame import create_frame
+from ._link_frame import link_frame
+
+__all__ = ["create_frame", "link_frame"]

offline_debug-0.2.0/offline_debug/_inner/c_api/_create_frame.py

@@ -0,0 +1,93 @@
+"""
+Abstraction of the CPython api for creating a traceback frame object.
+
+The reason we have to implement it, is that cpython doesn't expose
+the api to create a FrameType using pure python.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import sys
+from functools import cache
+from types import CodeType, FrameType
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import _ctypes
+
+
+@cache
+def _get_py_frame_new() -> ctypes._NamedFuncPointer:
+    """Get the PyFrame_New C function configured with ctypes."""
+    func: ctypes._NamedFuncPointer = ctypes.pythonapi.PyFrame_New
+    func.argtypes = (
+        ctypes.c_void_p,  # PyThreadState *tstate
+        ctypes.py_object,  # PyCodeObject *code
+        ctypes.py_object,  # PyObject *globals
+        ctypes.py_object,  # PyObject *locals
+    )
+    func.restype = ctypes.py_object
+
+    def errcheck[T](
+        result: T | None,
+        _func: _ctypes.CFuncPtr,
+        _args: tuple[Any, ...],
+    ) -> T:  # pragma: no cover
+        if not result:
+            msg = "failed to create a new frame while calling"
+            raise RuntimeError(msg)
+        return result
+
+    func.errcheck = errcheck
+    return func
+
+
+@cache
+def _get_py_thread_state_get() -> ctypes._NamedFuncPointer:
+    """Get the PyThreadState_Get C function configured with ctypes."""
+    func = ctypes.pythonapi.PyThreadState_Get
+    func.argtypes = ()
+    func.restype = ctypes.c_void_p
+
+    def errcheck[T](
+        result: T | None, _func: _ctypes.CFuncPtr, _args: tuple[Any, ...]
+    ) -> T:  # pragma: no cover
+        if not result:
+            msg = "failed to get the current thread state"
+            raise RuntimeError(msg)
+        return result
+
+    func.errcheck = errcheck
+    return func
+
+
+def create_frame(
+    code: CodeType,
+    frame_globals: dict[str, Any],
+    frame_locals: dict[str, Any],
+    thread_state: int | None = None,
+) -> FrameType:
+    """
+    Create a FrameType object using the received parameters.
+
+    If the thread state received is None, use the current thread state automatically.
+    """
+    py_frame_new = _get_py_frame_new()
+    py_thread_state_get = _get_py_thread_state_get()
+
+    if thread_state is None:
+        thread_state = py_thread_state_get()
+
+    frame: FrameType = py_frame_new(thread_state, code, frame_globals, frame_locals)
+
+    # In 3.13+, PEP 667 allows safe write-through access to locals.
+    # py_frame_new ignores the frame_locals argument,
+    # and must be assigned after the frame's creation in 3.13+
+    if sys.version_info >= (3, 13) and frame_locals:
+        frame.f_locals.update(frame_locals)
+
+    if not isinstance(frame, FrameType):
+        msg = f"Expected types.FrameType, but got {type(frame).__name__}"
+        raise TypeError(msg)
+    return frame

offline_debug-0.2.0/offline_debug/_inner/c_api/_link_frame.py

@@ -0,0 +1,128 @@
+"""
+Link 2 frames together, so that a linked chain of frames will eventually create a traceback.
+
+The native cpython api does not expose a way to link frames together
+"""
+
+from __future__ import annotations
+
+import ctypes
+import sys
+from functools import cache
+from typing import TYPE_CHECKING, Any
+
+from ._create_frame import create_frame
+
+if TYPE_CHECKING:
+    import _ctypes
+    from types import FrameType
+
+
+@cache
+def _get_py_incref() -> ctypes._NamedFuncPointer:
+    """
+    Get the Py_IncRef C function configured with ctypes.
+
+    Py_IncRef increases the reference count of an object.
+    We call this function when we want to "own" an object,
+    meaning that the object won't be deleted while we are still using it.
+
+    In our case, we use the function to hold the f_back reference to link between frames.
+    """
+    func: ctypes._NamedFuncPointer = ctypes.pythonapi.Py_IncRef
+    func.argtypes = (ctypes.py_object,)
+    func.restype = None
+
+    def errcheck[T](
+        result: T,
+        _func: _ctypes.CFuncPtr,
+        _args: tuple[Any, ...],
+    ) -> T:  # pragma: no cover
+        if result is not None:
+            msg = f"Unexpected {result=}, expected None."
+            raise TypeError(msg)
+        return result
+
+    func.errcheck = errcheck
+    return func
+
+
+def link_frame(frame: FrameType, f_back: FrameType) -> None:
+    """Link a frame to its parent frame using the discovered offset."""
+    _f_back_offset = _get_f_back_offset()
+    if _f_back_offset is None:
+        msg = "Failed discovering the offset for the f_back property."
+        raise RuntimeError(msg)
+
+    # In Python, setting f_back means the child frame now owns a reference
+    # to the parent frame. We must increment the reference count of the
+    # parent to reflect this.
+    py_incref = _get_py_incref()
+    py_incref(f_back)
+
+    # Use ctypes to write the address of the back frame into the discovered offset.
+    # We find the address of the f_back property, by finding the start of the frame struct,
+    # Then moving to the f_back offset in the struct.
+    ptr = ctypes.c_void_p.from_address(id(frame) + _f_back_offset)
+    ptr.value = id(f_back)
+
+
+@cache
+def _get_f_back_offset() -> int | None:
+    """
+    Dynamically discover the memory offset of f_back in PyFrameObject.
+
+    The offset for the f_back can change between python versions and operating systems,
+    So we find the location of the f_back property dynamically.
+    The general idea of the algorithm is to create a mock frame,
+    And scanning its memory until we hit the f_back property field.
+    We know we hit the f_back property by
+    setting the value of each slot in the memeory to another frame, and checking if the
+    f_back property was populated after changing that memory location.
+    """
+    try:
+        # Compile an empty code object that we can use to create a frame.
+        code = compile("pass", "<discovery>", "exec")
+
+        # Create 2 frames that we can attempt linking between to find the f_back property.
+        frame = create_frame(code=code, frame_globals={}, frame_locals={})
+        f_back_frame = create_frame(code=code, frame_globals={}, frame_locals={})
+
+        ptr_size = ctypes.sizeof(ctypes.c_void_p)
+        jump_size = ptr_size
+
+        ref_count_size = ptr_size  # The amount of references to the object
+        type_object_size = ptr_size
+        frame_header_size = ref_count_size + type_object_size
+        start = frame_header_size  # The header does not contain the f_back property
+
+        frame_size = sys.getsizeof(frame)
+
+        # We scan the memory ptr_size bytes forward, so we decrease it from the end.
+        # Since we want the last memory slot to be scanned as well,
+        # we add +1 because the for loop is exclusive to the end.
+        end = frame_size - ptr_size + 1
+
+        # We start scanning after the PyObject header (refcnt + type).
+        for offset in range(start, end, jump_size):
+            candidate_f_back_address = id(frame) + offset
+            candidate_f_back_ptr = ctypes.c_ssize_t.from_address(candidate_f_back_address)
+
+            # f_back is initially NULL (0) in a newly created frame,
+            # since no other frames are linked to it.
+            if candidate_f_back_ptr.value != 0:
+                continue
+
+            candidate_f_back_ptr.value = id(f_back_frame)
+            # If reading f_back via Python now returns our target, we found it.
+            if frame.f_back is f_back_frame:
+                # Success, but we must restore 0 so we don't mess up refcounts
+                # when 'frame' is eventually garbage collected.
+                candidate_f_back_ptr.value = 0
+                return offset
+            # Restore to 0 if this wasn't the correct offset.
+            candidate_f_back_ptr.value = 0
+
+    except Exception:  # noqa: BLE001
+        return None
+    return None

offline_debug-0.2.0/offline_debug/_inner/load_traceback.py

@@ -0,0 +1,129 @@
+"""Load traceback object from a dump file."""
+
+import marshal
+import pickle
+import sys
+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,
+)
+
+
+def _reconstruct_exc_data(data: _ExceptionData) -> BaseException:
+    """
+    Recursively reconstruct an exception from its serialized data.
+
+    Note on Python Locals:
+    Python uses two ways to store local variables:
+    1. "Slow" locals: A dictionary used for module-level code and class definitions.
+    2. "Fast" locals: A fixed-size array used for functions. This is faster than
+       dictionary lookups because variables are accessed by index.
+
+    During reconstruction, we must explicitly synchronize these because PyFrame_New
+    does not automatically populate the "fast" locals array from a dictionary.
+    """
+    exc: BaseException = pickle.loads(data.exc_pickle)  # noqa: S301
+    if not isinstance(exc, BaseException):
+        msg = f"Expected BaseException, but got {type(exc).__name__}"
+        raise TypeError(msg)
+
+    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
+        # 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,
+            )
+
+        # PyFrame_New returns a new reference to a PyFrameObject.
+        if f_data.module_name:
+            f_data.globals["__name__"] = f_data.module_name
+
+        frame: types.FrameType = create_frame(
+            code=code, frame_globals=f_data.globals, frame_locals=f_data.locals
+        )
+
+        if reconstructed_frames:
+            # link the frame back to the previously constructed frame.
+            link_frame(frame, reconstructed_frames[-1][0])
+
+        reconstructed_frames.append((frame, f_data))
+
+    tb_next: types.TracebackType | None = None
+    for frame, f_data in reversed(reconstructed_frames):
+        tb = types.TracebackType(
+            tb_next=tb_next,
+            tb_frame=frame,
+            tb_lasti=f_data.lasti,
+            tb_lineno=f_data.lineno,
+        )
+        tb_next = tb
+
+    exc = exc.with_traceback(tb_next)
+
+    if data.cause:
+        exc.__cause__ = _reconstruct_exc_data(data.cause)
+    if data.context:
+        exc.__context__ = _reconstruct_exc_data(data.context)
+
+    return exc
+
+
+def load_traceback(file: Path | BytesIO) -> Never:
+    """Load an exception and its traceback from a file and raise it."""
+    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):
+        msg = f"Expected _ExceptionData, but got {type(data).__name__}"
+        raise TypeError(msg)
+
+    exc = _reconstruct_exc_data(data)
+
+    current_frames: list[types.FrameType] = []
+    curr: types.FrameType | None = sys._getframe(1)  # noqa: SLF001
+    while curr:
+        current_frames.append(curr)
+        curr = curr.f_back
+
+    if exc.__traceback__ and current_frames:
+        reconstructed_outer = exc.__traceback__.tb_frame
+        link_frame(reconstructed_outer, current_frames[0])
+
+    tb_chain: types.TracebackType | None = exc.__traceback__
+    for frame in current_frames:
+        tb_chain = types.TracebackType(
+            tb_next=tb_chain,
+            tb_frame=frame,
+            tb_lasti=frame.f_lasti,
+            tb_lineno=frame.f_lineno,
+        )
+
+    exc = exc.with_traceback(tb_chain)
+    raise exc

offline_debug-0.2.0/offline_debug/_inner/models.py

@@ -0,0 +1,29 @@
+"""Functions for serializing and reconstructing exceptions with their tracebacks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class _FrameData:
+    """Serialized data for a single stack frame."""
+
+    code: bytes
+    globals: dict[str, Any]
+    locals: dict[str, Any]
+    lasti: int
+    lineno: int
+    stack_depth: int
+    module_name: str | None = None
+
+
+@dataclass
+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

offline_debug-0.2.0/offline_debug/_inner/save_traceback.py

@@ -0,0 +1,98 @@
+"""Save traceback to a file."""
+
+import marshal
+import pickle
+import types
+from io import BytesIO
+from pathlib import Path
+
+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
+# when the new frame is initialized or when the module is imported.
+_INTERNAL_ATTRIBUTES_TO_SKIP = ("__builtins__", "__doc__", "__loader__", "__package__", "__spec__")
+
+
+def _get_stack_depth(frame: types.FrameType) -> int:
+    """Calculate the depth of the current stack frame."""
+    depth = 0
+    curr: types.FrameType | None = frame
+    while curr:
+        depth += 1
+        curr = curr.f_back
+    return depth
+
+
+def _filter_dict(d: dict) -> dict:
+    """Filter dictionary to include only picklable items."""
+    result = {}
+    for k, v in d.items():
+        if k in _INTERNAL_ATTRIBUTES_TO_SKIP:
+            continue
+        try:
+            # We must verify if the value is picklable because many globals
+            # (like open file handles, database connections, or modules)
+            # cannot be saved to disk.
+            pickle.dumps(v)
+            result[k] = v
+        except Exception:  # noqa: BLE001
+            result[k] = f"<unpicklable {type(v).__name__}: {v!r}>"
+    return result
+
+
+def _serialize_exc_data(exc: BaseException) -> _ExceptionData:
+    """Recursively serialize exception data into dataclasses."""
+    tb_frames: list[_FrameData] = []
+    curr_tb = exc.__traceback__
+    while curr_tb:
+        f = curr_tb.tb_frame
+
+        # Try to get the "real" module name. If the module was run as a script,
+        # __name__ will be "__main__", but __spec__.name might contain the
+        # actual module path if run via `python -m`.
+        mod_name = f.f_globals.get("__name__")
+        if mod_name == "__main__":
+            spec = f.f_globals.get("__spec__")
+            if spec and hasattr(spec, "name"):
+                mod_name = spec.name
+
+        tb_frames.append(
+            _FrameData(
+                code=marshal.dumps(f.f_code),
+                globals=_filter_dict(f.f_globals),
+                locals=_filter_dict(f.f_locals),
+                lasti=curr_tb.tb_lasti,
+                lineno=curr_tb.tb_lineno,
+                stack_depth=_get_stack_depth(f),
+                module_name=mod_name,
+            )
+        )
+        curr_tb = curr_tb.tb_next
+
+    try:
+        exc_pickle = pickle.dumps(exc)
+    except Exception:  # noqa: BLE001
+        exc_pickle = pickle.dumps(
+            RuntimeError(f"Unpicklable exception {type(exc).__name__}: {exc!s}")
+        )
+
+    return _ExceptionData(
+        exc_pickle=exc_pickle,
+        tb_frames=tb_frames,
+        cause=_serialize_exc_data(exc.__cause__) if exc.__cause__ else None,
+        context=_serialize_exc_data(exc.__context__) if exc.__context__ else None,
+    )
+
+
+def save_traceback(exc: BaseException, file: Path | BytesIO) -> None:
+    """Serialize an exception and its traceback to a file."""
+    data = _serialize_exc_data(exc)
+    if isinstance(file, Path):
+        with file.open("wb") as f:
+            pickle.dump(data, f)
+    elif isinstance(file, BytesIO):
+        pickle.dump(data, file)
+    else:
+        msg = f"Unexpected type for file {type(file).__name__}"
+        raise TypeError(msg)

offline_debug-0.2.0/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "offline-debug"
+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 = [
+    { name = "Itai Elidan", email = "itaielidan@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "typing-extensions>=4.15.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/INTODAN/offline-debug"
+Repository = "https://github.com/INTODAN/offline-debug"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "D203", # One blank line before class
+    "D212", # Multi-line docstring summary should start at the first line
+    "COM812", # Trailing comma missing
+    "PLC0415", # import should be at top of file
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+    "S101", # Use of assert detected
+    "SLF001", # Private member accessed
+    "D103", # Missing docstring in public function
+    "ANN201", # Missing return type annotation for public function
+    "ANN001", # Missing type annotation for function argument
+    "PLW0603", # Using the global statement
+    "TRY003", # Avoid specifying long messages outside the exception class
+    "EM101", # Exception must not use a string literal
+]
+
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = ""
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.5.1",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.1.0",
+    "rich>=14.3.3",
+    "ruff>=0.15.8",
+    "ty>=0.0.27",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "if sys.version_info < \\(3, 13\\).*",
+    "if sys.version_info >= \\(3, 13\\).*",
+]

offline_debug-0.1.0b1/PKG-INFO

@@ -1,8 +0,0 @@
-Metadata-Version: 2.3
-Name: offline-debug
-Version: 0.1.0b1
-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.13

offline_debug-0.1.0b1/offline_debug/__init__.py

@@ -1,3 +0,0 @@
-from .serializer import save_traceback, load_traceback
-
-__all__ = ["save_traceback", "load_traceback"]

offline_debug-0.1.0b1/offline_debug/serializer.py

@@ -1,167 +0,0 @@
-import pickle
-import marshal
-import types
-import typing
-import ctypes
-import sys
-
-# Define C API for frame creation
-_py_frame_new = ctypes.pythonapi.PyFrame_New
-_py_frame_new.argtypes = (
-    ctypes.c_void_p,  # PyThreadState *tstate
-    ctypes.py_object,  # PyCodeObject *code
-    ctypes.py_object,  # PyObject *globals
-    ctypes.py_object,  # PyObject *locals
-)
-_py_frame_new.restype = ctypes.py_object
-
-_py_thread_state_get = ctypes.pythonapi.PyThreadState_Get
-_py_thread_state_get.restype = ctypes.c_void_p
-
-
-# Define ctypes structure to access f_back in PyFrameObject
-class _PyObject(ctypes.Structure):
-    _fields_ = [("ob_refcnt", ctypes.c_ssize_t), ("ob_type", ctypes.c_void_p)]
-
-
-class _PyFrameObject(ctypes.Structure):
-    _fields_ = [
-        ("ob_base", _PyObject),
-        ("f_back", ctypes.c_void_p),  # Pointer to previous frame
-    ]
-
-
-def _get_stack_depth(frame):
-    depth = 0
-    while frame:
-        depth += 1
-        frame = frame.f_back
-    return depth
-
-
-def _filter_dict(d: dict) -> dict:
-    """Filter dictionary to include only picklable items."""
-    result = {}
-    for k, v in d.items():
-        if k in ("__builtins__", "__doc__", "__loader__", "__package__", "__spec__"):
-            continue
-        try:
-            pickle.dumps(v)
-            result[k] = v
-        except Exception:
-            result[k] = f"<unpicklable {type(v).__name__}: {repr(v)}>"
-    return result
-
-
-def _serialize_exc_data(exc: BaseException) -> dict:
-    tb_frames = []
-    curr_tb = exc.__traceback__
-    while curr_tb:
-        f = curr_tb.tb_frame
-        tb_frames.append(
-            {
-                "code": marshal.dumps(f.f_code),
-                "globals": _filter_dict(f.f_globals),
-                "locals": _filter_dict(f.f_locals),
-                "lasti": curr_tb.tb_lasti,
-                "lineno": curr_tb.tb_lineno,
-                "stack_depth": _get_stack_depth(f),
-            }
-        )
-        curr_tb = curr_tb.tb_next
-
-    try:
-        exc_pickle = pickle.dumps(exc)
-    except Exception:
-        exc_pickle = pickle.dumps(
-            RuntimeError(f"Unpicklable exception {type(exc).__name__}: {str(exc)}")
-        )
-
-    return {
-        "exc_pickle": exc_pickle,
-        "tb_frames": tb_frames,
-        "cause": _serialize_exc_data(exc.__cause__) if exc.__cause__ else None,
-        "context": _serialize_exc_data(exc.__context__) if exc.__context__ else None,
-    }
-
-
-def save_traceback(exc: Exception, file_path: str):
-    """Serialize an exception and its traceback to a file."""
-    data = _serialize_exc_data(exc)
-    with open(file_path, "wb") as f:
-        pickle.dump(data, f)
-
-
-def _reconstruct_exc_data(data: dict) -> Exception:
-    exc = pickle.loads(data["exc_pickle"])
-
-    tstate = _py_thread_state_get()
-
-    reconstructed_frames = []
-    prev_frame = None
-    for f_data in data["tb_frames"]:
-        code = marshal.loads(f_data["code"])
-
-        frame = _py_frame_new(tstate, code, f_data["globals"], {})
-
-        if f_data["locals"]:
-            frame.f_locals.update(f_data["locals"])
-
-        if prev_frame:
-            frame_ptr = _PyFrameObject.from_address(id(frame))
-            frame_ptr.f_back = id(prev_frame)
-
-        reconstructed_frames.append((frame, f_data))
-        prev_frame = frame
-
-    tb_next = None
-    for frame, f_data in reversed(reconstructed_frames):
-        tb = types.TracebackType(
-            tb_next=tb_next,
-            tb_frame=frame,
-            tb_lasti=f_data["lasti"],
-            tb_lineno=f_data["lineno"],
-        )
-        tb_next = tb
-
-    exc = exc.with_traceback(tb_next)
-
-    if data["cause"]:
-        exc.__cause__ = _reconstruct_exc_data(data["cause"])
-    if data["context"]:
-        exc.__context__ = _reconstruct_exc_data(data["context"])
-
-    return exc
-
-
-def load_traceback(file_path: str) -> typing.Never:
-    """Load an exception and its traceback from a file and raise it."""
-    with open(file_path, "rb") as f:
-        data = pickle.load(f)
-
-    exc = _reconstruct_exc_data(data)
-
-    current_frames = []
-    curr = sys._getframe(1)
-    while curr:
-        current_frames.append(curr)
-        curr = curr.f_back
-
-    if exc.__traceback__ and current_frames:
-        reconstructed_outer = exc.__traceback__.tb_frame
-        caller_frame = current_frames[0]
-
-        frame_ptr = _PyFrameObject.from_address(id(reconstructed_outer))
-        frame_ptr.f_back = id(caller_frame)
-
-    tb_chain = exc.__traceback__
-    for frame in current_frames:
-        tb_chain = types.TracebackType(
-            tb_next=tb_chain,
-            tb_frame=frame,
-            tb_lasti=frame.f_lasti,
-            tb_lineno=frame.f_lineno,
-        )
-
-    exc = exc.with_traceback(tb_chain)
-    raise exc

offline_debug-0.1.0b1/pyproject.toml

@@ -1,26 +0,0 @@
-[project]
-name = "offline-debug"
-version = "0.1.0-beta1"
-description = "Debug exceptions offline by saving them to a dump and raising them at a later point."
-authors = [
-    { name = "Itai Elidan", email = "itaielidan@gmail.com" }
-]
-requires-python = ">=3.13"
-dependencies = [
-    "typing-extensions>=4.15.0",
-]
-
-[build-system]
-requires = ["uv_build"]
-build-backend = "uv_build"
-
-[tool.uv.build-backend]
-module-root = ""
-
-[dependency-groups]
-dev = [
-    "pytest>=9.0.2",
-    "pytest-cov>=7.1.0",
-    "ruff>=0.15.8",
-    "ty>=0.0.27",
-]