pyfect-dev 0.1.0__py3-none-any.whl

pyfect/rc_ref.py

@@ -0,0 +1,271 @@
+"""``RcRef[A, E]``: a resource acquired on first use and shared while in use.
+
+``get`` acquires the resource the first time (or joins an acquisition in
+progress) and holds a reference until the caller's ``Scope`` closes. The
+last reference to go releases the resource, at once or after
+``idle_time_to_live``; the next ``get`` acquires afresh. Closing the scope
+that made the ref releases the resource and interrupts a pending
+acquisition; a ``get`` after that is interrupted.
+
+The acquisition runs on a fiber of its own, so callers can leave without
+killing it while others still wait; it is interrupted once every waiting
+caller has left.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+import math
+from typing import Any, Final, Generic, Literal, Never, TypeVar, overload
+
+from pyfect._core import (
+    Effect,
+    Restore,
+    _Locally,
+    _Succeed,
+    _Suspend,
+    _Sync,
+    _WithFiber,
+    uninterruptible_mask,
+)
+from pyfect._effect_args import require_effect
+from pyfect._fiber import Fiber
+from pyfect._root import new_root, start_root
+from pyfect._unsubscripted import Unsubscripted
+from pyfect.clock import sleep
+from pyfect.context import Context
+from pyfect.duration import Duration, Seconds, to_seconds
+from pyfect.effect import interrupt
+from pyfect.exit import Exit, Failure, Success
+from pyfect.scope import CloseableScope, Scope
+
+_VOID: Final[Effect[None]] = _Succeed(None)
+_DONE: Final[Exit[None, Never]] = Success(None)
+
+A_co = TypeVar("A_co", covariant=True, default=Unsubscripted)
+E_co = TypeVar("E_co", covariant=True, default=Never)
+
+
+class _Acquiring[A]:
+    """An acquisition in progress and the callers waiting on it. ``acquired``
+    is set when the references are handed out, which can be before the
+    acquisition's fiber exits."""
+
+    __slots__ = ("acquired", "awaiters", "fiber")
+
+    def __init__(self, fiber: Fiber[_Acquired[A], Any]) -> None:
+        self.fiber = fiber
+        self.awaiters = 1  # the caller that starts it
+        self.acquired: _Acquired[A] | None = None
+
+
+class _Acquired[A]:
+    __slots__ = ("fiber", "invalidated", "ref_count", "scope", "value")
+
+    def __init__(self, value: A, scope: CloseableScope, ref_count: int) -> None:
+        self.value = value
+        self.scope = scope
+        self.ref_count = ref_count
+        self.invalidated = False
+        self.fiber: Fiber[None, Never] | None = None  # the idle timer
+
+
+type _State[A] = _Acquiring[A] | _Acquired[A] | Literal["empty", "closed"]
+
+
+class RcRef(Generic[A_co, E_co]):
+    """Make one with ``RcRef.make(acquire)`` inside a scope. Covariant, as
+    in Effect: the resource is only read."""
+
+    __slots__ = ("_acquire", "_context", "_idle_time_to_live", "_scope", "_state")
+
+    def __init__(
+        self,
+        acquire: Effect[A_co, E_co, Any],
+        context: Context,
+        scope: CloseableScope,
+        idle_time_to_live: Seconds | None,
+    ) -> None:
+        self._acquire = acquire
+        self._context = context
+        self._scope = scope
+        self._idle_time_to_live = idle_time_to_live
+        self._state: _State[A_co] = "empty"
+
+    @overload
+    @classmethod
+    def make[T, X = Never, R = Never](
+        cls: type[RcRef[Unsubscripted, Any]],
+        acquire: Effect[T, X, R],
+        *,
+        idle_time_to_live: Duration | None = None,
+    ) -> Effect[RcRef[T, X], Never, Scope | R]: ...
+    @overload
+    @classmethod
+    def make[R = Never](
+        cls, acquire: Effect[A_co, E_co, R], *, idle_time_to_live: Duration | None = None
+    ) -> Effect[RcRef[A_co, E_co], Never, Scope | R]: ...
+    @classmethod
+    def make[T, X = Never, R = Never](
+        cls, acquire: Effect[T, X, R], *, idle_time_to_live: Duration | None = None
+    ) -> Effect[RcRef[T, X], Never, Scope | R]:
+        """A ref that runs ``acquire`` (with the services in scope now, and
+        a scope of its own) when first used. Without ``idle_time_to_live``
+        the resource is released as soon as the last reference goes."""
+        require_effect(acquire, "acquire")
+        ttl = None if idle_time_to_live is None else to_seconds(idle_time_to_live)
+
+        def body(fiber: Fiber[Any, Any]) -> Effect[RcRef[T, X]]:
+            context = fiber._context
+            scope = context.get_unsafe(Scope)
+            ref = RcRef(acquire, context, scope, ttl)
+            return scope.add_finalizer(lambda _: ref._close()).as_(ref)
+
+        return _WithFiber(body)
+
+    def get(self) -> Effect[A_co, E_co, Scope]:
+        """The resource, held until the current scope closes."""
+
+        def body(restore: Restore) -> Effect[A_co, E_co, Scope]:
+            def with_fiber(fiber: Fiber[Any, Any]) -> Effect[A_co, E_co]:
+                scope = fiber._context.get_unsafe(Scope)
+                return self._get_state(fiber, restore).flat_map(
+                    lambda state: scope.add_finalizer(lambda _: self._release(state)).as_(
+                        state.value
+                    )
+                )
+
+            return _WithFiber(with_fiber)
+
+        return uninterruptible_mask(body)
+
+    def invalidate(self) -> Effect[None]:
+        """Forget the resource, so the next ``get`` acquires afresh. It is
+        released now if nobody holds it, else when the last holder lets go."""
+
+        def body() -> Effect[None]:
+            state = self._state
+            if not isinstance(state, _Acquired):
+                return _VOID
+            self._state = "empty"
+            state.invalidated = True
+            if state.ref_count > 0:
+                return _VOID
+            if state.fiber is not None:
+                state.fiber.interrupt_as_unsafe(None)
+            return state.scope.close(_DONE)
+
+        return _Suspend(body).uninterruptible()
+
+    def __repr__(self) -> str:
+        state = self._state
+        if isinstance(state, _Acquired):
+            return f"RcRef(acquired, refs={state.ref_count})"
+        return f"RcRef({'acquiring' if isinstance(state, _Acquiring) else state})"
+
+    def _get_state(self, fiber: Fiber[Any, Any], restore: Restore) -> Effect[_Acquired[A_co], E_co]:
+        state = self._state
+        if state == "closed":
+            return interrupt()
+        if isinstance(state, _Acquired):
+            state.ref_count += 1
+            idle = state.fiber
+            return _Succeed(state) if idle is None else idle.interrupt().as_(state)
+        if isinstance(state, _Acquiring):
+            state.awaiters += 1
+            return self._await_acquiring(state, restore)
+        return self._start_acquiring(fiber, restore)
+
+    def _start_acquiring(
+        self, parent: Fiber[Any, Any], restore: Restore
+    ) -> Effect[_Acquired[A_co], E_co]:
+        scope = CloseableScope()
+        context = self._context.add(Scope, scope)
+        acquiring: _Acquiring[A_co] = _Acquiring(new_root(parent._run_scheduler, parent._context))
+
+        def publish(value: A_co) -> Effect[_Acquired[A_co]]:
+            if self._state is not acquiring:  # closed, or abandoned
+                return interrupt()
+            # Every caller still waiting holds a reference.
+            acquired = _Acquired(value, scope, acquiring.awaiters)
+            self._state = acquiring.acquired = acquired
+            return _Succeed(acquired)
+
+        def settle(ex: Exit[_Acquired[A_co], E_co]) -> Effect[None]:
+            if isinstance(ex, Success):
+                return _VOID
+            if self._state is acquiring:
+                self._state = "empty"
+            return scope.close(ex)
+
+        self._state = acquiring
+        acquire: Effect[A_co, E_co] = _Locally(
+            self._acquire, lambda current: current.merge(context)
+        )
+        start_root(acquiring.fiber, acquire.flat_map(publish).on_exit(settle))
+        return self._await_acquiring(acquiring, restore)
+
+    def _await_acquiring(
+        self, acquiring: _Acquiring[A_co], restore: Restore
+    ) -> Effect[_Acquired[A_co], E_co]:
+        def leave(ex: Exit[_Acquired[A_co], E_co]) -> Effect[None]:
+            acquired = acquiring.acquired
+            if acquired is not None:
+                # Counted as a reference, maybe before the fiber exited:
+                # give it back if this caller was interrupted before it
+                # could register its release.
+                return self._release(acquired) if isinstance(ex, Failure) else _VOID
+            acquiring.awaiters -= 1
+            if acquiring.awaiters > 0 or self._state is not acquiring:
+                return _VOID
+            # Detach it first, so a new caller starts afresh rather than
+            # joining an acquisition being interrupted.
+            self._state = "empty"
+            return acquiring.fiber.interrupt()
+
+        return restore(acquiring.fiber.join()).on_exit(leave)
+
+    def _release(self, state: _Acquired[A_co]) -> Effect[None]:
+        return _WithFiber(lambda fiber: self._release_now(fiber, state))
+
+    def _release_now(self, fiber: Fiber[Any, Any], state: _Acquired[A_co]) -> Effect[None]:
+        state.ref_count -= 1
+        if state.ref_count > 0:
+            return _VOID
+        ttl = self._idle_time_to_live
+        if ttl is None or state.invalidated:
+            if self._state is state:
+                self._state = "empty"
+            return state.scope.close(_DONE)
+        if math.isinf(ttl):
+            return _VOID
+
+        def expire(_: None) -> Effect[None]:
+            if self._state is state and state.ref_count == 0:
+                self._state = "empty"
+                return state.scope.close(_DONE)
+            return _VOID
+
+        def forget() -> None:
+            state.fiber = None
+
+        idle = uninterruptible_mask(lambda restore: restore(sleep(ttl)).flat_map(expire)).ensuring(
+            _Sync(forget)
+        )
+        timer: Fiber[None, Never] = new_root(fiber._run_scheduler, self._context)
+        state.fiber = timer
+        start_root(timer, idle)
+        timer.run_in(self._scope)
+        return _VOID
+
+    def _close(self) -> Effect[None]:
+        state = self._state
+        self._state = "closed"
+        if isinstance(state, _Acquired):
+            return state.scope.close(_DONE)
+        if isinstance(state, _Acquiring):
+            return state.fiber.interrupt()
+        return _VOID
+
+
+__all__ = ["RcRef"]

