pyfect-dev 0.1.0__py3-none-any.whl

pyfect/stream/_map_methods.py

@@ -0,0 +1,233 @@
+"""``Stream`` methods that map items, flat-map them into streams, tap
+them, and put streams one after another."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import TYPE_CHECKING, Never
+
+from pyfect.stream._base import A_co, E_co, R_co, StreamBase, as_stream, require_stream
+
+if TYPE_CHECKING:
+    from pyfect._concurrency import Concurrency
+    from pyfect._core import Effect
+    from pyfect.result import Result
+    from pyfect.stream._stream import Stream
+    from pyfect.take import Take
+
+
+class MapMethods(StreamBase[A_co, E_co, R_co]):
+    __slots__ = ()
+
+    # --- mapping ------------------------------------------------------------
+
+    def map[B](self, f: Callable[[A_co], B]) -> Stream[B, E_co, R_co]:
+        """Apply ``f`` to each item."""
+        from pyfect.stream import _mapping
+
+        return _mapping.map_(self, f)
+
+    def as_[B](self, value: B) -> Stream[B, E_co, R_co]:
+        """Replace each item with ``value``."""
+        from pyfect.stream import _mapping
+
+        return _mapping.map_array(self, lambda chunk: (value,) * len(chunk))
+
+    def map_both[B, E2](
+        self, *, on_element: Callable[[A_co], B], on_error: Callable[[E_co], E2]
+    ) -> Stream[B, E2, R_co]:
+        """Apply ``on_element`` to each item and ``on_error`` to the error."""
+        return self.map(on_element).map_error(on_error)
+
+    def map_array[B](self, f: Callable[[tuple[A_co, ...]], tuple[B, ...]]) -> Stream[B, E_co, R_co]:
+        """Apply ``f`` to each chunk (a non-empty tuple); an empty result
+        writes nothing."""
+        from pyfect.stream import _mapping
+
+        return _mapping.map_array(self, f)
+
+    def map_effect[B, E2 = Never, R2 = Never](
+        self,
+        f: Callable[[A_co], Effect[B, E2, R2]],
+        *,
+        concurrency: Concurrency = None,
+        unordered: bool = False,
+    ) -> Stream[B, E_co | E2, R_co | R2]:
+        """Write what ``f(item)`` succeeds with, one item per chunk. With
+        ``concurrency`` above 1, up to that many run at once; their results
+        keep upstream's order unless ``unordered``."""
+        from pyfect.stream import _mapping
+
+        return _mapping.map_effect(self, f, concurrency, unordered)
+
+    def map_array_effect[B, E2 = Never, R2 = Never](
+        self, f: Callable[[tuple[A_co, ...]], Effect[tuple[B, ...], E2, R2]]
+    ) -> Stream[B, E_co | E2, R_co | R2]:
+        """Write the chunk ``f(chunk)`` succeeds with, for each chunk."""
+        from pyfect.stream import _mapping
+
+        return _mapping.map_array_effect(self, f)
+
+    def flatten_effect[B, E2 = Never, R2 = Never](
+        self: MapMethods[Effect[B, E2, R2], E_co, R_co],
+        *,
+        concurrency: Concurrency = None,
+        unordered: bool = False,
+    ) -> Stream[B, E_co | E2, R_co | R2]:
+        """Run each effect the stream writes and write its value."""
+        from pyfect.stream import _mapping
+
+        return _mapping.map_effect(self, _identity, concurrency, unordered)
+
+    def result(self) -> Stream[Result[A_co, E_co], Never, R_co]:
+        """Write each item as ``Ok``, then a typed failure as one last
+        ``Err`` instead of failing."""
+        from pyfect.stream import _mapping
+
+        return _mapping.result(self)
+
+    # --- tapping --------------------------------------------------------------
+
+    def tap[E2 = Never, R2 = Never](
+        self, f: Callable[[A_co], Effect[object, E2, R2]], *, concurrency: Concurrency = None
+    ) -> Stream[A_co, E_co | E2, R_co | R2]:
+        """Run ``f`` on each item, then write the item."""
+        from pyfect.stream import _mapping
+
+        return _mapping.map_effect(self, lambda a: f(a).as_(a), concurrency, False)
+
+    def tap_both[EE = Never, RR = Never](
+        self,
+        *,
+        on_element: Callable[[A_co], Effect[object, EE, RR]],
+        on_error: Callable[[E_co], Effect[object, EE, RR]],
+        concurrency: Concurrency = None,
+    ) -> Stream[A_co, E_co | EE, R_co | RR]:
+        """``tap`` with ``on_element`` and ``tap_error`` with ``on_error``."""
+        return as_stream(self).tap_error(on_error).tap(on_element, concurrency=concurrency)
+
+    # --- flat-mapping ---------------------------------------------------------
+
+    def flat_map[B, E2 = Never, R2 = Never](
+        self,
+        f: Callable[[A_co], StreamBase[B, E2, R2]],
+        *,
+        concurrency: Concurrency = None,
+        buffer_size: int = 16,
+    ) -> Stream[B, E_co | E2, R_co | R2]:
+        """Write the items of ``f(item)`` for each item, one stream after
+        another; with ``concurrency`` above 1, up to that many at once,
+        their items merged through a buffer of ``buffer_size``."""
+        from pyfect.stream import _mapping
+
+        return _mapping.flat_map(self, f, concurrency, buffer_size, switch=False)
+
+    def switch_map[B, E2 = Never, R2 = Never](
+        self,
+        f: Callable[[A_co], StreamBase[B, E2, R2]],
+        *,
+        concurrency: Concurrency = 1,
+        buffer_size: int = 16,
+    ) -> Stream[B, E_co | E2, R_co | R2]:
+        """``flat_map`` where each new item interrupts the oldest running
+        stream once ``concurrency`` are running."""
+        from pyfect.stream import _mapping
+
+        return _mapping.flat_map(self, f, concurrency, buffer_size, switch=True)
+
+    def flatten[B, E2 = Never, R2 = Never](
+        self: MapMethods[StreamBase[B, E2, R2], E_co, R_co],
+        *,
+        concurrency: Concurrency = None,
+        buffer_size: int = 16,
+    ) -> Stream[B, E_co | E2, R_co | R2]:
+        """Write the items of each stream this stream writes."""
+        from pyfect.stream import _mapping
+
+        return _mapping.flat_map(self, _identity, concurrency, buffer_size, switch=False)
+
+    def flatten_array[B, E, R](self: MapMethods[tuple[B, ...], E, R]) -> Stream[B, E, R]:
+        """Write the items of each tuple this stream writes, a tuple per
+        chunk."""
+        from pyfect.stream import _mapping
+
+        return _mapping.flatten_array(self)
+
+    def flatten_iterable[B, E, R](self: MapMethods[Iterable[B], E, R]) -> Stream[B, E, R]:
+        """Write the items of each iterable this stream writes."""
+        from pyfect.stream import _constructors
+
+        return self.flat_map(_constructors.from_iterable)
+
+    def flatten_take[B, E2](
+        self: MapMethods[Take[B, E2], E_co, R_co],
+    ) -> Stream[B, E_co | E2, R_co]:
+        """Replay each ``Take``: write its items, or fail or end as it says."""
+        from pyfect.stream import _mapping
+
+        return _mapping.flatten_take(self)
+
+    def drain(self) -> Stream[Never, E_co, R_co]:
+        """Run the stream for its effects, writing nothing."""
+        from pyfect.stream._stream import Stream
+
+        return Stream(self._channel.drain())
+
+    def drain_fork[E2 = Never, R2 = Never](
+        self, that: Stream[object, E2, R2]
+    ) -> Stream[A_co, E_co | E2, R_co | R2]:
+        """Run ``that`` for its effects alongside this stream; its failure
+        fails this stream, and it stops when this stream ends."""
+        require_stream(that, "that")
+        return as_stream(self).merge_effect(that.run_drain())
+
+    # --- sequencing -----------------------------------------------------------
+
+    def concat[B, E2 = Never, R2 = Never](
+        self, that: Stream[B, E2, R2]
+    ) -> Stream[A_co | B, E_co | E2, R_co | R2]:
+        """Write this stream's items, then ``that``'s. Each part's resources
+        are released before the next starts; a chain of thousands of
+        ``concat`` calls runs as one flat sequence."""
+        from pyfect.stream import _concat
+
+        require_stream(that, "that")
+        return _concat.concat(self, that)
+
+    def prepend[B](self, values: Iterable[B]) -> Stream[A_co | B, E_co, R_co]:
+        """Write ``values`` first, then this stream's items."""
+        from pyfect.stream import _concat, _constructors
+
+        return _concat.concat(_constructors.from_iterable(values), self)
+
+    def intersperse[B](self, element: B) -> Stream[A_co | B, E_co, R_co]:
+        """Write ``element`` between each two items."""
+        from pyfect.stream import _mapping
+
+        return _mapping.intersperse(self, element)
+
+    def intersperse_affixes[B, C, D](
+        self, *, start: B, middle: C, end: D
+    ) -> Stream[A_co | B | C | D, E_co, R_co]:
+        """Write ``start``, the items with ``middle`` between each two, then
+        ``end``."""
+        from pyfect.stream import _concat, _constructors
+
+        body = _concat.concat(_constructors.succeed(start), self.intersperse(middle))
+        return _concat.concat(body, _constructors.succeed(end))
+
+    def when[E2 = Never, R2 = Never](
+        self, test: Effect[bool, E2, R2]
+    ) -> Stream[A_co, E_co | E2, R_co | R2]:
+        """This stream if ``test`` succeeds with ``True``, else an empty one;
+        ``test`` runs each time the stream runs."""
+        from pyfect._effect_args import require_effect
+        from pyfect.stream import _constructors
+
+        require_effect(test, "test")
+        me = as_stream(self)
+        return _constructors.unwrap(test.map(lambda ok: me if ok else _constructors.empty))
+
+
+def _identity[T](value: T) -> T:
+    return value

