pyfect-dev 0.1.0__py3-none-any.whl

pyfect/sink/_sink.py

@@ -0,0 +1,265 @@
+"""The ``Sink`` type, its ``End`` and its methods.
+
+A sink is a function from an upstream pull of non-empty tuples (and a
+``CloseableScope``) to an effect that consumes some of that input and
+succeeds with an ``End``: the sink's value and the input it read but did
+not use (Effect v4's ``Sink.transform``). The upstream fails only with
+``Done()``; a stream's own failures reach a sink as hidden defects, so no
+sink error handler sees them (``Stream.run``).
+
+The methods give their work to ``pyfect.sink._combinators``, imported when
+called (it builds ``Sink`` values, so it loads after this module).
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Generic, Never, Self, TypeVar, overload
+
+from pyfect._core import Effect, _Suspend
+from pyfect._effect_args import wrong_argument
+from pyfect.errors import Done
+
+if TYPE_CHECKING:
+    from pyfect.cause import Cause
+    from pyfect.exit import Exit
+    from pyfect.scope import CloseableScope
+
+A_co = TypeVar("A_co", covariant=True)
+In_contra = TypeVar("In_contra", contravariant=True, default=object)
+L_co = TypeVar("L_co", covariant=True, default=Never)
+E_co = TypeVar("E_co", covariant=True, default=Never)
+R_co = TypeVar("R_co", covariant=True, default=Never)
+
+type End[A, L = Never] = tuple[A, tuple[L, ...] | None]
+"""What a sink ends with: its value, and the input it read but did not
+use (a non-empty tuple, or ``None``). Effect's ``Sink.End``."""
+
+type Upstream[In] = Effect[tuple[In, ...], Done]
+"""What a sink reads: a pull of non-empty tuples that ends with
+``Done()``."""
+
+type Transform[A, In, L, E, R] = Callable[[Upstream[In], CloseableScope], Effect[End[A, L], E, R]]
+"""What a sink is made of (see ``sink.from_transform``)."""
+
+
+class Sink(Generic[A_co, In_contra, L_co, E_co, R_co]):
+    """``Sink[A, In, L, E, R]``: reads ``In`` items until it has what it
+    needs, then succeeds with ``A`` and leaves over the ``L`` items it read
+    but did not use; or fails with ``E``. Needs the services ``R``.
+
+    Build sinks with the functions in ``pyfect.sink`` and run them with
+    ``Stream.run``. Methods keep or add to the type parameters; the
+    combinators that remove services (``provide_service``,
+    ``provide_context``) are functions in ``pyfect.sink``, used with
+    ``.pipe``.
+    """
+
+    __slots__ = ("_build",)
+
+    def __init__(self, transform: Transform[A_co, In_contra, L_co, E_co, R_co]) -> None:
+        self._build: Transform[Any, Any, Any, Any, Any] = transform
+
+    def _transform(self, upstream: Upstream[Any], scope: CloseableScope) -> Effect[End[Any, Any]]:
+        """The effect consuming ``upstream``. Built when it runs, so a
+        raising transform is a defect of the run."""
+        build = self._build
+        return _Suspend(lambda: build(upstream, scope))
+
+    def pipe[B](self, f: Callable[[Self], B], /) -> B:
+        """Apply ``f`` to this sink (one step; see ``Effect.pipe``)."""
+        return f(self)
+
+    # --- the value ---------------------------------------------------------
+
+    def map[B](self, f: Callable[[A_co], B]) -> Sink[B, In_contra, L_co, E_co, R_co]:
+        """The sink with its value replaced by ``f(value)``."""
+        from pyfect.sink import _combinators
+
+        return _combinators.map_end(self, lambda end: (f(end[0]), end[1]))
+
+    def as_[B](self, value: B) -> Sink[B, In_contra, L_co, E_co, R_co]:
+        """The sink with its value replaced by ``value``."""
+        from pyfect.sink import _combinators
+
+        return _combinators.map_end(self, lambda end: (value, end[1]))
+
+    def map_effect[B, E2 = Never, R2 = Never](
+        self, f: Callable[[A_co], Effect[B, E2, R2]]
+    ) -> Sink[B, In_contra, L_co, E_co | E2, R_co | R2]:
+        """The sink with its value replaced by what ``f(value)`` succeeds
+        with."""
+        from pyfect.sink import _combinators
+
+        return _combinators.map_effect_end(self, lambda end: f(end[0]).map(lambda b: (b, end[1])))
+
+    def map_end[B, L2 = Never](
+        self, f: Callable[[End[A_co, L_co]], End[B, L2]]
+    ) -> Sink[B, In_contra, L2, E_co, R_co]:
+        """The sink with its whole ``End`` (value and leftovers) replaced by
+        ``f(end)``."""
+        from pyfect.sink import _combinators
+
+        return _combinators.map_end(self, f)
+
+    def map_effect_end[B, L2 = Never, E2 = Never, R2 = Never](
+        self, f: Callable[[End[A_co, L_co]], Effect[End[B, L2], E2, R2]]
+    ) -> Sink[B, In_contra, L2, E_co | E2, R_co | R2]:
+        """``map_end`` with an effectful ``f``."""
+        from pyfect.sink import _combinators
+
+        return _combinators.map_effect_end(self, f)
+
+    def summarized[S, B, E2 = Never, R2 = Never](
+        self, summary: Effect[S, E2, R2], f: Callable[[S, S], B]
+    ) -> Sink[tuple[A_co, B], In_contra, L_co, E_co | E2, R_co | R2]:
+        """Run ``summary`` before and after the sink and pair its value with
+        ``f(before, after)``."""
+        from pyfect._effect_args import require_effect
+        from pyfect.sink import _combinators
+
+        require_effect(summary, "summary")
+        return _combinators.summarized(self, summary, f)
+
+    def with_duration(self) -> Sink[tuple[A_co, float], In_contra, L_co, E_co, R_co]:
+        """Pair the value with how long the sink ran, in seconds, measured in
+        whole monotonic nanoseconds."""
+        from pyfect.sink import _combinators
+
+        return _combinators.with_duration(self)
+
+    # --- the input and the leftovers ---------------------------------------
+
+    def map_input[In0](self, f: Callable[[In0], In_contra]) -> Sink[A_co, In0, L_co, E_co, R_co]:
+        """A sink reading ``In0`` items, each given to this sink as
+        ``f(item)``."""
+        from pyfect.sink import _combinators
+
+        return _combinators.map_input_array(self, lambda chunk: tuple(map(f, chunk)))
+
+    def map_input_effect[In0, E2 = Never, R2 = Never](
+        self, f: Callable[[In0], Effect[In_contra, E2, R2]]
+    ) -> Sink[A_co, In0, L_co, E_co | E2, R_co | R2]:
+        """``map_input`` with an effectful ``f``, run on each item in
+        order."""
+        from pyfect.sink import _combinators
+
+        return _combinators.map_input_effect(self, f)
+
+    def map_input_array[In0](
+        self, f: Callable[[tuple[In0, ...]], tuple[In_contra, ...]]
+    ) -> Sink[A_co, In0, L_co, E_co, R_co]:
+        """A sink reading ``In0`` chunks, each given to this sink as
+        ``f(chunk)``, which must be non-empty."""
+        from pyfect.sink import _combinators
+
+        return _combinators.map_input_array(self, f)
+
+    def map_input_array_effect[In0, E2 = Never, R2 = Never](
+        self, f: Callable[[tuple[In0, ...]], Effect[tuple[In_contra, ...], E2, R2]]
+    ) -> Sink[A_co, In0, L_co, E_co | E2, R_co | R2]:
+        """``map_input_array`` with an effectful ``f``."""
+        from pyfect.sink import _combinators
+
+        return _combinators.map_input_array_effect(self, f)
+
+    def map_leftover[L2](self, f: Callable[[L_co], L2]) -> Sink[A_co, In_contra, L2, E_co, R_co]:
+        """The sink with each leftover item replaced by ``f(item)``."""
+        from pyfect.sink import _combinators
+
+        return _combinators.map_end(
+            self, lambda end: (end[0], None if end[1] is None else tuple(map(f, end[1])))
+        )
+
+    def ignore_leftover(self) -> Sink[A_co, In_contra, Never, E_co, R_co]:
+        """The sink without its leftovers: what it read but did not use is
+        dropped."""
+        from pyfect.sink import _combinators
+
+        return _combinators.map_end(self, lambda end: (end[0], None))
+
+    # A sink without leftovers has none to feed on; the overload keeps
+    # pyright from reading the input type off ``L = Never``.
+    @overload
+    def flat_map[I, B, L2 = Never, E2 = Never, R2 = Never](
+        self: Sink[A_co, I, Never, E_co, R_co], f: Callable[[A_co], Sink[B, I, L2, E2, R2]]
+    ) -> Sink[B, I, L2, E_co | E2, R_co | R2]: ...
+    @overload
+    def flat_map[I, B, L2 = Never, E2 = Never, R2 = Never](
+        self: Sink[A_co, I, I, E_co, R_co], f: Callable[[A_co], Sink[B, I, L2, E2, R2]]
+    ) -> Sink[B, I, I | L2, E_co | E2, R_co | R2]: ...
+    def flat_map(
+        self, f: Callable[[A_co], Sink[Any, Any, Any, Any, Any]]
+    ) -> Sink[Any, Any, Any, Any, Any]:
+        """Run this sink, then ``f(value)`` on the rest of the input, its
+        leftovers first. Leftovers the second sink does not read stay
+        leftovers."""
+        from pyfect.sink import _combinators
+
+        return _combinators.flat_map(self, f)
+
+    # --- failures ----------------------------------------------------------
+
+    def map_error[E2](self, f: Callable[[E_co], E2]) -> Sink[A_co, In_contra, L_co, E2, R_co]:
+        """The sink with its typed error replaced by ``f(error)``."""
+        from pyfect.sink import _combinators
+
+        return _combinators.transform_effect(self, lambda eff: eff.map_error(f))
+
+    def catch_all[B, E2 = Never, R2 = Never](
+        self, f: Callable[[E_co], Effect[B, E2, R2]]
+    ) -> Sink[A_co | B, In_contra, L_co, E2, R_co | R2]:
+        """Recover from a typed failure with the value of ``f(error)``
+        (Effect's ``Sink.catch``). The stream's own failures pass by."""
+        from pyfect.sink import _combinators
+
+        return _combinators.catch_all(self, f)
+
+    def catch_cause[B, E2 = Never, R2 = Never](
+        self, f: Callable[[Cause[E_co]], Effect[B, E2, R2]]
+    ) -> Sink[A_co | B, In_contra, L_co, E2, R_co | R2]:
+        """Recover from any failure of the sink with the value of
+        ``f(cause)``. The stream's own failures pass by."""
+        from pyfect.sink import _combinators
+
+        return _combinators.catch_cause(self, f)
+
+    def or_else[I, B, L2 = Never, E2 = Never, R2 = Never](
+        self: Sink[A_co, I, L_co, E_co, R_co], f: Callable[[E_co], Sink[B, I, L2, E2, R2]]
+    ) -> Sink[A_co | B, I, L_co | L2, E2, R_co | R2]:
+        """After a typed failure, go on with ``f(error)`` on the rest of
+        the input. The stream's own failures pass by."""
+        from pyfect.sink import _combinators
+
+        return _combinators.or_else(self, f)
+
+    # --- finalizers --------------------------------------------------------
+
+    def on_exit[R2 = Never](
+        self, f: Callable[[Exit[A_co, E_co]], Effect[object, Never, R2]]
+    ) -> Sink[A_co, In_contra, L_co, E_co, R_co | R2]:
+        """Run ``f(exit)`` when the sink ends. A stream failure stops the
+        sink as an interruption would, so ``f`` sees an interrupt."""
+        from pyfect.sink import _combinators
+
+        return _combinators.on_exit(self, f)
+
+    def ensuring[R2 = Never](
+        self, finalizer: Effect[object, Never, R2]
+    ) -> Sink[A_co, In_contra, L_co, E_co, R_co | R2]:
+        """Run ``finalizer`` however the sink ends."""
+        from pyfect._effect_args import require_effect
+        from pyfect.sink import _combinators
+
+        require_effect(finalizer, "finalizer")
+        return _combinators.on_exit(self, lambda _: finalizer)
+
+
+type AnySink = Sink[Any, Any, Any, Any, Any]
+
+
+def require_sink(value: object, name: str) -> None:
+    """Raise ``TypeError`` naming ``name`` unless ``value`` is a ``Sink``."""
+    if not isinstance(value, Sink):
+        raise TypeError(wrong_argument(value, name, "a Sink", "build one with pyfect.sink"))

