pyeffect 0.1.0__py3-none-any.whl

pyeffect/__init__.py

@@ -0,0 +1,69 @@
+"""pyeffect: a fully typed functional core for Python."""
+
+from pyeffect.compose import (
+    compose,
+    constant,
+    curry,
+    flip,
+    identity,
+    lift,
+    lift2,
+    lift3,
+    partial,
+    tap,
+    unpack,
+)
+from pyeffect.effect import Effect, sequence
+from pyeffect.option import (
+    Nothing,
+    Option,
+    Some,
+    UnwrapNothingError,
+    flatten,
+    from_optional,
+)
+from pyeffect.pipe import pipe
+from pyeffect.result import (
+    Err,
+    ErrorContext,
+    Ok,
+    Result,
+    UnwrapError,
+    attempt,
+    guard,
+    traverse,
+)
+from pyeffect.retry import Policy, retry
+
+__all__ = [
+    "Effect",
+    "Err",
+    "ErrorContext",
+    "Nothing",
+    "Ok",
+    "Option",
+    "Policy",
+    "Result",
+    "Some",
+    "UnwrapError",
+    "UnwrapNothingError",
+    "attempt",
+    "compose",
+    "constant",
+    "curry",
+    "flatten",
+    "flip",
+    "from_optional",
+    "guard",
+    "identity",
+    "lift",
+    "lift2",
+    "lift3",
+    "partial",
+    "pipe",
+    "retry",
+    "sequence",
+    "tap",
+    "traverse",
+    "unpack",
+]

pyeffect/compose.py