pyfect/reactivity/__init__.py

@@ -0,0 +1,53 @@
+"""Queries that run again when what they read changes (Effect's
+``effect/reactivity/Reactivity``), and atoms (``atom``, ``atom_registry``,
+``hydration``; ``atom_rpc`` and ``atom_http_api`` over RPC and HttpApi
+clients, imported on first use)."""
+
+import importlib as _importlib
+import typing as _typing
+from types import ModuleType as _ModuleType
+
+from pyfect.reactivity import async_result, atom, atom_ref, atom_registry, hydration
+from pyfect.reactivity._reactivity import (
+    Keys,
+    Reactivity,
+    ReactivityService,
+    invalidate,
+    layer,
+    make,
+    mutation,
+    query,
+    stream,
+)
+
+if _typing.TYPE_CHECKING:
+    from pyfect.reactivity import atom_http_api, atom_rpc
+else:
+    # They import the rpc and http_api packages, which ``sql`` (a user of
+    # Reactivity) should not pay for.
+    _LAZY = ("atom_http_api", "atom_rpc")
+
+    def __getattr__(name: str) -> _ModuleType:
+        if name in _LAZY:
+            return _importlib.import_module(f"pyfect.reactivity.{name}")
+        raise AttributeError(f"module 'pyfect.reactivity' has no attribute {name!r}")
+
+
+__all__ = [
+    "Keys",
+    "Reactivity",
+    "ReactivityService",
+    "async_result",
+    "atom",
+    "atom_http_api",
+    "atom_ref",
+    "atom_registry",
+    "atom_rpc",
+    "hydration",
+    "invalidate",
+    "layer",
+    "make",
+    "mutation",
+    "query",
+    "stream",
+]

