Add Stacktrace.reconstruct_exception()

Summary:
Adds a public `Stacktrace.reconstruct_exception()` method to the tintype API that reconstructs a real `BaseException` (with `__traceback__` and a wired `__cause__`/`__context__` chain) from a snapshot stacktrace. The name uses the verb `reconstruct` to make clear it synthesizes a new exception from the snapshot rather than returning the originally-thrown object. This consolidates exception-reconstruction logic that consumers (e.g. the python_postmortem agent) previously hand-rolled.

- New pure-Python helper `tintype/_exception.py::reconstruct_exception`, with a `_MAX_CHAIN_DEPTH` cap + `id()` cycle guard (mirroring `tintype/dap/exceptions.py`) so a cyclic/deep chain can't spin forever.
- New C++ pybind `.def("reconstruct_exception", ...)` in `_snapshot.cpp` that delegates to the helper, mirroring how `get_traceback` delegates to `tintype/_traceback.py`.
- `_snapshot.pyi` stub + `PYTHON_API.md` row.
- Caveat (documented): the reconstructed class is always `Exception` because `exception_object` is a serialized object — the original class isn't recoverable; the message is preserved.

Reviewed By: aperez

Differential Revision: D115205582

fbshipit-source-id: c1dfbbead2adb9418ef097b6fc3787259565dba7

Author: pdepetro

PYTHON_API.md

