pyfect-dev 0.1.0__py3-none-any.whl

pyfect/stream/_stream.py

@@ -0,0 +1,162 @@
+"""The ``Stream`` type and the functions between streams, channels and
+pulls.
+
+A ``Stream[A, E, R]`` is a ``Channel`` writing non-empty tuples of ``A``
+(Effect v4's ``Stream`` over ``Channel<NonEmptyReadonlyArray<A>>``).
+Nothing runs until a run function or ``to_pull`` builds the channel's
+pull. ``Stream``'s methods come in groups, one module each (see
+``pyfect.stream._base``).
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Never, overload
+
+from pyfect._effect_args import require_effect
+from pyfect.channel import Channel, from_transform, from_transform_bracket
+from pyfect.channel import from_pull as channel_from_pull
+from pyfect.channel._base import require_channel
+from pyfect.stream._base import A_co, E_co, R_co, StreamBase, StreamChannel, require_stream
+from pyfect.stream._bridge_methods import BridgeMethods
+from pyfect.stream._channel_methods import ChannelMethods
+from pyfect.stream._chunk_methods import ChunkMethods
+from pyfect.stream._error_methods import ErrorMethods
+from pyfect.stream._fanout_methods import FanOutMethods
+from pyfect.stream._filter_methods import FilterMethods
+from pyfect.stream._map_methods import MapMethods
+from pyfect.stream._run_methods import RunMethods
+from pyfect.stream._service_methods import ServiceMethods
+from pyfect.stream._sink_methods import SinkMethods
+from pyfect.stream._timing_methods import TimingMethods
+from pyfect.stream._zip_methods import ZipMethods
+
+if TYPE_CHECKING:
+    from pyfect._core import Effect
+    from pyfect.errors import Done
+    from pyfect.pull import Pull
+    from pyfect.scope import CloseableScope
+
+
+class Stream(
+    MapMethods[A_co, E_co, R_co],
+    FilterMethods[A_co, E_co, R_co],
+    ChunkMethods[A_co, E_co, R_co],
+    ZipMethods[A_co, E_co, R_co],
+    ErrorMethods[A_co, E_co, R_co],
+    TimingMethods[A_co, E_co, R_co],
+    ServiceMethods[A_co, E_co, R_co],
+    RunMethods[A_co, E_co, R_co],
+    SinkMethods[A_co, E_co, R_co],
+    FanOutMethods[A_co, E_co, R_co],
+    BridgeMethods[A_co, E_co, R_co],
+    ChannelMethods[A_co, E_co, R_co],
+):
+    """``Stream[A, E, R]``: writes items of type ``A`` in non-empty tuples
+    (chunks), then fails with ``E`` or ends; needs the services ``R``.
+
+    Build streams with the functions in ``pyfect.stream``; methods that
+    keep or add to the type parameters are here. Combinators that remove
+    something from a type (``scoped``, ``catch_tag``, ``catch_if``,
+    ``provide*``, ``update_context``) are
+    functions in ``pyfect.stream``, used with ``.pipe``.
+    """
+
+    __slots__ = ()
+
+
+def from_channel[A, E = Never, R = Never](
+    channel: Channel[tuple[A, ...], E, None, object, object, object, R],
+) -> Stream[A, E, R]:
+    """The stream of the items in the tuples ``channel`` writes. Each tuple
+    must be non-empty."""
+    require_channel(channel, "channel")
+    return Stream(channel)
+
+
+def to_channel[A, E, R](stream: StreamBase[A, E, R]) -> StreamChannel[A, E, R]:
+    """The channel a stream is made of: it writes the stream's chunks."""
+    require_stream(stream, "stream")
+    return stream._channel
+
+
+@overload
+def from_pull[A, EE = Never, RR = Never](
+    make: Effect[Effect[tuple[A, ...], Done, RR], EE, RR],
+) -> Stream[A, EE, RR]: ...
+@overload
+def from_pull[A, EE = Never, RR = Never](
+    make: Effect[Effect[tuple[A, ...], EE | Done, RR], EE, RR],
+) -> Stream[A, EE, RR]: ...
+def from_pull(make: Effect[Any, Any, Any]) -> Stream[Any, Any, Any]:
+    """A stream whose pull ``make`` builds each time it runs. The pull
+    succeeds with a non-empty tuple, fails, or ends with ``Done()``."""
+    require_effect(make, "make")
+    return Stream(channel_from_pull(make))
+
+
+@overload
+def transform_pull[A, E, B, EE = Never, RR = Never](
+    stream: StreamBase[A, E, RR],
+    f: Callable[
+        [Pull[tuple[A, ...], E], CloseableScope],
+        Effect[Effect[tuple[B, ...], Done, RR], EE, RR],
+    ],
+) -> Stream[B, EE, RR]: ...
+@overload
+def transform_pull[A, E, B, EE = Never, RR = Never](
+    stream: StreamBase[A, E, RR],
+    f: Callable[
+        [Pull[tuple[A, ...], E], CloseableScope],
+        Effect[Effect[tuple[B, ...], EE | Done, RR], EE, RR],
+    ],
+) -> Stream[B, EE, RR]: ...
+def transform_pull(
+    stream: StreamBase[Any, Any, Any],
+    f: Callable[[Any, CloseableScope], Effect[Any, Any, Any]],
+) -> Stream[Any, Any, Any]:
+    """A stream whose pull is ``f(pull, scope)`` of ``stream``'s pull. The
+    upstream pull is built in the new stream's scope."""
+    require_stream(stream, "stream")
+    channel = stream._channel
+
+    def transform(_upstream: Any, scope: CloseableScope) -> Effect[Any, Any, Any]:
+        return channel.to_pull_scoped(scope).flat_map(lambda pull: f(pull, scope))
+
+    built: Channel[Any, Any, Any, Any, Any, Any, Any] = from_transform(transform)
+    return Stream(built)
+
+
+@overload
+def transform_pull_bracket[A, E, B, EE = Never, RR = Never](
+    stream: StreamBase[A, E, RR],
+    f: Callable[
+        [Pull[tuple[A, ...], E, None, RR], CloseableScope, CloseableScope],
+        Effect[Effect[tuple[B, ...], Done, RR], EE, RR],
+    ],
+) -> Stream[B, EE, RR]: ...
+@overload
+def transform_pull_bracket[A, E, B, EE = Never, RR = Never](
+    stream: StreamBase[A, E, RR],
+    f: Callable[
+        [Pull[tuple[A, ...], E, None, RR], CloseableScope, CloseableScope],
+        Effect[Effect[tuple[B, ...], EE | Done, RR], EE, RR],
+    ],
+) -> Stream[B, EE, RR]: ...
+def transform_pull_bracket(
+    stream: StreamBase[Any, Any, Any],
+    f: Callable[[Any, CloseableScope, CloseableScope], Effect[Any, Any, Any]],
+) -> Stream[Any, Any, Any]:
+    """``transform_pull`` with a third argument: a child of the stream's
+    scope, closed as soon as the new stream fails or ends."""
+    require_stream(stream, "stream")
+    channel = stream._channel
+
+    def transform(
+        _upstream: Any, scope: CloseableScope, forked: CloseableScope
+    ) -> Effect[Any, Any, Any]:
+        return channel.to_pull_scoped(scope).flat_map(lambda pull: f(pull, scope, forked))
+
+    built: Channel[Any, Any, Any, Any, Any, Any, Any] = from_transform_bracket(transform)
+    return Stream(built)

