whytrail 0.1.0__py3-none-any.whl

whytrail/__init__.py

@@ -0,0 +1,210 @@
+"""Python tells you where. whytrail tells you why.
+
+Two tiers, one entry point (ADR §02, §05):
+
+  Tier 1 -- zero configuration. why(some_exception) reassembles a
+  causal chain from data CPython already retains: __traceback__,
+  __cause__, __context__, and live frame locals.
+
+  Tier 2 -- opt-in and scoped. why(some_tracked_value) walks a small
+  provenance graph built only for values a developer deliberately
+  watched with track(), @tracked, or trace().
+
+Both answer through why(). Something that was never tracked gets an
+honest "unknown," never a fabricated answer -- see ADR §11.
+"""
+
+from __future__ import annotations
+
+import typing as t
+
+from ._repr import safe_repr
+from .core import serialize as _serialize
+from .core.explanation import Explanation, ExplanationStep
+from .core.graph import ProvenanceGraph
+from .core.node import Confidence, Edge, Node
+from .explainers.builtin import explain_exception
+from .protocols import call_why_protocol
+from .registry import coerce, register, register_from_plugin, resolve_explainer
+from .runtime.capture import track, tracked
+from .runtime.context import current_scope, default_graph, trace
+
+__version__ = "0.1.0"
+
+# Deliberately small: five verbs, two persistence helpers, and the two
+# names every explainer author touches (Explanation, ExplanationStep,
+# Confidence). Everything else a plugin author or advanced user needs
+# -- ProvenanceGraph, TraceScope, SupportsWhy, NodeKind, EdgeKind, the
+# raw Node/Edge types -- is one submodule import away
+# (whytrail.core.graph, whytrail.runtime.context, whytrail.protocols,
+# whytrail.core.node) rather than crowding `import whytrail; whytrail.<tab>`
+# for the median user who only ever calls why(). See the strategy
+# review's namespace audit.
+__all__ = [
+    "why",
+    "track",
+    "tracked",
+    "trace",
+    "register",
+    "register_from_plugin",
+    "snapshot",
+    "restore",
+    "Explanation",
+    "ExplanationStep",
+    "Confidence",
+    "__version__",
+]
+
+
+def why(obj: t.Any, *, max_depth: int = 8) -> Explanation:
+    """The one public entry point (ADR §05, §10).
+
+    Tier 1: obj is an exception -- reconstructs its causal chain from
+    data CPython already retains. No setup required.
+
+    Tier 2: obj is anything else -- looks for a __why__ method, then a
+    registered explainer, then a provenance-graph node captured by
+    track()/@tracked/trace(). If none of those know anything about
+    obj, returns an Explanation that says so plainly.
+
+    Never raises: a failure anywhere in resolution degrades to an
+    "unknown" Explanation rather than propagating into caller code
+    (ADR §19).
+    """
+    try:
+        return _why_impl(obj, max_depth=max_depth)
+    except Exception:  # noqa: BLE001 - why() must never raise, see ADR §19
+        return Explanation(subject=safe_repr(obj), steps=[], tracked=False)
+
+
+def _why_impl(obj: t.Any, *, max_depth: int) -> Explanation:
+    # Protocol and registry get first look even for exceptions -- a
+    # plugin explaining e.g. requests.RequestException with domain
+    # detail (method, URL, response body) should win over the generic
+    # traceback walk. Tier 1's exception explainer is the built-in,
+    # always-available *fallback* for exceptions nothing more specific
+    # claims, not a shortcut that preempts plugins (ADR §02, §06).
+    protocol_result = call_why_protocol(obj)
+    if protocol_result is not None:
+        return protocol_result
+
+    explainer = resolve_explainer(type(obj))
+    if explainer is not None:
+        try:
+            raw = explainer(obj)
+        except Exception:  # noqa: BLE001 - a broken plugin must not crash why()
+            raw = None
+        coerced = coerce(obj, raw)
+        if coerced is not None:
+            return coerced
+
+    if isinstance(obj, BaseException):
+        return explain_exception(obj, max_depth=max_depth)
+
+    return _explain_from_graph(obj, max_depth=max_depth)
+
+
+def _explain_from_graph(obj: t.Any, *, max_depth: int) -> Explanation:
+    candidates: list[ProvenanceGraph] = []
+    scope = current_scope()
+    if scope is not None:
+        candidates.append(scope.graph)
+    default = default_graph()
+    if default not in candidates:
+        candidates.append(default)
+
+    for graph in candidates:
+        node = graph.node_for(obj)
+        if node is not None:
+            nodes, edges = graph.ancestors(node.id, max_depth=max_depth)
+            steps = _steps_from_traversal(node, nodes, edges)
+            return Explanation(subject=safe_repr(obj), steps=steps, tracked=True, nodes=nodes, edges=edges)
+
+    return Explanation(subject=safe_repr(obj), steps=[], tracked=False)
+
+
+def _steps_from_traversal(
+    target: Node, nodes: list[Node], edges: list[Edge]
+) -> list[ExplanationStep]:
+    """Turn the ancestor subgraph into an ordered, human-readable
+    *single dominant path* -- root cause first, ending at the node the
+    caller asked about. When a node has more than one real parent (a
+    diamond: two calls converging on the same value, common under
+    trace(deep=True)), this picks the highest-confidence one and does
+    not narrate the rest -- .text/.steps is a readable summary, not
+    the full picture. Explanation.graph()/.nodes/.edges carry the
+    complete captured DAG for anyone who needs it; that distinction is
+    deliberate, not a bug (see ADR §11: honest partial answers are
+    fine, silently-lossy ones presented as complete are not).
+
+    At each step, follows the highest-confidence parent; ties are
+    broken by which edge was recorded first."""
+    nodes_by_id = {n.id: n for n in nodes}
+    incoming: dict[int, list[Edge]] = {}
+    for edge in edges:
+        incoming.setdefault(edge.target, []).append(edge)
+
+    chain: list[Node] = []
+    branch_counts: dict[int, int] = {}  # node.id -> how many real parents it had
+    seen: set[int] = set()
+    current: Node | None = target
+    while current is not None and current.id not in seen:
+        seen.add(current.id)
+        chain.append(current)
+        parents = incoming.get(current.id, [])
+        branch_counts[current.id] = len(parents)
+        if not parents:
+            break
+        best_edge = max(parents, key=lambda e: e.confidence)
+        current = nodes_by_id.get(best_edge.source)
+    chain.reverse()
+
+    steps: list[ExplanationStep] = []
+    for i, node in enumerate(chain):
+        confidence = Confidence.EXPLICIT.value
+        if i > 0:
+            # named distinctly from the `edge` loop variable above --
+            # Python has no block scoping, and mypy --strict correctly
+            # flags reusing a name for a differently-typed (Optional)
+            # value in the same function scope.
+            matching_edge = next(
+                (e for e in incoming.get(chain[i].id, []) if e.source == chain[i - 1].id),
+                None,
+            )
+            confidence = matching_edge.confidence if matching_edge is not None else Confidence.INFERRED.value
+        description = f"{node.kind.value}: {node.label}"
+        if node.tombstoned:
+            description += " (garbage collected)"
+        # Surface, don't hide, when this step's summary skipped real
+        # branches (ADR 0002 §3 item 3): this function documents that it
+        # follows one dominant path through a DAG, which is only honest
+        # if a reader can tell *from the output itself* that there was
+        # more to see, not just from reading this function's docstring.
+        other_parents = branch_counts.get(node.id, 0) - 1
+        if other_parents > 0:
+            plural = "path" if other_parents == 1 else "paths"
+            description += f"  (+{other_parents} other {plural} converge here, see .graph())"
+        steps.append(
+            ExplanationStep(
+                description=description,
+                confidence=confidence,
+                location=node.location,
+                kind=node.kind.value,
+            )
+        )
+    return steps
+
+
+def snapshot(graph: ProvenanceGraph | None = None) -> str:
+    """Persist a graph as JSON-lines (ADR §05, §12). Defaults to the
+    shared process graph. Explicit and opt-in -- capture itself never
+    writes to disk on its own."""
+    return _serialize.dumps(graph if graph is not None else default_graph())
+
+
+def restore(data: str) -> ProvenanceGraph:
+    """Rebuild a read-only replay graph from a snapshot() (ADR §14).
+    Replayed nodes carry their original metadata but, having outlived
+    the process that captured them, behave as tombstones -- there is
+    no live object left to hold a weakref to."""
+    return _serialize.loads(data)

