pyfect-dev 0.1.0__py3-none-any.whl

pyfect/execution_plan/_events.py

@@ -0,0 +1,128 @@
+"""What a running plan reports: ``CurrentMetadata`` inside each attempt and
+the ``Event``\\ s an ``on_event`` observer receives around it."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Generic, Never, TypeVar
+
+from pyfect._core import Effect, _Suspend
+from pyfect.cause import Cause
+from pyfect.clock import Clock, ClockService
+from pyfect.context import Reference
+from pyfect.duration import Seconds
+from pyfect.exit import Exit, Failure
+
+E_co = TypeVar("E_co", covariant=True)
+
+
+@dataclass(frozen=True, slots=True)
+class Metadata:
+    """``attempt`` counts the plan's attempts from 1, across steps;
+    ``step_index`` is the step running it, from 0."""
+
+    attempt: int
+    step_index: int
+
+
+class CurrentMetadata(Reference[Metadata]):
+    """The plan metadata of the running attempt (``attempt`` 0 outside a plan)."""
+
+    @classmethod
+    def default(cls) -> Metadata:
+        return Metadata(attempt=0, step_index=0)
+
+
+@dataclass(frozen=True, slots=True)
+class AttemptStart:
+    """An attempt is about to run. ``step_attempt`` counts attempts within
+    the step, from 1; ``attempt`` matches ``CurrentMetadata.attempt``."""
+
+    attempt: int
+    step_attempt: int
+    step_index: int
+
+
+@dataclass(frozen=True, slots=True)
+class AttemptSuccess:
+    """The attempt started by the last ``AttemptStart`` succeeded after ``duration``."""
+
+    attempt: int
+    step_attempt: int
+    step_index: int
+    duration: Seconds
+
+
+@dataclass(frozen=True, slots=True)
+class AttemptFailure(Generic[E_co]):
+    """The attempt started by the last ``AttemptStart`` failed (or was
+    interrupted) with ``cause`` after ``duration``."""
+
+    attempt: int
+    step_attempt: int
+    step_index: int
+    duration: Seconds
+    cause: Cause[E_co]
+
+
+type Event[E] = AttemptStart | AttemptSuccess | AttemptFailure[E]
+"""Every ``AttemptStart`` is followed by exactly one ``AttemptSuccess`` or
+``AttemptFailure``."""
+
+type OnEvent[E, R] = Callable[[Event[E]], Effect[object, Never, R]]
+
+
+@dataclass(frozen=True, slots=True)
+class AttemptState:
+    attempt: int
+    step_attempt: int
+    step_index: int
+    start_nanos: int
+
+
+class EventEmitter:
+    """Effect's ``makeEventEmitter``: numbers the attempts of one run of a
+    plan and sends their events to ``on_event``, whose failures and defects
+    are dropped so observing never changes the outcome."""
+
+    __slots__ = ("current", "last_step_index", "on_event", "step_attempt")
+
+    def __init__(self, on_event: OnEvent[Any, Any], current: Callable[[], Metadata]) -> None:
+        self.on_event = on_event
+        self.current = current
+        self.last_step_index = -1
+        self.step_attempt = 0
+
+    def _emit(self, event: Event[Any]) -> Effect[None, Never, Any]:
+        return _Suspend(lambda: self.on_event(event)).ignore_cause()
+
+    def begin(self) -> Effect[AttemptState, Never, Any]:
+        def start(clock: ClockService) -> Effect[AttemptState, Never, Any]:
+            meta = self.current()
+            if meta.step_index != self.last_step_index:
+                self.last_step_index = meta.step_index
+                self.step_attempt = 0
+            self.step_attempt += 1
+            state = AttemptState(
+                meta.attempt, self.step_attempt, meta.step_index, clock.monotonic_nanos_unsafe()
+            )
+            event = AttemptStart(state.attempt, state.step_attempt, state.step_index)
+            return self._emit(event).as_(state)
+
+        return Clock().flat_map(start)
+
+    def end(self, state: AttemptState, ex: Exit[Any, Any]) -> Effect[None, Never, Any]:
+        def finish(clock: ClockService) -> Effect[None, Never, Any]:
+            duration = Seconds((clock.monotonic_nanos_unsafe() - state.start_nanos) / 1_000_000_000)
+            event: Event[Any] = (
+                AttemptFailure(
+                    state.attempt, state.step_attempt, state.step_index, duration, ex.cause
+                )
+                if isinstance(ex, Failure)
+                else AttemptSuccess(state.attempt, state.step_attempt, state.step_index, duration)
+            )
+            return self._emit(event)
+
+        return Clock().flat_map(finish)

pyfect/execution_plan/_model.py

@@ -0,0 +1,108 @@
+"""``ExecutionPlan`` values: steps, ``make``, ``merge`` and
+``capture_requirements``."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Generic, Never, TypeVar
+
+from pyfect._core import Effect, _Succeed, _WithFiber
+from pyfect.context import Context
+from pyfect.layer import Layer, provide, succeed_context
+from pyfect.schedule import Schedule
+from pyfect.schedule._model import StepFn
+
+# Variance is declared, not inferred: a step providing more services is a
+# step providing fewer (``Layer`` and ``Context`` are contravariant in what
+# they provide), so ``make`` over steps solves ``P`` to what *every* step
+# provides, Effect's intersection of the steps' services.
+P_contra = TypeVar("P_contra", contravariant=True)
+In_contra = TypeVar("In_contra", contravariant=True, default=object)
+E_co = TypeVar("E_co", covariant=True, default=Never)
+R_co = TypeVar("R_co", covariant=True, default=Never)
+
+type Predicate[In, E, R] = Callable[[In], bool | Effect[bool, E, R]]
+
+
+@dataclass(frozen=True, slots=True)
+class Step(Generic[P_contra, In_contra, E_co, R_co]):
+    """One step of a plan (Effect's ``ExecutionPlan.make.Step``): run with
+    ``provide`` (a layer or a context) up to ``attempts`` times, retrying
+    on ``schedule``'s delays while ``while_(error)`` holds.
+
+    Without ``attempts`` or ``schedule`` the step runs once. ``attempts``
+    must be at least 1 (``make`` checks it)."""
+
+    provide: Context[P_contra] | Layer[P_contra, E_co, R_co]
+    attempts: int | None = None
+    while_: Predicate[In_contra, E_co, R_co] | None = None
+    schedule: Schedule[Any, In_contra, E_co, R_co] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionPlan(Generic[P_contra, In_contra, E_co, R_co]):
+    """``ExecutionPlan[P, In, E, R]``: steps to try in order until one
+    succeeds. ``P`` is what every step provides, ``In`` the errors the
+    steps' predicates and schedules accept, ``E`` and ``R`` what building
+    the steps' layers and running their predicates and schedules may fail
+    with and need. Build one with ``make`` or ``merge``."""
+
+    steps: tuple[Step[P_contra, In_contra, E_co, R_co], ...]
+
+    @property
+    def capture_requirements(self) -> Effect[ExecutionPlan[P_contra, In_contra, E_co], Never, R_co]:
+        """The plan with the current services baked into every step's
+        layer, predicate and schedule, so it no longer needs ``R``. The
+        captured services win over those where the plan later runs."""
+        steps = self.steps
+        return _WithFiber(
+            lambda fiber: _Succeed(ExecutionPlan(tuple(_capture(s, fiber._context) for s in steps)))
+        )
+
+
+def make[P, In = object, EE = Never, RR = Never](
+    first: Step[P, In, EE, RR], /, *rest: Step[P, In, EE, RR]
+) -> ExecutionPlan[P, In, EE, RR]:
+    """A plan of one or more steps (Effect's ``ExecutionPlan.make``)."""
+    steps = (first, *rest)
+    for i, step in enumerate(steps):
+        if step.attempts is not None and step.attempts < 1:
+            raise ValueError(f"ExecutionPlan.make: step[{i}].attempts must be greater than 0")
+    return ExecutionPlan(steps)
+
+
+def merge[P, In = object, EE = Never, RR = Never](
+    first: ExecutionPlan[P, In, EE, RR], /, *rest: ExecutionPlan[P, In, EE, RR]
+) -> ExecutionPlan[P, In, EE, RR]:
+    """One plan running the steps of each plan in turn."""
+    return ExecutionPlan(tuple(step for plan in (first, *rest) for step in plan.steps))
+
+
+def _capture(step: Step[Any, Any, Any, Any], ctx: Context[Any]) -> Step[Any, Any, Any, Never]:
+    with_ctx = provide(ctx)
+    predicate = step.while_
+    schedule = step.schedule
+    source = step.provide
+    return Step(
+        provide=source if isinstance(source, Context) else provide(succeed_context(ctx))(source),
+        attempts=step.attempts,
+        while_=None if predicate is None else lambda error: with_ctx(_as_effect(predicate(error))),
+        schedule=None if schedule is None else _capture_schedule(schedule, ctx),
+    )
+
+
+def _as_effect(verdict: bool | Effect[bool, Any, Any]) -> Effect[bool, Any, Any]:
+    return verdict if isinstance(verdict, Effect) else _Succeed(verdict)
+
+
+def _capture_schedule(
+    schedule: Schedule[Any, Any, Any, Any], ctx: Context[Any]
+) -> Schedule[Any, Any, Any, Never]:
+    with_ctx = provide(ctx)
+
+    def wrap(step: StepFn[Any, Any, Any, Any]) -> StepFn[Any, Any, Any, Never]:
+        return lambda now, input: with_ctx(step(now, input))
+
+    return Schedule(with_ctx(schedule._make_step.map(wrap)))