pyfect/stream/_taking.py

@@ -0,0 +1,330 @@
+"""The work behind ``Stream``'s filtering, taking, dropping and ``changes``
+methods. Each keeps its state in the pull a run builds, so every run
+starts afresh."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Callable, Generator, Iterable
+from typing import Any
+
+from pyfect._core import Effect, _FlatMap, _Gen, _Succeed, _Suspend
+from pyfect.channel import transform_pull
+from pyfect.channel._base import end_with
+from pyfect.result import Ok, Result
+from pyfect.stream._base import AnyStream
+from pyfect.stream._mapping import map_array_effect, map_chunks
+from pyfect.stream._stream import Stream
+
+type AnyEffect = Effect[Any, Any, Any]
+type Chunk = tuple[Any, ...]
+type AnyStream_ = Stream[Any, Any, Any]
+
+_ENDED: AnyEffect = end_with(None)
+
+
+def count_of(n: int) -> int:
+    """Effect's ``Count.normalize`` for an ``int``: below zero is zero."""
+    return max(0, n)
+
+
+def _pulling(self: AnyStream, build: Callable[[AnyEffect], AnyEffect]) -> AnyStream_:
+    return Stream(transform_pull(self._channel, lambda pull, _: _Succeed(build(pull))))
+
+
+# --- filtering ----------------------------------------------------------------
+
+
+def _passed(results: Iterable[Result[Any, object]]) -> Chunk:
+    return tuple(r.value for r in results if isinstance(r, Ok))
+
+
+def filter_map(self: AnyStream, f: Callable[[Any], Result[Any, object]]) -> AnyStream_:
+    return map_chunks(self, lambda: lambda chunk: _passed(map(f, chunk)))
+
+
+def filter_map_effect(self: AnyStream, f: Callable[[Any], AnyEffect]) -> AnyStream_:
+    def each(chunk: Chunk) -> AnyEffect:
+        def body() -> Generator[AnyEffect, Any, Chunk]:
+            results: list[Any] = []
+            for item in chunk:
+                results.append((yield f(item)))  # noqa: PERF401 (no yield in comprehensions)
+            return _passed(results)
+
+        return _Gen(body)
+
+    return map_array_effect(self, each)
+
+
+# --- taking -------------------------------------------------------------------
+
+
+def take(self: AnyStream, n: int) -> AnyStream_:
+    from pyfect.stream._constructors import empty
+
+    count = count_of(n)
+    if count == 0:
+        return empty
+
+    def build(pull: AnyEffect) -> AnyEffect:
+        taken = 0
+
+        def cut(chunk: Chunk) -> AnyEffect:
+            nonlocal taken
+            kept = chunk[: count - taken]
+            taken += len(kept)
+            return _Succeed(kept)
+
+        return _Suspend(lambda: _ENDED if taken >= count else _FlatMap(pull, cut))
+
+    return _pulling(self, build)
+
+
+def take_right(self: AnyStream, n: int) -> AnyStream_:
+    from pyfect.stream._constructors import empty
+
+    count = count_of(n)
+    if count == 0:
+        return empty
+
+    def keep(last: deque[Any], chunk: Chunk) -> tuple[deque[Any], tuple[()]]:
+        last.extend(chunk)
+        return last, ()
+
+    def on_halt(last: deque[Any]) -> list[Chunk]:
+        return [tuple(last)] if last else []
+
+    return Stream(self._channel.map_accum(lambda: deque[Any](maxlen=count), keep, on_halt=on_halt))
+
+
+def take_until(self: AnyStream, predicate: Callable[[Any], bool], exclude_last: bool) -> AnyStream_:
+    def build(pull: AnyEffect) -> AnyEffect:
+        done = False
+
+        def cut(chunk: Chunk) -> AnyEffect:
+            nonlocal done
+            for index, item in enumerate(chunk):
+                if predicate(item):
+                    done = True
+                    kept = chunk[: index if exclude_last else index + 1]
+                    return _Succeed(kept) if kept else _ENDED
+            return _Succeed(chunk)
+
+        return _Suspend(lambda: _ENDED if done else _FlatMap(pull, cut))
+
+    return _pulling(self, build)
+
+
+def take_until_effect(
+    self: AnyStream, predicate: Callable[[Any], AnyEffect], exclude_last: bool
+) -> AnyStream_:
+    def build(pull: AnyEffect) -> AnyEffect:
+        done = False
+
+        def body() -> Generator[AnyEffect, Any, Chunk]:
+            nonlocal done
+            if done:
+                return (yield _ENDED)
+            chunk: Chunk = yield pull
+            for index, item in enumerate(chunk):
+                if (yield predicate(item)):
+                    done = True
+                    kept = chunk[: index if exclude_last else index + 1]
+                    return kept if kept else (yield _ENDED)
+            return chunk
+
+        return _Gen(body)
+
+    return _pulling(self, build)
+
+
+def take_while(self: AnyStream, predicate: Callable[[Any], bool]) -> AnyStream_:
+    def build(pull: AnyEffect) -> AnyEffect:
+        done = False
+
+        def cut(chunk: Chunk) -> AnyEffect:
+            nonlocal done
+            for index, item in enumerate(chunk):
+                if not predicate(item):
+                    done = True
+                    kept = chunk[:index]
+                    return _Succeed(kept) if kept else _ENDED
+            return _Succeed(chunk)
+
+        return _Suspend(lambda: _ENDED if done else _FlatMap(pull, cut))
+
+    return _pulling(self, build)
+
+
+def take_while_filter(self: AnyStream, f: Callable[[Any], Result[Any, object]]) -> AnyStream_:
+    def build(pull: AnyEffect) -> AnyEffect:
+        done = False
+
+        def cut(chunk: Chunk) -> AnyEffect:
+            nonlocal done
+            out: list[Any] = []
+            for item in chunk:
+                result = f(item)
+                if not isinstance(result, Ok):
+                    done = True
+                    return _Succeed(tuple(out)) if out else _ENDED
+                out.append(result.value)
+            return _Succeed(tuple(out))
+
+        return _Suspend(lambda: _ENDED if done else _FlatMap(pull, cut))
+
+    return _pulling(self, build)
+
+
+def limit_bytes(
+    self: AnyStream, limit: int, on_limit_reached: Callable[[], AnyStream]
+) -> AnyStream_:
+    from pyfect.stream._concat import concat
+    from pyfect.stream._constructors import empty, suspend
+
+    def make() -> AnyStream_:
+        size = 0
+        reached = False
+
+        def within(chunk: bytes) -> bool:
+            nonlocal size, reached
+            if size + len(chunk) > limit:
+                reached = True
+                return False
+            size += len(chunk)
+            return True
+
+        return concat(
+            take_while(self, within), suspend(lambda: on_limit_reached() if reached else empty)
+        )
+
+    return suspend(make)
+
+
+# --- dropping -----------------------------------------------------------------
+
+
+def drop(self: AnyStream, n: int) -> AnyStream_:
+    count = count_of(n)
+    if count == 0:
+        return Stream(self._channel)
+
+    def build(pull: AnyEffect) -> AnyEffect:
+        dropped = 0
+
+        def skip(chunk: Chunk) -> AnyEffect:
+            nonlocal dropped
+            if dropped >= count:
+                return _Succeed(chunk)
+            before = dropped
+            dropped += len(chunk)
+            if dropped <= count:
+                return pump
+            return _Succeed(chunk[count - before :])
+
+        pump = _FlatMap(pull, skip)
+        return pump
+
+    return _pulling(self, build)
+
+
+def drop_right(self: AnyStream, n: int) -> AnyStream_:
+    count = count_of(n)
+    if count == 0:
+        return Stream(self._channel)
+
+    def build(pull: AnyEffect) -> AnyEffect:
+        held: deque[Any] = deque()
+
+        def emit(chunk: Chunk) -> AnyEffect:
+            held.extend(chunk)
+            ready = len(held) - count
+            if ready <= 0:
+                return pump
+            return _Succeed(tuple(held.popleft() for _ in range(ready)))
+
+        pump = _FlatMap(pull, emit)
+        return pump
+
+    return _pulling(self, build)
+
+
+def drop_while(self: AnyStream, predicate: Callable[[Any], bool]) -> AnyStream_:
+    def build(pull: AnyEffect) -> AnyEffect:
+        dropping = True
+
+        def skip(chunk: Chunk) -> AnyEffect:
+            nonlocal dropping
+            for index, item in enumerate(chunk):
+                if not predicate(item):
+                    dropping = False
+                    return _Succeed(chunk[index:])
+            return filtered
+
+        filtered = _FlatMap(pull, skip)
+        return _Suspend(lambda: filtered if dropping else pull)
+
+    return _pulling(self, build)
+
+
+def drop_while_effect(self: AnyStream, predicate: Callable[[Any], AnyEffect]) -> AnyStream_:
+    def build(pull: AnyEffect) -> AnyEffect:
+        dropping = True
+
+        def body() -> Generator[AnyEffect, Any, Chunk]:
+            nonlocal dropping
+            while True:
+                chunk: Chunk = yield pull
+                for index, item in enumerate(chunk):
+                    if (yield predicate(item)):
+                        continue
+                    dropping = False
+                    return chunk[index:]
+
+        filtered = _Gen(body)
+        return _Suspend(lambda: filtered if dropping else pull)
+
+    return _pulling(self, build)
+
+
+# --- repeats ------------------------------------------------------------------
+
+
+def changes_with(self: AnyStream, f: Callable[[Any, Any], bool]) -> AnyStream_:
+    def make() -> Callable[[Chunk], Chunk]:
+        last: list[Any] = []
+
+        def keep(chunk: Chunk) -> Chunk:
+            out: list[Any] = []
+            for item in chunk:
+                if last and f(item, last[0]):
+                    continue
+                last[:] = [item]
+                out.append(item)
+            return tuple(out)
+
+        return keep
+
+    return map_chunks(self, make)
+
+
+def changes_with_effect(self: AnyStream, f: Callable[[Any, Any], AnyEffect]) -> AnyStream_:
+    def build(pull: AnyEffect) -> AnyEffect:
+        last: list[Any] = []
+
+        def body() -> Generator[AnyEffect, Any, Chunk]:
+            while True:
+                chunk: Chunk = yield pull
+                out: list[Any] = []
+                for item in chunk:
+                    if last and (yield f(item, last[0])):
+                        continue
+                    last[:] = [item]
+                    out.append(item)
+                if out:
+                    return tuple(out)
+
+        return _Gen(body)
+
+    return _pulling(self, build)