whytrail/_repr.py

@@ -0,0 +1,27 @@
+"""Shared bounded, never-raising repr helper.
+
+whytrail's core promise (ADR §19) is that it never raises from inside
+its own machinery, even when the object being described has a broken
+or hostile __repr__. Every place that needs a short label for an
+arbitrary object goes through here.
+"""
+
+from __future__ import annotations
+
+import reprlib
+import typing as t
+
+_repr = reprlib.Repr()
+_repr.maxstring = 100
+_repr.maxother = 100
+_repr.maxlist = 8
+_repr.maxdict = 8
+_repr.maxtuple = 8
+_repr.maxset = 8
+
+
+def safe_repr(value: t.Any) -> str:
+    try:
+        return _repr.repr(value)
+    except Exception:  # noqa: BLE001 - deliberately broad, see module docstring
+        return f"<unrepresentable {type(value).__name__}>"

whytrail/cli/__main__.py

@@ -0,0 +1,74 @@
+"""whytrail CLI (ADR §14 -- v2.0): `whytrail run script.py` runs a script
+and, if it raises, prints why() instead of a bare traceback.
+
+Deliberately the only subcommand for now -- a CLI that grows verbs
+ahead of demonstrated need repeats the mistake ADR §10 rejected for
+the Python API itself.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import runpy
+import sys
+import typing as t
+
+import whytrail
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="whytrail", description="Python tells you where. whytrail tells you why.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    run_parser = subparsers.add_parser(
+        "run", help="Run a script; on an uncaught exception, print why() instead of a bare traceback."
+    )
+    run_parser.add_argument("script", help="path to the Python script to run")
+    run_parser.add_argument("script_args", nargs=argparse.REMAINDER, help="arguments passed to the script")
+    run_parser.add_argument("--json", action="store_true", help="print the explanation as JSON")
+    run_parser.add_argument("--graph", action="store_true", help="also print a Mermaid provenance graph")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "run":
+        return _run(args)
+    parser.print_help()
+    return 1
+
+
+def _run(args: argparse.Namespace) -> int:
+    old_argv = sys.argv
+    sys.argv = [args.script, *args.script_args]
+    try:
+        runpy.run_path(args.script, run_name="__main__")
+    except SystemExit as exc:
+        return exc.code if isinstance(exc.code, int) else (0 if exc.code is None else 1)
+    except BaseException as exc:  # noqa: BLE001 - the whole point is to catch whatever the script raises
+        explanation = whytrail.why(exc)
+        _report(explanation, as_json=args.json, with_graph=args.graph)
+        return 1
+    finally:
+        sys.argv = old_argv
+    return 0
+
+
+def _report(explanation: "whytrail.Explanation", *, as_json: bool, with_graph: bool) -> None:
+    if as_json:
+        payload: dict[str, t.Any] = explanation.json()
+        if with_graph:
+            payload["graph"] = explanation.graph()
+        print(json.dumps(payload, indent=2))
+        return
+    print(explanation.text, file=sys.stderr)
+    if with_graph:
+        print(file=sys.stderr)
+        print(explanation.graph(), file=sys.stderr)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

whytrail/core/explanation.py

@@ -0,0 +1,187 @@
+"""The result type every why() call returns -- one model, several
+renderings (ADR §05)."""
+
+from __future__ import annotations
+
+import dataclasses
+import typing as t
+
+from .node import Confidence, Edge, Node
+
+_STYLES = {
+    Confidence.EXPLICIT.value: "bold",
+    Confidence.INFERRED.value: "yellow",
+    Confidence.HEURISTIC.value: "dim yellow",
+}
+
+
+def _confidence_label(confidence: float) -> str:
+    if confidence >= Confidence.EXPLICIT.value:
+        return "explicit"
+    if confidence >= Confidence.INFERRED.value:
+        return "inferred"
+    if confidence >= Confidence.HEURISTIC.value:
+        return "heuristic"
+    return "unknown"
+
+
+def _confidence_marker(confidence: float) -> str:
+    # Spelled out, not a symbol: an earlier version used ASCII markers
+    # (==/~~/..) that were legible only after reading the docs -- see
+    # ADR 0002 §3 item 2. Still plain ASCII deliberately: box-drawing
+    # or bracket-free glyphs have crashed stdout on a default Windows
+    # console (cp1252) before, and a debugging tool that crashes
+    # trying to print its own output would be absurd.
+    return f"[{_confidence_label(confidence)}]"
+
+
+def _confidence_style(confidence: float) -> str:
+    return _STYLES.get(confidence, "dim")
+
+
+@dataclasses.dataclass(slots=True)
+class ExplanationStep:
+    """One causal hop in the chain, ordered root-cause first.
+
+    `locals` is a separate field from `description` on purpose: local
+    variables at an exception's origin frame are exactly the kind of
+    thing that can hold a password, an API key, or a customer record,
+    and anything that exports an Explanation off-box (Sentry, OTel, a
+    PR comment, an HTTP error response) needs a way to drop them
+    without hand-parsing text out of a human-readable string. See
+    Explanation.redacted() and ADR 0002 §3 item 5.
+    """
+
+    description: str
+    confidence: float = Confidence.EXPLICIT.value
+    location: str | None = None
+    kind: str = "value"
+    locals: dict[str, str] | None = None
+
+
+@dataclasses.dataclass(slots=True)
+class Explanation:
+    """Returned by every why() call. Honest by construction: an
+    Explanation with no steps says so plainly rather than fabricating a
+    chain (ADR §11)."""
+
+    subject: str
+    steps: list[ExplanationStep] = dataclasses.field(default_factory=list)
+    tracked: bool = True
+    nodes: list[Node] = dataclasses.field(default_factory=list)
+    edges: list[Edge] = dataclasses.field(default_factory=list)
+
+    @property
+    def confidence(self) -> float:
+        if not self.steps:
+            return Confidence.UNKNOWN.value
+        return min(step.confidence for step in self.steps)
+
+    @property
+    def known(self) -> bool:
+        return bool(self.steps)
+
+    @property
+    def text(self) -> str:
+        if not self.steps:
+            return (
+                f"why({self.subject}): unknown -- no provenance captured.\n"
+                f"  This value was never tracked. Wrap it with whytrail.track(), "
+                f"@whytrail.tracked, or raise it as an exception to get an answer."
+            )
+        lines = [f"why({self.subject}):"]
+        for step in self.steps:
+            marker = _confidence_marker(step.confidence)
+            loc = f"  [{step.location}]" if step.location else ""
+            lines.append(f"  {marker} {step.description}{loc}")
+            if step.locals:
+                lines.append(f"      locals: {_format_locals(step.locals)}")
+        return "\n".join(lines)
+
+    def __str__(self) -> str:
+        return self.text
+
+    def __repr__(self) -> str:
+        return (
+            f"<Explanation subject={self.subject!r} steps={len(self.steps)} "
+            f"confidence={_confidence_label(self.confidence)} tracked={self.tracked}>"
+        )
+
+    def rich(self) -> t.Any:
+        """Render as a rich.tree.Tree. Requires the 'rich' extra."""
+        try:
+            from rich.text import Text
+            from rich.tree import Tree
+        except ImportError as exc:  # pragma: no cover - exercised via extras test
+            raise ImportError(
+                "Rich rendering needs the 'rich' extra: pip install whytrail[rich]"
+            ) from exc
+
+        tree = Tree(f"why({self.subject})")
+        if not self.steps:
+            tree.add(Text("unknown -- no provenance captured", style="dim italic"))
+            return tree
+        for step in self.steps:
+            label = Text(step.description, style=_confidence_style(step.confidence))
+            if step.location:
+                label.append(f"  {step.location}", style="dim")
+            label.append(f"  ({_confidence_label(step.confidence)})", style="dim italic")
+            if step.locals:
+                label.append(f"\n      locals: {_format_locals(step.locals)}", style="dim")
+            tree.add(label)
+        return tree
+
+    def json(self) -> dict[str, t.Any]:
+        return {
+            "subject": self.subject,
+            "tracked": self.tracked,
+            "known": self.known,
+            "confidence": self.confidence,
+            "steps": [
+                {
+                    "description": s.description,
+                    "confidence": s.confidence,
+                    "confidence_label": _confidence_label(s.confidence),
+                    "location": s.location,
+                    "kind": s.kind,
+                    "locals": s.locals,
+                }
+                for s in self.steps
+            ],
+        }
+
+    def redacted(self) -> "Explanation":
+        """A copy with every step's locals stripped -- the one-line
+        way for any integration that exports off-box (Sentry, OTel, a
+        CI comment, an HTTP error response) to get a safe-to-share
+        version. Everything else (description, location, confidence,
+        the causal chain itself) is preserved; only the raw local
+        variable values are dropped, since those are the one thing
+        that can plausibly contain a secret.
+        """
+        return dataclasses.replace(
+            self,
+            steps=[dataclasses.replace(step, locals=None) for step in self.steps],
+        )
+
+    def graph(self) -> str:
+        """Render the traversed provenance subgraph as a Mermaid
+        flowchart (ADR §12, Fig. 1)."""
+        if not self.nodes:
+            return f'graph TD\n    A["{_escape(self.subject)} -- no provenance captured"]'
+        lines = ["graph TD"]
+        for node in self.nodes:
+            marker = " (tombstoned)" if node.tombstoned else ""
+            lines.append(f'    N{node.id}["{node.kind.value}: {_escape(node.label)}{marker}"]')
+        for edge in self.edges:
+            arrow = "-->" if edge.confidence >= Confidence.EXPLICIT.value else "-.->"
+            lines.append(f"    N{edge.source} {arrow}|{edge.kind.value}| N{edge.target}")
+        return "\n".join(lines)
+
+
+def _escape(label: str) -> str:
+    return label.replace('"', "'").replace("\n", " ")
+
+
+def _format_locals(locals_: dict[str, str]) -> str:
+    return ", ".join(f"{name}={value}" for name, value in locals_.items())

whytrail/core/graph.py

@@ -0,0 +1,160 @@
+"""The provenance graph store (ADR §08, §12).
+
+An append-only, bounded-retention DAG. Nodes never hold a strong reference
+to the object they describe -- only an id() and a bounded repr snapshot --
+so the graph can never be the reason an object outlives its natural
+lifetime. When a tracked object is garbage collected its node is
+tombstoned rather than silently disappearing (ADR §11's honesty
+principle applied to memory management).
+"""
+
+from __future__ import annotations
+
+import collections
+import threading
+import weakref
+import typing as t
+
+from .node import Confidence, Edge, EdgeKind, Node, NodeKind
+
+DEFAULT_MAX_NODES = 10_000
+
+
+class ProvenanceGraph:
+    def __init__(self, *, max_nodes: int = DEFAULT_MAX_NODES) -> None:
+        self.max_nodes = max_nodes
+        self._lock = threading.RLock()
+        self._nodes: "collections.OrderedDict[int, Node]" = collections.OrderedDict()
+        self._edges: list[Edge] = []
+        self._edges_by_target: dict[int, list[Edge]] = collections.defaultdict(list)
+        self._edges_by_source: dict[int, list[Edge]] = collections.defaultdict(list)
+        # id(obj) -> node id. Never holds a strong reference to obj itself.
+        self._object_to_node: dict[int, int] = {}
+        # weakref.finalize isn't usefully genericizable here (its type
+        # parameter tracks the finalized object's type, which varies
+        # per call site) -- t.Any is the correct escape hatch, not a
+        # laziness shortcut.
+        self._finalizers: dict[int, t.Any] = {}
+
+    # -- writing ---------------------------------------------------------
+
+    def add_node(
+        self,
+        kind: NodeKind,
+        label: str,
+        *,
+        obj: t.Any = None,
+        location: str | None = None,
+        thread: str | None = None,
+        metadata: dict[str, t.Any] | None = None,
+    ) -> Node:
+        node = Node.create(kind, label, location=location, thread=thread, metadata=metadata)
+        with self._lock:
+            self._nodes[node.id] = node
+            if obj is not None:
+                self._track_identity(obj, node.id)
+            self._evict_if_needed()
+        return node
+
+    def add_edge(
+        self,
+        source: Node | int,
+        target: Node | int,
+        kind: EdgeKind,
+        *,
+        confidence: float = Confidence.EXPLICIT.value,
+        note: str | None = None,
+    ) -> Edge:
+        source_id = source.id if isinstance(source, Node) else source
+        target_id = target.id if isinstance(target, Node) else target
+        edge = Edge(source=source_id, target=target_id, kind=kind, confidence=confidence, note=note)
+        with self._lock:
+            self._edges.append(edge)
+            self._edges_by_target[target_id].append(edge)
+            self._edges_by_source[source_id].append(edge)
+        return edge
+
+    def _track_identity(self, obj: t.Any, node_id: int) -> None:
+        key = id(obj)
+        self._object_to_node[key] = node_id
+        try:
+            fin = weakref.finalize(obj, self._on_collected, key, node_id)
+            # atexit is a real, documented, settable property on
+            # weakref.finalize at runtime; typeshed's stub omits it
+            # from __slots__, which is a stub gap, not a real error.
+            fin.atexit = False  # type: ignore[misc]
+            self._finalizers[node_id] = fin
+        except TypeError:
+            # Object doesn't support weak references (e.g. plain int, str,
+            # tuple). We keep the id()->node mapping without a collection
+            # hook; it may go stale under id() reuse in long-running
+            # processes. Documented limitation, not silently pretended away.
+            pass
+
+    def _on_collected(self, key: int, node_id: int) -> None:
+        with self._lock:
+            if self._object_to_node.get(key) == node_id:
+                del self._object_to_node[key]
+            node = self._nodes.get(node_id)
+            if node is not None:
+                node.tombstone()
+            self._finalizers.pop(node_id, None)
+
+    def _evict_if_needed(self) -> None:
+        while len(self._nodes) > self.max_nodes:
+            oldest_id, _ = self._nodes.popitem(last=False)
+            self._edges_by_target.pop(oldest_id, None)
+            self._edges_by_source.pop(oldest_id, None)
+            self._edges = [e for e in self._edges if oldest_id not in (e.source, e.target)]
+
+    # -- reading -----------------------------------------------------------
+
+    def node_for(self, obj: t.Any) -> Node | None:
+        with self._lock:
+            node_id = self._object_to_node.get(id(obj))
+            if node_id is None:
+                return None
+            return self._nodes.get(node_id)
+
+    def get(self, node_id: int) -> Node | None:
+        return self._nodes.get(node_id)
+
+    def ancestors(self, node_id: int, *, max_depth: int = 8) -> tuple[list[Node], list[Edge]]:
+        """Walk causal edges backward from node_id, breadth-first, bounded
+        by max_depth. Returns the visited nodes and the edges connecting
+        them, in traversal order."""
+        visited_nodes: dict[int, Node] = {}
+        visited_edges: list[Edge] = []
+        frontier = [node_id]
+        depth = 0
+        with self._lock:
+            start = self._nodes.get(node_id)
+            if start is not None:
+                visited_nodes[node_id] = start
+            while frontier and depth < max_depth:
+                next_frontier: list[int] = []
+                for nid in frontier:
+                    for edge in self._edges_by_target.get(nid, ()):
+                        visited_edges.append(edge)
+                        if edge.source not in visited_nodes:
+                            src = self._nodes.get(edge.source)
+                            if src is not None:
+                                visited_nodes[edge.source] = src
+                                next_frontier.append(edge.source)
+                frontier = next_frontier
+                depth += 1
+        return list(visited_nodes.values()), visited_edges
+
+    def __len__(self) -> int:
+        return len(self._nodes)
+
+    def clear(self) -> None:
+        """Drop all nodes and edges. Mainly a test/notebook convenience;
+        production code should rely on max_nodes retention instead."""
+        with self._lock:
+            self._nodes.clear()
+            self._edges.clear()
+            self._edges_by_target.clear()
+            self._edges_by_source.clear()
+            self._object_to_node.clear()
+            self._finalizers.clear()