errpath 0.1.0__py3-none-any.whl

errpath/machine.py

@@ -0,0 +1,165 @@
+"""Emit XState MachineJSON from a function's IR nodes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from errpath.ir import (
+    CATCH_ANY,
+    Branch,
+    Fail,
+    Function,
+    Jump,
+    Loop,
+    Node,
+    Panic,
+    Recover,
+    Step,
+    Succeed,
+    Swallow,
+    escaping,
+)
+
+
+def _safe_id(name: str, used: set[str]) -> str:
+    base = "".join(c if c.isalnum() or c in "_-" else "_" for c in name).strip("_") or "state"
+    if base[0].isdigit():
+        base = f"s_{base}"
+    candidate = base
+    n = 2
+    while candidate in used:
+        candidate = f"{base}_{n}"
+        n += 1
+    used.add(candidate)
+    return candidate
+
+
+def _event_name(label: str) -> str:
+    cleaned = "".join(c if c.isalnum() or c in "_-" else "_" for c in label).strip("_")
+    return cleaned[:40] or "arm"
+
+
+def function_to_machine(fn: Function) -> dict[str, Any]:
+    """Build data-only MachineJSON suitable for autovisualizer ``definition``."""
+    used: set[str] = set()
+    states: dict[str, Any] = {}
+    error_finals: dict[str, str] = {}
+    handlers: dict[str, str] = {}  # "<try tag>#<arm index>" -> handler entry state
+    counters = {"step": 0}
+
+    def error_state(label: str) -> str:
+        if label not in error_finals:
+            sid = _safe_id(label, used)
+            error_finals[label] = sid
+            states[sid] = {"type": "final", "tags": ["error"]}
+        return error_finals[label]
+
+    success_id = _safe_id("Success", used)
+    states[success_id] = {"type": "final"}
+
+    def emit(nodes: list[Node], join: str) -> str:
+        def at(index: int) -> str:
+            if index >= len(nodes):
+                return join
+            node = nodes[index]
+            rest = at(index + 1)
+
+            if isinstance(node, Step):
+                counters["step"] += 1
+                sid = _safe_id(node.name or f"step_{counters['step']}", used)
+                states[sid] = {"on": {"ok": {"target": rest}, **error_events(node, None)}}
+                return sid
+
+            if isinstance(node, Succeed):
+                return success_id
+
+            if isinstance(node, Fail):
+                return error_state(node.error or "Error")
+
+            if isinstance(node, Panic):
+                panic_sid = _safe_id(node.name or "panic", used)
+                # a raise exits with its own type; an unwrap outside @safe is a Panic
+                on_panic = error_events(
+                    node, node.error if node.terminal and node.error else "Panic"
+                )
+                if not node.terminal:
+                    on_panic["ok"] = {"target": rest}
+                states[panic_sid] = {"tags": ["error"], "on": on_panic}
+                return panic_sid
+
+            if isinstance(node, Swallow):
+                sid = _safe_id(f"swallow_{node.name}", used)
+                states[sid] = {
+                    "on": {"ok": {"target": rest}},
+                    "description": f"swallowed ({node.how})",
+                }
+                return sid
+
+            if isinstance(node, Recover):
+                sid = _safe_id(f"recover_{node.name}", used)
+                states[sid] = {"on": {"ok": {"target": rest}}, "description": node.how}
+                return sid
+
+            if isinstance(node, Jump):
+                sid = _safe_id(node.name, used)
+                states[sid] = {"on": {"ok": {"target": rest}}}
+                return sid
+
+            if isinstance(node, Branch):
+                sid = _safe_id("branch", used)
+                targets: dict[int, str] = {}
+                # try: emit handlers first so steps in the body can point their errors at them
+                order = [*range(1, len(node.arms)), 0] if node.tag else range(len(node.arms))
+                for i in order:
+                    targets[i] = emit(list(node.arms[i].body), rest)
+                    if node.tag and i > 0:
+                        handlers[f"{node.tag}#{i}"] = targets[i]
+                on: dict[str, Any] = {}
+                for i, arm in enumerate(node.arms):
+                    event = arm.label if arm.label in {"yes", "no"} else _event_name(arm.label)
+                    on[event] = {"target": targets[i]}
+                states[sid] = {"on": on, "description": node.label}
+                return sid
+
+            if isinstance(node, Loop):
+                sid = _safe_id("loop", used)
+                body_entry = emit(list(node.body), sid)
+                states[sid] = {
+                    "on": {
+                        "next": {"target": body_entry},
+                        "done": {"target": rest},
+                    },
+                    "description": node.label,
+                }
+                return sid
+
+            return rest
+
+        return at(0)
+
+    def error_events(node: Step | Panic, escape_label: str | None) -> dict[str, Any]:
+        """``err_<Type>`` per caught type to its handler; ``err`` for what escapes.
+
+        Each goes through its ``finally`` cleanup first.
+        """
+        on: dict[str, Any] = {}
+        for key, catch in node.caught_by.items():
+            handler = handlers[catch.handler]
+            event = "err_any" if key == CATCH_ANY else f"err_{_event_name(key)}"
+            on[event] = {"target": emit(list(catch.cleanup), handler) if catch.cleanup else handler}
+        left = escaping(node.error, node.caught_by)
+        if left is not None:
+            label = escape_label or left
+            target = emit([*node.cleanup, Fail(error=label)], error_state(label))
+            on["err"] = {"target": target}
+        return on
+
+    initial = emit(list(fn.nodes), success_id)
+    if initial not in states:
+        initial = success_id
+
+    return {
+        "id": fn.name,
+        "initial": initial,
+        "states": states,
+    }

errpath/result.py

@@ -0,0 +1,254 @@
+"""Ok / Err Result type inspired by Rust and safe-result."""
+
+from __future__ import annotations
+
+import copy
+import traceback
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Any, Generic, Literal, NoReturn, TypeGuard, TypeVar
+
+if TYPE_CHECKING:
+    # Type checkers ship typing_extensions, so this needs no runtime dependency.
+    from typing_extensions import TypeIs
+else:
+    # A runtime name too, so typing.get_type_hints(ok) works.
+    try:
+        from typing import TypeIs  # Python 3.13+
+    except ImportError:
+        try:
+            from typing_extensions import TypeIs
+        except ImportError:
+            TypeIs = TypeGuard  # only seen by runtime introspection; checkers use the line above
+
+T = TypeVar("T")
+E = TypeVar("E")
+# Results can't be changed, so they are covariant like tuple: an Err[KeyError] is also an
+# Err[KeyError | ValueError], and an early `return err` type-checks against a wider Result.
+T_co = TypeVar("T_co", covariant=True)
+E_co = TypeVar("E_co", covariant=True)
+R = TypeVar("R")
+U = TypeVar("U")
+F = TypeVar("F")
+ExcT = TypeVar("ExcT", bound=BaseException)
+
+
+# Callbacks a variant ignores take Any: on a Result, checkers test the callback against
+# both Ok and Err, and an `object` parameter would turn `lambda v: v * 2` into an error.
+
+
+class _Frozen:
+    """Results can't be changed after they're made: they are hashable, so a change
+    would silently break any set or dict that holds them."""
+
+    __slots__ = ()
+
+    def __setattr__(self, name: str, _: object) -> NoReturn:
+        kind = type(self).__name__
+        raise AttributeError(f"{kind} can't be changed; make a new one: {kind}(...)")
+
+    def __delattr__(self, name: str) -> NoReturn:
+        raise AttributeError(f"{type(self).__name__} can't be changed")
+
+
+class Ok(_Frozen, Generic[T_co]):
+    """A successful result. Read the value with ``.value``."""
+
+    __slots__ = ("value",)
+    __match_args__ = ("value",)
+
+    value: T_co
+
+    def __init__(self, value: T_co) -> None:
+        object.__setattr__(self, "value", value)
+
+    @property
+    def error(self) -> None:
+        """Always ``None`` on ``Ok``."""
+        return None
+
+    def is_ok(self) -> Literal[True]:
+        return True
+
+    def is_err(self) -> Literal[False]:
+        return False
+
+    def unwrap(self) -> T_co:
+        """Return the value. (On ``Err`` this raises the error.)"""
+        return self.value
+
+    def unwrap_or(self, default: object) -> T_co:  # noqa: ARG002 - same signature as Err
+        """Return the value. (On ``Err`` this returns ``default``.)"""
+        return self.value
+
+    def map(self, func: Callable[[T_co], R]) -> Ok[R]:
+        """Change the value with ``func``. (On ``Err`` this does nothing.)"""
+        return Ok(func(self.value))
+
+    async def map_async(self, func: Callable[[T_co], Awaitable[R]]) -> Ok[R]:
+        """Like ``map``, for an async ``func``."""
+        return Ok(await func(self.value))
+
+    def map_err(self, func: Callable[[Any], Any]) -> Ok[T_co]:  # noqa: ARG002 - same signature as Err
+        """Change the error with ``func``. ``Ok`` has no error, so this returns it unchanged."""
+        return self
+
+    def and_then(self, func: Callable[[T_co], Result[R, E]]) -> Result[R, E]:
+        """Run the next step, ``func``, which can itself fail. (On ``Err`` it is skipped.)"""
+        return func(self.value)
+
+    async def and_then_async(self, func: Callable[[T_co], Awaitable[Result[R, E]]]) -> Result[R, E]:
+        """Like ``and_then``, for an async ``func``."""
+        return await func(self.value)
+
+    def flatten(self) -> Result[T_co, E]:
+        """Turn ``Ok(Ok(x))`` into ``Ok(x)`` and ``Ok(Err(e))`` into ``Err(e)``."""
+        result: Result[Any, Any] = self
+        while isinstance(result, Ok) and isinstance(result.value, (Ok, Err)):
+            result = result.value
+        return result
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source: Any, handler: Any) -> Any:
+        from errpath._pydantic import result_schema  # only loaded when Pydantic asks
+
+        return result_schema(cls, source, handler, ok=True)
+
+    def __reduce__(self) -> tuple[type[Ok[T_co]], tuple[T_co]]:
+        return (Ok, (self.value,))  # copy and pickle rebuild via __init__, not setattr
+
+    def __deepcopy__(self, memo: dict[int, object]) -> Ok[T_co]:
+        # Register the copy before copying the value, so a value that refers back
+        # to this result points at the copy instead of making a second one.
+        new = object.__new__(type(self))
+        memo[id(self)] = new
+        object.__setattr__(new, "value", copy.deepcopy(self.value, memo))
+        return new
+
+    def __repr__(self) -> str:
+        return f"Ok({self.value!r})"
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Ok) and other.value == self.value
+
+    def __hash__(self) -> int:
+        return hash((True, self.value))
+
+
+class Err(_Frozen, Generic[E_co]):
+    """A failed result. Read the error with ``.error``."""
+
+    __slots__ = ("error",)
+    __match_args__ = ("error",)
+
+    error: E_co
+
+    def __init__(self, error: E_co) -> None:
+        object.__setattr__(self, "error", error)
+
+    @property
+    def value(self) -> None:
+        """Always ``None`` on ``Err``."""
+        return None
+
+    def is_ok(self) -> Literal[False]:
+        return False
+
+    def is_err(self) -> Literal[True]:
+        return True
+
+    def unwrap(self: Err[BaseException]) -> NoReturn:
+        """Raise the error (as itself, so ``except`` and ``@safe`` see its real type).
+
+        Only for exception errors: Python can't raise a ``str`` or a model, so type
+        checkers reject ``.unwrap()`` on, say, ``Result[int, str]``. Use ``match``,
+        ``unwrap_or(default)``, or ``map_err`` to turn the error into an exception first.
+        """
+        if isinstance(self.error, BaseException):
+            raise self.error
+        # Unchecked code can still get here; fail loudly with what to do instead.
+        raise RuntimeError(
+            f"unwrap() was called on {self!r}, whose error isn't an exception. "
+            "Use match, unwrap_or(default), or map_err(...) to turn it into one."
+        )
+
+    def unwrap_or(self, default: U) -> U:
+        """Return ``default``, because there is no value."""
+        return default
+
+    def map(self, _: Callable[[Any], Any]) -> Err[E_co]:
+        """Change the value. ``Err`` has no value, so this returns it unchanged."""
+        return self
+
+    async def map_async(self, _: Callable[[Any], Awaitable[Any]]) -> Err[E_co]:
+        """Like ``map``, for an async function."""
+        return self
+
+    def map_err(self, func: Callable[[E_co], F]) -> Err[F]:
+        """Change the error with ``func``, e.g. wrap a low-level error in your own type."""
+        return Err(func(self.error))
+
+    def and_then(self, _: Callable[[Any], Any]) -> Err[E_co]:
+        """Skip the next step, because this already failed."""
+        return self
+
+    async def and_then_async(self, _: Callable[[Any], Awaitable[Any]]) -> Err[E_co]:
+        """Like ``and_then``, for an async function."""
+        return self
+
+    def flatten(self) -> Err[E_co]:
+        """Already flat: returns itself."""
+        return self
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source: Any, handler: Any) -> Any:
+        from errpath._pydantic import result_schema  # only loaded when Pydantic asks
+
+        return result_schema(cls, source, handler, ok=False)
+
+    def __reduce__(self) -> tuple[type[Err[E_co]], tuple[E_co]]:
+        return (Err, (self.error,))  # copy and pickle rebuild via __init__, not setattr
+
+    def __deepcopy__(self, memo: dict[int, object]) -> Err[E_co]:
+        new = object.__new__(type(self))  # registered first, as in Ok.__deepcopy__
+        memo[id(self)] = new
+        object.__setattr__(new, "error", copy.deepcopy(self.error, memo))
+        return new
+
+    def __repr__(self) -> str:
+        return f"Err({self.error!r})"
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Err) and other.error == self.error
+
+    def __hash__(self) -> int:
+        return hash((False, self.error))
+
+
+Result = Ok[T] | Err[E]
+
+
+def ok(result: Result[T, E]) -> TypeIs[Ok[T]]:
+    """True when ``result`` succeeded.
+
+    Type checkers narrow both branches: after ``if ok(r):`` you get ``r.value``
+    with its real type, and in the ``else`` branch ``r.error`` with its real type.
+    """
+    return isinstance(result, Ok)
+
+
+def err_type(result: object, exc_type: type[ExcT]) -> TypeGuard[Err[ExcT]]:
+    """True when ``result`` failed with ``exc_type`` (or a subclass of it).
+
+    After ``if err_type(r, KeyError):`` type checkers know ``r.error`` is a ``KeyError``.
+    """
+    return isinstance(result, Err) and isinstance(result.error, exc_type)
+
+
+def traceback_of(result: object) -> str:
+    """Formatted traceback if ``result`` is an ``Err`` holding an Exception."""
+    if not isinstance(result, Err):
+        return ""
+    error = result.error
+    if not isinstance(error, BaseException):
+        return ""
+    return "".join(traceback.format_exception(type(error), error, error.__traceback__))