pyfect/execution_plan/_run.py

@@ -0,0 +1,176 @@
+"""Running an effect under a plan (Effect's ``Effect.withExecutionPlan``),
+and the per-step retry schedules shared with ``Stream.with_execution_plan``."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from typing import Any, Generic, Never, TypeVar, overload
+
+from pyfect._context_effects import provide_service_effect
+from pyfect._core import Effect, _Gen, _Suspend, uninterruptible_mask
+from pyfect._effect_args import require_effect
+from pyfect.effect import from_result, sync
+from pyfect.execution_plan._events import (
+    CurrentMetadata,
+    EventEmitter,
+    Metadata,
+    OnEvent,
+)
+from pyfect.execution_plan._model import ExecutionPlan, Step
+from pyfect.layer import provide
+from pyfect.result import Ok, Result
+from pyfect.schedule import Schedule, recurs
+from pyfect.schedule._drive import from_options, retry
+
+P_contra = TypeVar("P_contra", contravariant=True)
+In_contra = TypeVar("In_contra", contravariant=True)
+PE_co = TypeVar("PE_co", covariant=True)
+PR_co = TypeVar("PR_co", covariant=True)
+
+_ONCE = recurs(1)
+
+
+def first_schedule(step: Step[Any, Any, Any, Any]) -> Schedule[Any, Any, Any, Any] | None:
+    """The retry schedule of the plan's first step: ``attempts - 1``
+    retries on the step's schedule, or none when it runs once."""
+    if step.attempts == 1 or not (step.schedule or step.attempts):
+        return None
+    times = None if step.attempts is None else step.attempts - 1
+    return from_options(step.schedule, times, step.while_, None)
+
+
+def fallback_schedule(step: Step[Any, Any, Any, Any]) -> Schedule[Any, Any, Any, Any]:
+    """The retry schedule of a step after an earlier one failed: its first
+    retry replays that failure, so the step's schedule (or a single retry)
+    always applies at least once."""
+    default = None if step.attempts else _ONCE
+    return from_options(step.schedule or default, step.attempts, step.while_, None)
+
+
+class PlanRun:
+    """The state of one run of a plan: which step is running and the
+    metadata of the latest attempt."""
+
+    __slots__ = ("emitter", "index", "meta")
+
+    def __init__(self, on_event: OnEvent[Any, Any] | None) -> None:
+        self.index = 0
+        self.meta = CurrentMetadata.default()
+        self.emitter = None if on_event is None else EventEmitter(on_event, lambda: self.meta)
+
+    def next_meta(self) -> Metadata:
+        self.meta = Metadata(attempt=self.meta.attempt + 1, step_index=self.index)
+        return self.meta
+
+
+def _provide_meta[A, E, R](run: PlanRun, eff: Effect[A, E, R]) -> Effect[A, E, R]:
+    return eff.pipe(provide_service_effect(CurrentMetadata, sync(run.next_meta)))
+
+
+def _instrument[A, E, R](run: PlanRun, attempt: Effect[A, E, R]) -> Effect[A, E, R]:
+    emitter = run.emitter
+    if emitter is None:
+        return attempt
+    return uninterruptible_mask(
+        lambda restore: emitter.begin().flat_map(
+            lambda state: restore(attempt).on_exit(lambda ex: emitter.end(state, ex))
+        )
+    )
+
+
+def _replaying_first(
+    failed: Result[Any, Any], attempt: Effect[Any, Any, Any]
+) -> Effect[Any, Any, Any]:
+    replayed = False
+
+    def next_run() -> Effect[Any, Any, Any]:
+        nonlocal replayed
+        if replayed:
+            return attempt
+        replayed = True
+        return from_result(failed)
+
+    return _Suspend(next_run)
+
+
+def run_plan(
+    eff: Effect[Any, Any, Any],
+    plan: ExecutionPlan[Any, Any, Any, Any],
+    on_event: OnEvent[Any, Any] | None,
+) -> Effect[Any, Any, Any]:
+    def attempt(run: PlanRun, step: Step[Any, Any, Any, Any]) -> Effect[Any, Any, Any]:
+        return _provide_meta(run, _instrument(run, provide(step.provide)(eff)))
+
+    def body() -> Any:
+        run = PlanRun(on_event)
+        first, *rest = plan.steps
+        policy = first_schedule(first)
+        tried = attempt(run, first)
+        result = yield from (tried if policy is None else retry(tried, policy)).result()
+        for step in rest:
+            if isinstance(result, Ok):
+                break
+            run.index += 1
+            replayed = _replaying_first(result, attempt(run, step))
+            result = yield from retry(replayed, fallback_schedule(step)).result()
+        return (yield from from_result(result))
+
+    return _Gen(body)
+
+
+class _WithExecutionPlan(Generic[P_contra, In_contra, PE_co, PR_co]):
+    """Runs an effect under a plan, removing ``P`` from its services. When
+    the plan's predicates or schedules read the errors (``In`` is not
+    ``object``), the effect's errors must be ``In`` and are typed as ``In``."""
+
+    __slots__ = ("on_event", "plan")
+
+    def __init__(
+        self, plan: ExecutionPlan[Any, Any, Any, Any], on_event: OnEvent[Any, Any] | None
+    ) -> None:
+        self.plan = plan
+        self.on_event = on_event
+
+    @overload
+    def __call__[A, E, R = Never](
+        self: _WithExecutionPlan[P_contra, object, PE_co, PR_co], eff: Effect[A, E, P_contra]
+    ) -> Effect[A, E | PE_co, PR_co]: ...
+    @overload
+    def __call__[A, E, R = Never](
+        self: _WithExecutionPlan[P_contra, object, PE_co, PR_co], eff: Effect[A, E, P_contra | R]
+    ) -> Effect[A, E | PE_co, R | PR_co]: ...
+    @overload
+    def __call__[A, R = Never](
+        self, eff: Effect[A, In_contra, P_contra]
+    ) -> Effect[A, In_contra | PE_co, PR_co]: ...
+    @overload
+    def __call__[A, R = Never](
+        self, eff: Effect[A, In_contra, P_contra | R]
+    ) -> Effect[A, In_contra | PE_co, R | PR_co]: ...
+    def __call__(self, eff: Effect[Any, Any, Any]) -> Effect[Any, Any, Any]:
+        require_effect(eff, "eff")
+        return run_plan(eff, self.plan, self.on_event)
+
+
+@overload
+def with_execution_plan[P, In, PE, PR](
+    plan: ExecutionPlan[P, In, PE, PR],
+) -> _WithExecutionPlan[P, In, PE, PR]: ...
+@overload
+def with_execution_plan[P, In, PE, RR](
+    plan: ExecutionPlan[P, In, PE, RR], *, on_event: OnEvent[In | PE, RR]
+) -> _WithExecutionPlan[P, In, PE, RR]: ...
+def with_execution_plan(
+    plan: ExecutionPlan[Any, Any, Any, Any], *, on_event: OnEvent[Any, Any] | None = None
+) -> _WithExecutionPlan[Any, Any, Any, Any]:
+    """Run an effect under ``plan``: each step in turn, with the services
+    it provides, retried as the step says, until an attempt succeeds or
+    the plan runs out (then fail with the last error). Defects and
+    interruptions are not retried. Use with ``.pipe``::
+
+        fetch.pipe(fx.with_execution_plan(plan))
+
+    Each attempt sees its ``CurrentMetadata``. ``on_event`` observes every
+    attempt's start and end, in order; its failures are ignored, and the
+    end is reported even when the attempt is interrupted."""
+    return _WithExecutionPlan(plan, on_event)

