pyfect-dev 0.1.0__py3-none-any.whl

pyfect/_concurrency.py

@@ -0,0 +1,291 @@
+"""Running effects concurrently: ``for_each``, ``all``, racing, timeouts.
+
+Everything here forks child fibers of the calling fiber, so the rules are
+the same everywhere: if the caller is interrupted, the children are
+interrupted and awaited; if one child fails, its siblings are interrupted
+and awaited before the failure is reported. Nothing outlives the call.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import Any, Literal, Never
+
+from pyfect._core import (
+    Effect,
+    _Callback,
+    _FailCause,
+    _FromExit,
+    _Gen,
+    _SetInterruptible,
+    _Succeed,
+    _Suspend,
+    _WithFiber,
+)
+from pyfect._effect_args import require_effects
+from pyfect._fiber import Fiber, interrupt_all
+from pyfect.cause import Cause, Interrupt, fail, merge
+from pyfect.duration import Duration, to_seconds
+from pyfect.errors import TimeoutException
+from pyfect.exit import Exit, Failure, Success
+from pyfect.option import Option, Some
+
+type Concurrency = int | Literal["unbounded"] | None
+"""``None`` runs one at a time; an ``int`` caps how many run at once."""
+
+
+def _parse_limit(concurrency: int | Literal["unbounded"]) -> Callable[[int], int]:
+    """Maps the number of items (known when it runs) to how many run at once.
+    As in Effect, a limit under 1 runs them one at a time."""
+    if concurrency == "unbounded":
+        return lambda n: max(n, 1)
+    return lambda _: max(concurrency, 1)
+
+
+def _drop_own_interrupts(causes: list[Cause[Any]], by: int) -> Cause[Any]:
+    """Combine sibling causes, dropping the interrupts we sent ourselves."""
+    return merge(
+        *(
+            Cause(
+                tuple(r for r in c.reasons if not (isinstance(r, Interrupt) and r.fiber_id == by))
+            )
+            for c in causes
+        )
+    )
+
+
+def _with_late_failure(failure: Cause[Any] | None, late: Cause[Any]) -> Cause[Any] | None:
+    """Add a failure that came after the first (or after the caller was
+    interrupted): its interrupts are dropped, as Effect's ``forEach`` does,
+    since they only report how the sibling was stopped."""
+    reasons = tuple(r for r in late.reasons if not isinstance(r, Interrupt))
+    if not reasons:
+        return failure
+    return Cause(reasons) if failure is None else merge(failure, Cause(reasons))
+
+
+def for_each[T, B, E = Never, R = Never](
+    items: Iterable[T],
+    f: Callable[[T], Effect[B, E, R]],
+    *,
+    concurrency: Concurrency = None,
+) -> Effect[list[B], E, R]:
+    """Run ``f`` on every item and collect the results in order.
+
+    With ``concurrency``, up to that many run at once. The first failure
+    interrupts the rest. ``items`` is read each time the effect runs.
+    """
+    if concurrency is None:
+        return _for_each_sequential(items, f)
+    limit_for = _parse_limit(concurrency)
+
+    def start() -> Effect[list[B], E, R]:
+        snapshot = list(items)
+        limit = limit_for(len(snapshot))
+        if limit == 1:
+            return _for_each_sequential(snapshot, f)
+        return _for_each_concurrent(snapshot, f, limit)
+
+    return _Suspend(start)
+
+
+def _for_each_sequential[T, B, E, R](
+    items: Iterable[T], f: Callable[[T], Effect[B, E, R]]
+) -> Effect[list[B], E, R]:
+    def loop():
+        out: list[B] = []
+        for item in items:
+            out.append((yield from f(item)))  # noqa: PERF401 - yield is not allowed in comprehensions
+        return out
+
+    return _Gen(loop)
+
+
+def _for_each_concurrent[T, B, E, R](
+    items: list[T], f: Callable[[T], Effect[B, E, R]], limit: int
+) -> Effect[list[B], E, R]:
+    def body(parent: Fiber[Any, Any]) -> Effect[list[B], E, R]:
+        n = len(items)
+        if n == 0:
+            return _Succeed([])
+        results: list[Any] = [None] * n
+        next_index = 0
+        # Once an item fails (or the caller is interrupted), no worker takes
+        # another item, as Effect's forEach starts no item after its
+        # terminal exit; this matters where the workers cannot be
+        # interrupted (inside ``uninterruptible``).
+        stopped = False
+        # The first failure's cause, then what later failures add.
+        failure: Cause[Any] | None = None
+
+        def worker():
+            nonlocal next_index
+            while not stopped and next_index < n:
+                i = next_index
+                next_index += 1
+                results[i] = yield from f(items[i])
+
+        def register(resume: Callable[[Effect[Any, Any, Any]], None]) -> Effect[None]:
+            workers: list[Fiber[Any, Any]] = []
+            remaining = 0
+            forking = True
+
+            def result() -> Effect[Any, Any, Any]:
+                return _Succeed(results) if failure is None else _FailCause(failure)
+
+            def observer(ex: Exit[Any, Any]) -> None:
+                # Record first: interrupting siblings finishes them (and
+                # re-enters this observer) before the loop below returns.
+                nonlocal remaining, stopped, failure
+                remaining -= 1
+                failed_first = False
+                if isinstance(ex, Failure):
+                    if not stopped:
+                        stopped = failed_first = True
+                        failure = ex.cause
+                    else:
+                        failure = _with_late_failure(failure, ex.cause)
+                if remaining == 0 and not forking:
+                    resume(result())
+                elif failed_first:
+                    for w in workers:
+                        w.interrupt_as_unsafe(parent.id, parent._interruptor_annotations())
+
+            # Started at once, as in Effect, each as interruptible as the
+            # parent; a worker runs before the next is forked, so once an
+            # item has failed no further worker starts.
+            for _ in range(min(limit, n)):
+                if stopped or next_index >= n:
+                    break
+                w = parent._fork(
+                    _Gen(worker), daemon=False, start_immediately=True, uninterruptible="inherit"
+                )
+                workers.append(w)
+                remaining += 1
+                w.add_observer_unsafe(observer)
+            forking = False
+            if remaining == 0:
+                resume(result())
+
+            def cancel() -> Effect[None]:
+                # Interrupted from outside: report what the workers did too.
+                nonlocal stopped
+                stopped = True
+                return interrupt_all(
+                    workers, parent.id, parent._interruptor_annotations()
+                ).and_then(_Suspend(report))
+
+            def report() -> Effect[None]:
+                return _Succeed(None) if failure is None else _FailCause(failure)
+
+            return _Suspend(cancel)
+
+        return _Callback(register)
+
+    return _WithFiber(body)
+
+
+# --- racing -------------------------------------------------------------------
+
+
+def _race(effects: list[Effect[Any, Any, Any]], *, first_exit_wins: bool) -> Effect[Any, Any, Any]:
+    def body(parent: Fiber[Any, Any]) -> Effect[Any, Any, Any]:
+        def register(resume: Callable[[Effect[Any, Any, Any]], None]) -> Effect[None]:
+            fibers: list[Fiber[Any, Any]] = []
+            remaining = len(effects)
+            decided = False
+            causes: list[Cause[Any]] = []
+
+            def observer_for(me: Fiber[Any, Any]) -> Callable[[Exit[Any, Any]], None]:
+                def observer(ex: Exit[Any, Any]) -> None:
+                    nonlocal remaining, decided
+                    remaining -= 1
+                    if decided:
+                        return
+                    if isinstance(ex, Success) or first_exit_wins:
+                        decided = True
+
+                        def stop_losers() -> Effect[None]:
+                            # Read when the parent goes on, as Effect's
+                            # exit hook does: a loser still starting when
+                            # this one won (it may be what settled the
+                            # race) is in ``fibers`` by then.
+                            losers = [f for f in fibers if f is not me]
+                            return interrupt_all(
+                                losers, parent.id, parent._interruptor_annotations()
+                            )
+
+                        resume(
+                            _SetInterruptible(_Suspend(stop_losers), False).and_then(_FromExit(ex))
+                        )
+                        return
+                    causes.append(ex.cause)
+                    if remaining == 0:
+                        decided = True
+                        resume(_FailCause(_drop_own_interrupts(causes, parent.id)))
+
+                return observer
+
+            # Started at once, as in Effect: each runs before the next is
+            # forked, and once one has decided the race no other starts.
+            for e in effects:
+                if decided:
+                    break
+                f = parent._fork(e, daemon=False, start_immediately=True)
+                fibers.append(f)
+                f.add_observer_unsafe(observer_for(f))
+            return interrupt_all(fibers, parent.id, parent._interruptor_annotations())
+
+        return _Callback(register)
+
+    return _WithFiber(body)
+
+
+# The public types for these two live on ``Effect.race`` / ``Effect.race_first``.
+
+
+def race(a: Effect[Any, Any, Any], b: Effect[Any, Any, Any]) -> Effect[Any, Any, Any]:
+    return _race([a, b], first_exit_wins=False)
+
+
+def race_first(a: Effect[Any, Any, Any], b: Effect[Any, Any, Any]) -> Effect[Any, Any, Any]:
+    return _race([a, b], first_exit_wins=True)
+
+
+def race_all[A = Never, EE = Never, RR = Never](*effects: Effect[A, EE, RR]) -> Effect[A, EE, RR]:
+    """The first to succeed wins; the rest are interrupted. Fails only if
+    all fail. With no effects it never finishes, as in Effect."""
+    require_effects(effects, "effects")
+    return _race(list(effects), first_exit_wins=False)
+
+
+def race_all_first[A = Never, EE = Never, RR = Never](
+    *effects: Effect[A, EE, RR],
+) -> Effect[A, EE, RR]:
+    """The first to finish wins, success or failure; the rest are
+    interrupted. With no effects it never finishes, as in Effect."""
+    require_effects(effects, "effects")
+    return _race(list(effects), first_exit_wins=True)
+
+
+# The public types of the timeouts live on the ``Effect`` methods.
+
+
+def timeout_option[A, E, R](eff: Effect[A, E, R], duration: Duration) -> Effect[Option[A], E, R]:
+    from pyfect.clock import sleep
+
+    return race_first(eff.map(Some), sleep(duration).as_(None))
+
+
+def timeout_or_else(
+    eff: Effect[Any, Any, Any], duration: Duration, or_else: Callable[[], Effect[Any, Any, Any]]
+) -> Effect[Any, Any, Any]:
+    return timeout_option(eff, duration).flat_map(
+        lambda found: or_else() if found is None else _Succeed(found.value)
+    )
+
+
+def timeout(eff: Effect[Any, Any, Any], duration: Duration) -> Effect[Any, Any, Any]:
+    seconds = to_seconds(duration)
+    return timeout_or_else(eff, seconds, lambda: _FailCause(fail(TimeoutException(seconds))))

pyfect/_context_effects.py

@@ -0,0 +1,163 @@
+"""Effects that read or provide services: ``context``, ``service_option``,
+``provide_context``, ``update_context``, ``set_context``,
+``provide_service_effect`` and ``update_service_scoped``.
+
+The providers remove what they provide from ``R``, so they are used with
+``.pipe``; ``Effect.update_service`` adds a requirement, so it is a method.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Never, overload
+
+from pyfect._core import Effect, _Locally, _Succeed, _Suspend, _WithFiber
+from pyfect._effect_args import require_effect
+from pyfect._fiber import Fiber
+from pyfect.context import Context, TagLike, tag_class
+from pyfect.exit import Exit
+from pyfect.option import Option
+from pyfect.scope import Scope
+
+_VOID: Effect[None] = _Succeed(None)
+
+
+def context[T = Never](*tags: TagLike[Any, T]) -> Effect[Context[T], Never, T]:
+    """The current fiber's services. Name the tags the caller reads (Effect's
+    ``context<R>()``): they join ``R``, and the context is typed to hold
+    them::
+
+        ctx = yield from fx.context(Database, Clock)
+    """
+    return _WithFiber(lambda fiber: _Succeed(fiber._context))
+
+
+def service_option[S, T](tag: TagLike[S, T]) -> Effect[Option[S]]:
+    """``Some(service)`` if it is provided, else ``None``. Never needs the
+    service, so ``tag`` does not join ``R``."""
+    return _WithFiber(lambda fiber: _Succeed(fiber._context.get_option(tag)))
+
+
+class _ProvideContext[RO]:
+    __slots__ = ("ctx",)
+
+    def __init__(self, ctx: Context[RO]) -> None:
+        self.ctx = ctx
+
+    @overload
+    def __call__[A, E = Never](self, target: Effect[A, E, RO]) -> Effect[A, E]: ...
+    @overload
+    def __call__[A, E = Never, R = Never](
+        self, target: Effect[A, E, RO | R]
+    ) -> Effect[A, E, R]: ...
+    def __call__(self, target: Effect[Any, Any, Any]) -> Effect[Any, Any, Any]:
+        ctx = self.ctx
+        return _Locally(target, lambda current: current.merge(ctx))
+
+
+def provide_context[RO](ctx: Context[RO]) -> _ProvideContext[RO]:
+    """Provide every service of ``ctx`` and remove them from ``R``::
+
+    eff.pipe(provide_context(ctx))
+    """
+    return _ProvideContext(ctx)
+
+
+class _UpdateContext[R2, RO]:
+    __slots__ = ("f",)
+
+    def __init__(self, f: Callable[[Context[R2]], Context[RO]]) -> None:
+        self.f = f
+
+    def __call__[A, E = Never](self, target: Effect[A, E, RO]) -> Effect[A, E, R2]:
+        return _Locally(target, self.f)
+
+
+def update_context[R2, RO](f: Callable[[Context[R2]], Context[RO]]) -> _UpdateContext[R2, RO]:
+    """Run the effect with ``f`` of the current services, which then need
+    only what ``f`` reads. ``f`` is a typed ``def``: in ``.pipe``, a lambda's
+    parameter would be ``Unknown`` (research/typing/catch_2_lambda.py)::
+
+        def with_cache(ctx: Context[Never]) -> Context[Cache]:
+            return ctx.add(Cache, 2)
+
+        eff.pipe(update_context(with_cache))
+    """
+    return _UpdateContext(f)
+
+
+def set_context[RO](ctx: Context[RO]) -> _UpdateContext[Never, RO]:
+    """Run the effect with exactly the services of ``ctx``, no others."""
+    return _UpdateContext(lambda _: ctx)
+
+
+class _ProvideServiceEffect[T, E2, R2]:
+    __slots__ = ("acquire", "tag")
+
+    def __init__(self, tag: type[Any], acquire: Effect[Any, E2, R2]) -> None:
+        self.tag = tag
+        self.acquire = acquire
+
+    @overload
+    def __call__[A, E = Never](self, eff: Effect[A, E, T]) -> Effect[A, E | E2, R2]: ...
+    @overload
+    def __call__[A, E = Never, R = Never](
+        self, eff: Effect[A, E, T | R]
+    ) -> Effect[A, E | E2, R | R2]: ...
+    def __call__(self, eff: Effect[Any, Any, Any]) -> Effect[Any, Any, Any]:
+        tag = self.tag
+        return self.acquire.flat_map(
+            lambda service: _Locally(eff, lambda ctx: ctx.add(tag, service))
+        )
+
+
+def provide_service_effect[S, T, E2 = Never, R2 = Never](
+    tag: TagLike[S, T], acquire: Effect[S, E2, R2]
+) -> _ProvideServiceEffect[T, E2, R2]:
+    """Run ``acquire`` and provide its value as ``tag``'s service, removing
+    ``tag`` from ``R``::
+
+    eff.pipe(provide_service_effect(Database, connect()))
+    """
+    require_effect(acquire, "acquire")
+    return _ProvideServiceEffect(tag_class(tag), acquire)
+
+
+def update_service_scoped[S, T](
+    tag: TagLike[S, T],
+    f: Callable[[S], S],
+    *,
+    reset: Callable[[S, S, S], S] | None = None,
+) -> Effect[None, Never, T | Scope]:
+    """Replace the service of ``tag`` with ``f(service)`` for the rest of
+    the current fiber's region, and put the original back when the current
+    ``Scope`` closes, unless the service has changed again by then.
+    ``reset(original, updated, current)`` decides what to put back instead.
+    """
+
+    def update(fiber: Fiber[Any, Any]) -> Effect[None]:
+        original = fiber._context.get_unsafe(tag)
+        updated = f(original)
+        fiber._set_context(fiber._context.add(tag, updated))
+
+        def put_back() -> Effect[None]:
+            current = fiber._context.get_option(tag)
+            if current is None or (reset is None and current.value is not updated):
+                return _VOID
+            restored = original if reset is None else reset(original, updated, current.value)
+            fiber._set_context(fiber._context.add(tag, restored))
+            return _VOID
+
+        def finalizer(_ex: Exit[Any, Any]) -> Effect[None]:
+            return _Suspend(put_back)
+
+        scope = fiber._context.get_unsafe(Scope)
+        if scope._closed is not None:
+            return finalizer(scope._closed)
+        # Not ``add_finalizer``: it restores the closing fiber's services
+        # afterwards, which would undo the put-back when this fiber closes.
+        scope._add(object(), finalizer)
+        return _VOID
+
+    return _WithFiber(update).uninterruptible()