pyfect/sink/_steps.py

@@ -0,0 +1,34 @@
+"""What the sinks' read loops share: the effects a step returns to go on
+or to stop reading, and ending a loop with the sink's ``End``."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from pyfect._core import Effect, _Succeed, _Sync
+from pyfect.channel._base import end_with
+from pyfect.channel._loop import PullLoop
+from pyfect.pull import catch_done
+from pyfect.sink._sink import End
+
+type AnyEffect = Effect[Any, Any, Any]
+
+VOID: Effect[None] = _Succeed(None)
+"""A step's way to read on."""
+
+ENDED: Effect[Any, Any] = end_with(None)
+"""A step's way to stop reading; also an upstream that has ended."""
+
+
+def ignore(_: object) -> None:
+    return None
+
+
+def read_until_done(
+    step: AnyEffect, end: Callable[[], End[Any, Any]]
+) -> Effect[End[Any, Any], Any, Any]:
+    """Run ``step`` (a pull and what is done with each chunk) until it ends
+    with ``Done``, then succeed with ``end()``."""
+    return catch_done(PullLoop(step, ignore), lambda _: _Sync(end))

pyfect/sink/_taking.py

@@ -0,0 +1,183 @@
+"""Sinks that take items: ``take``, the ``take_while`` family and the
+``take_until`` family.
+
+``take_while`` reads the first item that fails its predicate and drops
+it, as Effect's does; ``take_until`` keeps the item that matches. What
+follows in the same chunk is left over.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Generator
+from typing import Any, Never, TypeIs, overload
+
+from pyfect._core import Effect, _Gen, _Succeed
+from pyfect.result import Err, Ok, Result
+from pyfect.scope import CloseableScope
+from pyfect.sink._sink import Sink, Upstream
+from pyfect.sink._steps import ENDED, VOID, read_until_done
+
+type AnyEffect = Effect[Any, Any, Any]
+type Chunk = tuple[Any, ...]
+
+
+_REJECTED: Result[Never, None] = Err(None)
+"""What a predicate that fails gives the shared ``take_while`` loop."""
+
+
+def _rest(chunk: Chunk, start: int) -> Chunk | None:
+    return chunk[start:] or None
+
+
+def take[In](n: int) -> Sink[list[In], In, In]:
+    """A sink taking the first ``n`` items (none for ``n`` 0 or less); the
+    rest of the chunk that reaches ``n`` is left over."""
+    count = max(n, 0)
+
+    def transform(upstream: Upstream[In], _scope: CloseableScope) -> AnyEffect:
+        taken: list[In] = []
+        if count == 0:
+            return _Succeed((taken, None))
+        leftover: Chunk | None = None
+
+        def step(chunk: tuple[In, ...]) -> AnyEffect:
+            nonlocal leftover
+            room = count - len(taken)
+            if len(chunk) < room:
+                taken.extend(chunk)
+                return VOID
+            taken.extend(chunk[:room])
+            leftover = _rest(chunk, room)
+            return ENDED
+
+        return read_until_done(upstream.flat_map(step), lambda: (taken, leftover))
+
+    return Sink(transform)
+
+
+def _taking_while[In](
+    keep: Callable[[In], Result[Any, object]],
+) -> Sink[list[Any], In, In]:
+    def transform(upstream: Upstream[In], _scope: CloseableScope) -> AnyEffect:
+        taken: list[Any] = []
+        leftover: Chunk | None = None
+
+        def step(chunk: tuple[In, ...]) -> AnyEffect:
+            nonlocal leftover
+            for i, item in enumerate(chunk):
+                kept = keep(item)
+                if not isinstance(kept, Ok):
+                    leftover = _rest(chunk, i + 1)
+                    return ENDED
+                taken.append(kept.value)
+            return VOID
+
+        return read_until_done(upstream.flat_map(step), lambda: (taken, leftover))
+
+    return Sink(transform)
+
+
+@overload
+def take_while[In, B](predicate: Callable[[In], TypeIs[B]]) -> Sink[list[B], In, In]: ...
+@overload
+def take_while[In](predicate: Callable[[In], bool]) -> Sink[list[In], In, In]: ...
+def take_while(predicate: Callable[[Any], bool]) -> Sink[list[Any], Any, Any]:
+    """A sink taking items while ``predicate`` holds."""
+    return _taking_while(lambda item: Ok(item) if predicate(item) else _REJECTED)
+
+
+def take_while_filter[In, B](f: Callable[[In], Result[B, object]]) -> Sink[list[B], In, In]:
+    """A sink taking the ``Ok`` values of ``f(item)`` until it gives an
+    ``Err``."""
+    return _taking_while(f)
+
+
+def _taking_while_effect[In](
+    keep: Callable[[In], Effect[Result[Any, object], Any, Any]],
+) -> Sink[list[Any], In, In, Any, Any]:
+    def transform(upstream: Upstream[In], _scope: CloseableScope) -> AnyEffect:
+        taken: list[Any] = []
+        leftover: Chunk | None = None
+
+        def step(chunk: tuple[In, ...]) -> AnyEffect:
+            def body() -> Generator[AnyEffect, Any, AnyEffect]:
+                nonlocal leftover
+                for i, item in enumerate(chunk):
+                    kept: Result[Any, object] = yield keep(item)
+                    if not isinstance(kept, Ok):
+                        leftover = _rest(chunk, i + 1)
+                        return ENDED
+                    taken.append(kept.value)
+                return VOID
+
+            return _Gen(body).flatten()
+
+        return read_until_done(upstream.flat_map(step), lambda: (taken, leftover))
+
+    return Sink(transform)
+
+
+def take_while_effect[In, E = Never, R = Never](
+    predicate: Callable[[In], Effect[bool, E, R]],
+) -> Sink[list[In], In, In, E, R]:
+    """``take_while`` with an effectful ``predicate``."""
+    return _taking_while_effect(
+        lambda item: predicate(item).map(lambda ok: Ok(item) if ok else _REJECTED)
+    )
+
+
+def take_while_filter_effect[In, B, E = Never, R = Never](
+    f: Callable[[In], Effect[Result[B, object], E, R]],
+) -> Sink[list[B], In, In, E, R]:
+    """``take_while_filter`` with an effectful ``f``."""
+    return _taking_while_effect(f)
+
+
+def take_until[In](predicate: Callable[[In], bool]) -> Sink[list[In], In, In]:
+    """A sink taking items up to and including the first one
+    ``predicate`` holds for."""
+
+    def transform(upstream: Upstream[In], _scope: CloseableScope) -> AnyEffect:
+        taken: list[In] = []
+        leftover: Chunk | None = None
+
+        def step(chunk: tuple[In, ...]) -> AnyEffect:
+            nonlocal leftover
+            for i, item in enumerate(chunk):
+                taken.append(item)
+                if predicate(item):
+                    leftover = _rest(chunk, i + 1)
+                    return ENDED
+            return VOID
+
+        return read_until_done(upstream.flat_map(step), lambda: (taken, leftover))
+
+    return Sink(transform)
+
+
+def take_until_effect[In, E = Never, R = Never](
+    predicate: Callable[[In], Effect[bool, E, R]],
+) -> Sink[list[In], In, In, E, R]:
+    """``take_until`` with an effectful ``predicate``."""
+
+    def transform(upstream: Upstream[In], _scope: CloseableScope) -> AnyEffect:
+        taken: list[In] = []
+        leftover: Chunk | None = None
+
+        def step(chunk: tuple[In, ...]) -> AnyEffect:
+            def body() -> Generator[AnyEffect, Any, AnyEffect]:
+                nonlocal leftover
+                for i, item in enumerate(chunk):
+                    matched = yield predicate(item)
+                    taken.append(item)
+                    if matched:
+                        leftover = _rest(chunk, i + 1)
+                        return ENDED
+                return VOID
+
+            return _Gen(body).flatten()
+
+        return read_until_done(upstream.flat_map(step), lambda: (taken, leftover))
+
+    return Sink(transform)

pyfect/socket/__init__.py

@@ -0,0 +1,146 @@
+"""Sockets (Effect's ``Socket`` and ``NodeSocket``).
+
+A ``SocketService`` has a ``reader`` and a ``writer``, both acquired in a
+scope. Acquiring the reader opens the connection (closed with the scope);
+its ``pull`` waits for the next batch of chunks and fails with a
+``SocketError`` once the socket closes (a ``SocketCloseError`` with code
+1000 when the peer ended the stream). The writer writes to the open
+connection; writing a ``CloseEvent`` closes it::
+
+    socket = make_net(8080, "127.0.0.1")
+
+    def talk():
+        writer = yield socket.writer
+        reader = yield socket.reader
+        yield writer.write_all([b"ping"])
+        return (yield reader.pull)
+
+    reply = yield from scoped(gen(talk))
+
+``to_channel`` and ``to_stream`` turn a socket into a channel (input
+written, output read) or a stream. The live sockets run on an asyncio loop
+of their own, on a background thread, so they work under ``run_blocking`` too.
+``pyfect.socket.server`` listens for connections and
+``pyfect.socket.datagram`` sends and receives UDP packets. ``from_web_socket``
+adapts a browser-style WebSocket and ``make_web_socket`` opens a client
+through the ``WebSocketConstructor`` service, which ``pyfect.socket.ws``
+provides on the ``websockets`` library (extra ``pyfect-dev[websockets]``).
+"""
+
+from pyfect._public import publish
+from pyfect.socket import datagram, server
+from pyfect.socket._errors import (
+    CloseEvent,
+    OpenErrorKind,
+    SocketCloseError,
+    SocketError,
+    SocketErrorReason,
+    SocketOpenError,
+    SocketReadError,
+    SocketUpgradeError,
+    SocketWriteError,
+    is_clean_close,
+)
+from pyfect.socket._net import (
+    from_socket,
+    layer_net,
+    layer_tls,
+    make_net,
+    make_net_channel,
+    make_tls,
+    make_tls_channel,
+    make_unix,
+)
+from pyfect.socket._socket import (
+    Chunk,
+    PemInput,
+    Reader,
+    Socket,
+    SocketChannel,
+    SocketService,
+    TlsUpgradeOptions,
+    Upgrade,
+    Write,
+    WriteAll,
+    Writer,
+    make,
+    make_channel,
+    reader_bytes,
+    reader_string,
+    to_channel,
+    to_channel_string,
+    to_stream,
+    unsupported_upgrade,
+)
+from pyfect.socket._web_socket import (
+    Listener,
+    Pausable,
+    WebSocket,
+    WebSocketClientOptions,
+    WebSocketConstructor,
+    WebSocketConstructorService,
+    WebSocketEvent,
+    WebSocketEventType,
+    WebSocketLike,
+    from_web_socket,
+    layer_web_socket,
+    make_web_socket,
+    make_web_socket_channel,
+)
+
+__all__ = [
+    "Chunk",
+    "CloseEvent",
+    "Listener",
+    "OpenErrorKind",
+    "Pausable",
+    "PemInput",
+    "Reader",
+    "Socket",
+    "SocketChannel",
+    "SocketCloseError",
+    "SocketError",
+    "SocketErrorReason",
+    "SocketOpenError",
+    "SocketReadError",
+    "SocketService",
+    "SocketUpgradeError",
+    "SocketWriteError",
+    "TlsUpgradeOptions",
+    "Upgrade",
+    "WebSocket",
+    "WebSocketClientOptions",
+    "WebSocketConstructor",
+    "WebSocketConstructorService",
+    "WebSocketEvent",
+    "WebSocketEventType",
+    "WebSocketLike",
+    "Write",
+    "WriteAll",
+    "Writer",
+    "datagram",
+    "from_socket",
+    "from_web_socket",
+    "is_clean_close",
+    "layer_net",
+    "layer_tls",
+    "layer_web_socket",
+    "make",
+    "make_channel",
+    "make_net",
+    "make_net_channel",
+    "make_tls",
+    "make_tls_channel",
+    "make_unix",
+    "make_web_socket",
+    "make_web_socket_channel",
+    "reader_bytes",
+    "reader_string",
+    "server",
+    "to_channel",
+    "to_channel_string",
+    "to_stream",
+    "unsupported_upgrade",
+]
+
+publish(globals())

pyfect/socket/_accepted.py

@@ -0,0 +1,65 @@
+"""Connections a server accepted that no ``run`` has taken yet."""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from typing import Never, Protocol
+
+from pyfect._core import Effect
+from pyfect.socket._connection import Signal
+from pyfect.socket._socket import SocketService
+
+type Handler[E, R] = Callable[[SocketService], Effect[object, E, R]]
+
+
+class Incoming(Protocol):
+    """An accepted connection: ``handle`` runs the handler on its socket;
+    ``release`` closes it once the handler's fiber is done (gracefully);
+    ``abort`` closes it at once."""
+
+    def handle[E, R](self, handler: Handler[E, R]) -> Effect[None, Never, R]: ...
+
+    def release(self) -> None: ...
+
+    def abort(self) -> None: ...
+
+
+class Accepted:
+    """Connections the server accepted that no run has taken yet. Once
+    closed (with the server), a connection made late is aborted."""
+
+    __slots__ = ("_closed", "_pending", "lock", "signal")
+
+    def __init__(self) -> None:
+        self.lock = threading.Lock()
+        self.signal = Signal(self.lock)
+        self._pending: list[Incoming] = []
+        self._closed = False
+
+    def add(self, incoming: Incoming) -> None:
+        with self.lock:
+            closed = self._closed
+            if not closed:
+                self._pending.append(incoming)
+            waiters = self.signal.notify_locked()
+        if closed:
+            incoming.abort()
+        for wake in waiters:
+            wake()
+
+    def has_pending(self) -> bool:
+        return bool(self._pending)
+
+    def take(self) -> list[Incoming]:
+        with self.lock:
+            taken, self._pending = self._pending, []
+        return taken
+
+    def close(self) -> None:
+        """Abort the pending connections and every later one."""
+        with self.lock:
+            self._closed = True
+            taken, self._pending = self._pending, []
+        for incoming in taken:
+            incoming.abort()