@@ -0,0 +1,342 @@
+# ruff: noqa: UP047 -- PEP 695 type params on @overload are not checked by ty;
+# classic TypeVars required. Non-overload functions below use PEP 695.
+"""Function composition: ``compose``, ``tap``, and small combinators.
+
+``compose`` builds a new function from existing ones, right to left::
+
+    >>> from pyeffect.compose import compose
+    >>> compose(str, lambda x: x + 1)(2)
+    '3'
+
+``tap`` runs a side effect on a value and passes it through unchanged — a
+convenient debug step inside a ``pipe``.
+
+``curry`` turns a multi-argument function into nested single-argument
+calls; ``lift``/``lift2``/``lift3`` push plain functions into the
+``Result`` domain::
+
+    >>> from pyeffect.compose import curry, lift2
+    >>> from pyeffect.result import Ok
+    >>> curry(lambda a, b: a + b)(2)(3)
+    5
+    >>> lift2(lambda a, b: a + b)(Ok(1), Ok(2))
+    Ok(value=3)
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from functools import partial
+from typing import Any, TypeVar, overload
+
+from pyeffect.result import Err, Ok, Result
+
+__all__ = [
+    "compose",
+    "constant",
+    "curry",
+    "flip",
+    "identity",
+    "lift",
+    "lift2",
+    "lift3",
+    "partial",
+    "tap",
+    "unpack",
+]
+
+_A = TypeVar("_A")
+_B = TypeVar("_B")
+_C = TypeVar("_C")
+_D = TypeVar("_D")
+_E = TypeVar("_E")
+_F = TypeVar("_F")
+_G = TypeVar("_G")
+_H = TypeVar("_H")
+_I = TypeVar("_I")
+_J = TypeVar("_J")
+_K = TypeVar("_K")
+
+
+@overload
+def compose() -> Callable[[_A], _A]: ...
+@overload
+def compose(f: Callable[[_A], _B]) -> Callable[[_A], _B]: ...
+@overload
+def compose(f: Callable[[_A], _B], g: Callable[[_C], _A]) -> Callable[[_C], _B]: ...
+@overload
+def compose(
+    f: Callable[[_A], _B],
+    g: Callable[[_C], _A],
+    h: Callable[[_D], _C],
+) -> Callable[[_D], _B]: ...
+@overload
+def compose(
+    f: Callable[[_A], _B],
+    g: Callable[[_C], _A],
+    h: Callable[[_D], _C],
+    i: Callable[[_E], _D],
+) -> Callable[[_E], _B]: ...
+@overload
+def compose(
+    f: Callable[[_A], _B],
+    g: Callable[[_C], _A],
+    h: Callable[[_D], _C],
+    i: Callable[[_E], _D],
+    j: Callable[[_F], _E],
+) -> Callable[[_F], _B]: ...
+@overload
+def compose(
+    f: Callable[[_A], _B],
+    g: Callable[[_C], _A],
+    h: Callable[[_D], _C],
+    i: Callable[[_E], _D],
+    j: Callable[[_F], _E],
+    k: Callable[[_G], _F],
+) -> Callable[[_G], _B]: ...
+@overload
+def compose(
+    f: Callable[[_A], _B],
+    g: Callable[[_C], _A],
+    h: Callable[[_D], _C],
+    i: Callable[[_E], _D],
+    j: Callable[[_F], _E],
+    k: Callable[[_G], _F],
+    l: Callable[[_H], _G],
+) -> Callable[[_H], _B]: ...
+@overload
+def compose(
+    f: Callable[[_A], _B],
+    g: Callable[[_C], _A],
+    h: Callable[[_D], _C],
+    i: Callable[[_E], _D],
+    j: Callable[[_F], _E],
+    k: Callable[[_G], _F],
+    l: Callable[[_H], _G],
+    m: Callable[[_I], _H],
+) -> Callable[[_I], _B]: ...
+@overload
+def compose(
+    f: Callable[[_A], _B],
+    g: Callable[[_C], _A],
+    h: Callable[[_D], _C],
+    i: Callable[[_E], _D],
+    j: Callable[[_F], _E],
+    k: Callable[[_G], _F],
+    l: Callable[[_H], _G],
+    m: Callable[[_I], _H],
+    n: Callable[[_J], _I],
+) -> Callable[[_J], _B]: ...
+@overload
+def compose(
+    f: Callable[[_A], _B],
+    g: Callable[[_C], _A],
+    h: Callable[[_D], _C],
+    i: Callable[[_E], _D],
+    j: Callable[[_F], _E],
+    k: Callable[[_G], _F],
+    l: Callable[[_H], _G],
+    m: Callable[[_I], _H],
+    n: Callable[[_J], _I],
+    o: Callable[[_K], _J],
+) -> Callable[[_K], _B]: ...
+def compose(*functions: Callable[[Any], Any]) -> Callable[[Any], Any]:
+    """Compose functions right to left: ``compose(f, g)(x) == f(g(x))``.
+
+    ``compose()`` (no functions) is the identity function. Up to ten
+    functions are fully type-checked; the runtime accepts any number.
+    """
+    if not functions:
+        return identity
+
+    def composed(value: Any) -> Any:
+        for fn in reversed(functions):
+            value = fn(value)
+        return value
+
+    return composed
+
+
+def identity[A](value: A) -> A:
+    """Return ``value`` unchanged."""
+
+    return value
+
+
+def tap[A](fn: Callable[[A], object]) -> Callable[[A], A]:
+    """Return a function that runs ``fn`` on the value, then returns it.
+
+    The return value of ``fn`` is discarded — ``tap`` is for side effects
+    (logging, recording) inside a pipeline.
+    """
+
+    def tapped(value: A) -> A:
+        fn(value)
+        return value
+
+    return tapped
+
+
+def constant[A](value: A) -> Callable[..., A]:
+    """Return a function that ignores its arguments and yields ``value``."""
+
+    def const(*args: object, **kwargs: object) -> A:
+        return value
+
+    return const
+
+
+def flip[A, B, C](f: Callable[[A, B], C]) -> Callable[[B, A], C]:
+    """Swap the first two arguments of a binary function."""
+
+    def flipped(b: B, a: A) -> C:
+        return f(a, b)
+
+    return flipped
+
+
+@overload
+def unpack[A, R](f: Callable[[A], R]) -> Callable[[tuple[A]], R]: ...
+@overload
+def unpack[A, B, R](f: Callable[[A, B], R]) -> Callable[[tuple[A, B]], R]: ...
+@overload
+def unpack[A, B, C, R](f: Callable[[A, B, C], R]) -> Callable[[tuple[A, B, C]], R]: ...
+def unpack(f: Callable[..., Any]) -> Callable[[tuple[Any, ...]], Any]:
+    """Return a function that applies ``f`` to the elements of a tuple.
+
+    ``unpack(f)((1, 2))`` is ``f(1, 2)``. Arities 1-3 are fully
+    type-checked; the runtime accepts any arity.
+    """
+
+    def applied(args: tuple[Any, ...]) -> Any:
+        return f(*args)
+
+    return applied
+
+
+def _positional_arity(f: Callable[..., Any]) -> int:
+    """Count the fixed positional parameters of ``f``.
+
+    Currying must know when a call has supplied every positional argument.
+    A ``*args`` parameter makes that unknowable, and a required
+    keyword-only parameter can never be supplied positionally — both are
+    defects and crash at construction instead of misbehaving at call time.
+    """
+    parameters = inspect.signature(f).parameters.values()
+    for parameter in parameters:
+        if parameter.kind is inspect.Parameter.VAR_POSITIONAL:
+            raise TypeError(f"curry requires a fixed arity, got variadic {f!r}")
+        if (
+            parameter.kind is inspect.Parameter.KEYWORD_ONLY
+            and parameter.default is inspect.Parameter.empty
+        ):
+            raise TypeError(
+                f"curry requires positional parameters only, got required "
+                f"keyword-only {parameter.name!r} in {f!r}"
+            )
+    return sum(
+        1
+        for parameter in parameters
+        if parameter.kind
+        in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+    )
+
+
+@overload
+def curry[R](f: Callable[[], R]) -> Callable[[], R]: ...
+@overload
+def curry[A, R](f: Callable[[A], R]) -> Callable[[A], R]: ...
+@overload
+def curry[A, B, R](
+    f: Callable[[A, B], R],
+) -> Callable[[A], Callable[[B], R]]: ...
+@overload
+def curry[A, B, C, R](
+    f: Callable[[A, B, C], R],
+) -> Callable[[A], Callable[[B], Callable[[C], R]]]: ...
+@overload
+def curry[A, B, C, D, R](
+    f: Callable[[A, B, C, D], R],
+) -> Callable[[A], Callable[[B], Callable[[C], Callable[[D], R]]]]: ...
+@overload
+def curry[A, B, C, D, E, R](
+    f: Callable[[A, B, C, D, E], R],
+) -> Callable[[A], Callable[[B], Callable[[C], Callable[[D], Callable[[E], R]]]]]: ...
+def curry(f: Callable[..., Any]) -> Callable[..., Any]:
+    """Curry ``f`` so each step supplies one positional argument.
+
+    ``curry(f)(a)(b)(c)`` is ``f(a, b, c)``; a step may also supply
+    several arguments at once (``curry(f)(a, b)(c)``), and the step that
+    completes the arity runs ``f`` immediately. Arities 1-5 are fully
+    type-checked; the runtime accepts any fixed arity. Variadic ``*args``
+    callables and required keyword-only parameters are rejected at
+    construction — the arity is unknowable or unreachable positionally.
+    """
+    arity = _positional_arity(f)
+
+    def curried(*args: Any) -> Any:
+        if len(args) >= arity:
+            return f(*args)
+        return curry(partial(f, *args))
+
+    return curried
+
+
+def lift[T, U, E](
+    f: Callable[[T], U],
+) -> Callable[[Result[T, E]], Result[U, E]]:
+    """Lift a unary function into the ``Result`` domain.
+
+    ``lift(f)(r)`` is ``r.map(f)`` as a reusable value — useful when the
+    function must be passed somewhere instead of called on a receiver.
+    """
+
+    def lifted(result: Result[T, E]) -> Result[U, E]:
+        if isinstance(result, Ok):
+            return Ok(f(result.value))
+        return result
+
+    return lifted
+
+
+def lift2[T, U, R, E](
+    f: Callable[[T, U], R],
+) -> Callable[[Result[T, E], Result[U, E]], Result[R, E]]:
+    """Lift a binary function into the ``Result`` domain (applicative style).
+
+    ``lift2(f)(r1, r2)`` applies ``f`` to both values, failing fast on the
+    first ``Err``.
+    """
+
+    def lifted(first: Result[T, E], second: Result[U, E]) -> Result[R, E]:
+        if isinstance(first, Err):
+            return first
+        if isinstance(second, Err):
+            return second
+        return Ok(f(first.value, second.value))
+
+    return lifted
+
+
+def lift3[T, U, V, R, E](
+    f: Callable[[T, U, V], R],
+) -> Callable[[Result[T, E], Result[U, E], Result[V, E]], Result[R, E]]:
+    """Lift a ternary function into the ``Result`` domain (applicative style).
+
+    ``lift3(f)(r1, r2, r3)`` applies ``f`` to all three values, failing
+    fast on the first ``Err``.
+    """
+
+    def lifted(
+        first: Result[T, E], second: Result[U, E], third: Result[V, E]
+    ) -> Result[R, E]:
+        if isinstance(first, Err):
+            return first
+        if isinstance(second, Err):
+            return second
+        if isinstance(third, Err):
+            return third
+        return Ok(f(first.value, second.value, third.value))
+
+    return lifted

pyeffect/effect.py

@@ -0,0 +1,279 @@
+# Classic TypeVars are required for the attempt overloads: PEP 695 type
+# params on @overload are not checked by ty (ty 0.0.77 silently skips
+# overload checking and falls back to the implementation signature).
+"""A lazy, fully typed ``Effect``: defer a computation, compose, then run.
+
+An ``Effect[T, E]`` is a *description* of a computation that succeeds with
+``T`` or fails with ``E``. Constructing and composing it runs nothing; only
+``run``/``run_result`` execute the underlying thunk, so effects are
+re-runnable and side effects happen exactly when you run them::
+
+    >>> from pyeffect.effect import Effect
+    >>> Effect.success(2).map(lambda x: x * 3).run()
+    6
+    >>> Effect.attempt(lambda: 1 / 0, catch=lambda e: str(e)).run_result()
+    Err(error='division by zero')
+    >>> Effect.success(1).zip(Effect.success("a")).run()
+    (1, 'a')
+    >>> Effect.failure("boom").context("while parsing").run_result()
+    Err(error=ErrorContext(message='while parsing', source='boom'))
+
+Dependencies are captured in the thunk's closure — the idiomatic Python
+form of dependency injection. ``and_then`` preserves the error type (Python
+generics are invariant, so a widened error union cannot be expressed
+honestly); combine effects with different failure types via ``map_err`` or
+``catch`` first.
+
+Why ``Any`` slots? :meth:`Effect.success` and :meth:`Effect.failure` leave
+the *other* slot as ``Any`` rather than ``Never``: under Python's invariant
+generics a ``Never`` error slot would refuse to flow into chains whose
+error type is fixed later, so ``Effect.success(1).and_then(...)`` would not
+type-check at all. The cost is that the unbound slot stays ``Any`` until
+the chain is anchored — with an annotation (``effect: Effect[int, str] =
+Effect.failure("boom")``) or with an operation that fixes the slot
+(:meth:`Effect.attempt`'s ``catch``, ``map_err``, ``catch``). This is the
+documented compromise of PEP 695 typing, which has no variance annotations.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable, Iterable
+from typing import Any, TypeVar, overload
+
+from pyeffect.result import Err, ErrorContext, Ok, Result, attempt
+from pyeffect.retry import Policy
+from pyeffect.retry import retry as retry_result
+
+__all__ = ["Effect", "sequence"]
+
+_AttemptT = TypeVar("_AttemptT")
+_AttemptE = TypeVar("_AttemptE")
+
+
+class Effect[T, E]:
+    """A deferred computation that succeeds with ``T`` or fails with ``E``."""
+
+    __slots__ = ("_thunk",)
+
+    def __init__(self, thunk: Callable[[], Result[T, E]]) -> None:
+        self._thunk = thunk
+
+    @staticmethod
+    def success[U](value: U) -> Effect[U, Any]:
+        """An effect that yields ``value``.
+
+        The error slot is unbound (``Any``) so it composes into chains
+        with any error type — under Python's invariant generics a
+        ``Never`` error slot would refuse to flow into typed chains.
+        """
+
+        return Effect(lambda: Ok(value))
+
+    @staticmethod
+    def failure[V](error: V) -> Effect[Any, V]:
+        """An effect that fails with ``error``.
+
+        The success slot is unbound (``Any``) — declare it with an
+        annotation (``effect: Effect[int, str] = Effect.failure("boom")``)
+        and :meth:`catch` recovers with full precision.
+        """
+
+        return Effect(lambda: Err(error))
+
+    @overload
+    @staticmethod
+    def attempt(fn: Callable[[], _AttemptT]) -> Effect[_AttemptT, Exception]: ...
+    @overload
+    @staticmethod
+    def attempt(
+        fn: Callable[[], _AttemptT], *, catch: Callable[[Exception], _AttemptE]
+    ) -> Effect[_AttemptT, _AttemptE]: ...
+    @staticmethod
+    def attempt(
+        fn: Callable[[], _AttemptT],
+        *,
+        catch: Callable[[Exception], Any] = lambda e: e,
+    ) -> Effect[_AttemptT, Any]:
+        """An effect that runs ``fn`` and captures its failure as a value.
+
+        The exception boundary for effects: :func:`pyeffect.result.attempt`
+        deferred until ``run``/``run_result``. Only ``Exception`` is
+        captured — ``KeyboardInterrupt`` and ``SystemExit`` are
+        bugs/interrupts and must propagate (fail fast).
+        """
+
+        def thunk() -> Result[_AttemptT, Any]:
+            return attempt(fn, catch=catch)
+
+        return Effect(thunk)
+
+    def map[U](self, f: Callable[[T], U]) -> Effect[U, E]:
+        """Transform the success value; a failure passes through unchanged."""
+
+        return Effect(lambda: self._thunk().map(f))
+
+    def map_err[E2](self, f: Callable[[E], E2]) -> Effect[T, E2]:
+        """Transform the failure value; a success passes through unchanged."""
+
+        return Effect(lambda: self._thunk().map_err(f))
+
+    def inspect(self, f: Callable[[T], object]) -> Effect[T, E]:
+        """Run ``f`` on the success value for its side effect, lazily."""
+
+        return Effect(lambda: self._thunk().inspect(f))
+
+    def inspect_err(self, f: Callable[[E], object]) -> Effect[T, E]:
+        """Run ``f`` on the failure for its side effect, lazily."""
+
+        return Effect(lambda: self._thunk().inspect_err(f))
+
+    def and_then[U](self, f: Callable[[T], Effect[U, E]]) -> Effect[U, E]:
+        """Chain onto the success value; a failure short-circuits."""
+
+        def thunk() -> Result[U, E]:
+            return self._thunk().and_then(lambda value: f(value).run_result())
+
+        return Effect(thunk)
+
+    def and_[U](self, other: Effect[U, E]) -> Effect[U, E]:
+        """Run ``self``; on success run and return ``other`` (the eager ``and``)."""
+
+        return self.and_then(lambda _: other)
+
+    def flatten[U](self: Effect[Effect[U, E], E]) -> Effect[U, E]:
+        """Collapse a nested effect: running it runs the inner effect."""
+
+        def thunk() -> Result[U, E]:
+            outer = self._thunk()
+            if isinstance(outer, Ok):
+                return outer.value.run_result()
+            return outer
+
+        return Effect(thunk)
+
+    def zip[U](self, other: Effect[U, E]) -> Effect[tuple[T, U], E]:
+        """Pair this effect's value with ``other``'s; fail fast on the first error.
+
+        Nothing runs at construction. When the result is run, the thunks
+        execute left to right, and the second is skipped entirely if the
+        first fails.
+        """
+
+        def thunk() -> Result[tuple[T, U], E]:
+            first = self._thunk()
+            if isinstance(first, Ok):
+                second = other._thunk()
+                if isinstance(second, Ok):
+                    return Ok((first.value, second.value))
+                return second
+            return first
+
+        return Effect(thunk)
+
+    def map2[U, R](self, other: Effect[U, E], f: Callable[[T, U], R]) -> Effect[R, E]:
+        """Apply ``f`` to this effect's value and ``other``'s; fail fast.
+
+        ``a.map2(b, f)`` is ``a.zip(b).map(unpack(f))``, deferred and lazy.
+        """
+
+        def thunk() -> Result[R, E]:
+            first = self._thunk()
+            if isinstance(first, Ok):
+                second = other._thunk()
+                if isinstance(second, Ok):
+                    return Ok(f(first.value, second.value))
+                return second
+            return first
+
+        return Effect(thunk)
+
+    def catch[E2](self, f: Callable[[E], Effect[T, E2]]) -> Effect[T, E2]:
+        """Recover from failure; a success passes through unchanged."""
+
+        def thunk() -> Result[T, E2]:
+            return self._thunk().or_else(lambda error: f(error).run_result())
+
+        return Effect(thunk)
+
+    def or_[F](self, other: Effect[T, F]) -> Effect[T, F]:
+        """Run ``self``; on failure run and return ``other`` (the eager ``or``)."""
+
+        return self.catch(lambda _: other)
+
+    def map_or[R](self, default: R, f: Callable[[T], R]) -> Effect[R, E]:
+        """Apply ``f`` to the value, or yield ``default`` on failure."""
+
+        return Effect(lambda: Ok(self._thunk().map_or(default, f)))
+
+    def map_or_else[R](
+        self, default: Callable[[E], R], f: Callable[[T], R]
+    ) -> Effect[R, E]:
+        """Apply ``f`` to the value, or ``default(error)`` on failure."""
+
+        return Effect(lambda: Ok(self._thunk().map_or_else(default, f)))
+
+    def context(self, message: str) -> Effect[T, ErrorContext]:
+        """Attach context to the failure; a success passes through unchanged.
+
+        Mirrors :meth:`pyeffect.result.Result.context` — the error slot
+        becomes an :class:`~pyeffect.result.ErrorContext` carrying the
+        message and the original error.
+        """
+
+        return Effect(lambda: self._thunk().context(message))
+
+    def with_context(self, f: Callable[[E], str]) -> Effect[T, ErrorContext]:
+        """Like :meth:`context`, but the message is computed lazily on failure."""
+
+        return Effect(lambda: self._thunk().with_context(f))
+
+    def retry(
+        self,
+        policy: Policy,
+        *,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> Effect[T, E]:
+        """Re-run this effect's thunk according to ``policy``."""
+
+        def thunk() -> Result[T, E]:
+            return retry_result(lambda _attempt: self._thunk(), policy, sleep=sleep)
+
+        return Effect(thunk)
+
+    def run_result(self) -> Result[T, E]:
+        """Execute the effect and return its :data:`Result`."""
+
+        return self._thunk()
+
+    def run(self) -> T:
+        """Execute the effect and return the value.
+
+        Panics with :class:`~pyeffect.result.UnwrapError` on failure — the
+        caller chose the fail-fast edge. Use :meth:`run_result` or
+        :meth:`catch` to handle failure as a value.
+        """
+
+        return self._thunk().unwrap()
+
+
+def sequence[T, E](effects: Iterable[Effect[T, E]]) -> Effect[list[T], E]:
+    """Run a list of effects in order; fail fast on the first failure.
+
+    The effects are materialized up front, so the resulting effect is
+    re-runnable even when given a generator.
+    """
+
+    materialized = list(effects)
+
+    def thunk() -> Result[list[T], E]:
+        values: list[T] = []
+        for effect in materialized:
+            result = effect.run_result()
+            if isinstance(result, Ok):
+                values.append(result.value)
+            else:
+                return result
+        return Ok(values)
+
+    return Effect(thunk)