pyfect-dev 0.1.0__py3-none-any.whl

pyfect/_primitives.py

@@ -0,0 +1,434 @@
+"""The primitives the fiber runtime interprets, and the helpers built on them.
+
+Each primitive reduces itself in ``_step``; continuation frames consume
+results in ``_on_success`` / ``_on_failure`` (see ``pyfect._core``).
+
+Import these through ``pyfect._core``, which loads this module once
+``Effect`` exists: importing this module first is a circular import.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Generator
+from typing import TYPE_CHECKING, Any, Never, Protocol, cast, final
+
+from pyfect._core import Effect, Frame, Step
+from pyfect.cause import Cause, merge
+from pyfect.cause import die as die_cause
+from pyfect.exit import Exit, Failure, Success
+
+if TYPE_CHECKING:
+    from pyfect._fiber import Fiber, Uninterruptible
+    from pyfect.context import Context
+
+
+# --- primitives ---------------------------------------------------------------
+
+
+@final
+class _Succeed[A](Effect[A, Never, Never]):
+    __slots__ = ("value",)
+
+    def __init__(self, value: A) -> None:
+        self.value = value
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        return Success(self.value)
+
+
+@final
+class _FailCause[E](Effect[Never, E, Never]):
+    __slots__ = ("cause",)
+
+    def __init__(self, cause: Cause[E]) -> None:
+        self.cause = cause
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        return Failure(self.cause)
+
+
+@final
+class _FromExit[A, E](Effect[A, E, Never]):
+    __slots__ = ("outcome",)
+
+    def __init__(self, ex: Exit[A, E]) -> None:
+        self.outcome = ex
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        return self.outcome
+
+
+def known_exit[A, E](eff: Effect[A, E, Any]) -> Exit[A, E] | None:
+    """The outcome of an effect that is nothing but its outcome
+    (``succeed``, ``fail_cause``, ``from_exit``), without running it; else
+    ``None``. Lets a caller stay synchronous where Effect returns an
+    ``Exit`` (which is an ``Effect`` there)."""
+    if isinstance(eff, _Succeed):
+        return Success(eff.value)
+    if isinstance(eff, _FailCause):
+        return Failure(eff.cause)
+    if isinstance(eff, _FromExit):
+        return eff.outcome
+    return None
+
+
+def run_known(eff: Effect[Any, Any, Any]) -> Step:
+    """``eff``'s outcome if it is nothing but that (``known_exit``), else
+    ``eff``. A step or continuation that has just claimed state returns
+    this, so the claimed result reaches its continuation in the same step:
+    returned as an effect, it would run in a later step, and a yield in
+    between could let an interrupt drop it."""
+    ex = known_exit(eff)
+    return eff if ex is None else ex
+
+
+@final
+class _Sync[A](Effect[A, Never, Never]):
+    """Run a side-effecting thunk. If it raises, that is a defect."""
+
+    __slots__ = ("thunk",)
+
+    def __init__(self, thunk: Callable[[], A]) -> None:
+        self.thunk = thunk
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        return Success(self.thunk())
+
+
+@final
+class _Suspend[A, E, R](Effect[A, E, R]):
+    """Build the effect lazily, each time it runs."""
+
+    __slots__ = ("thunk",)
+
+    def __init__(self, thunk: Callable[[], Effect[A, E, R]]) -> None:
+        self.thunk = thunk
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        # A thunk that has already decided its result (a queue take, a permit
+        # grab) hands it on in this same step: as a separate step it could be
+        # parked at a yield, where an interrupt would drop it.
+        return run_known(self.thunk())
+
+
+@final
+class _Map(Effect[Any, Any, Any]):
+    __slots__ = ("f", "inner")
+
+    def __init__(self, inner: Effect[Any, Any, Any], f: Callable[[Any], Any]) -> None:
+        self.inner = inner
+        self.f = f
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        fiber._push(self)
+        return self.inner
+
+    def _on_success(self, value: Any, fiber: Fiber[Any, Any]) -> Step:
+        return Success(self.f(value))
+
+
+@final
+class _FlatMap(Effect[Any, Any, Any]):
+    __slots__ = ("f", "inner")
+
+    def __init__(
+        self, inner: Effect[Any, Any, Any], f: Callable[[Any], Effect[Any, Any, Any]]
+    ) -> None:
+        self.inner = inner
+        self.f = f
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        fiber._push(self)
+        return self.inner
+
+    def _on_success(self, value: Any, fiber: Fiber[Any, Any]) -> Step:
+        return self.f(value)
+
+
+@final
+class _MatchCause(Effect[Any, Any, Any]):
+    """The one recovery primitive. ``on_failure`` is skipped when the fiber
+    has been interrupted and is interruptible: an interrupted fiber can
+    clean up (finalizers run in uninterruptible regions) but not recover.
+    """
+
+    __slots__ = ("inner", "on_failure", "on_success")
+
+    def __init__(
+        self,
+        inner: Effect[Any, Any, Any],
+        on_failure: Callable[[Cause[Any]], Step] | None,
+        on_success: Callable[[Any], Step] | None,
+    ) -> None:
+        self.inner = inner
+        self.on_failure = on_failure
+        self.on_success = on_success
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        fiber._push(self)
+        return self.inner
+
+    def _on_success(self, value: Any, fiber: Fiber[Any, Any]) -> Step:
+        return Success(value) if self.on_success is None else self.on_success(value)
+
+    def _on_failure(self, cause: Cause[Any], fiber: Fiber[Any, Any]) -> Step:
+        if self.on_failure is None:
+            return Failure(cause)
+        if fiber._interrupted_and_interruptible():
+            # Skipping a recovery handler: the fiber can no longer act on
+            # typed errors, so only defects and the interruption remain.
+            return Failure(cause.without_failures())
+        return self.on_failure(cause)
+
+
+type Register[A, E, R] = Callable[
+    [Callable[[Effect[A, E, R]], None]], Effect[object, Never, R] | None
+]
+
+
+@final
+class _Callback[A, E, R](Effect[A, E, R]):
+    """Suspend the fiber until ``register``'s resume callback is called.
+
+    ``register`` may return a canceler effect, run if the fiber is
+    interrupted while waiting.
+    """
+
+    __slots__ = ("register",)
+
+    def __init__(self, register: Register[A, E, R]) -> None:
+        self.register = register
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        return fiber._suspend(self.register)
+
+
+@final
+class _WithFiber[A, E, R](Effect[A, E, R]):
+    """Read the running fiber. Internal building block for concurrency."""
+
+    __slots__ = ("f",)
+
+    def __init__(self, f: Callable[[Fiber[Any, Any]], Effect[A, E, R]]) -> None:
+        self.f = f
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        return self.f(fiber)
+
+
+@final
+class _SetInterruptible[A, E, R](Effect[A, E, R]):
+    __slots__ = ("flag", "inner")
+
+    def __init__(self, inner: Effect[A, E, R], flag: bool) -> None:
+        self.inner = inner
+        self.flag = flag
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        if fiber._interruptible != self.flag:
+            fiber._push(_RestoreInterruptible(fiber._interruptible))
+            fiber._interruptible = self.flag
+        return self.inner
+
+
+@final
+class _RestoreInterruptible(Frame):
+    __slots__ = ("flag",)
+
+    def __init__(self, flag: bool) -> None:
+        self.flag = flag
+
+    def _on_success(self, value: Any, fiber: Fiber[Any, Any]) -> Step:
+        fiber._interruptible = self.flag
+        return Success(value)
+
+    def _on_failure(self, cause: Cause[Any], fiber: Fiber[Any, Any]) -> Step:
+        fiber._interruptible = self.flag
+        return Failure(cause)
+
+
+@final
+class _Locally[A, E, R](Effect[A, E, R]):
+    """Run ``inner`` with a modified context, restoring it afterwards."""
+
+    __slots__ = ("f", "inner")
+
+    def __init__(self, inner: Effect[A, E, Any], f: Callable[[Context], Context]) -> None:
+        self.inner = inner
+        self.f = f
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        fiber._push(_RestoreContext(fiber._context))
+        fiber._set_context(self.f(fiber._context))
+        return self.inner
+
+
+@final
+class _RestoreContext(Frame):
+    __slots__ = ("context",)
+
+    def __init__(self, context: Context) -> None:
+        self.context = context
+
+    def _on_success(self, value: Any, fiber: Fiber[Any, Any]) -> Step:
+        fiber._set_context(self.context)
+        return Success(value)
+
+    def _on_failure(self, cause: Cause[Any], fiber: Fiber[Any, Any]) -> Step:
+        fiber._set_context(self.context)
+        return Failure(cause)
+
+
+@final
+class _Fork[A, E, R](Effect[Any, Never, R]):
+    __slots__ = ("daemon", "inner", "start_immediately", "start_uninterruptible")
+
+    def __init__(
+        self,
+        inner: Effect[A, E, R],
+        *,
+        daemon: bool,
+        start_immediately: bool,
+        uninterruptible: Uninterruptible,
+    ) -> None:
+        self.inner = inner
+        self.daemon = daemon
+        self.start_immediately = start_immediately
+        self.start_uninterruptible: Uninterruptible = uninterruptible
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        child = fiber._fork(
+            self.inner,
+            daemon=self.daemon,
+            start_immediately=self.start_immediately,
+            uninterruptible=self.start_uninterruptible,
+        )
+        return fiber._after_started(Success(child))
+
+
+@final
+class _AfterStarted[A](Effect[A, Never, Never]):
+    """Succeed with ``value`` once the fibers this run started immediately
+    have run, up to their first wait or yield."""
+
+    __slots__ = ("value",)
+
+    def __init__(self, value: A) -> None:
+        self.value = value
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        return fiber._after_started(Success(self.value))
+
+
+@final
+class _YieldNow(Effect[None, Never, Never]):
+    __slots__ = ("priority",)
+
+    def __init__(self, priority: int = 0) -> None:
+        self.priority = priority
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        return fiber._yield_now(self.priority)
+
+
+@final
+class _Gen[A, E, R](Effect[A, E, R]):
+    __slots__ = ("factory",)
+
+    def __init__(self, factory: Callable[[], Generator[Effect[Any, E, R], Any, A]]) -> None:
+        self.factory = factory
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        gen = cast(object, self.factory())  # a lambda may return anything
+        if not isinstance(gen, Generator):
+            return Failure(
+                die_cause(TypeError(f"gen expected a generator, got {type(gen).__name__}"))
+            )
+        return _GenFrame(cast("Generator[Effect[Any, Any, Any], Any, Any]", gen))._on_success(
+            None, fiber
+        )
+
+
+@final
+class _GenFrame(Frame):
+    """One running generator. It is resumed with each yielded effect's
+    value. On failure it is closed, so ``finally`` and ``with`` blocks run.
+    (They cannot yield effects; use ``ensuring`` for effectful cleanup.)
+    """
+
+    __slots__ = ("gen",)
+
+    def __init__(self, gen: Generator[Effect[Any, Any, Any], Any, Any]) -> None:
+        self.gen = gen
+
+    def _on_success(self, value: Any, fiber: Fiber[Any, Any]) -> Step:
+        try:
+            nxt = self.gen.send(value)
+        except StopIteration as stop:
+            return Success(stop.value)
+        fiber._push(self)
+        return nxt
+
+    def _on_failure(self, cause: Cause[Any], fiber: Fiber[Any, Any]) -> Step:
+        try:
+            self.gen.close()
+        except KeyboardInterrupt:
+            raise  # Ctrl-C: the loop interrupts the fiber (Fiber._raised)
+        except BaseException as exc:
+            return Failure(merge(cause, die_cause(exc)))
+        return Failure(cause)
+
+
+# --- interruptibility regions -------------------------------------------------
+
+
+class Restore(Protocol):
+    """Runs an effect with the interruptibility from outside the mask."""
+
+    def __call__[A, E, R](self, eff: Effect[A, E, R], /) -> Effect[A, E, R]: ...
+
+
+def uninterruptible_mask[A, E, R](f: Callable[[Restore], Effect[A, E, R]]) -> Effect[A, E, R]:
+    """Run ``f`` uninterruptibly. ``f`` receives ``restore``, which runs an
+    inner effect with the interruptibility the caller had."""
+
+    def body(fiber: Fiber[Any, Any]) -> Effect[A, E, R]:
+        restore = _interruptible if fiber._interruptible else _uninterruptible
+        return _SetInterruptible(_Suspend(lambda: f(restore)), False)
+
+    return _WithFiber(body)
+
+
+def interruptible_mask[A, E, R](f: Callable[[Restore], Effect[A, E, R]]) -> Effect[A, E, R]:
+    """Run ``f`` interruptibly. ``f`` receives ``restore``, which runs an
+    inner effect with the interruptibility the caller had. An interrupt that
+    arrived while the caller was uninterruptible lands at once."""
+
+    def body(fiber: Fiber[Any, Any]) -> Effect[A, E, R]:
+        if fiber._interruptible:
+            return f(_keep_interruptibility)
+        # As in Effect, ``f`` runs even when an interrupt is already waiting.
+        return _SetInterruptible(f(_uninterruptible), True)
+
+    return _WithFiber(body)
+
+
+class _KeepInterruptibility:
+    def __call__[A, E, R](self, eff: Effect[A, E, R], /) -> Effect[A, E, R]:
+        return eff
+
+
+class _Uninterruptible:
+    def __call__[A, E, R](self, eff: Effect[A, E, R], /) -> Effect[A, E, R]:
+        return _SetInterruptible(eff, False)
+
+
+class _Interruptible:
+    def __call__[A, E, R](self, eff: Effect[A, E, R], /) -> Effect[A, E, R]:
+        return _SetInterruptible(eff, True)
+
+
+_keep_interruptibility = _KeepInterruptibility()
+_interruptible = _Interruptible()
+_uninterruptible = _Uninterruptible()

pyfect/_public.py

@@ -0,0 +1,36 @@
+"""Public names for classes defined in private modules."""
+
+import itertools
+from collections.abc import Mapping, Sequence
+from typing import cast
+
+
+def public_home(module: str) -> str:
+    """``module`` without its private part: ``pyfect.config._error`` is at
+    home in ``pyfect.config``, ``pyfect._root`` in ``pyfect``."""
+    return ".".join(itertools.takewhile(lambda part: not part.startswith("_"), module.split(".")))
+
+
+def is_private(module: str) -> bool:
+    return any(part.startswith("_") for part in module.split("."))
+
+
+def publish(namespace: Mapping[str, object]) -> None:
+    """Give each exception this public module exports from a private module
+    under it this module's name as ``__module__``, so tracebacks and reprs
+    show ``pyfect.config.ConfigError`` rather than its private file. The
+    first public module to export it names it (a package's ``__init__``
+    runs after its submodules'). Call it after ``__all__`` as
+    ``publish(globals())``; ``tests/test_public_names.py`` checks."""
+    module = namespace["__name__"]
+    exported = cast("Sequence[str]", namespace.get("__all__", ()))
+    assert isinstance(module, str)
+    for name in exported:
+        value = namespace.get(name)
+        if (
+            isinstance(value, type)
+            and issubclass(value, BaseException)
+            and is_private(value.__module__)
+            and (module + ".").startswith(public_home(value.__module__) + ".")
+        ):
+            value.__module__ = module

pyfect/_reasons.py

@@ -0,0 +1,64 @@
+"""Reason errors: an error that wraps a more specific error as ``reason``.
+
+Effect v4's ``catchReason`` / ``catchReasons`` / ``unwrapReason`` work on
+any error with a ``reason`` field, usually a ``TaggedError`` dataclass::
+
+    @dataclass
+    class AiError(fx.TaggedError):
+        reason: RateLimitError | QuotaExceededError
+
+``HasReason`` is the protocol those combinators use to read the reason's
+type off the parent error's class. ``ReasonCatch`` is the runtime half
+shared by the Effect, Stream and Channel versions.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any, Protocol
+
+type ReasonHandler[H] = Callable[[Any, Any], H]
+
+
+class HasReason[RE](Protocol):
+    """An error carrying a ``reason`` of type ``RE`` (Effect's errors with a
+    tagged ``reason``; ``TagsWithReason`` is ``type[HasReason[Any]]``)."""
+
+    @property
+    def reason(self) -> RE: ...
+
+
+class ReasonCatch[H]:
+    """Decides which errors a reason combinator catches and runs the handler.
+
+    An instance of ``tag`` is caught when its reason is an instance of one of
+    the ``cases`` classes, or always when there is an ``or_else``. A caught
+    error goes to the first matching case's handler, else to ``or_else``;
+    both get ``(reason, error)``."""
+
+    __slots__ = ("cases", "or_else", "refail", "tag")
+
+    def __init__(
+        self,
+        tag: type[Any],
+        cases: Sequence[tuple[type[Any], ReasonHandler[H]]],
+        or_else: ReasonHandler[H] | None,
+        refail: Callable[[Any], H],
+    ) -> None:
+        self.tag = tag
+        self.cases = tuple(cases)
+        self.or_else = or_else
+        self.refail = refail
+
+    def accepts(self, error: Any) -> bool:
+        if not isinstance(error, self.tag):
+            return False
+        reason = error.reason
+        return self.or_else is not None or any(isinstance(reason, cls) for cls, _ in self.cases)
+
+    def __call__(self, error: Any) -> H:
+        reason = error.reason
+        for cls, f in self.cases:
+            if isinstance(reason, cls):
+                return f(reason, error)
+        return self.refail(error) if self.or_else is None else self.or_else(reason, error)

pyfect/_released.py

@@ -0,0 +1,67 @@
+"""Use after release: a service kept past the scope that owns it.
+
+A value made inside ``.pipe(provide(layer))`` can outlive the layer, which
+is released once the effect it was provided to ends. Every resource pyfect
+releases fails a later use with its own typed error carrying
+``closed_message(owner)``, rather than hanging or raising a defect from a
+thread pool or event loop that has stopped.
+
+``Lifetime`` is that check for a resource that hands work to a thread or
+loop of its own: ``submit`` gives a future failed with ``Released`` once
+the lifetime is closed, also when the executor or loop stopped first.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from concurrent.futures import Future
+
+
+def closed_message(owner: str) -> str:
+    """Why ``owner`` can't be used: the scope that owns it closed."""
+    return f"the {owner} is closed (used after the scope that owns it closed)"
+
+
+class Released(RuntimeError):
+    """``owner`` was used after the scope that owns it closed."""
+
+    def __init__(self, owner: str) -> None:
+        super().__init__(closed_message(owner))
+        self.owner = owner
+
+
+class Lifetime:
+    """Whether a resource owning a thread or loop is still open."""
+
+    __slots__ = ("_closed", "owner")
+
+    def __init__(self, owner: str) -> None:
+        self.owner = owner
+        self._closed = False
+
+    @property
+    def closed(self) -> bool:
+        return self._closed
+
+    def close(self) -> None:
+        self._closed = True
+
+    def error(self) -> Released:
+        return Released(self.owner)
+
+    def submit[A](self, start: Callable[[], Future[A]]) -> Future[A]:
+        """``start()``, or a future failed with ``Released`` once closed.
+        A ``RuntimeError`` from ``start`` after closing (an executor shut
+        down, a loop closed) is that same failure."""
+        if not self._closed:
+            try:
+                return start()
+            except RuntimeError:
+                if not self._closed:
+                    raise
+        failed: Future[A] = Future()
+        failed.set_exception(self.error())
+        return failed
+
+
+__all__ = ["Lifetime", "Released", "closed_message"]

pyfect/_root.py

@@ -0,0 +1,87 @@
+"""Root fibers: the fibers the run functions and runtimes start."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from pyfect._core import Effect
+from pyfect._fiber import Fiber, current_run_scheduler
+from pyfect.context import Context
+from pyfect.scheduler import AsyncioScheduler, CurrentScheduler, Scheduler
+
+
+def new_root(
+    run_scheduler: Scheduler,
+    context: Context,
+    *,
+    scheduler: Scheduler | None = None,
+    uninterruptible: bool = False,
+) -> Fiber[Any, Any]:
+    """An unstarted fiber with no parent, of the run on ``run_scheduler``.
+    ``scheduler`` is provided as its ``CurrentScheduler``."""
+    if scheduler is not None:
+        context = context.add(CurrentScheduler, scheduler)
+    return Fiber(run_scheduler, context, None, interruptible=not uninterruptible)
+
+
+def start_root(fiber: Fiber[Any, Any], eff: Effect[Any, Any, Any], *, now: bool = False) -> None:
+    """Start a root fiber. Called from a fiber of the same run, or with
+    ``now`` (the caller is on the run's thread and no fiber of it is
+    running), it runs at once, up to its first wait, before this returns
+    (Effect evaluates it synchronously); otherwise it is scheduled."""
+    if now or current_run_scheduler() is fiber._run_scheduler:
+        fiber._evaluate(eff)
+    else:
+        fiber._start(eff)
+
+
+def run_loop() -> asyncio.AbstractEventLoop | None:
+    """The asyncio loop driving the run of the fiber running on this thread,
+    or ``None`` (no fiber, or a ``run_blocking`` run). A loop merely running on
+    this thread does not count: ``run_blocking`` blocks it until it returns, so
+    nothing scheduled on it runs before then."""
+    run = current_run_scheduler()
+    return run.loop if isinstance(run, AsyncioScheduler) else None
+
+
+def loop_running_here() -> bool:
+    """Whether an asyncio loop is running on this thread."""
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return False
+    return True
+
+
+def run_identity(run_scheduler: Scheduler) -> object:
+    """What fibers of one run share: the asyncio loop for runs on a loop
+    (each ``run_async`` has a scheduler of its own, all driven by the
+    loop), else the run's scheduler, which stops when its run ends."""
+    return run_scheduler._loop if isinstance(run_scheduler, AsyncioScheduler) else run_scheduler
+
+
+def ambient_run(scheduler: Scheduler | None) -> tuple[Scheduler, bool]:
+    """The run a root fiber started here joins, and whether it can start
+    at once: the current fiber's (it can), else the running asyncio loop's
+    (it can: this is the loop's thread), else ``scheduler``, which the
+    caller then drives (it is scheduled)."""
+    run = current_run_scheduler()
+    if run is not None:
+        return run, True
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        if scheduler is None:
+            raise NoRunError(
+                "run_fork needs a running fiber, a running asyncio loop, or a scheduler "
+                "to run on; use run_blocking or run_async otherwise"
+            ) from None
+        return scheduler, False
+    return AsyncioScheduler(loop), True
+
+
+class NoRunError(RuntimeError):
+    """``run_fork`` or ``run_callback`` was called with nothing to run the
+    fiber: no fiber, no asyncio loop and no scheduler."""