pyfect/reactivity/_async_result_schema.py

@@ -0,0 +1,227 @@
+"""The schema of ``AsyncResult`` values (Effect's ``AsyncResult.Schema``).
+
+It takes an ``AsyncResult`` and parses the success value with ``success``
+and a failure's cause with ``Cause(error, Defect())``. As JSON it is a
+tagged object: ``{"_tag": "Initial", "waiting": w}``, ``{"_tag":
+"Success", "value": v, "waiting": w, "timestamp": t}`` or ``{"_tag":
+"Failure", "cause": reasons, "previousSuccess": Option(Success),
+"waiting": w}``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Generic, Never, TypeVar, cast
+
+from pyfect._equal import equals
+from pyfect.cause import Cause
+from pyfect.exit import Exit
+from pyfect.exit import Success as ExitSuccess
+from pyfect.exit import fail as fail_exit
+from pyfect.option import Option, Some
+from pyfect.reactivity.async_result import AsyncResult, Failure, Initial, Success
+from pyfect.schema import Bottom, Codec, Defect, ParseOptions, ast
+from pyfect.schema import Cause as CauseSchema
+from pyfect.schema import Never as NeverSchema
+from pyfect.schema import Option as OptionSchema
+from pyfect.schema._codec_links import link, tagged
+from pyfect.schema._primitives import Int
+from pyfect.schema._to_equivalence import Equivalence
+from pyfect.schema._to_formatter import Formatter
+from pyfect.schema.issue import Composite, Issue, Pointer, reported
+
+A_co = TypeVar("A_co", covariant=True)
+E_co = TypeVar("E_co", covariant=True)
+AI_co = TypeVar("AI_co", covariant=True)
+EI_co = TypeVar("EI_co", covariant=True)
+RD_co = TypeVar("RD_co", covariant=True)
+RE_co = TypeVar("RE_co", covariant=True)
+
+type _Tagged = Mapping[str, Any]
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class AsyncResultSchema(
+    Bottom[AsyncResult[A_co, E_co], AsyncResult[AI_co, EI_co], RD_co, RE_co],
+    Generic[A_co, E_co, AI_co, EI_co, RD_co, RE_co],
+):
+    """``AsyncResult`` values whose success ``success`` takes and whose
+    failure's error ``error`` takes."""
+
+    success: Codec[A_co, AI_co, RD_co, RE_co]
+    error: Codec[E_co, EI_co, RD_co, RE_co]
+
+
+def _run(nodes: tuple[ast.AST, ...]) -> ast.DeclarationParser:
+    value, cause = nodes
+
+    def parse_success(
+        node: ast.Declaration, input: Success[Any, Any], options: ParseOptions
+    ) -> ast.ParseResult:
+        parsed = ast.parse_at_key(node, "value", value, input.value, input=input, options=options)
+        return ast.map_value(parsed, lambda v: Success(v, input.waiting, input.timestamp))
+
+    def parse_previous(
+        node: ast.Declaration, input: Failure[Any, Any], options: ParseOptions
+    ) -> ast.ParseResult:
+        previous = input.previous_success
+        if not isinstance(previous, Some):
+            return ExitSuccess(None)
+        ps = previous.value
+
+        def at_previous(exit: Exit[object, Issue]) -> ast.ParseResult:
+            if isinstance(exit, ExitSuccess):
+                parsed: Success[object] = Success(exit.value, ps.waiting, ps.timestamp)
+                return ExitSuccess(Some(parsed))
+            issue = ast.issue_of(exit)
+            if issue is None:
+                return exit
+            pointer = Pointer(("previous_success", "value"), issue)
+            return fail_exit(Composite(node, (pointer,), reported(input, options)))
+
+        return ast.then(value.parse(ps.value, options), at_previous)
+
+    def parse(input: object, node: ast.Declaration, options: ParseOptions) -> ast.ParseResult:
+        match input:
+            case Initial():
+                return ExitSuccess(cast("Initial[object]", input))
+            case Success():
+                return parse_success(node, cast("Success[Any, Any]", input), options)
+            case Failure():
+                failed = cast("Failure[Any, Any]", input)
+
+                def with_cause(previous: object) -> ast.ParseResult:
+                    parsed = ast.parse_at_key(
+                        node, "cause", cause, failed.cause, input=failed, options=options
+                    )
+                    return ast.map_value(
+                        parsed,
+                        lambda c: Failure(
+                            cast("Cause[Any]", c),
+                            cast("Option[Success[Any, Any]]", previous),
+                            failed.waiting,
+                        ),
+                    )
+
+                return ast.flat_map(parse_previous(node, failed, options), with_cause)
+            case _:
+                return ast.invalid_type(node, input, options)
+
+    return parse
+
+
+def _of(encoded: _Tagged) -> AsyncResult[object, object]:
+    match encoded["_tag"]:
+        case "Initial":
+            return Initial(encoded["waiting"])
+        case "Success":
+            return Success(encoded["value"], encoded["waiting"], encoded["timestamp"])
+        case _:
+            previous = cast("Option[_Tagged]", encoded["previousSuccess"])
+            return Failure(
+                encoded["cause"],
+                None
+                if previous is None
+                else Some(Success(previous.value["value"], **_flags(previous.value))),
+                encoded["waiting"],
+            )
+
+
+def _flags(encoded: _Tagged) -> dict[str, Any]:
+    return {"waiting": encoded["waiting"], "timestamp": encoded["timestamp"]}
+
+
+def _success_to(result: Success[object, object]) -> _Tagged:
+    return {
+        "_tag": "Success",
+        "value": result.value,
+        "waiting": result.waiting,
+        "timestamp": result.timestamp,
+    }
+
+
+def _to(result: AsyncResult[object, object]) -> _Tagged:
+    match result:
+        case Initial():
+            return {"_tag": "Initial", "waiting": result.waiting}
+        case Success():
+            return _success_to(result)
+        case Failure():
+            previous = result.previous_success
+            return {
+                "_tag": "Failure",
+                "cause": result.cause,
+                "previousSuccess": None if previous is None else Some(_success_to(previous.value)),
+                "waiting": result.waiting,
+            }
+
+
+def _to_codec(nodes: tuple[ast.AST, ...]) -> ast.Link:
+    value, cause = nodes
+    success = tagged("Success", value=value, waiting=ast.boolean, timestamp=Int.__codec__().ast)
+    previous = OptionSchema(Bottom[object](success)).ast
+    union = ast.Union(
+        (
+            tagged("Initial", waiting=ast.boolean),
+            success,
+            tagged("Failure", cause=cause, previousSuccess=previous, waiting=ast.boolean),
+        )
+    )
+    return link(union, decode=_of, encode=_to)
+
+
+def _equivalence(_: tuple[Equivalence[Any], ...]) -> Equivalence[AsyncResult[object, object]]:
+    return equals
+
+
+def _formatter(parameters: tuple[Formatter[Any], ...]) -> Formatter[AsyncResult[object, object]]:
+    value, cause = parameters
+
+    def format(result: AsyncResult[object, object]) -> str:
+        match result:
+            case Success():
+                return (
+                    f"AsyncResult.Success({value(result.value)}, "
+                    f"{_js_bool(result.waiting)}, {result.timestamp})"
+                )
+            case Failure():
+                return f"AsyncResult.Failure({cause(result.cause)}, {_js_bool(result.waiting)})"
+            case Initial():
+                waiting = _js_bool(result.waiting)
+                return f"AsyncResult.Initial({waiting}, {waiting})"
+
+    return format
+
+
+def _js_bool(value: bool) -> str:
+    return "true" if value else "false"
+
+
+def Schema[A = Never, E = Never, AI = Never, EI = Never, RD = Never, RE = Never](
+    *,
+    success: Codec[A, AI, RD, RE] | None = None,
+    error: Codec[E, EI, RD, RE] | None = None,
+) -> AsyncResultSchema[A, E, AI, EI, RD, RE]:
+    """An ``AsyncResult`` whose success ``success`` takes and whose
+    failure's errors ``error`` takes (Effect's ``AsyncResult.Schema``;
+    either left out is ``S.Never``). Issues are at ``["value"]``,
+    ``["previous_success", "value"]`` and ``["cause"]``; anything else is
+    ``Expected AsyncResult``."""
+    success_ = cast("Codec[A, AI, RD, RE]", NeverSchema if success is None else success)
+    error_ = cast("Codec[E, EI, RD, RE]", NeverSchema if error is None else error)
+    cause = CauseSchema(error_, cast("Any", Defect()))
+    node = ast.Declaration(
+        (success_.__codec__().ast, cause.ast),
+        _run,
+        annotations={
+            "expected": "AsyncResult",
+            "to_codec": _to_codec,
+            "to_equivalence": _equivalence,
+            "to_formatter": _formatter,
+        },
+    )
+    return AsyncResultSchema(node, success_, error_)
+
+
+__all__ = ["AsyncResultSchema", "Schema"]

