pyfect-dev 0.1.0__py3-none-any.whl

pyfect/_effect_logging.py

@@ -0,0 +1,57 @@
+"""``Effect`` methods for logging: annotations, spans and extra loggers."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, overload
+
+from pyfect import _core
+from pyfect._effect_base import A_co, E_co, EffectBase, R_co, as_effect
+
+if TYPE_CHECKING:
+    from pyfect._core import Effect
+    from pyfect._fiber import Fiber
+    from pyfect.logger import Logger
+
+
+class LoggingMethods(EffectBase[A_co, E_co, R_co]):
+    __slots__ = ()
+
+    @overload
+    def annotate_logs(self, key: str, value: object, /) -> Effect[A_co, E_co, R_co]: ...
+    @overload
+    def annotate_logs(self, values: Mapping[str, object], /) -> Effect[A_co, E_co, R_co]: ...
+    def annotate_logs(
+        self, key_or_values: str | Mapping[str, object], value: object = None, /
+    ) -> Effect[A_co, E_co, R_co]:
+        """Run with these annotations added to every log."""
+        from pyfect.logger import CurrentLogAnnotations
+
+        added = {key_or_values: value} if isinstance(key_or_values, str) else dict(key_or_values)
+        return as_effect(self).update_service(
+            CurrentLogAnnotations, lambda annotations: {**annotations, **added}
+        )
+
+    def with_log_span(self, label: str) -> Effect[A_co, E_co, R_co]:
+        """Run inside a log span: logs show ``label=<elapsed>ms``, timed by
+        the ``Clock`` from when this effect starts."""
+        from pyfect.clock import Clock, now_millis_unsafe
+        from pyfect.logger import CurrentLogSpans, LogSpan
+
+        inner = as_effect(self)
+
+        def body(fiber: Fiber[Any, Any]) -> Effect[A_co, E_co, R_co]:
+            span = LogSpan(label, now_millis_unsafe(fiber.get_ref(Clock)))
+            return inner.update_service(CurrentLogSpans, lambda spans: (span, *spans))
+
+        return _core._WithFiber(body)
+
+    def with_logger(self, logger: Logger[object]) -> Effect[A_co, E_co, R_co]:
+        """Run with ``logger`` added to the current loggers."""
+        from pyfect.logger import CurrentLoggers
+
+        return as_effect(self).update_service(
+            CurrentLoggers,
+            lambda loggers: loggers if any(lg is logger for lg in loggers) else (*loggers, logger),
+        )

pyfect/_effect_metrics.py

@@ -0,0 +1,102 @@
+"""``Effect`` methods for metrics: update a metric with how an effect
+ended, what it succeeded or failed with, or how long it took."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, overload
+
+from pyfect import _core
+from pyfect._effect_base import A_co, E_co, EffectBase, R_co, as_effect
+
+if TYPE_CHECKING:
+    from pyfect._core import Effect
+    from pyfect._fiber import Fiber
+    from pyfect.duration import Seconds
+    from pyfect.exit import Exit
+    from pyfect.metric import Metric
+
+
+class MetricMethods(EffectBase[A_co, E_co, R_co]):
+    __slots__ = ()
+
+    @overload
+    def track(self, metric: Metric[Exit[A_co, E_co], object], /) -> Effect[A_co, E_co, R_co]: ...
+    @overload
+    def track[I](
+        self, metric: Metric[I, object], f: Callable[[Exit[A_co, E_co]], I], /
+    ) -> Effect[A_co, E_co, R_co]: ...
+    def track(
+        self, metric: Metric[Any, object], f: Callable[[Any], Any] | None = None, /
+    ) -> Effect[A_co, E_co, R_co]:
+        """Update ``metric`` with this effect's exit (or ``f(exit)``)
+        however it ends."""
+        return as_effect(self).on_exit(lambda ex: metric.update(ex if f is None else f(ex)))
+
+    @overload
+    def track_successes(self, metric: Metric[A_co, object], /) -> Effect[A_co, E_co, R_co]: ...
+    @overload
+    def track_successes[I](
+        self, metric: Metric[I, object], f: Callable[[A_co], I], /
+    ) -> Effect[A_co, E_co, R_co]: ...
+    def track_successes(
+        self, metric: Metric[Any, object], f: Callable[[Any], Any] | None = None, /
+    ) -> Effect[A_co, E_co, R_co]:
+        """Update ``metric`` with each value (or ``f(value)``)."""
+        return as_effect(self).tap(lambda a: metric.update(a if f is None else f(a)))
+
+    @overload
+    def track_errors(self, metric: Metric[E_co, object], /) -> Effect[A_co, E_co, R_co]: ...
+    @overload
+    def track_errors[I](
+        self, metric: Metric[I, object], f: Callable[[E_co], I], /
+    ) -> Effect[A_co, E_co, R_co]: ...
+    def track_errors(
+        self, metric: Metric[Any, object], f: Callable[[Any], Any] | None = None, /
+    ) -> Effect[A_co, E_co, R_co]:
+        """Update ``metric`` with each typed error (or ``f(error)``)."""
+        return as_effect(self).tap_error(lambda e: metric.update(e if f is None else f(e)))
+
+    @overload
+    def track_defects(
+        self, metric: Metric[BaseException, object], /
+    ) -> Effect[A_co, E_co, R_co]: ...
+    @overload
+    def track_defects[I](
+        self, metric: Metric[I, object], f: Callable[[object], I], /
+    ) -> Effect[A_co, E_co, R_co]: ...
+    def track_defects(
+        self, metric: Metric[Any, object], f: Callable[[Any], Any] | None = None, /
+    ) -> Effect[A_co, E_co, R_co]:
+        """Update ``metric`` with each defect (or ``f(defect)``)."""
+        return as_effect(self).tap_defect(lambda d: metric.update(d if f is None else f(d)))
+
+    @overload
+    def track_duration(self, metric: Metric[Seconds, object], /) -> Effect[A_co, E_co, R_co]: ...
+    @overload
+    def track_duration[I](
+        self, metric: Metric[I, object], f: Callable[[Seconds], I], /
+    ) -> Effect[A_co, E_co, R_co]: ...
+    def track_duration(
+        self, metric: Metric[Any, object], f: Callable[[Any], Any] | None = None, /
+    ) -> Effect[A_co, E_co, R_co]:
+        """Update ``metric`` with how long this effect took (or
+        ``f(duration)``), measured on the ``Clock``'s monotonic time
+        however it ends."""
+        from pyfect.clock import Clock
+        from pyfect.duration import Seconds
+
+        inner = as_effect(self)
+
+        def body(fiber: Fiber[Any, Any]) -> Effect[A_co, E_co, R_co]:
+            clock = fiber.get_ref(Clock)
+            start = clock.monotonic_nanos_unsafe()
+
+            def record(_: object) -> Effect[None]:
+                elapsed = Seconds((clock.monotonic_nanos_unsafe() - start) / 1_000_000_000)
+                return metric.update(elapsed if f is None else f(elapsed))
+
+            return inner.on_exit(record)
+
+        return _core._WithFiber(body)