pyfect/exit.py

@@ -0,0 +1,205 @@
+"""The outcome of running an effect: ``Success[A] | Failure[E]``.
+
+Test which one you have with ``match`` (``case Success(v)`` /
+``case Failure(cause)``), ``isinstance``, or the ``is_success`` /
+``is_failure`` guards. The methods exist on both classes, so they work on
+an ``Exit`` without narrowing first.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from typing import Generic, Never, TypeIs, TypeVar
+
+from pyfect._some import Some
+from pyfect.cause import Cause
+from pyfect.cause import die as _die_cause
+from pyfect.cause import fail as _fail_cause
+from pyfect.cause import interrupt as _interrupt_cause
+from pyfect.result import Err, Ok, Result
+
+A_co = TypeVar("A_co", covariant=True)
+E_co = TypeVar("E_co", covariant=True)
+
+
+@dataclass(frozen=True, slots=True)
+class Success(Generic[A_co]):
+    value: A_co
+
+    def map[B](self, f: Callable[[A_co], B]) -> Success[B]:
+        return Success(f(self.value))
+
+    def map_error(self, f: Callable[[Never], object]) -> Success[A_co]:
+        return self
+
+    def map_both[B](
+        self, *, on_failure: Callable[[Never], object], on_success: Callable[[A_co], B]
+    ) -> Success[B]:
+        return Success(on_success(self.value))
+
+    def as_void(self) -> Success[None]:
+        return Success(None)
+
+    def match[C](
+        self, *, on_failure: Callable[[Never], object], on_success: Callable[[A_co], C]
+    ) -> C:
+        return on_success(self.value)
+
+    @property
+    def has_fails(self) -> bool:
+        return False
+
+    @property
+    def has_dies(self) -> bool:
+        return False
+
+    @property
+    def has_interrupts(self) -> bool:
+        return False
+
+    def filter_success(self) -> Ok[Success[A_co]]:
+        return Ok(self)
+
+    def filter_value(self) -> Ok[A_co]:
+        return Ok(self.value)
+
+    def filter_failure(self) -> Err[Success[A_co]]:
+        return Err(self)
+
+    def filter_cause(self) -> Err[Success[A_co]]:
+        return Err(self)
+
+    def find_error(self) -> Err[Success[A_co]]:
+        return Err(self)
+
+    def find_defect(self) -> Err[Success[A_co]]:
+        return Err(self)
+
+    def get_success(self) -> Some[A_co]:
+        return Some(self.value)
+
+    def get_cause(self) -> None:
+        return None
+
+
+@dataclass(frozen=True, slots=True)
+class Failure(Generic[E_co]):
+    cause: Cause[E_co]
+
+    def map(self, f: Callable[[Never], object]) -> Failure[E_co]:
+        return self
+
+    def map_error[E2](self, f: Callable[[E_co], E2]) -> Failure[E2]:
+        """Map the typed errors; defects and interruptions stay."""
+        return Failure(self.cause.map(f))
+
+    def map_both[E2](
+        self, *, on_failure: Callable[[E_co], E2], on_success: Callable[[Never], object]
+    ) -> Failure[E2]:
+        return Failure(self.cause.map(on_failure))
+
+    def as_void(self) -> Failure[E_co]:
+        return self
+
+    def match[B](
+        self, *, on_failure: Callable[[Cause[E_co]], B], on_success: Callable[[Never], object]
+    ) -> B:
+        return on_failure(self.cause)
+
+    @property
+    def has_fails(self) -> bool:
+        return self.cause.has_fails
+
+    @property
+    def has_dies(self) -> bool:
+        return self.cause.has_dies
+
+    @property
+    def has_interrupts(self) -> bool:
+        return self.cause.has_interrupts
+
+    def filter_success(self) -> Err[Failure[E_co]]:
+        return Err(self)
+
+    def filter_value(self) -> Err[Failure[E_co]]:
+        return Err(self)
+
+    def filter_failure(self) -> Ok[Failure[E_co]]:
+        return Ok(self)
+
+    def filter_cause(self) -> Ok[Cause[E_co]]:
+        return Ok(self.cause)
+
+    def find_error(self) -> Result[E_co, Failure[E_co]]:
+        """``Ok`` of the first typed error, else ``Err`` of this exit."""
+        found = self.cause.find_error()
+        return found if isinstance(found, Ok) else Err(self)
+
+    def find_defect(self) -> Result[object, Failure[E_co]]:
+        found = self.cause.find_defect()
+        return found if isinstance(found, Ok) else Err(self)
+
+    def get_success(self) -> None:
+        return None
+
+    def get_cause(self) -> Some[Cause[E_co]]:
+        return Some(self.cause)
+
+
+type Exit[A, E] = Success[A] | Failure[E]
+
+
+def succeed[A](value: A) -> Success[A]:
+    return Success(value)
+
+
+void: Success[None] = Success(None)
+"""``Success(None)``."""
+
+
+def fail_cause[E](cause: Cause[E]) -> Failure[E]:
+    return Failure(cause)
+
+
+def fail[E](error: E) -> Failure[E]:
+    return Failure(_fail_cause(error))
+
+
+def die(defect: object) -> Failure[Never]:
+    return Failure(_die_cause(defect))
+
+
+def interrupt(fiber_id: int | None = None) -> Failure[Never]:
+    return Failure(_interrupt_cause(fiber_id))
+
+
+def is_success[A, E](ex: Exit[A, E]) -> TypeIs[Success[A]]:
+    return isinstance(ex, Success)
+
+
+def is_failure[A, E](ex: Exit[A, E]) -> TypeIs[Failure[E]]:
+    return isinstance(ex, Failure)
+
+
+def as_void_all[E = Never](exits: Iterable[Exit[object, E]]) -> Exit[None, E]:
+    """``Success(None)`` if every exit succeeded, otherwise one failure
+    holding every failed exit's reasons, in order."""
+    reasons = tuple(r for ex in exits if isinstance(ex, Failure) for r in ex.cause.reasons)
+    return Failure(Cause(reasons)) if reasons else Success(None)
+
+
+__all__ = [
+    "Exit",
+    "Failure",
+    "Success",
+    "as_void_all",
+    "die",
+    "fail",
+    "fail_cause",
+    "interrupt",
+    "is_failure",
+    "is_success",
+    "succeed",
+    "void",
+]