pyfect/stream/_mapping.py

@@ -0,0 +1,126 @@
+"""The work behind ``Stream``'s mapping, flat-mapping and flattening
+methods, and ``map_chunks``, the chunk-by-chunk loop most stateful
+operators share."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from pyfect._concurrency import Concurrency
+from pyfect._core import Effect, _FlatMap, _Succeed
+from pyfect.channel import transform_pull
+from pyfect.result import Err, Ok
+from pyfect.stream._base import AnyStream
+from pyfect.stream._stream import Stream
+
+type AnyEffect = Effect[Any, Any, Any]
+type Chunk = tuple[Any, ...]
+type AnyStream_ = Stream[Any, Any, Any]
+
+
+def one[A](value: A) -> tuple[A]:
+    return (value,)
+
+
+def map_chunks(self: AnyStream, make: Callable[[], Callable[[Chunk], Chunk]]) -> AnyStream_:
+    """A stream writing ``f(chunk)`` for each chunk, where ``f = make()``
+    is built once per run (so it may keep state); an empty result pulls
+    the next chunk instead of writing."""
+
+    def build(pull: AnyEffect, _scope: object) -> AnyEffect:
+        f = make()
+
+        def loop(chunk: Chunk) -> AnyEffect:
+            out = f(chunk)
+            return _Succeed(out) if out else _FlatMap(pull, loop)
+
+        return _Succeed(_FlatMap(pull, loop))
+
+    return Stream(transform_pull(self._channel, build))
+
+
+def map_(self: AnyStream, f: Callable[[Any], Any]) -> AnyStream_:
+    return Stream(self._channel.map(lambda chunk: tuple(map(f, chunk))))
+
+
+def map_array(self: AnyStream, f: Callable[[Chunk], Chunk]) -> AnyStream_:
+    return map_chunks(self, lambda: f)
+
+
+def map_effect(
+    self: AnyStream,
+    f: Callable[[Any], AnyEffect],
+    concurrency: Concurrency,
+    unordered: bool,
+) -> AnyStream_:
+    mapped = self._channel.flatten_array().map_effect(
+        f, concurrency=concurrency, unordered=unordered
+    )
+    return Stream(mapped.map(one))
+
+
+def map_array_effect(self: AnyStream, f: Callable[[Chunk], AnyEffect]) -> AnyStream_:
+    def build(pull: AnyEffect, _scope: object) -> AnyEffect:
+        def loop(chunk: Chunk) -> AnyEffect:
+            return _FlatMap(f(chunk), lambda out: _Succeed(out) if out else _FlatMap(pull, loop))
+
+        return _Succeed(_FlatMap(pull, loop))
+
+    return Stream(transform_pull(self._channel, build))
+
+
+def result(self: AnyStream) -> AnyStream_:
+    from pyfect.stream import _constructors
+
+    oks = map_(self, Ok)
+    return oks.catch_all(lambda error: _constructors.succeed(Err(error)))
+
+
+def flat_map(
+    self: AnyStream,
+    f: Callable[[Any], AnyStream],
+    concurrency: Concurrency,
+    buffer_size: int,
+    *,
+    switch: bool,
+) -> AnyStream_:
+    items = self._channel.flatten_array()
+    if switch:
+        return Stream(
+            items.switch_map(
+                lambda a: f(a)._channel, concurrency=concurrency or 1, buffer_size=buffer_size
+            )
+        )
+    return Stream(
+        items.flat_map(lambda a: f(a)._channel, concurrency=concurrency, buffer_size=buffer_size)
+    )
+
+
+def flatten_array(self: AnyStream) -> AnyStream_:
+    return Stream(self._channel.flatten_array().filter(bool))
+
+
+def flatten_take(self: AnyStream) -> AnyStream_:
+    taken: Any = self._channel.flatten_array().flatten_take()
+    return Stream(taken)
+
+
+def intersperse(self: AnyStream, element: Any) -> AnyStream_:
+    def make() -> Callable[[Chunk], Chunk]:
+        first = True
+
+        def f(chunk: Chunk) -> Chunk:
+            nonlocal first
+            out: list[Any] = [] if first else [element]
+            first = False
+            for item in chunk:
+                out.append(item)
+                out.append(element)
+            out.pop()
+            return tuple(out)
+
+        return f
+
+    return map_chunks(self, make)

pyfect/stream/_run.py

@@ -0,0 +1,114 @@
+"""Running a stream: its channel's runs, item by item over each chunk."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Generator
+from typing import Any
+
+from pyfect._core import Effect, _Gen
+from pyfect.option import Option, Some
+from pyfect.stream._base import AnyStream
+
+type AnyEffect = Effect[Any, Any, Any]
+type Chunk = tuple[Any, ...]
+
+
+def _extend(acc: list[Any], chunk: Chunk) -> list[Any]:
+    acc.extend(chunk)
+    return acc
+
+
+def run_collect(self: AnyStream) -> AnyEffect:
+    return self._channel.run_fold(list, _extend)
+
+
+def run_count(self: AnyStream) -> AnyEffect:
+    return self._channel.run_fold(int, lambda n, chunk: n + len(chunk))
+
+
+def run_sum(self: AnyStream) -> AnyEffect:
+    return self._channel.run_fold(int, lambda total, chunk: total + sum(chunk))
+
+
+def run_string(self: AnyStream) -> AnyEffect:
+    return self._channel.run_fold(list, _extend).map("".join)
+
+
+def run_bytes(self: AnyStream) -> AnyEffect:
+    return self._channel.run_fold(list, _extend).map(b"".join)
+
+
+def run_fold(
+    self: AnyStream, initial: Callable[[], Any], f: Callable[[Any, Any], Any]
+) -> AnyEffect:
+    def fold_chunk(acc: Any, chunk: Chunk) -> Any:
+        for item in chunk:
+            acc = f(acc, item)
+        return acc
+
+    return self._channel.run_fold(initial, fold_chunk)
+
+
+def run_fold_effect(
+    self: AnyStream, initial: Callable[[], Any], f: Callable[[Any, Any], AnyEffect]
+) -> AnyEffect:
+    def fold_chunk(acc: Any, chunk: Chunk) -> AnyEffect:
+        if len(chunk) == 1:
+            return f(acc, chunk[0])
+
+        def body() -> Generator[AnyEffect, Any, Any]:
+            state = acc
+            for item in chunk:
+                state = yield f(state, item)
+            return state
+
+        return _Gen(body)
+
+    return self._channel.run_fold_effect(initial, fold_chunk)
+
+
+def run_for_each(self: AnyStream, f: Callable[[Any], AnyEffect]) -> AnyEffect:
+    def each(chunk: Chunk) -> AnyEffect:
+        if len(chunk) == 1:
+            return f(chunk[0])
+
+        def body() -> Generator[AnyEffect, Any]:
+            for item in chunk:
+                yield f(item)
+
+        return _Gen(body)
+
+    return self._channel.run_for_each(each)
+
+
+def run_for_each_while(self: AnyStream, f: Callable[[Any], Effect[bool, Any, Any]]) -> AnyEffect:
+    def each(chunk: Chunk) -> Effect[bool, Any, Any]:
+        if len(chunk) == 1:
+            return f(chunk[0])
+
+        def body() -> Generator[AnyEffect, Any, bool]:
+            for item in chunk:
+                if not (yield f(item)):
+                    return False
+            return True
+
+        return _Gen(body)
+
+    return self._channel.run_for_each_while(each)
+
+
+def _first(chunk: Option[Chunk]) -> Option[Any]:
+    return None if chunk is None else Some(chunk.value[0])
+
+
+def _last(chunk: Option[Chunk]) -> Option[Any]:
+    return None if chunk is None else Some(chunk.value[-1])
+
+
+def run_head(self: AnyStream) -> AnyEffect:
+    return self._channel.run_head().map(_first)
+
+
+def run_last(self: AnyStream) -> AnyEffect:
+    return self._channel.run_last().map(_last)