pyfect/_effect_resources.py

@@ -0,0 +1,179 @@
+"""``Effect`` methods for resource safety: finalizers and interruptibility.
+
+Every user callback runs through ``_call_user``, so a raise becomes a
+defect inside the surrounding finalizer or region.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Never
+
+from pyfect import _core
+from pyfect._effect_args import require_effect
+from pyfect._effect_base import A_co, E_co, EffectBase, R_co, Step, as_effect
+from pyfect.cause import Cause, merge
+from pyfect.exit import Exit, Failure, Success
+from pyfect.result import Ok, Result
+
+if TYPE_CHECKING:
+    from pyfect._core import Effect
+
+
+class ResourceMethods(EffectBase[A_co, E_co, R_co]):
+    __slots__ = ()
+
+    def on_exit[R2 = Never](
+        self, f: Callable[[Exit[A_co, E_co]], Effect[object, Never, R2]]
+    ) -> Effect[A_co, E_co, R_co | R2]:
+        """Run ``f`` after this effect however it ends. ``f`` runs
+        uninterruptibly; if it fails, its cause is added to the result."""
+        return _on_exit(as_effect(self), f)
+
+    def on_exit_primitive[E2 = Never, R2 = Never](
+        self,
+        f: Callable[[Exit[A_co, E_co]], Effect[object, E2, R2] | None],
+        interruptible: bool = False,
+    ) -> Effect[A_co, E_co | E2, R_co | R2]:
+        """``on_exit`` whose ``f`` may return ``None``, and may fail, as
+        Effect's building block for it. With ``interruptible`` the finalizer
+        stays as interruptible as the fiber is: ``f`` is still called, but an
+        interrupted fiber does not run the effect it returns."""
+
+        def run(ex: Exit[A_co, E_co]) -> Effect[object, E2, R2]:
+            after = f(ex)
+            return _core._Succeed(None) if after is None else after
+
+        effect = as_effect(self)
+        if not interruptible:
+            return _on_exit(effect, run)
+
+        def finish(ex: Exit[A_co, E_co]) -> Step:
+            return _run_finalizer(run(ex), ex)
+
+        return _core._MatchCause(effect, lambda c: finish(Failure(c)), lambda a: finish(Success(a)))
+
+    def ensuring[R2 = Never](
+        self, finalizer: Effect[object, Never, R2]
+    ) -> Effect[A_co, E_co, R_co | R2]:
+        require_effect(finalizer, "finalizer")
+        return self.on_exit(lambda _: finalizer)
+
+    def on_error[R2 = Never](
+        self, f: Callable[[Cause[E_co]], Effect[object, Never, R2]]
+    ) -> Effect[A_co, E_co, R_co | R2]:
+        def handle(ex: Exit[A_co, E_co]) -> Effect[object, Never, R2]:
+            return f(ex.cause) if isinstance(ex, Failure) else _core._Succeed(None)
+
+        return self.on_exit(handle)
+
+    def on_error_if[E2 = Never, R2 = Never](
+        self,
+        predicate: Callable[[Cause[E_co]], bool],
+        f: Callable[[Cause[E_co]], Effect[object, E2, R2]],
+    ) -> Effect[A_co, E_co | E2, R_co | R2]:
+        """``on_error`` for the causes ``predicate`` accepts. If ``f``
+        fails, its cause is added to the result."""
+
+        def handle(ex: Exit[A_co, E_co]) -> Effect[object, E2, R2]:
+            if isinstance(ex, Failure) and predicate(ex.cause):
+                return f(ex.cause)
+            return _core._Succeed(None)
+
+        return _on_exit(as_effect(self), handle)
+
+    def on_error_filter[B, E2 = Never, R2 = Never](
+        self,
+        filter: Callable[[Cause[E_co]], Result[B, object]],
+        f: Callable[[B, Cause[E_co]], Effect[object, E2, R2]],
+    ) -> Effect[A_co, E_co | E2, R_co | R2]:
+        """``on_error`` for the causes ``filter`` passes (``Ok(value)``):
+        run ``f(value, cause)``."""
+
+        def handle(ex: Exit[A_co, E_co]) -> Effect[object, E2, R2]:
+            if isinstance(ex, Failure):
+                passed = filter(ex.cause)
+                if isinstance(passed, Ok):
+                    return f(passed.value, ex.cause)
+            return _core._Succeed(None)
+
+        return _on_exit(as_effect(self), handle)
+
+    def on_exit_if[E2 = Never, R2 = Never](
+        self,
+        predicate: Callable[[Exit[A_co, E_co]], bool],
+        f: Callable[[Exit[A_co, E_co]], Effect[object, E2, R2]],
+    ) -> Effect[A_co, E_co | E2, R_co | R2]:
+        """``on_exit`` for the exits ``predicate`` accepts. If ``f`` fails,
+        its cause is added to the result."""
+
+        def handle(ex: Exit[A_co, E_co]) -> Effect[object, E2, R2]:
+            return f(ex) if predicate(ex) else _core._Succeed(None)
+
+        return _on_exit(as_effect(self), handle)
+
+    def on_exit_filter[B, E2 = Never, R2 = Never](
+        self,
+        filter: Callable[[Exit[A_co, E_co]], Result[B, object]],
+        f: Callable[[B, Exit[A_co, E_co]], Effect[object, E2, R2]],
+    ) -> Effect[A_co, E_co | E2, R_co | R2]:
+        """``on_exit`` for the exits ``filter`` passes (``Ok(value)``): run
+        ``f(value, exit)``."""
+
+        def handle(ex: Exit[A_co, E_co]) -> Effect[object, E2, R2]:
+            passed = filter(ex)
+            return f(passed.value, ex) if isinstance(passed, Ok) else _core._Succeed(None)
+
+        return _on_exit(as_effect(self), handle)
+
+    def on_interrupt[R2 = Never](
+        self, finalizer: Effect[object, Never, R2]
+    ) -> Effect[A_co, E_co, R_co | R2]:
+        require_effect(finalizer, "finalizer")
+
+        def handle(ex: Exit[A_co, E_co]) -> Effect[object, Never, R2]:
+            if isinstance(ex, Failure) and ex.cause.has_interrupts:
+                return finalizer
+            return _core._Succeed(None)
+
+        return self.on_exit(handle)
+
+    def uninterruptible(self) -> Effect[A_co, E_co, R_co]:
+        return _core._SetInterruptible(as_effect(self), False)
+
+    def interruptible(self) -> Effect[A_co, E_co, R_co]:
+        return _core._SetInterruptible(as_effect(self), True)
+
+
+def _on_exit[A, E, R, E2, R2](
+    eff: Effect[A, E, R], f: Callable[[Exit[A, E]], Effect[object, E2, R2]]
+) -> Effect[A, E | E2, R | R2]:
+    """Run ``f(exit)`` uninterruptibly after ``eff``; a failure of ``f``
+    adds its cause to the result."""
+    return _core.uninterruptible_mask(
+        lambda restore: _core._MatchCause(
+            restore(eff),
+            lambda c: _run_finalizer(_call_user(f, Failure(c)), Failure(c)),
+            lambda a: _run_finalizer(_call_user(f, Success(a)), Success(a)),
+        )
+    )
+
+
+def _call_user[*Ts, A, E, R](f: Callable[[*Ts], Effect[A, E, R]], *args: *Ts) -> Effect[A, E, R]:
+    """Call user code when the effect runs, not when it is built. A raise
+    then becomes a defect at that point of the program, inside whatever
+    finalizer or region surrounds it. Resource and finalizer combinators
+    call every user callback through this."""
+    return _core._Suspend(lambda: f(*args))
+
+
+def _run_finalizer(finalizer: Effect[object, Any, Any], ex: Exit[Any, Any]) -> Step:
+    """Run ``finalizer``, then end with ``ex``. A failing finalizer adds
+    its cause to the result."""
+
+    def after_failure(fin_cause: Cause[Any]) -> Effect[Any, Any, Any]:
+        base = ex.cause if isinstance(ex, Failure) else Cause(())
+        return _core._FailCause(merge(base, fin_cause))
+
+    return _core._MatchCause(finalizer, after_failure, lambda _: _core._FromExit(ex))

pyfect/_effect_services.py

@@ -0,0 +1,25 @@
+"""``Effect`` methods for services."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from pyfect import _core
+from pyfect._effect_base import A_co, E_co, EffectBase, R_co, as_effect
+
+if TYPE_CHECKING:
+    from pyfect._core import Effect
+    from pyfect.context import TagLike
+
+
+class ServiceMethods(EffectBase[A_co, E_co, R_co]):
+    __slots__ = ()
+
+    def update_service[S, T](
+        self, tag: TagLike[S, T], f: Callable[[S], S]
+    ) -> Effect[A_co, E_co, R_co | T]:
+        """Run with ``f`` applied to the service of ``tag``, which this
+        effect then needs."""
+        return _core._Locally(as_effect(self), lambda ctx: ctx.add(tag, f(ctx.get_unsafe(tag))))