@@ -412,6 +412,7 @@ Represents a stacktrace within a snapshot. For single-thread snapshots (`take_sn
 | `get_cause()` | `Stacktrace \| None` | Get the `__cause__` stacktrace, or `None` if there is no cause. Caches the result. |
 | `get_context()` | `Stacktrace \| None` | Get the `__context__` stacktrace, or `None` if there is no context. Caches the result. |
 | `get_traceback()` | `TracebackType \| None` | Generate a synthetic Python traceback object from this stacktrace's frames. Useful for feeding into debuggers. |
+| `reconstruct_exception()` | `BaseException \| None` | Reconstruct a `BaseException` from this stacktrace with `__traceback__` and a wired `__cause__`/`__context__` chain, or `None` if it has no exception. At most 10 chained exceptions are wired. Nodes with a wired `__cause__` have `__suppress_context__` set. The reconstructed class is always `Exception` (the original class is not recoverable from a snapshot — read it from the message or `exception_object`). |
 
 #### Internal Attributes
 

_exception.py

@@ -0,0 +1,79 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+# pyre-strict
+
+"""Reconstruct a ``BaseException`` from a snapshot ``Stacktrace``.
+
+The returned exception carries the reconstructed ``__traceback__`` and a
+wired ``__cause__`` / ``__context__`` chain, so it can be fed to a debugger
+or the ``traceback`` module.
+
+Caveat: the original exception *classes* are not recoverable from a
+snapshot — ``Stacktrace.exception_object`` is a serialized object — so every
+node in the reconstructed chain is a plain ``Exception`` carrying the
+original message. Read the true class name from the message (e.g.
+``KeyError: 'foo'``) or from ``exception_object`` if you need it.
+"""
+
+from types import TracebackType
+from typing import Any
+
+# Mirror CPython's cap in ``traceback.py`` (and tintype's DAP renderer) so a
+# cyclic or pathologically deep ``__cause__`` / ``__context__`` chain cannot
+# spin forever or blow the stack.
+_MAX_CHAIN_DEPTH = 10
+
+
+def _synthesize(stacktrace: Any) -> Exception:
+    """Build a single synthetic ``Exception`` (message + traceback, no chain)
+    from one stacktrace."""
+    orig = stacktrace.exception_object
+    exc = Exception(str(orig) if orig is not None else "(unknown exception)")
+    tb: TracebackType | None = stacktrace.get_traceback()
+    if tb is not None:
+        exc.__traceback__ = tb
+    return exc
+
+
+def reconstruct_exception(stacktrace: Any) -> BaseException | None:
+    """Reconstruct a ``BaseException`` with its traceback and chained causes.
+
+    Returns ``None`` when the stacktrace has no exception (e.g. a thread
+    snapshot) or no reconstructable traceback. At most ``_MAX_CHAIN_DEPTH``
+    (10) chained exceptions are wired; a longer chain is silently truncated at
+    the tail, matching CPython's own cap in ``traceback.py``. See the module
+    docstring for the "class is always ``Exception``" caveat.
+    """
+
+    if stacktrace.exception_object is None or not stacktrace.frames:
+        return None
+
+    head = _synthesize(stacktrace)
+
+    current_st = stacktrace
+    current_exc: BaseException = head
+    seen: set[int] = {id(stacktrace)}
+    depth = 0
+    while depth < _MAX_CHAIN_DEPTH:
+        # Prefer ``__cause__`` (``raise X from Y``) over ``__context__``
+        # (implicit during-handling chain), matching CPython's precedence.
+        nxt = current_st.get_cause()
+        wire_cause = nxt is not None
+        if nxt is None:
+            nxt = current_st.get_context()
+        if nxt is None or id(nxt) in seen:
+            break
+        seen.add(id(nxt))
+        nxt_exc = _synthesize(nxt)
+        if wire_cause:
+            current_exc.__cause__ = nxt_exc
+            current_exc.__suppress_context__ = True
+        else:
+            current_exc.__context__ = nxt_exc
+        current_st = nxt
+        current_exc = nxt_exc
+        depth += 1
+
+    return head

_snapshot.cpp

@@ -812,7 +812,23 @@ PYBIND11_MODULE(_snapshot, m) {
 
             return result;
           },
-          "Generate a Python traceback from this stacktrace's frames.");
+          "Generate a Python traceback from this stacktrace's frames.")
+      .def(
+          "reconstruct_exception",
+          [](const py::object& self) -> py::object {
+            // Delegate to the pure-Python helper (mirrors get_traceback's
+            // delegation to tintype._traceback). The helper walks
+            // get_cause()/get_context()/get_traceback() and wires a real
+            // BaseException chain.
+            py::module_ exception_utils =
+                py::module_::import("tintype._exception");
+            py::object fn = exception_utils.attr("reconstruct_exception");
+            return fn(self);
+          },
+          "Reconstruct a BaseException (with wired __cause__/__context__ and "
+          "__traceback__) from this stacktrace, or None if it has no "
+          "exception. The reconstructed class is always Exception; read the "
+          "original class from the message or exception_object.");
 
   py::class_<snapshot::Snapshot>(m, "Snapshot", py::dynamic_attr())
       .def_readonly("timestamp", &snapshot::Snapshot::timestamp)

_snapshot.pyi

@@ -320,6 +320,16 @@ class Stacktrace:
         """Generate a Python traceback from this stacktrace's frames."""
         ...
 
+    def reconstruct_exception(self) -> BaseException | None:
+        """Reconstruct a BaseException from this stacktrace.
+
+        The reconstructed exception carries __traceback__ and a wired
+        __cause__/__context__ chain. Returns None if the stacktrace has no
+        exception. The reconstructed class is always Exception (the original
+        class is not recoverable from a snapshot).
+        """
+        ...
+
 class Snapshot:
     """Represents a snapshot record."""
 

tests/test_reconstruct_exception.py

@@ -0,0 +1,138 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+# pyre-strict
+
+import os
+import tempfile
+import unittest
+
+import tintype
+from tintype._exception import _MAX_CHAIN_DEPTH
+
+
+class ReconstructExceptionTest(unittest.TestCase):
+    def _capture(
+        self, exc: BaseException
+    ) -> tuple[tintype.SnapshotReader, tintype.Snapshot]:
+        tmpdir = tempfile.mkdtemp()
+        path = os.path.join(tmpdir, "test.pytb")
+        tintype.initialize()
+        tintype.take_snapshot(exc)
+        tintype.finalize(path)
+        reader = tintype.SnapshotReader(path)
+        snap = reader.get_latest_snapshot()
+        self.assertIsNotNone(snap)
+        assert snap is not None
+        return reader, snap
+
+    def _find(self, snap: tintype.Snapshot, type_name: str) -> tintype.Stacktrace:
+        for st in snap.stacktraces.values():
+            if st.exception_object is not None and type_name in repr(
+                st.exception_object
+            ):
+                return st
+        self.fail(f"No stacktrace found for exception type {type_name}")
+
+    def test_reconstructs_message_and_traceback(self) -> None:
+        try:
+            raise KeyError("missing")
+        except KeyError as e:
+            captured = e
+        _reader, snap = self._capture(captured)
+        st = self._find(snap, "KeyError")
+
+        exc = st.reconstruct_exception()
+        self.assertIsNotNone(exc)
+        assert exc is not None
+        # Class is always Exception (original class is not recoverable), but
+        # the message is preserved and the traceback is wired.
+        self.assertIsInstance(exc, Exception)
+        self.assertIn("missing", str(exc))
+        self.assertIsNotNone(exc.__traceback__)
+
+    def test_wires_cause_chain(self) -> None:
+        try:
+            try:
+                raise KeyError("inner")
+            except KeyError as inner:
+                raise RuntimeError("outer") from inner
+        except RuntimeError as e:
+            captured = e
+        _reader, snap = self._capture(captured)
+        st = self._find(snap, "RuntimeError")
+
+        exc = st.reconstruct_exception()
+        assert exc is not None
+        self.assertIn("outer", str(exc))
+        cause = exc.__cause__
+        self.assertIsNotNone(cause)
+        assert cause is not None
+        self.assertIn("inner", str(cause))
+        self.assertTrue(exc.__suppress_context__)
+
+    def test_wires_context_chain(self) -> None:
+        try:
+            try:
+                raise ValueError("first")
+            except ValueError:
+                raise TypeError("second")
+        except TypeError as e:
+            captured = e
+        _reader, snap = self._capture(captured)
+        st = self._find(snap, "TypeError")
+
+        exc = st.reconstruct_exception()
+        assert exc is not None
+        self.assertIn("second", str(exc))
+        context = exc.__context__
+        self.assertIsNotNone(context)
+        assert context is not None
+        self.assertIn("first", str(context))
+
+    def test_chain_depth_is_capped(self) -> None:
+        def raise_chain(level: int) -> None:
+            if level == 0:
+                raise RuntimeError("level-0")
+            try:
+                raise_chain(level - 1)
+            except RuntimeError as inner:
+                raise RuntimeError(f"level-{level}") from inner
+
+        # Unlike the tests above, the raise is behind a call, so the type
+        # checker cannot prove the ``except`` branch runs — seed ``captured``.
+        captured: RuntimeError | None = None
+        try:
+            raise_chain(_MAX_CHAIN_DEPTH + 3)
+        except RuntimeError as e:
+            captured = e
+        assert captured is not None
+        _reader, snap = self._capture(captured)
+        st = snap.stacktraces[1]
+
+        exc = st.reconstruct_exception()
+        assert exc is not None
+        depth = 0
+        current = exc
+        while current.__cause__ is not None or current.__context__ is not None:
+            current = current.__cause__ or current.__context__
+            assert current is not None
+            depth += 1
+        self.assertEqual(depth, _MAX_CHAIN_DEPTH)
+
+    def test_none_for_thread_snapshot(self) -> None:
+        tmpdir = tempfile.mkdtemp()
+        path = os.path.join(tmpdir, "thread.pytb")
+        tintype.initialize()
+        tintype.take_snapshot()
+        tintype.finalize(path)
+        snap = tintype.SnapshotReader(path).get_latest_snapshot()
+        assert snap is not None
+        # A plain (non-exception) snapshot has no exception_object, so
+        # reconstruct_exception is None.
+        for st in snap.stacktraces.values():
+            if st.exception_object is None:
+                self.assertIsNone(st.reconstruct_exception())
+                return
+        self.skipTest("no non-exception stacktrace present")