pyfect/_context_managers.py

@@ -0,0 +1,76 @@
+"""Python context managers as scoped resources, Effect's
+``acquireDisposable`` for ``with`` and ``async with``.
+
+The manager is entered when the resource is acquired and exited when the
+enclosing ``Scope`` closes. ``__exit__`` sees the scope's outcome: nothing
+on success, otherwise ``Cause.raisable()`` of the failure. A finalizer cannot
+recover a failure, so a true return from ``__exit__`` suppresses nothing.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from contextlib import AbstractAsyncContextManager, AbstractContextManager
+from types import TracebackType
+from typing import Any, Never
+
+from pyfect._core import Effect, _Sync
+from pyfect._effect_args import require_effect
+from pyfect.effect import from_async
+from pyfect.exit import Exit, Failure
+from pyfect.scope import Scope, acquire_release
+
+type _ExcInfo = (
+    tuple[type[BaseException], BaseException, TracebackType | None] | tuple[None, None, None]
+)
+
+
+def acquire_context[T, E = Never, R = Never](
+    acquire: Effect[AbstractContextManager[T], E, R],
+) -> Effect[T, E, R | Scope]:
+    """Enter the context manager ``acquire`` produces; exit it when the
+    scope closes. If ``__enter__`` or ``__exit__`` raises, that is a defect."""
+    require_effect(acquire, "acquire")
+
+    def enter(cm: AbstractContextManager[T]) -> Effect[tuple[AbstractContextManager[T], T]]:
+        return _Sync(lambda: (cm, cm.__enter__()))
+
+    def release(entered: tuple[AbstractContextManager[T], T], ex: Exit[Any, Any]) -> Effect[None]:
+        return _Sync(lambda: _discard(entered[0].__exit__(*_exc_info(ex))))
+
+    return acquire_release(acquire.flat_map(enter), release).map(_second)
+
+
+def acquire_async_context[T, E = Never, R = Never](
+    acquire: Effect[AbstractAsyncContextManager[T], E, R],
+) -> Effect[T, E, R | Scope]:
+    """``acquire_context`` for ``async with`` managers. Needs an asyncio
+    loop (``run_async`` / ``run_main``), like ``from_async``."""
+    require_effect(acquire, "acquire")
+
+    def enter(
+        cm: AbstractAsyncContextManager[T],
+    ) -> Effect[tuple[AbstractAsyncContextManager[T], T]]:
+        return from_async(cm.__aenter__).map(lambda value: (cm, value))
+
+    def release(
+        entered: tuple[AbstractAsyncContextManager[T], T], ex: Exit[Any, Any]
+    ) -> Effect[None]:
+        return from_async(lambda: entered[0].__aexit__(*_exc_info(ex))).map(_discard)
+
+    return acquire_release(acquire.flat_map(enter), release).map(_second)
+
+
+def _exc_info(ex: Exit[Any, Any]) -> _ExcInfo:
+    if not isinstance(ex, Failure):
+        return (None, None, None)
+    error = ex.cause.raisable()
+    return (type(error), error, error.__traceback__)
+
+
+def _second[T](pair: tuple[object, T]) -> T:
+    return pair[1]
+
+
+def _discard(_: object) -> None:
+    return None