pyfect/_effect_timing.py

@@ -0,0 +1,199 @@
+"""``Effect`` methods over time: delaying, timing, caching and schedules.
+The work lives in ``pyfect.clock``, ``pyfect._cached`` and
+``pyfect.schedule``; these are the method spellings."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Never, TypeIs, overload
+
+from pyfect._effect_base import A_co, E_co, EffectBase, R_co, as_effect
+from pyfect.duration import Duration
+
+if TYPE_CHECKING:
+    from pyfect._core import Effect
+    from pyfect.exit import Exit
+    from pyfect.schedule import Metadata, Schedule, SetInputType
+
+
+class TimingMethods(EffectBase[A_co, E_co, R_co]):
+    __slots__ = ()
+
+    def delay(self, duration: Duration) -> Effect[A_co, E_co, R_co]:
+        from pyfect.clock import sleep
+
+        return sleep(duration).and_then(as_effect(self))
+
+    def timed(self) -> Effect[tuple[float, A_co], E_co, R_co]:
+        """Pair the value with how long it took, in seconds."""
+        from pyfect.clock import timed
+
+        return timed(as_effect(self))
+
+    def cached(self) -> Effect[Effect[A_co, E_co, R_co]]:
+        """An effect that runs this one on first use and then replays its
+        exit. Concurrent callers share one run; an interrupted run is not
+        cached (see ``cached_invalidate_with_ttl``)."""
+        from pyfect._cached import cached
+
+        return cached(as_effect(self))
+
+    def cached_with_ttl(
+        self, time_to_live: Duration | Callable[[Exit[A_co, E_co]], Duration]
+    ) -> Effect[Effect[A_co, E_co, R_co]]:
+        """``cached``, but each exit is replayed only for ``time_to_live``
+        (or ``time_to_live(exit)``) after it was produced."""
+        from pyfect._cached import cached_invalidate_with_ttl
+
+        return cached_invalidate_with_ttl(as_effect(self), time_to_live).map(lambda pair: pair[0])
+
+    def cached_invalidate_with_ttl(
+        self, time_to_live: Duration | Callable[[Exit[A_co, E_co]], Duration]
+    ) -> Effect[tuple[Effect[A_co, E_co, R_co], Effect[None]]]:
+        """``cached_with_ttl`` plus an effect that drops the cached exit.
+
+        Callers already waiting on a run keep waiting on it; later callers
+        start a fresh run. A run is interrupted once every caller waiting on
+        it has gone, and an interrupted run is never cached."""
+        from pyfect._cached import cached_invalidate_with_ttl
+
+        return cached_invalidate_with_ttl(as_effect(self), time_to_live)
+
+    @overload
+    def retry[EE = Never, RR = Never](
+        self, policy: Schedule[object, E_co, EE, RR], /
+    ) -> Effect[A_co, E_co | EE, R_co | RR]: ...
+    @overload
+    def retry[A, E, R, EE = Never, RR = Never](
+        self: TimingMethods[A, E, R],
+        builder: Callable[[SetInputType[E]], Schedule[object, E, EE, RR]],
+        /,
+    ) -> Effect[A, E | EE, R | RR]: ...
+    @overload
+    def retry[E2](self, /, *, until: Callable[[E_co], TypeIs[E2]]) -> Effect[A_co, E2, R_co]: ...
+    @overload
+    def retry[EE = Never, RR = Never](
+        self,
+        /,
+        *,
+        schedule: Schedule[object, E_co, EE, RR] | None = None,
+        times: int | None = None,
+        while_: Callable[[E_co], bool | Effect[bool, EE, RR]] | None = None,
+        until: Callable[[E_co], bool | Effect[bool, EE, RR]] | None = None,
+    ) -> Effect[A_co, E_co | EE, R_co | RR]: ...
+    def retry(
+        self,
+        policy: Schedule[Any, Any, Any, Any] | Callable[[Any], Any] | None = None,
+        /,
+        *,
+        schedule: Schedule[Any, Any, Any, Any] | None = None,
+        times: int | None = None,
+        while_: Callable[[Any], Any] | None = None,
+        until: Callable[[Any], Any] | None = None,
+    ) -> Effect[Any, Any, Any]:
+        """Retry on typed failure while ``policy`` recurs; then fail with the
+        last error. Defects and interruptions are not retried.
+
+        ``policy`` is a schedule, or a function from ``SetInputType`` to
+        one, so the schedule's metadata sees this effect's error type::
+
+            eff.retry(lambda typed: typed(schedule.recurs(3)).while_(lambda m: m.input.retryable))
+
+        Instead of a policy, the keywords build one: retry at most
+        ``times`` times, only while ``while_(error)`` holds, until
+        ``until(error)`` holds, on ``schedule``'s delays. Predicates may
+        return a bool or an effect of one; with a ``TypeIs`` predicate as
+        ``until`` and no other keyword, the error narrows (``while_`` can
+        stop on any error, so with it nothing narrows)."""
+        from pyfect.schedule._drive import resolve_policy, retry
+
+        policy = resolve_policy(policy, schedule, times, while_, until)
+        return retry(as_effect(self), policy)
+
+    def retry_or_else[B, A2, EE = Never, RR = Never](
+        self,
+        policy: Schedule[B, E_co, EE, RR],
+        or_else: Callable[[E_co, B], Effect[A2, EE, RR]],
+    ) -> Effect[A_co | A2, EE, R_co | RR]:
+        """``retry``, handing the last error and the policy's final output
+        to ``or_else`` once the policy stops."""
+        from pyfect.schedule._drive import retry_or_else
+
+        return retry_or_else(as_effect(self), policy, or_else)
+
+    @overload
+    def repeat[B, EE = Never, RR = Never](
+        self, schedule: Schedule[B, A_co, EE, RR], /
+    ) -> Effect[B, E_co | EE, R_co | RR]: ...
+    @overload
+    def repeat[A, E, R, B, EE = Never, RR = Never](
+        self: TimingMethods[A, E, R],
+        builder: Callable[[SetInputType[A]], Schedule[B, A, EE, RR]],
+        /,
+    ) -> Effect[B, E | EE, R | RR]: ...
+    @overload
+    def repeat[B](self, /, *, until: Callable[[A_co], TypeIs[B]]) -> Effect[B, E_co, R_co]: ...
+    @overload
+    def repeat[EE = Never, RR = Never](
+        self,
+        /,
+        *,
+        schedule: Schedule[object, A_co, EE, RR] | None = None,
+        times: int | None = None,
+        while_: Callable[[A_co], bool | Effect[bool, EE, RR]] | None = None,
+        until: Callable[[A_co], bool | Effect[bool, EE, RR]] | None = None,
+    ) -> Effect[A_co, E_co | EE, R_co | RR]: ...
+    def repeat(
+        self,
+        policy: Schedule[Any, Any, Any, Any] | Callable[[Any], Any] | None = None,
+        /,
+        *,
+        schedule: Schedule[Any, Any, Any, Any] | None = None,
+        times: int | None = None,
+        while_: Callable[[Any], Any] | None = None,
+        until: Callable[[Any], Any] | None = None,
+    ) -> Effect[Any, Any, Any]:
+        """Repeat after each success while the schedule recurs. Succeeds
+        with the schedule's final output. The schedule may also be given
+        as a function from ``SetInputType`` to one (see ``retry``).
+
+        Instead of a schedule, the keywords build one: repeat at most
+        ``times`` times, only while ``while_(value)`` holds, until
+        ``until(value)`` holds, on ``schedule``'s delays. That form
+        succeeds with the last value, narrowed by a ``TypeIs`` predicate
+        as ``until`` when it is the only keyword. Predicates may
+        return a bool or an effect of one."""
+        from pyfect.schedule._drive import repeat, resolve_policy
+
+        policy = resolve_policy(policy, schedule, times, while_, until)
+        return repeat(as_effect(self), policy)
+
+    def repeat_or_else[B, B2, E2, EE = Never, RR = Never](
+        self,
+        schedule: Schedule[B, A_co, EE, RR],
+        or_else: Callable[[E_co | EE, Metadata[B, A_co] | None], Effect[B2, E2, RR]],
+    ) -> Effect[B | B2, E2, R_co | RR]:
+        """``repeat``, handing a typed failure (of this effect or of the
+        schedule) and the last step's metadata (``None`` before the first)
+        to ``or_else``."""
+        from pyfect.schedule._drive import repeat_or_else
+
+        return repeat_or_else(as_effect(self), schedule, or_else)
+
+    def schedule[B, EE = Never, RR = Never](
+        self, schedule: Schedule[B, A_co | None, EE, RR]
+    ) -> Effect[B, E_co | EE, R_co | RR]:
+        """Run after each recurrence of ``schedule`` (first after its first
+        delay), stepping it with ``None`` and then each result. Succeeds
+        with the schedule's final output."""
+        from pyfect.schedule._drive import scheduled
+
+        return scheduled(as_effect(self), schedule)
+
+    def schedule_from[A, B, EE = Never, RR = Never](
+        self: TimingMethods[A, E_co, R_co], initial: A, schedule: Schedule[B, A, EE, RR]
+    ) -> Effect[B, E_co | EE, R_co | RR]:
+        """``schedule``, stepping first with ``initial``."""
+        from pyfect.schedule._drive import schedule_from
+
+        return schedule_from(as_effect(self), initial, schedule)