pyfect/reactivity/_hydration.py

@@ -0,0 +1,18 @@
+"""Whether a hydrated value replaces a node's current one (Effect's
+``internal/hydration``)."""
+
+from __future__ import annotations
+
+from pyfect.reactivity.async_result import Initial, Success, is_async_result
+
+
+def should_hydrate(current: object, incoming: object) -> bool:
+    """An ``Initial`` replaces only an ``Initial``, and a success only an
+    older success; a failure has no timestamp, so it always replaces."""
+    if not is_async_result(current) or not is_async_result(incoming):
+        return True
+    if isinstance(incoming, Initial):
+        return isinstance(current, Initial)
+    if isinstance(current, Success) and isinstance(incoming, Success):
+        return incoming.timestamp >= current.timestamp
+    return True

pyfect/reactivity/_live.py

@@ -0,0 +1,21 @@
+"""JavaScript ``Set`` iteration over an insertion-ordered ``dict``.
+
+Effect iterates live ``Set``s of listeners and handlers (and the ``Map``
+of nodes when dehydrating): one removed by an earlier callback is
+skipped, and one added meanwhile is visited too.
+Iterating a ``list`` snapshot gets both wrong, so every such loop in
+``pyfect.reactivity`` goes through ``live_keys``.
+"""
+
+from collections.abc import Iterator, Mapping
+
+
+def live_keys[K](items: Mapping[K, object]) -> Iterator[K]:
+    """The keys of ``items`` in order, each once, as ``items`` changes:
+    a key removed before it is reached is skipped, one added is reached."""
+    seen: dict[K, None] = {}
+    while pending := [key for key in items if key not in seen]:
+        for key in pending:
+            if key in items:
+                seen[key] = None
+                yield key