pyfect/stream/_text.py

@@ -0,0 +1,43 @@
+"""The work behind ``Stream``'s channel and text methods: each pipes the
+stream's channel through another channel."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from typing import Any
+
+from pyfect.channel import Channel
+from pyfect.channel import decode_text as channel_decode_text
+from pyfect.channel import encode_text as channel_encode_text
+from pyfect.channel import split_lines as channel_split_lines
+from pyfect.channel._base import require_channel
+from pyfect.stream._base import AnyStream
+from pyfect.stream._stream import Stream
+
+type AnyChannel = Channel[Any, Any, Any, Any, Any, Any, Any]
+type AnyStream_ = Stream[Any, Any, Any]
+
+
+def pipe_through_channel(self: AnyStream, channel: AnyChannel) -> AnyStream_:
+    require_channel(channel, "channel")
+    return Stream(self._channel.pipe_to(channel))
+
+
+def pipe_through_channel_or_fail(self: AnyStream, channel: AnyChannel) -> AnyStream_:
+    require_channel(channel, "channel")
+    return Stream(self._channel.pipe_to_or_fail(channel))
+
+
+def decode_text(self: AnyStream, encoding: str) -> AnyStream_:
+    decoder: AnyChannel = channel_decode_text(encoding)
+    return Stream(self._channel.pipe_to(decoder))
+
+
+def encode_text(self: AnyStream) -> AnyStream_:
+    encoder: AnyChannel = channel_encode_text()
+    return Stream(self._channel.pipe_to(encoder))
+
+
+def split_lines(self: AnyStream) -> AnyStream_:
+    splitter: AnyChannel = channel_split_lines()
+    return Stream(self._channel.pipe_to(splitter))