pyfect/stream/_run_methods.py

@@ -0,0 +1,114 @@
+"""``Stream`` methods that run a stream: the ``run_*`` folds and
+``to_pull``. Each runs the stream's channel; the item-by-item work is in
+``pyfect.stream._run``."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Never
+
+from pyfect.stream._base import A_co, E_co, R_co, StreamBase
+
+if TYPE_CHECKING:
+    from pyfect._core import Effect
+    from pyfect.option import Option
+    from pyfect.pull import Pull
+    from pyfect.scope import Scope
+
+
+class RunMethods(StreamBase[A_co, E_co, R_co]):
+    __slots__ = ()
+
+    def run_collect(self) -> Effect[list[A_co], E_co, R_co]:
+        """Run the stream and collect its items."""
+        from pyfect.stream import _run
+
+        return _run.run_collect(self)
+
+    def run_drain(self) -> Effect[None, E_co, R_co]:
+        """Run the stream, dropping its items."""
+        return self._channel.run_drain()
+
+    def run_count(self) -> Effect[int, E_co, R_co]:
+        """Run the stream and count its items."""
+        from pyfect.stream import _run
+
+        return _run.run_count(self)
+
+    def run_sum[N: (int, float), E, R](self: RunMethods[N, E, R]) -> Effect[N, E, R]:
+        """Run a stream of numbers and add them up (``0`` when empty)."""
+        from pyfect.stream import _run
+
+        return _run.run_sum(self)
+
+    def run_fold[Z](
+        self, initial: Callable[[], Z], f: Callable[[Z, A_co], Z]
+    ) -> Effect[Z, E_co, R_co]:
+        """Fold the items into ``initial()`` with ``f``."""
+        from pyfect.stream import _run
+
+        return _run.run_fold(self, initial, f)
+
+    def run_fold_effect[Z, E2 = Never, R2 = Never](
+        self, initial: Callable[[], Z], f: Callable[[Z, A_co], Effect[Z, E2, R2]]
+    ) -> Effect[Z, E_co | E2, R_co | R2]:
+        """Fold the items into ``initial()`` with the effect ``f``, one item
+        at a time."""
+        from pyfect.stream import _run
+
+        return _run.run_fold_effect(self, initial, f)
+
+    def run_head(self) -> Effect[Option[A_co], E_co, R_co]:
+        """The first item (``Some``), or ``None`` for an empty stream. Stops
+        the stream after its first chunk."""
+        from pyfect.stream import _run
+
+        return _run.run_head(self)
+
+    def run_last(self) -> Effect[Option[A_co], E_co, R_co]:
+        """The last item (``Some``), or ``None`` for an empty stream."""
+        from pyfect.stream import _run
+
+        return _run.run_last(self)
+
+    def run_for_each[E2 = Never, R2 = Never](
+        self, f: Callable[[A_co], Effect[object, E2, R2]]
+    ) -> Effect[None, E_co | E2, R_co | R2]:
+        """Run ``f`` on each item, in order."""
+        from pyfect.stream import _run
+
+        return _run.run_for_each(self, f)
+
+    def run_for_each_while[E2 = Never, R2 = Never](
+        self, f: Callable[[A_co], Effect[bool, E2, R2]]
+    ) -> Effect[None, E_co | E2, R_co | R2]:
+        """Run ``f`` on each item until it succeeds with ``False``; the
+        stream stops there."""
+        from pyfect.stream import _run
+
+        return _run.run_for_each_while(self, f)
+
+    def run_for_each_array[E2 = Never, R2 = Never](
+        self, f: Callable[[tuple[A_co, ...]], Effect[object, E2, R2]]
+    ) -> Effect[None, E_co | E2, R_co | R2]:
+        """Run ``f`` on each chunk (a non-empty tuple), in order."""
+        return self._channel.run_for_each(f)
+
+    def run_string[E, R](self: RunMethods[str, E, R]) -> Effect[str, E, R]:
+        """Run a stream of strings and join them (Effect's ``mkString``)."""
+        from pyfect.stream import _run
+
+        return _run.run_string(self)
+
+    def run_bytes[E, R](self: RunMethods[bytes, E, R]) -> Effect[bytes, E, R]:
+        """Run a stream of byte strings and join them (Effect's
+        ``mkUint8Array`` and ``mkArrayBuffer``)."""
+        from pyfect.stream import _run
+
+        return _run.run_bytes(self)
+
+    def to_pull(self) -> Effect[Pull[tuple[A_co, ...], E_co], Never, R_co | Scope]:
+        """Build the stream's pull in the current ``Scope``, which holds its
+        resources. Each pull succeeds with the next chunk or fails with
+        ``Done()`` at the end; fibers pulling at once take turns."""
+        return self._channel.to_pull()

pyfect/stream/_service_methods.py

@@ -0,0 +1,36 @@
+"""``Stream`` methods for services and spans that keep or add to the
+stream's type: ``update_service`` and ``with_span``. The providers, which
+remove services from the type, are curried functions in
+``pyfect.stream._context``."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Unpack
+
+from pyfect.stream._base import A_co, E_co, R_co, StreamBase
+
+if TYPE_CHECKING:
+    from pyfect.context import TagLike
+    from pyfect.stream._stream import Stream
+    from pyfect.tracer import SpanOptions
+
+
+class ServiceMethods(StreamBase[A_co, E_co, R_co]):
+    __slots__ = ()
+
+    def update_service[S, T](
+        self, tag: TagLike[S, T], f: Callable[[S], S]
+    ) -> Stream[A_co, E_co, R_co | T]:
+        """Run with ``f`` applied to the service of ``tag``, which this
+        stream then needs."""
+        from pyfect.stream._stream import Stream
+
+        return Stream(self._channel.update_service(tag, f))
+
+    def with_span(self, name: str, **options: Unpack[SpanOptions]) -> Stream[A_co, E_co, R_co]:
+        """Run inside a new span, the parent of the spans made inside. It
+        ends with the stream's exit."""
+        from pyfect.stream._stream import Stream
+
+        return Stream(self._channel.with_span(name, **options))