pyfect-dev 0.1.0__py3-none-any.whl

pyfect/pubsub/_subscription.py

@@ -0,0 +1,226 @@
+"""``Subscription[A]``: one subscriber's view of a ``PubSub``.
+
+A subscription reads its replayed messages first, then what was published
+after it subscribed. Once the hub has ended, a subscription that has read
+everything gets the final message from every ``take`` (``take_up_to`` never
+waits, so it gets nothing). Once unsubscribed (its scope closed, or the hub
+shut down), every take is interrupted, but for one already woken with a
+message, which gets it (Effect runs that take before the unsubscribe).
+
+The subscription only gives ``A``s, so it is covariant (Effect's ``out
+A``): its state is kept as ``Any`` and typed by the methods, and batches
+are typed ``Sequence`` (they are lists).
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Generator, Sequence
+from typing import TYPE_CHECKING, Any, Never, cast
+
+from pyfect._core import (
+    Effect,
+    Frame,
+    Step,
+    _Callback,
+    _FailCause,
+    _Gen,
+    _Succeed,
+    _Suspend,
+    _Sync,
+    _WithFiber,
+)
+from pyfect.cause import Cause
+from pyfect.cause import interrupt as interrupt_cause
+from pyfect.exit import Failure, Success
+from pyfect.pubsub._hub import Hub, Reader, Ticket
+
+if TYPE_CHECKING:
+    from pyfect._fiber import Fiber
+
+
+def _identity[T](value: T) -> T:
+    return value
+
+
+def _interrupt() -> Effect[Never]:
+    return _WithFiber(lambda fiber: _FailCause(interrupt_cause(fiber.id)))
+
+
+class Subscription[A]:
+    __slots__ = ("_hub", "_reader")
+
+    def __init__(self, hub: Hub[Any], reader: Reader[Any]) -> None:
+        self._hub = hub
+        self._reader = reader
+
+    def take(self) -> Effect[A]:
+        """Wait for the next message."""
+        reader = self._reader
+        hub = self._hub
+
+        def attempt() -> Effect[A]:
+            if reader.unsubscribed:
+                return _interrupt()
+            replayed = reader.replay.take()
+            if replayed is not None:
+                return _Succeed(replayed.value)
+            polled = reader.read_up_to(1)
+            if polled:
+                hub.deliver()
+                return _Succeed(polled[0])
+            if hub.ended is not None:
+                return _Succeed(hub.ended.value)
+            return self._park(_identity, attempt)
+
+        return _Suspend(attempt)
+
+    def take_all(self) -> Effect[Sequence[A]]:
+        """Wait for at least one message, then take every one there is."""
+        reader = self._reader
+        hub = self._hub
+
+        def more(first: A) -> list[A]:
+            rest = reader.read_up_to(reader.size())
+            hub.deliver()
+            return [first, *rest]
+
+        def attempt() -> Effect[list[A]]:
+            if reader.unsubscribed:
+                return _interrupt()
+            polled = reader.read_up_to(reader.size())
+            hub.deliver()
+            if reader.replay.remaining:
+                return _Succeed(reader.replay.take_all() + polled)
+            if polled:
+                return _Succeed(polled)
+            if hub.ended is not None:
+                return _Succeed([hub.ended.value])
+            return self._park(more, attempt)
+
+        return _Suspend(attempt)
+
+    def take_up_to(self, n: int) -> Effect[Sequence[A]]:
+        """Take up to ``n`` messages without waiting (none if ``n`` is 0 or
+        less, or while other takes wait)."""
+        reader = self._reader
+
+        def attempt() -> Effect[list[A]]:
+            if reader.unsubscribed:
+                return _interrupt()
+            limit = max(n, 0)
+            if reader.replay.remaining >= limit:
+                return _Succeed(reader.replay.take_n(limit))
+            replayed = reader.replay.take_all()
+            polled = reader.read_up_to(limit - len(replayed))
+            self._hub.deliver()
+            return _Succeed(replayed + polled)
+
+        return _Suspend(attempt)
+
+    def take_between(self, minimum: int, maximum: int) -> Effect[Sequence[A]]:
+        """Take at least ``minimum`` and at most ``maximum`` messages, waiting
+        for the minimum. Nothing, at once, if ``maximum < minimum``."""
+
+        def body() -> Generator[Effect[Any], Any, list[A]]:
+            low, high = max(minimum, 0), max(maximum, 0)
+            out: list[A] = []
+            while high >= low:
+                taken: Sequence[A] = yield self.take_up_to(high)
+                out.extend(taken)
+                missing = low - len(taken)
+                if missing <= 0:
+                    break
+                out.append((yield self.take()))
+                low, high = missing - 1, high - len(taken) - 1
+                if low == 0:
+                    break
+            return out
+
+        return _Gen(body)
+
+    def remaining(self) -> Effect[int]:
+        """How many messages there are to take now."""
+
+        def attempt() -> Effect[int]:
+            count = self.remaining_unsafe()
+            return _interrupt() if count is None else _Succeed(count)
+
+        return _Suspend(attempt)
+
+    def remaining_unsafe(self) -> int | None:
+        """``remaining`` now; ``None`` once unsubscribed."""
+        reader = self._reader
+        if reader.unsubscribed:
+            return None
+        return reader.size() + reader.replay.remaining
+
+    def _park[X](self, then: Callable[[A], X], again: Callable[[], Effect[X]]) -> Effect[X]:
+        """Wait behind the takes already waiting. Woken with a message, end
+        with ``then(message)``; woken without one (the hub ended or the
+        subscription closed), look again with ``again()``. A take waiting
+        when the subscription closes is interrupted by the closing fiber, as
+        in Effect."""
+        reader = self._reader
+        hub = self._hub
+        ticket = Ticket(_ignore)
+
+        def register(resume: Callable[[Effect[None]], None]) -> Effect[None] | None:
+            if reader.unsubscribed or hub.ended is not None:
+                resume(_VOID)
+                return None
+            ticket.wake = lambda: resume(_VOID)
+            reader.waiting.append(ticket)
+            hub.deliver()
+            return _Sync(lambda: reader.discard(ticket))
+
+        def run(fiber: Fiber[Any, Any]) -> Effect[None]:
+            fiber._push(_Collect(hub, reader, ticket, then, again))
+            return _Callback(register)
+
+        return cast("Effect[X]", _WithFiber(run))
+
+
+_VOID: Effect[None] = _Succeed(None)
+
+
+def _ignore() -> None:
+    pass
+
+
+class _Collect[A, X](Frame):
+    """Below a parked take. Woken with a message, collect it in this same
+    step, so no interrupt can land between collecting and returning it.
+    Failing before that (interrupted while parked, or woken and interrupted
+    before collecting), leave the message to the next take."""
+
+    __slots__ = ("again", "hub", "reader", "then", "ticket")
+    # Collecting claims the message; it reaches the caller with no pause.
+    claims = True
+
+    def __init__(
+        self,
+        hub: Hub[A],
+        reader: Reader[A],
+        ticket: Ticket,
+        then: Callable[[A], X],
+        again: Callable[[], Effect[X]],
+    ) -> None:
+        self.hub = hub
+        self.reader = reader
+        self.ticket = ticket
+        self.then = then
+        self.again = again
+
+    def _on_success(self, value: Any, fiber: Fiber[Any, Any]) -> Step:
+        reader = self.reader
+        if self.ticket.claimed:
+            return Success(self.then(reader.collect(self.ticket)))
+        if reader.unsubscribed:
+            return Failure(interrupt_cause(reader.closed_by))
+        return self.again()
+
+    def _on_failure(self, cause: Cause[Any], fiber: Fiber[Any, Any]) -> Step:
+        if self.reader.release(self.ticket):
+            self.hub.deliver()
+        return Failure(cause)

pyfect/pull.py

@@ -0,0 +1,132 @@
+"""``Pull[A, E, L, R]``: one step of a pull-based producer (Effect's ``Pull``).
+
+A pull is an effect that succeeds with the next item, fails with an ordinary
+error ``E``, or fails with ``Done(leftover)`` when the producer has finished
+normally. Keeping the end in the error channel lets a consumer tell normal
+completion from failure while every effect combinator still applies::
+
+    item = yield from pull          # Done(...) ends the surrounding loop
+
+``filter_done`` and the helpers here separate ``Done`` from real failures:
+``catch_done`` and ``match_effect`` handle it, ``done_exit_from_cause``
+turns a cause into the producer's final ``Exit``.
+
+Pyright cannot subtract ``Done`` from an error union, so the functions that
+take ``Done`` out of a type are data-first (``catch_done(pull, f)``): their
+overloads read ``E | Done[L]`` off the pull itself.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Never, TypeIs, overload
+
+from pyfect._core import Effect, _FailCause, _MatchCause
+from pyfect._effect_args import require_effect
+from pyfect.cause import Cause, Fail, Reason
+from pyfect.errors import Done, _is_done, filter_done
+from pyfect.exit import Exit, Failure, Success
+from pyfect.result import Err, Ok, Result
+
+type Pull[A, E = Never, L = None, R = Never] = Effect[A, E | Done[L], R]
+"""An effect producing one ``A``, failing with ``E``, or ending with
+``Done[L]``."""
+
+
+def is_done_failure(reason: Reason[object]) -> TypeIs[Fail[Done[Any]]]:
+    """Whether ``reason`` is a ``Fail`` holding a ``Done``."""
+    return _is_done(reason)
+
+
+def is_done_cause(cause: Cause[object]) -> bool:
+    """Whether ``cause`` holds any ``Done`` failure."""
+    return any(_is_done(r) for r in cause.reasons)
+
+
+def filter_no_done[E](cause: Cause[E]) -> Result[Cause[E], Cause[E]]:
+    """``Ok(cause)`` when it holds no ``Done`` failure, else ``Err(cause)``."""
+    return Err(cause) if is_done_cause(cause) else Ok(cause)
+
+
+def filter_done_leftover[E](cause: Cause[E]) -> Result[Any, Cause[E]]:
+    """``filter_done``, keeping only the ``Done``'s leftover value."""
+    found = filter_done(cause)
+    return Ok(found.value.value) if isinstance(found, Ok) else found
+
+
+def done_exit_from_cause[E](cause: Cause[E]) -> Exit[Any, E]:
+    """The producer's final exit: success with the leftover when ``Done``
+    is the only failure, else a failure with the cause stripped of
+    ``Done``."""
+    found = filter_done(cause)
+    return Success(found.value.value) if isinstance(found, Ok) else Failure(found.error)
+
+
+@overload
+def catch_done[A, L, B, EE = Never, RR = Never](
+    pull: Effect[A, Done[L], RR], f: Callable[[L], Effect[B, EE, RR]]
+) -> Effect[A | B, EE, RR]: ...
+@overload
+def catch_done[A, L, B, EE = Never, RR = Never](
+    pull: Effect[A, EE | Done[L], RR], f: Callable[[L], Effect[B, EE, RR]]
+) -> Effect[A | B, EE, RR]: ...
+def catch_done(
+    pull: Effect[Any, Any, Any], f: Callable[[Any], Effect[Any, Any, Any]]
+) -> Effect[Any, Any, Any]:
+    """Recover from ``Done`` with ``f(leftover)``; other failures pass
+    through (a ``Done`` merged with a real failure is dropped from it)."""
+    require_effect(pull, "pull")
+
+    def on_failure(cause: Cause[Any]) -> Effect[Any, Any, Any]:
+        found = filter_done(cause)
+        return f(found.value.value) if isinstance(found, Ok) else _FailCause(found.error)
+
+    return _MatchCause(pull, on_failure, None)
+
+
+@overload
+def match_effect[A, L, B, EE = Never, RR = Never](
+    pull: Effect[A, Done[L], RR],
+    *,
+    on_success: Callable[[A], Effect[B, EE, RR]],
+    on_failure: Callable[[Cause[Never]], Effect[B, EE, RR]],
+    on_done: Callable[[L], Effect[B, EE, RR]],
+) -> Effect[B, EE, RR]: ...
+@overload
+def match_effect[A, E, L, B, EE = Never, RR = Never](
+    pull: Effect[A, E | Done[L], RR],
+    *,
+    on_success: Callable[[A], Effect[B, EE, RR]],
+    on_failure: Callable[[Cause[E]], Effect[B, EE, RR]],
+    on_done: Callable[[L], Effect[B, EE, RR]],
+) -> Effect[B, EE, RR]: ...
+def match_effect(
+    pull: Effect[Any, Any, Any],
+    *,
+    on_success: Callable[[Any], Effect[Any, Any, Any]],
+    on_failure: Callable[[Cause[Any]], Effect[Any, Any, Any]],
+    on_done: Callable[[Any], Effect[Any, Any, Any]],
+) -> Effect[Any, Any, Any]:
+    """Handle each outcome of ``pull``: an item, a failure (without
+    ``Done``), or the end with its leftover."""
+    require_effect(pull, "pull")
+
+    def failed(cause: Cause[Any]) -> Effect[Any, Any, Any]:
+        found = filter_done(cause)
+        return on_done(found.value.value) if isinstance(found, Ok) else on_failure(found.error)
+
+    return _MatchCause(pull, failed, on_success)
+
+
+__all__ = [
+    "Pull",
+    "catch_done",
+    "done_exit_from_cause",
+    "filter_done",
+    "filter_done_leftover",
+    "filter_no_done",
+    "is_done_cause",
+    "is_done_failure",
+    "match_effect",
+]

pyfect/pydantic.py

@@ -0,0 +1,188 @@
+"""Pydantic and pyfect schemas, each usable in the other. Needs the
+``pydantic`` extra (``pyfect-dev[pydantic]``).
+
+A pyfect schema is a pydantic field type: annotate the field with it::
+
+    from typing import Annotated
+
+    from pydantic import BaseModel
+
+    from pyfect import schema as S
+
+    class Order(BaseModel):
+        total: Annotated[float, S.FiniteFromString]
+
+Python input the schema's decoded side accepts is kept as it is (so
+pydantic's revalidation and ``validate_assignment`` never decode twice);
+other Python input is decoded with the schema, JSON input with
+``S.to_codec_json(schema)``;
+dumping encodes the same way, and the JSON Schema is the schema's. A schema
+class (``S.Class``) works as a field type directly. A failure is one
+pydantic error, the pyfect message. Only schemas that need no services can
+run inside pydantic.
+
+``from_model(Model)`` goes the other way: a pyfect schema of a pydantic
+model, decoding JSON values with ``Model.model_validate`` and encoding with
+``model_dump(mode="json")``; pydantic's errors become a pyfect issue tree.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Never, cast
+
+from pyfect._extras import missing_extra
+
+try:
+    from pydantic import BaseModel, GetCoreSchemaHandler, GetJsonSchemaHandler, ValidationError
+    from pydantic_core import CoreSchema, PydanticCustomError, core_schema
+except ImportError as error:  # pragma: no cover - depends on the environment
+    raise missing_extra("pyfect.pydantic", "pydantic") from error
+
+from pyfect.exit import Exit, Failure, Success
+from pyfect.exit import fail as fail_exit
+from pyfect.result import Err, Ok, Result
+from pyfect.schema import (
+    Bottom,
+    Codec,
+    Json,
+    JsonValue,
+    ParseOptions,
+    SchemaError,
+    decode_to,
+    decode_unknown_result,
+    encode_unknown_result,
+    instance_of,
+    to_codec_json,
+    to_json_schema_document,
+)
+from pyfect.schema import ast as schema_ast
+from pyfect.schema import transformation as T
+from pyfect.schema.issue import Composite, InvalidValue, Issue, MissingKey, Pointer
+
+__all__ = [
+    "core_schema_of",
+    "from_model",
+    "get_pydantic_core_schema",
+    "get_pydantic_json_schema",
+    "json_schema_of",
+]
+
+type _Codec = Codec[Any, Any, Never, Never]
+
+
+def core_schema_of(schema: _Codec, /) -> CoreSchema:
+    """The pydantic core schema validating and serializing with ``schema``
+    (what ``__get_pydantic_core_schema__`` of a pyfect schema returns)."""
+    json_codec = to_codec_json(schema)
+    decoded_side = schema.__codec__().ast.to_type()
+
+    def decode_python(input: object) -> object:
+        # A decoded value is kept first, so validating again (pydantic's
+        # revalidation and assignment) never decodes a value twice.
+        match schema_ast.run_now(decoded_side.parse(input, {})):
+            case Success(value):
+                return value
+            case Failure():
+                return _unwrap(decode_unknown_result(schema)(input))
+
+    def decode_json(input: object) -> object:
+        return _unwrap(decode_unknown_result(json_codec)(input))
+
+    def serialize(value: object, info: core_schema.SerializationInfo) -> object:
+        codec = json_codec if info.mode_is_json() else schema
+        return _unwrap(encode_unknown_result(codec)(value))
+
+    return core_schema.json_or_python_schema(
+        json_schema=core_schema.no_info_plain_validator_function(decode_json),
+        python_schema=core_schema.no_info_plain_validator_function(decode_python),
+        serialization=core_schema.plain_serializer_function_ser_schema(serialize, info_arg=True),
+    )
+
+
+def json_schema_of(schema: _Codec, /) -> dict[str, Any]:
+    """``schema``'s JSON Schema for pydantic, with its definitions inlined
+    (pydantic keeps its own ``$defs``); a recursive reference is left
+    unconstrained."""
+    document = to_json_schema_document(schema)
+    return cast("dict[str, Any]", _inline(document.schema, document.definitions, ()))
+
+
+def _inline(node: object, definitions: Mapping[str, object], seen: tuple[str, ...]) -> object:
+    if isinstance(node, list):
+        return [_inline(value, definitions, seen) for value in cast("list[object]", node)]
+    if not isinstance(node, dict):
+        return node
+    fields = cast("dict[str, object]", node)
+    out = {key: _inline(value, definitions, seen) for key, value in fields.items() if key != "$ref"}
+    ref = fields.get("$ref")
+    if not (isinstance(ref, str) and ref.startswith(_DEFS)):
+        return out if ref is None else {**out, "$ref": ref}
+    name = ref.removeprefix(_DEFS)
+    if name in seen:
+        return out
+    target = cast("dict[str, object]", _inline(definitions[name], definitions, (*seen, name)))
+    return {**target, **out}
+
+
+_DEFS = "#/$defs/"
+
+
+def get_pydantic_core_schema(
+    schema: _Codec, _source: object, _handler: GetCoreSchemaHandler
+) -> CoreSchema:
+    return core_schema_of(schema)
+
+
+def get_pydantic_json_schema(
+    schema: _Codec, _core: CoreSchema, _handler: GetJsonSchemaHandler
+) -> dict[str, Any]:
+    return json_schema_of(schema)
+
+
+def _unwrap(result: Result[object, SchemaError]) -> object:
+    match result:
+        case Ok(value):
+            return value
+        case Err(error):
+            return _raise(error)
+
+
+def _raise(error: SchemaError) -> Never:
+    raise PydanticCustomError("pyfect_schema", "{message}", {"message": str(error)})
+
+
+def from_model[M: BaseModel](model: type[M], /) -> Bottom[M, JsonValue]:
+    """``model`` as a pyfect schema: decodes a JSON value with
+    ``model.model_validate``, encodes with ``model_dump(mode="json")``.
+    Each pydantic error is an issue at its location (``Missing key`` for a
+    missing field)."""
+    target = instance_of(model)
+    node = target.ast
+
+    def decode(input: JsonValue, _options: ParseOptions) -> Exit[M, Issue]:
+        try:
+            return Success(model.model_validate(input))
+        except ValidationError as error:
+            return fail_exit(_issue_of(error, node))
+
+    def encode(value: M, _options: ParseOptions) -> Exit[JsonValue, Issue]:
+        return Success(cast("JsonValue", value.model_dump(mode="json")))
+
+    return Json.pipe(decode_to(target, T.transform_effect(decode=decode, encode=encode)))
+
+
+def _issue_of(error: ValidationError, node: schema_ast.AST) -> Issue:
+    issues: list[Issue] = []
+    for detail in error.errors(include_url=False):
+        leaf: Issue = (
+            MissingKey()
+            if detail["type"] == "missing"
+            else InvalidValue({"message": detail["msg"]})
+        )
+        location = tuple(detail["loc"])
+        issues.append(Pointer(location, leaf) if location else leaf)
+    if len(issues) == 1:
+        return issues[0]
+    first, *rest = issues
+    return Composite(node, (first, *rest))

pyfect/queue/__init__.py

@@ -0,0 +1,33 @@
+"""``Queue[A, E]``: an async queue fibers can share.
+
+Capacity and overflow behavior are fixed at creation:
+
+- ``"suspend"`` (default): ``offer`` waits while the queue is full.
+  Capacity 0 is a rendezvous: an offer completes when a taker takes it.
+- ``"dropping"``: ``offer`` on a full queue drops the new item.
+- ``"sliding"``: ``offer`` on a full queue drops the oldest item. As in
+  Effect, ``sliding(0)`` keeps the newest offered item without waking a
+  parked taker (the next take gets it), while ``offer_all`` to it keeps
+  nothing.
+
+A queue can be finished. After ``fail(error)`` (or ``interrupt()``), new
+offers return ``False``, but takers still drain the items and the offers
+that were already waiting, and then fail with ``error``. A queue that should
+be endable declares it in its type, ``Queue[int, Done]``; only then do
+``end()`` and ``into(eff)`` type-check, takers fail with ``Done()`` once it
+drains, and ``collect`` / ``clear`` / ``await_done`` take ``Done`` out of the
+error type. ``shutdown()`` drops everything at once: items are cleared,
+waiting offers return ``False`` and takers are interrupted.
+
+``Enqueue`` and ``Dequeue`` are the write-only and read-only views of a
+queue, for passing it to code that only offers or only takes.
+
+The ``unsafe_*`` methods act at once, outside an effect; call them on the
+scheduler thread of the fibers that use the queue.
+"""
+
+from pyfect.errors import Done
+from pyfect.queue._queue import Queue, Strategy
+from pyfect.queue._views import Dequeue, Enqueue
+
+__all__ = ["Dequeue", "Done", "Enqueue", "Queue", "Strategy"]