pyfect/_effect_tracing.py

@@ -0,0 +1,99 @@
+"""``Effect`` methods for tracing: spans around an effect, and what the
+spans made inside it carry."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Unpack, overload
+
+from pyfect._effect_base import A_co, E_co, EffectBase, R_co, as_effect
+
+if TYPE_CHECKING:
+    from pyfect._core import Effect
+    from pyfect._stack_frame import CaptureStackTrace
+    from pyfect.scope import Scope
+    from pyfect.tracer import AnySpan, TracedSpanOptions, Tracer
+
+
+class TracingMethods(EffectBase[A_co, E_co, R_co]):
+    __slots__ = ()
+
+    def with_span(
+        self, name: str, **options: Unpack[TracedSpanOptions]
+    ) -> Effect[A_co, E_co, R_co]:
+        """Run inside a new span, the parent of the spans made inside. It
+        ends with this effect's exit. Failures inside record the span's
+        stack frame: this call site unless ``capture_stack_trace`` says
+        otherwise."""
+        from pyfect._stack_frame import stack_of
+        from pyfect.tracer._spans import in_span_frame, span_using
+
+        eff = as_effect(self)
+        stack = stack_of(options.get("capture_stack_trace", True), 1)
+        return span_using(name, lambda span: in_span_frame(eff, span, stack), options)
+
+    def with_span_scoped(
+        self, name: str, **options: Unpack[TracedSpanOptions]
+    ) -> Effect[A_co, E_co, R_co | Scope]:
+        """Run inside a new span that ends when the current scope closes."""
+        from pyfect._stack_frame import stack_of
+        from pyfect.tracer._spans import in_span_frame, span_scoped
+
+        eff = as_effect(self)
+        stack = stack_of(options.get("capture_stack_trace", True), 1)
+        return span_scoped(name, options).flat_map(lambda span: in_span_frame(eff, span, stack))
+
+    def with_parent_span(
+        self, span: AnySpan, *, capture_stack_trace: CaptureStackTrace = True
+    ) -> Effect[A_co, E_co, R_co]:
+        """Run with ``span`` as the parent of the spans made inside, and,
+        unless it is external, inside its stack frame."""
+        from pyfect._stack_frame import stack_of
+        from pyfect.tracer._spans import in_span_frame
+
+        return in_span_frame(as_effect(self), span, stack_of(capture_stack_trace, 1))
+
+    @overload
+    def annotate_spans(self, key: str, value: object, /) -> Effect[A_co, E_co, R_co]: ...
+    @overload
+    def annotate_spans(self, values: Mapping[str, object], /) -> Effect[A_co, E_co, R_co]: ...
+    def annotate_spans(
+        self, key_or_values: str | Mapping[str, object], value: object = None, /
+    ) -> Effect[A_co, E_co, R_co]:
+        """Run with these attributes set on every span made inside."""
+        from pyfect.tracer._refs import TracerSpanAnnotations
+
+        added = {key_or_values: value} if isinstance(key_or_values, str) else dict(key_or_values)
+        return as_effect(self).update_service(
+            TracerSpanAnnotations, lambda annotations: {**annotations, **added}
+        )
+
+    def link_spans(
+        self, *spans: AnySpan, attributes: Mapping[str, object] | None = None
+    ) -> Effect[A_co, E_co, R_co]:
+        """Run with links to ``spans`` added to every span made inside."""
+        from pyfect.tracer._model import SpanLink
+        from pyfect.tracer._refs import TracerSpanLinks
+
+        shared: Mapping[str, object] = {} if attributes is None else attributes
+        links = tuple(SpanLink(span, shared) for span in spans)
+        return as_effect(self).update_service(TracerSpanLinks, lambda current: (*current, *links))
+
+    def with_tracer(self, tracer: Tracer) -> Effect[A_co, E_co, R_co]:
+        """Run with spans made by ``tracer``."""
+        from pyfect._tracer_ref import CurrentTracer
+
+        return as_effect(self).update_service(CurrentTracer, lambda _: tracer)
+
+    def with_tracer_enabled(self, enabled: bool) -> Effect[A_co, E_co, R_co]:
+        """Run with tracing on or off: off, every span is a no-op span."""
+        from pyfect.tracer._refs import TracerEnabled
+
+        return as_effect(self).update_service(TracerEnabled, lambda _: enabled)
+
+    def with_tracer_timing(self, enabled: bool) -> Effect[A_co, E_co, R_co]:
+        """Run with span timing on or off: off, spans start and end at 0."""
+        from pyfect.tracer._refs import TracerTimingEnabled
+
+        return as_effect(self).update_service(TracerTimingEnabled, lambda _: enabled)