pyfect-dev 0.1.0__py3-none-any.whl

pyfect/_core.py

@@ -0,0 +1,368 @@
+"""``Effect[A, E, R]``: the lazy description of a computation, and its
+sequencing methods.
+
+An effect is an immutable description. Running it is the fiber's job
+(``pyfect._fiber``). The runtime loop knows nothing about specific
+primitives: each primitive reduces itself in ``_step``, and continuation
+frames (often the primitive itself, pushed onto the fiber's stack) consume
+the result in ``_on_success`` / ``_on_failure``. The step protocol is in
+``pyfect._effect_base``.
+
+``Effect`` gathers its methods from one module per concern:
+
+- sequencing: here
+- error handling: ``pyfect._effect_errors``
+- folding (``match``, ``exit``, ``result``): ``pyfect._effect_folding``
+- finalizers and interruptibility: ``pyfect._effect_resources``
+- log annotations, log spans and loggers: ``pyfect._effect_logging``
+- tracing spans: ``pyfect._effect_tracing``
+- forking, racing and timeouts: ``pyfect._effect_concurrency``
+- delays, caching and schedules: ``pyfect._effect_timing``
+
+Every method is built from about a dozen primitives, defined in
+``pyfect._primitives`` and re-exported from this module. Import effects and
+primitives from here: loading this module loads the rest in the right order.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Generator, Iterable
+from typing import TYPE_CHECKING, Any, Literal, Never, Self, TypeIs, cast, overload
+
+from pyfect._effect_args import require_effect
+from pyfect._effect_base import SUSPEND, A_co, E_co, EffectBase, Frame, R_co, Step
+from pyfect._effect_concurrency import ConcurrencyMethods
+from pyfect._effect_eager import EagerMethods
+from pyfect._effect_errors import (
+    ErrorMethods,
+    _catching_if,
+    _fail,
+    _ignore_failure,
+    _recovering,
+    _succeed_none,
+)
+from pyfect._effect_folding import FoldingMethods
+from pyfect._effect_logging import LoggingMethods
+from pyfect._effect_metrics import MetricMethods
+from pyfect._effect_resources import ResourceMethods, _call_user, _run_finalizer
+from pyfect._effect_services import ServiceMethods
+from pyfect._effect_timing import TimingMethods
+from pyfect._effect_tracing import TracingMethods
+from pyfect.result import Err, Ok
+
+if TYPE_CHECKING:
+    from pyfect._concurrency import Concurrency
+    from pyfect._fiber import Fiber
+    from pyfect.errors import NoSuchElementException
+    from pyfect.option import Option
+
+
+class Effect(
+    EagerMethods[A_co, E_co, R_co],
+    ErrorMethods[A_co, E_co, R_co],
+    FoldingMethods[A_co, E_co, R_co],
+    ResourceMethods[A_co, E_co, R_co],
+    ServiceMethods[A_co, E_co, R_co],
+    LoggingMethods[A_co, E_co, R_co],
+    TracingMethods[A_co, E_co, R_co],
+    MetricMethods[A_co, E_co, R_co],
+    ConcurrencyMethods[A_co, E_co, R_co],
+    TimingMethods[A_co, E_co, R_co],
+):
+    """A lazy description of a computation.
+
+    - ``A``: the value it succeeds with
+    - ``E``: the typed errors it can fail with (``Never`` if none)
+    - ``R``: the services it needs (``Never`` if none)
+
+    Build effects with the functions in ``pyfect`` (``succeed``, ``gen``,
+    ...). Inside a generator, ``x = yield from eff`` runs ``eff`` and gives
+    back its value; its errors and requirements join the generator's own.
+    """
+
+    __slots__ = ()
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        raise NotImplementedError(f"{type(self).__name__} is not a primitive")
+
+    def __iter__(self) -> Generator[Effect[Any, E_co, R_co], Any, A_co]:
+        return (yield self)
+
+    def pipe[B](self, f: Callable[[Self], B], /) -> B:
+        """Apply ``f`` to this effect. One step per call, on purpose:
+        pyright only narrows types correctly for a single step, so chain
+        ``.pipe(a).pipe(b)`` rather than passing several functions."""
+        return f(self)
+
+    # --- sequencing -------------------------------------------------------
+
+    def map[B](self, f: Callable[[A_co], B]) -> Effect[B, E_co, R_co]:
+        return _Map(self, f)
+
+    def flat_map[B, E2 = Never, R2 = Never](
+        self, f: Callable[[A_co], Effect[B, E2, R2]]
+    ) -> Effect[B, E_co | E2, R_co | R2]:
+        return _FlatMap(self, f)
+
+    def and_then[B, E2 = Never, R2 = Never](
+        self, that: Effect[B, E2, R2] | Callable[[A_co], Effect[B, E2, R2]]
+    ) -> Effect[B, E_co | E2, R_co | R2]:
+        """Run ``that``, or ``that(value)``, after this effect, keeping only
+        its value."""
+        if callable(that) and not isinstance(that, EffectBase):
+            return _FlatMap(self, that)
+        effect = cast("Effect[B, E2, R2]", that)
+        require_effect(effect, "that")
+        return _FlatMap(self, lambda _: effect)
+
+    def tap[E2 = Never, R2 = Never](
+        self, f: Callable[[A_co], Effect[object, E2, R2]]
+    ) -> Effect[A_co, E_co | E2, R_co | R2]:
+        """Run ``f(value)`` for its effects, keeping the original value."""
+        return _FlatMap(self, lambda a: _Map(f(a), lambda _: a))
+
+    def as_[B](self, value: B) -> Effect[B, E_co, R_co]:
+        return _Map(self, lambda _: value)
+
+    def as_void(self) -> Effect[None, E_co, R_co]:
+        return _Map(self, _to_none)
+
+    def zip[B, E2 = Never, R2 = Never](
+        self, that: Effect[B, E2, R2], *, concurrent: bool = False
+    ) -> Effect[tuple[A_co, B], E_co | E2, R_co | R2]:
+        """Pair the results: in order, or both at once with ``concurrent``."""
+        require_effect(that, "that")
+        return self.zip_with(that, _pair, concurrent=concurrent)
+
+    def zip_with[B, C, E2 = Never, R2 = Never](
+        self, that: Effect[B, E2, R2], f: Callable[[A_co, B], C], *, concurrent: bool = False
+    ) -> Effect[C, E_co | E2, R_co | R2]:
+        """Combine the results with ``f``. With ``concurrent``, both run at
+        once and the first failure interrupts the other."""
+        require_effect(that, "that")
+        if not concurrent:
+            return _FlatMap(self, lambda a: _Map(that, lambda b: f(a, b)))
+        from pyfect._all import all
+
+        return all(self, that, concurrency=2).map(lambda ab: f(*ab))
+
+    @overload
+    def replicate_effect(
+        self, n: int, *, concurrency: Concurrency = None, discard: Literal[False] = False
+    ) -> Effect[list[A_co], E_co, R_co]: ...
+    @overload
+    def replicate_effect(
+        self, n: int, *, concurrency: Concurrency = None, discard: Literal[True]
+    ) -> Effect[None, E_co, R_co]: ...
+    def replicate_effect(
+        self, n: int, *, concurrency: Concurrency = None, discard: bool = False
+    ) -> Effect[Any, E_co, R_co]:
+        """Run this effect ``n`` times, like ``for_each``, collecting the
+        values (or none, with ``discard``)."""
+        from pyfect._concurrency import for_each
+
+        repeated = for_each([self] * n, _identity, concurrency=concurrency)
+        return repeated.as_void() if discard else repeated
+
+    def replicate(self, n: int) -> list[Effect[A_co, E_co, R_co]]:
+        """A list holding this effect ``n`` times."""
+        return [self] * n
+
+    def forever(self, *, disable_yield: bool = False) -> Effect[Never, E_co, R_co]:
+        """Run this effect again and again, until it fails. As in Effect,
+        the fiber yields after each run (so a loop of steps that never wait
+        lets other fibers in between), unless ``disable_yield``."""
+        if disable_yield:
+            loop: Effect[Never, E_co, R_co] = _Suspend(lambda: _FlatMap(self, lambda _: loop))
+            return loop
+        yielding: Effect[Never, E_co, R_co] = _Suspend(
+            lambda: _FlatMap(self, lambda _: _FlatMap(_YieldNow(), lambda _: yielding))
+        )
+        return yielding
+
+    def flatten[B, E2, R2](
+        self: Effect[Effect[B, E2, R2], E_co, R_co],
+    ) -> Effect[B, E_co | E2, R_co | R2]:
+        """Run the effect this effect succeeds with."""
+        return _FlatMap(self, _identity)
+
+    def head[B](
+        self: Effect[Iterable[B], E_co, R_co],
+    ) -> Effect[B, E_co | NoSuchElementException, R_co]:
+        """The first item of the iterable this effect succeeds with; a
+        ``NoSuchElementException`` if it is empty."""
+
+        def first(items: Iterable[B]) -> Effect[B, NoSuchElementException]:
+            from pyfect.errors import NoSuchElementException
+
+            for item in items:
+                return _Succeed(item)
+            return _fail(NoSuchElementException())
+
+        return _FlatMap(self, first)
+
+    def when[E2 = Never, R2 = Never](
+        self, condition: Effect[bool, E2, R2]
+    ) -> Effect[Option[A_co], E_co | E2, R_co | R2]:
+        """Run this effect only if ``condition`` succeeds with ``True``:
+        ``Some(value)`` if it ran, ``None`` if it did not."""
+        require_effect(condition, "condition")
+        from pyfect.option import Some
+
+        return _FlatMap(condition, lambda run: _Map(self, Some) if run else _Succeed(None))
+
+    @overload
+    def filter_or_fail[B](
+        self, predicate: Callable[[A_co], TypeIs[B]]
+    ) -> Effect[B, E_co | NoSuchElementException, R_co]: ...
+    @overload
+    def filter_or_fail(
+        self, predicate: Callable[[A_co], bool]
+    ) -> Effect[A_co, E_co | NoSuchElementException, R_co]: ...
+    @overload
+    def filter_or_fail[B, E2](
+        self, predicate: Callable[[A_co], TypeIs[B]], or_fail_with: Callable[[A_co], E2]
+    ) -> Effect[B, E_co | E2, R_co]: ...
+    @overload
+    def filter_or_fail[E2](
+        self, predicate: Callable[[A_co], bool], or_fail_with: Callable[[A_co], E2]
+    ) -> Effect[A_co, E_co | E2, R_co]: ...
+    def filter_or_fail(
+        self, predicate: Callable[[Any], bool], or_fail_with: Callable[[Any], Any] | None = None
+    ) -> Effect[Any, Any, Any]:
+        """Fail with ``or_fail_with(value)`` (by default a
+        ``NoSuchElementException``) when the value fails ``predicate``."""
+        if or_fail_with is None:
+            from pyfect.errors import NoSuchElementException
+
+            return self.filter_or_else(predicate, lambda _: _fail(NoSuchElementException()))
+        return self.filter_or_else(predicate, lambda a: _fail(or_fail_with(a)))
+
+    @overload
+    def filter_or_else[B, C, E2 = Never, R2 = Never](
+        self, predicate: Callable[[A_co], TypeIs[B]], or_else: Callable[[A_co], Effect[C, E2, R2]]
+    ) -> Effect[B | C, E_co | E2, R_co | R2]: ...
+    @overload
+    def filter_or_else[C, E2 = Never, R2 = Never](
+        self, predicate: Callable[[A_co], bool], or_else: Callable[[A_co], Effect[C, E2, R2]]
+    ) -> Effect[A_co | C, E_co | E2, R_co | R2]: ...
+    def filter_or_else(
+        self, predicate: Callable[[Any], bool], or_else: Callable[[Any], Effect[Any, Any, Any]]
+    ) -> Effect[Any, Any, Any]:
+        """Continue with ``or_else(value)`` when the value fails ``predicate``."""
+        return _FlatMap(self, lambda a: _Succeed(a) if predicate(a) else or_else(a))
+
+    def filter_map_or_else[B, X, C, E2 = Never, R2 = Never](
+        self,
+        filter: Callable[[A_co], Ok[B] | Err[X]],
+        or_else: Callable[[X], Effect[C, E2, R2]],
+    ) -> Effect[B | C, E_co | E2, R_co | R2]:
+        """Succeed with what ``filter`` passes; continue with ``or_else`` of
+        what it rejects."""
+
+        def next_step(a: Any) -> Effect[Any, Any, Any]:
+            r = filter(a)
+            return _Succeed(r.value) if isinstance(r, Ok) else or_else(r.error)
+
+        return _FlatMap(self, next_step)
+
+    @overload
+    def filter_map_or_fail[B](
+        self, filter: Callable[[A_co], Ok[B] | Err[object]]
+    ) -> Effect[B, E_co | NoSuchElementException, R_co]: ...
+    @overload
+    def filter_map_or_fail[B, X, E2](
+        self, filter: Callable[[A_co], Ok[B] | Err[X]], or_fail_with: Callable[[X], E2]
+    ) -> Effect[B, E_co | E2, R_co]: ...
+    def filter_map_or_fail(
+        self, filter: Callable[[Any], Any], or_fail_with: Callable[[Any], Any] | None = None
+    ) -> Effect[Any, Any, Any]:
+        """Succeed with what ``filter`` passes; fail with ``or_fail_with`` of
+        what it rejects (by default a ``NoSuchElementException``)."""
+        if or_fail_with is None:
+            from pyfect.errors import NoSuchElementException
+
+            return self.filter_map_or_else(filter, lambda _: _fail(NoSuchElementException()))
+        return self.filter_map_or_else(filter, lambda x: _fail(or_fail_with(x)))
+
+
+def _to_none(_: object) -> None:
+    return None
+
+
+def _identity[T](value: T) -> T:
+    return value
+
+
+def _pair[A, B](a: A, b: B) -> tuple[A, B]:
+    return (a, b)
+
+
+# The primitives subclass ``Effect``, so they load after it. The methods above
+# use them only when called, and other modules import them from here.
+from pyfect._primitives import (  # noqa: E402
+    Register,
+    Restore,
+    _AfterStarted,
+    _Callback,
+    _FailCause,
+    _FlatMap,
+    _Fork,
+    _FromExit,
+    _Gen,
+    _GenFrame,
+    _Locally,
+    _Map,
+    _MatchCause,
+    _RestoreContext,
+    _RestoreInterruptible,
+    _SetInterruptible,
+    _Succeed,
+    _Suspend,
+    _Sync,
+    _WithFiber,
+    _YieldNow,
+    interruptible_mask,
+    run_known,
+    uninterruptible_mask,
+)
+
+__all__ = [
+    "SUSPEND",
+    "Effect",
+    "Frame",
+    "Register",
+    "Restore",
+    "Step",
+    "_AfterStarted",
+    "_Callback",
+    "_FailCause",
+    "_FlatMap",
+    "_Fork",
+    "_FromExit",
+    "_Gen",
+    "_GenFrame",
+    "_Locally",
+    "_Map",
+    "_MatchCause",
+    "_RestoreContext",
+    "_RestoreInterruptible",
+    "_SetInterruptible",
+    "_Succeed",
+    "_Suspend",
+    "_Sync",
+    "_WithFiber",
+    "_YieldNow",
+    "_call_user",
+    "_catching_if",
+    "_fail",
+    "_ignore_failure",
+    "_recovering",
+    "_run_finalizer",
+    "_succeed_none",
+    "_to_none",
+    "interruptible_mask",
+    "run_known",
+    "uninterruptible_mask",
+]

pyfect/_digits.py

@@ -0,0 +1,71 @@
+"""ASCII decimal numbers in text from outside: headers, URLs, wire tags.
+
+``str.isdigit`` also accepts digits like ``"²"`` that ``int`` rejects, and
+``int`` alone accepts signs, spaces, underscores and non-ASCII digits, and
+raises past 4300 digits, so every such parse goes through this module (a
+guard test bans ``.isdigit()`` and hand-written digit-run regexes
+elsewhere).
+"""
+
+from __future__ import annotations
+
+MAX_DIGITS = 1000
+"""The most digits ``parse_digits`` reads; longer text is no number."""
+
+
+def is_digits(value: str) -> bool:
+    """``value`` is one or more ASCII digits, however many."""
+    return value != "" and value.isascii() and value.isdigit()
+
+
+def parse_digits(value: str, *, unpadded: bool = False) -> int | None:
+    """``value`` as an int when it is 1 to ``MAX_DIGITS`` ASCII digits (with
+    no leading zero when ``unpadded``), else ``None``."""
+    if len(value) > MAX_DIGITS or not is_digits(value):
+        return None
+    if unpadded and value[0] == "0" and value != "0":
+        return None
+    return int(value)
+
+
+def parse_signed_digits(value: str) -> int | None:
+    """``parse_digits`` after an optional ``+`` or ``-``."""
+    sign = value[:1]
+    if sign in ("+", "-"):
+        magnitude = parse_digits(value[1:])
+        return None if magnitude is None else (-magnitude if sign == "-" else magnitude)
+    return parse_digits(value)
+
+
+_SHORT_RUN = 4000
+"""Digits ``int`` reads in one call (its limit is 4300)."""
+
+
+def digits_value(value: str) -> int | None:
+    """``value`` as an int when it is ASCII digits, however many (what
+    JavaScript's ``BigInt`` reads), else ``None``."""
+    return _run_value(value) if is_digits(value) else None
+
+
+def _run_value(run: str) -> int:
+    if len(run) <= _SHORT_RUN:
+        return int(run)
+    half = len(run) // 2
+    return _run_value(run[:half]) * 10 ** (len(run) - half) + _run_value(run[half:])
+
+
+_MAX_ARRAY_INDEX = 2**32 - 2
+
+
+def array_index(key: str) -> int | None:
+    """``key`` as a JavaScript array index, which an object lists first."""
+    index = parse_digits(key, unpadded=True)
+    return index if index is not None and index <= _MAX_ARRAY_INDEX else None
+
+
+def in_object_order[A](values: dict[str, A]) -> dict[str, A]:
+    """``values`` in ``Object.keys`` order: array indexes ascending, then the
+    others as they came."""
+    indexes = {key: index for key in values if (index := array_index(key)) is not None}
+    ordered = sorted(indexes, key=indexes.__getitem__)
+    return {key: values[key] for key in (*ordered, *(k for k in values if k not in indexes))}

pyfect/_effect_args.py

@@ -0,0 +1,46 @@
+"""Validate the effects handed to public combinators, once, when the
+combinator is called. Layers are checked the same way (``require_layer``
+in ``_layer_core``).
+
+An effect is a value, so a combinator that takes one can only notice a
+wrong value (a lambda, a coroutine, ``None``) when it runs it, possibly
+much later and inside a finalizer that hides the defect. Every public
+combinator with an ``Effect`` parameter calls ``require_effect`` on it
+first; ``tests/test_effect_arguments.py`` walks the public API to keep it
+that way. The run loop never checks again.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from pyfect._effect_base import EffectBase
+
+
+def require_effect(value: object, name: str) -> None:
+    """Raise ``TypeError`` naming the parameter ``name`` unless ``value``
+    is an ``Effect``."""
+    if not isinstance(value, EffectBase):
+        raise TypeError(_message(value, name))
+
+
+def require_effects(values: Iterable[object], name: str) -> None:
+    """``require_effect`` for each of a ``*args`` parameter's values."""
+    for i, value in enumerate(values):
+        if not isinstance(value, EffectBase):
+            raise TypeError(_message(value, f"{name}[{i}]"))
+
+
+def _message(value: object, name: str) -> str:
+    return wrong_argument(
+        value, name, "an Effect", "to run a function, pass fx.sync(f) or fx.suspend(f)"
+    )
+
+
+def wrong_argument(value: object, name: str, expected: str, hint_for_callable: str) -> str:
+    """The ``TypeError`` message for a parameter ``name`` that must be
+    ``expected``; a callable gets ``hint_for_callable``."""
+    message = f"{name} must be {expected}, got {type(value).__name__}: {value!r}"
+    if callable(value):
+        message += f" ({hint_for_callable})"
+    return message

pyfect/_effect_base.py

@@ -0,0 +1,71 @@
+"""What every effect and continuation frame shares: the step protocol and
+the base of ``Effect``'s method groups.
+
+A step is one of:
+
+- another ``Effect``: evaluate it next
+- a ``Success`` / ``Failure``: hand it to the next frame on the stack
+- ``SUSPEND``: the fiber parked itself; a callback will resume it
+
+``Effect`` (``pyfect._core``) is assembled from method groups, each a
+subclass of ``EffectBase`` in a module of its own. ``as_effect`` lets a
+group hand ``self`` to the primitives, which take an ``Effect``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar, Final, Generic, Never, TypeVar, cast, final
+
+from pyfect.cause import Cause
+from pyfect.exit import Failure, Success
+
+if TYPE_CHECKING:
+    from pyfect._core import Effect
+    from pyfect._fiber import Fiber
+
+A_co = TypeVar("A_co", covariant=True)
+E_co = TypeVar("E_co", covariant=True, default=Never)
+R_co = TypeVar("R_co", covariant=True, default=Never)
+
+
+@final
+class _SuspendMarker:
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "SUSPEND"
+
+
+SUSPEND: Final = _SuspendMarker()
+
+type Step = Effect[Any, Any, Any] | Success[Any] | Failure[Any] | _SuspendMarker
+
+
+class Frame:
+    """A continuation on the fiber's stack. Defaults pass results through.
+
+    A frame that claims state (takes a permit) and returns the result as an
+    ``Exit`` sets ``claims``: the loop then hands that exit on with no pause
+    in between, as it does for a step's exit."""
+
+    __slots__ = ()
+    claims: ClassVar[bool] = False
+
+    def _on_success(self, value: Any, fiber: Fiber[Any, Any]) -> Step:
+        return Success(value)
+
+    def _on_failure(self, cause: Cause[Any], fiber: Fiber[Any, Any]) -> Step:
+        return Failure(cause)
+
+
+class EffectBase(Frame, Generic[A_co, E_co, R_co]):
+    """The base of each group of ``Effect`` methods. Every instance is an
+    ``Effect``: only ``Effect`` combines the groups, and nothing else
+    subclasses them."""
+
+    __slots__ = ()
+
+
+def as_effect[A, E, R](group: EffectBase[A, E, R]) -> Effect[A, E, R]:
+    """``self`` inside a method group, typed as the ``Effect`` it is."""
+    return cast("Effect[A, E, R]", group)

pyfect/_effect_concurrency.py

@@ -0,0 +1,133 @@
+"""``Effect`` methods that fork, race and time out. The work lives in
+``pyfect._concurrency`` and ``pyfect.scope``; these are the method spellings."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Never
+
+from pyfect import _core
+from pyfect._effect_args import require_effect
+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._fiber import Fiber, Uninterruptible
+    from pyfect.errors import TimeoutException
+    from pyfect.option import Option
+    from pyfect.scope import CloseableScope, Scope
+
+
+class ConcurrencyMethods(EffectBase[A_co, E_co, R_co]):
+    __slots__ = ()
+
+    def fork(
+        self, *, start_immediately: bool = False, uninterruptible: Uninterruptible = False
+    ) -> Effect[Fiber[A_co, E_co], Never, R_co]:
+        """Start this effect on a child fiber. The child is interrupted if
+        it is still running when the parent fiber finishes.
+
+        With ``start_immediately`` the child runs at once, up to its first
+        wait, before the parent goes on; otherwise it starts on the next
+        scheduler turn. ``uninterruptible`` starts it uninterruptible
+        (``True``) or as interruptible as the parent is (``"inherit"``)."""
+        return _core._Fork(
+            as_effect(self),
+            daemon=False,
+            start_immediately=start_immediately,
+            uninterruptible=uninterruptible,
+        )
+
+    def fork_daemon(
+        self, *, start_immediately: bool = False, uninterruptible: Uninterruptible = False
+    ) -> Effect[Fiber[A_co, E_co], Never, R_co]:
+        """Start this effect on a fiber that outlives its parent. Options as
+        for ``fork``."""
+        return _core._Fork(
+            as_effect(self),
+            daemon=True,
+            start_immediately=start_immediately,
+            uninterruptible=uninterruptible,
+        )
+
+    def fork_scoped(
+        self, *, start_immediately: bool = False, uninterruptible: Uninterruptible = False
+    ) -> Effect[Fiber[A_co, E_co], Never, R_co | Scope]:
+        """``fork_in`` the enclosing ``Scope``."""
+        from pyfect.scope import fork_scoped
+
+        return fork_scoped(
+            as_effect(self), start_immediately=start_immediately, uninterruptible=uninterruptible
+        )
+
+    def fork_in(
+        self,
+        scope: CloseableScope,
+        *,
+        start_immediately: bool = False,
+        uninterruptible: Uninterruptible = False,
+    ) -> Effect[Fiber[A_co, E_co], Never, R_co]:
+        """Start this effect on a fiber that outlives its parent and is
+        interrupted when ``scope`` closes. Into a closed scope it gives an
+        interrupted fiber that never ran. Options as for ``fork``."""
+        from pyfect.scope import fork_in
+
+        return fork_in(
+            as_effect(self),
+            scope,
+            start_immediately=start_immediately,
+            uninterruptible=uninterruptible,
+        )
+
+    def await_all_children(self) -> Effect[A_co, E_co, R_co]:
+        """When this effect ends, wait for the child fibers it forked
+        (not those forked before it started). The wait is interruptible
+        if the fiber was interruptible when this effect started."""
+        from pyfect._fiber_all import await_all_children
+
+        return await_all_children(as_effect(self))
+
+    def race[B, E2 = Never, R2 = Never](
+        self, that: Effect[B, E2, R2]
+    ) -> Effect[A_co | B, E_co | E2, R_co | R2]:
+        """The first to succeed wins and the other is interrupted. Fails
+        only if both fail."""
+        require_effect(that, "that")
+        from pyfect._concurrency import race
+
+        return race(as_effect(self), that)
+
+    def race_first[B, E2 = Never, R2 = Never](
+        self, that: Effect[B, E2, R2]
+    ) -> Effect[A_co | B, E_co | E2, R_co | R2]:
+        """The first to finish wins, success or failure."""
+        require_effect(that, "that")
+        from pyfect._concurrency import race_first
+
+        return race_first(as_effect(self), that)
+
+    def timeout(self, duration: Duration) -> Effect[A_co, E_co | TimeoutException, R_co]:
+        """Fail with ``TimeoutException`` if this takes longer than
+        ``duration``. The effect is interrupted when time runs out."""
+        from pyfect._concurrency import timeout
+
+        return timeout(as_effect(self), duration)
+
+    def timeout_option(self, duration: Duration) -> Effect[Option[A_co], E_co, R_co]:
+        """``Some(value)``, or ``None`` if this takes longer than
+        ``duration``. The effect is interrupted when time runs out."""
+        from pyfect._concurrency import timeout_option
+
+        return timeout_option(as_effect(self), duration)
+
+    def timeout_or_else[B, E2 = Never, R2 = Never](
+        self, duration: Duration, or_else: Callable[[], Effect[B, E2, R2]]
+    ) -> Effect[A_co | B, E_co | E2, R_co | R2]:
+        """Continue with ``or_else()`` if this takes longer than
+        ``duration``. ``or_else`` runs once this effect has been
+        interrupted and has finished cleaning up."""
+        from pyfect._concurrency import timeout_or_else
+
+        return timeout_or_else(as_effect(self), duration, or_else)