pyfect-dev 0.1.0__py3-none-any.whl

pyfect/channel/_filters.py

@@ -0,0 +1,225 @@
+"""The work behind the filtering and folding ``Channel`` methods:
+``filter`` and ``filter_map`` with their effect and tuple variants (a
+filter returns ``Ok(value)`` to write ``value``, ``Err`` to skip),
+``scan_effect``,
+``map_accum`` and ``flatten_array``.
+
+A pull that skips items pulls again from the continuation, so skipping
+any number of items keeps the fiber's stack flat.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any, cast
+
+from pyfect._concurrency import for_each
+from pyfect._core import Effect, _FailCause, _FlatMap, _MatchCause, _Succeed, _Suspend
+from pyfect._iterables import filter as filter_items
+from pyfect.cause import Cause
+from pyfect.channel._base import AnyChannel, AnyPull
+from pyfect.channel._channel import Channel, transform_pull
+from pyfect.result import Ok, Result
+
+type Channel_ = Channel[Any, Any, Any, Any, Any, Any, Any]
+
+
+def filter_(self: AnyChannel, predicate: Callable[[Any], bool]) -> Channel_:
+    def with_pull(pull: AnyPull) -> AnyPull:
+        def loop(item: Any) -> AnyPull:
+            return _Succeed(item) if predicate(item) else _FlatMap(pull, loop)
+
+        return _FlatMap(pull, loop)
+
+    return transform_pull(self, lambda pull, _: _Succeed(with_pull(pull)))
+
+
+def filter_effect(self: AnyChannel, predicate: Callable[[Any], Effect[bool, Any, Any]]) -> Channel_:
+    def with_pull(pull: AnyPull) -> AnyPull:
+        def loop(item: Any) -> AnyPull:
+            return _FlatMap(
+                predicate(item), lambda keep: _Succeed(item) if keep else _FlatMap(pull, loop)
+            )
+
+        return _FlatMap(pull, loop)
+
+    return transform_pull(self, lambda pull, _: _Succeed(with_pull(pull)))
+
+
+def filter_array(self: AnyChannel, predicate: Callable[[Any], bool]) -> Channel_:
+    def with_pull(pull: AnyPull) -> AnyPull:
+        def loop(items: tuple[Any, ...]) -> AnyPull:
+            kept = tuple(item for item in items if predicate(item))
+            return _Succeed(kept) if kept else _FlatMap(pull, loop)
+
+        return _FlatMap(pull, loop)
+
+    return transform_pull(self, lambda pull, _: _Succeed(with_pull(pull)))
+
+
+def filter_array_effect(
+    self: AnyChannel, predicate: Callable[[Any], Effect[bool, Any, Any]]
+) -> Channel_:
+    def with_pull(pull: AnyPull) -> AnyPull:
+        filtered = _FlatMap(pull, lambda items: filter_items(items, predicate))
+
+        def loop(kept: list[Any]) -> AnyPull:
+            return _Succeed(tuple(kept)) if kept else _FlatMap(filtered, loop)
+
+        return _FlatMap(filtered, loop)
+
+    return transform_pull(self, lambda pull, _: _Succeed(with_pull(pull)))
+
+
+def filter_map(self: AnyChannel, f: Callable[[Any], Result[Any, object]]) -> Channel_:
+    def with_pull(pull: AnyPull) -> AnyPull:
+        def loop(item: Any) -> AnyPull:
+            result = f(item)
+            return _Succeed(result.value) if isinstance(result, Ok) else _FlatMap(pull, loop)
+
+        return _FlatMap(pull, loop)
+
+    return transform_pull(self, lambda pull, _: _Succeed(with_pull(pull)))
+
+
+def filter_map_effect(
+    self: AnyChannel, f: Callable[[Any], Effect[Result[Any, object], Any, Any]]
+) -> Channel_:
+    def with_pull(pull: AnyPull) -> AnyPull:
+        def loop(item: Any) -> AnyPull:
+            return _FlatMap(f(item), written)
+
+        def written(result: Result[Any, object]) -> AnyPull:
+            return _Succeed(result.value) if isinstance(result, Ok) else _FlatMap(pull, loop)
+
+        return _FlatMap(pull, loop)
+
+    return transform_pull(self, lambda pull, _: _Succeed(with_pull(pull)))
+
+
+def _passing(results: Sequence[Result[Any, object]]) -> tuple[Any, ...]:
+    return tuple(result.value for result in results if isinstance(result, Ok))
+
+
+def filter_map_array(self: AnyChannel, f: Callable[[Any], Result[Any, object]]) -> Channel_:
+    def with_pull(pull: AnyPull) -> AnyPull:
+        def loop(items: tuple[Any, ...]) -> AnyPull:
+            kept = _passing([f(item) for item in items])
+            return _Succeed(kept) if kept else _FlatMap(pull, loop)
+
+        return _FlatMap(pull, loop)
+
+    return transform_pull(self, lambda pull, _: _Succeed(with_pull(pull)))
+
+
+def filter_map_array_effect(
+    self: AnyChannel, f: Callable[[Any], Effect[Result[Any, object], Any, Any]]
+) -> Channel_:
+    def with_pull(pull: AnyPull) -> AnyPull:
+        filtered = _FlatMap(pull, lambda items: for_each(items, f).map(_passing))
+
+        def loop(kept: tuple[Any, ...]) -> AnyPull:
+            return _Succeed(kept) if kept else _FlatMap(filtered, loop)
+
+        return _FlatMap(filtered, loop)
+
+    return transform_pull(self, lambda pull, _: _Succeed(with_pull(pull)))
+
+
+def scan_effect(
+    self: AnyChannel, initial: Any, f: Callable[[Any, Any], Effect[Any, Any, Any]]
+) -> Channel_:
+    def with_pull(pull: AnyPull) -> AnyPull:
+        state = initial
+        first = True
+
+        def keep(new_state: Any) -> AnyPull:
+            nonlocal state
+            state = new_state
+            return _Succeed(new_state)
+
+        def next_state() -> AnyPull:
+            nonlocal first
+            if first:
+                first = False
+                return _Succeed(state)
+            return _FlatMap(_FlatMap(pull, lambda item: f(state, item)), keep)
+
+        return _Suspend(next_state)
+
+    return transform_pull(self, lambda pull, _: _Succeed(with_pull(pull)))
+
+
+def map_accum(
+    self: AnyChannel,
+    initial: Callable[[], Any],
+    f: Callable[[Any, Any], Any],
+    on_halt: Callable[[Any], Sequence[Any]] | None,
+) -> Channel_:
+    def with_pull(pull: AnyPull) -> AnyPull:
+        state = initial()
+        pending: Sequence[Any] = ()
+        index = 0
+        halted: Cause[Any] | None = None
+
+        def on_failure(cause: Cause[Any]) -> Effect[Any, Any, Any]:
+            nonlocal halted
+            halted = cause
+            last = () if on_halt is None else on_halt(state)
+            return _Succeed((state, last)) if last else _FailCause(cause)
+
+        def on_success(item: Any) -> Effect[Any, Any, Any]:
+            step: object = f(state, item)
+            if isinstance(step, tuple):
+                return _Succeed(cast("tuple[Any, Sequence[Any]]", step))
+            return cast("Effect[Any, Any, Any]", step)
+
+        pull_next = _MatchCause(pull, on_failure, on_success)
+
+        def written(result: tuple[Any, Sequence[Any]]) -> AnyPull:
+            nonlocal state, pending, index
+            state, values = result
+            if len(values) == 1:
+                return _Succeed(values[0])
+            pending, index = values, 0
+            return loop()
+
+        def loop() -> AnyPull:
+            nonlocal pending, index
+            if index < len(pending):
+                item = pending[index]
+                index += 1
+                return _Succeed(item)
+            if halted is not None:
+                return _FailCause(halted)
+            return _FlatMap(pull_next, written)
+
+        return _Suspend(loop)
+
+    return transform_pull(self, lambda pull, _: _Succeed(with_pull(pull)))
+
+
+def flatten_array(self: AnyChannel) -> Channel_:
+    def with_pull(pull: AnyPull) -> AnyPull:
+        pending: Sequence[Any] = ()
+        index = 0
+
+        def refill(items: Sequence[Any]) -> AnyPull:
+            nonlocal pending, index
+            if len(items) == 1:
+                return _Succeed(items[0])
+            pending, index = items, 0
+            return loop()
+
+        def loop() -> AnyPull:
+            nonlocal index
+            if index < len(pending):
+                item = pending[index]
+                index += 1
+                return _Succeed(item)
+            return _FlatMap(pull, refill)
+
+        return _Suspend(loop)
+
+    return transform_pull(self, lambda pull, _: _Succeed(with_pull(pull)))

pyfect/channel/_lifecycle.py

@@ -0,0 +1,71 @@
+"""The work behind ``on_start``, ``on_first``, ``on_end``, ``on_exit`` and
+``with_span``."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from pyfect._core import Effect, _FlatMap, _Succeed, _Suspend, _WithFiber
+from pyfect.channel._base import AnyChannel, AnyPull, end_with
+from pyfect.channel._channel import Channel, transform_pull
+from pyfect.channel._constructors import acquire_use_release, bracket, unwrap_effect
+from pyfect.channel._context import update_context_with
+from pyfect.clock import Clock
+from pyfect.exit import Exit
+from pyfect.pull import catch_done
+from pyfect.scope import CloseableScope
+from pyfect.tracer import Span, SpanOptions
+from pyfect.tracer._refs import ParentSpan, TracerTimingEnabled
+from pyfect.tracer._spans import _SpanEnder, make_span
+
+type Channel_ = Channel[Any, Any, Any, Any, Any, Any, Any]
+
+
+def on_start(self: AnyChannel, eff: Effect[Any, Any, Any]) -> Channel_:
+    return unwrap_effect(eff.as_(self))
+
+
+def on_first(self: AnyChannel, f: Callable[[Any], Effect[Any, Any, Any]]) -> Channel_:
+    def with_pull(pull: AnyPull) -> AnyPull:
+        first = True
+
+        def tap(item: Any) -> Effect[Any, Any, Any]:
+            nonlocal first
+            first = False
+            return f(item).as_(item)
+
+        pull_first = _FlatMap(pull, tap)
+        return _Suspend(lambda: pull_first if first else pull)
+
+    return transform_pull(self, lambda pull, _: _Succeed(with_pull(pull)))
+
+
+def on_end(self: AnyChannel, eff: Effect[Any, Any, Any]) -> Channel_:
+    def ended(leftover: Any) -> AnyPull:
+        return eff.and_then(end_with(leftover))
+
+    return transform_pull(self, lambda pull, _: _Succeed(catch_done(pull, ended)))
+
+
+def on_exit(self: AnyChannel, f: Callable[[Exit[Any, Any]], Effect[Any, Any, Any]]) -> Channel_:
+    def build(upstream: AnyPull, scope: CloseableScope, forked: CloseableScope) -> Effect[AnyPull]:
+        return forked.add_finalizer(f).and_then(self._transform(upstream, scope))
+
+    return bracket(build)
+
+
+def with_span(self: AnyChannel, name: str, options: SpanOptions) -> Channel_:
+    def use(span: Span) -> Channel_:
+        return update_context_with(self, lambda ctx: ctx.add(ParentSpan, span))
+
+    def end(span: Span, ex: Exit[Any, Any]) -> Effect[None]:
+        def run(fiber: Any) -> Effect[None]:
+            _SpanEnder(span, fiber.get_ref(Clock), fiber.get_ref(TracerTimingEnabled))(ex)
+            return _Succeed(None)
+
+        return _WithFiber(run)
+
+    channel: Channel_ = acquire_use_release(make_span(name, **options), use, end)
+    return channel

pyfect/channel/_lifecycle_methods.py

@@ -0,0 +1,206 @@
+"""``Channel`` methods about a channel's life: effects at its start, first
+item, end and exit; spans and services around it; and running it again
+(``repeat``, ``forever``) or pacing it (``schedule``)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Never, Unpack, overload
+
+from pyfect.channel._base import (
+    ChannelBase,
+    Env_co,
+    InDone_contra,
+    InElem_contra,
+    InErr_contra,
+    OutDone_co,
+    OutElem_co,
+    OutErr_co,
+)
+
+if TYPE_CHECKING:
+    from pyfect._core import Effect
+    from pyfect.cause import Cause
+    from pyfect.channel._channel import Channel
+    from pyfect.context import TagLike
+    from pyfect.exit import Exit
+    from pyfect.schedule import Schedule
+    from pyfect.schedule._model import SetInputType
+    from pyfect.tracer import SpanOptions
+
+
+class LifecycleMethods(
+    ChannelBase[
+        OutElem_co, OutErr_co, OutDone_co, InElem_contra, InErr_contra, InDone_contra, Env_co
+    ]
+):
+    __slots__ = ()
+
+    def on_start[E2 = Never, R2 = Never](
+        self, eff: Effect[object, E2, R2]
+    ) -> Channel[
+        OutElem_co,
+        OutErr_co | E2,
+        OutDone_co,
+        InElem_contra,
+        InErr_contra,
+        InDone_contra,
+        Env_co | R2,
+    ]:
+        """Run ``eff`` on the first pull, before the channel starts."""
+        from pyfect._effect_args import require_effect
+        from pyfect.channel import _lifecycle
+
+        require_effect(eff, "eff")
+        return _lifecycle.on_start(self, eff)
+
+    def on_first[E2 = Never, R2 = Never](
+        self, f: Callable[[OutElem_co], Effect[object, E2, R2]]
+    ) -> Channel[
+        OutElem_co,
+        OutErr_co | E2,
+        OutDone_co,
+        InElem_contra,
+        InErr_contra,
+        InDone_contra,
+        Env_co | R2,
+    ]:
+        """Run ``f`` on the first item, before writing it."""
+        from pyfect.channel import _lifecycle
+
+        return _lifecycle.on_first(self, f)
+
+    def on_end[E2 = Never, R2 = Never](
+        self, eff: Effect[object, E2, R2]
+    ) -> Channel[
+        OutElem_co,
+        OutErr_co | E2,
+        OutDone_co,
+        InElem_contra,
+        InErr_contra,
+        InDone_contra,
+        Env_co | R2,
+    ]:
+        """Run ``eff`` when the channel ends (not when it fails)."""
+        from pyfect._effect_args import require_effect
+        from pyfect.channel import _lifecycle
+
+        require_effect(eff, "eff")
+        return _lifecycle.on_end(self, eff)
+
+    def on_exit[R2 = Never](
+        self, f: Callable[[Exit[OutDone_co, OutErr_co]], Effect[object, Never, R2]]
+    ) -> Channel[
+        OutElem_co, OutErr_co, OutDone_co, InElem_contra, InErr_contra, InDone_contra, Env_co | R2
+    ]:
+        """Run ``f(exit)`` as soon as the channel ends or fails, or when its
+        run stops early."""
+        from pyfect.channel import _lifecycle
+
+        return _lifecycle.on_exit(self, f)
+
+    def on_error[R2 = Never](
+        self, f: Callable[[Cause[OutErr_co]], Effect[object, Never, R2]]
+    ) -> Channel[
+        OutElem_co, OutErr_co, OutDone_co, InElem_contra, InErr_contra, InDone_contra, Env_co | R2
+    ]:
+        """``on_exit`` for a failure (or an early stop that interrupts)."""
+        from pyfect.channel import _lifecycle
+
+        return _lifecycle.on_exit(self, lambda ex: ex.match(on_success=_void, on_failure=f))
+
+    def ensuring[R2 = Never](
+        self, finalizer: Effect[object, Never, R2]
+    ) -> Channel[
+        OutElem_co, OutErr_co, OutDone_co, InElem_contra, InErr_contra, InDone_contra, Env_co | R2
+    ]:
+        """Run ``finalizer`` however the channel stops."""
+        from pyfect._effect_args import require_effect
+        from pyfect.channel import _lifecycle
+
+        require_effect(finalizer, "finalizer")
+        return _lifecycle.on_exit(self, lambda _: finalizer)
+
+    def with_span(
+        self, name: str, **options: Unpack[SpanOptions]
+    ) -> Channel[
+        OutElem_co, OutErr_co, OutDone_co, InElem_contra, InErr_contra, InDone_contra, Env_co
+    ]:
+        """Run inside a new span, the parent of the spans made inside. It
+        ends with the channel's exit."""
+        from pyfect.channel import _lifecycle
+
+        return _lifecycle.with_span(self, name, options)
+
+    def update_service[S, T](
+        self, tag: TagLike[S, T], f: Callable[[S], S]
+    ) -> Channel[
+        OutElem_co, OutErr_co, OutDone_co, InElem_contra, InErr_contra, InDone_contra, Env_co | T
+    ]:
+        """Run with ``f`` applied to the service of ``tag``, which this
+        channel then needs."""
+        from pyfect.channel import _context
+
+        return _context.update_context_with(self, lambda ctx: ctx.add(tag, f(ctx.get_unsafe(tag))))
+
+    # --- repetition -----------------------------------------------------------
+
+    @overload
+    def repeat[EE = Never, RR = Never](
+        self, schedule: Schedule[object, OutDone_co, EE, RR], /
+    ) -> Channel[
+        OutElem_co,
+        OutErr_co | EE,
+        OutDone_co,
+        InElem_contra,
+        InErr_contra,
+        InDone_contra,
+        Env_co | RR,
+    ]: ...
+    @overload
+    def repeat[O, E, D, I, IE, ID, R, EE = Never, RR = Never](
+        self: LifecycleMethods[O, E, D, I, IE, ID, R],
+        builder: Callable[[SetInputType[D]], Schedule[object, D, EE, RR]],
+        /,
+    ) -> Channel[O, E | EE, D, I, IE, ID, R | RR]: ...
+    def repeat(
+        self, schedule: Schedule[Any, Any, Any, Any] | Callable[[Any], Any], /
+    ) -> Channel[Any, Any, Any, Any, Any, Any, Any]:
+        """Run the channel again after each end, stepping ``schedule`` with
+        its end value, until the schedule stops; then end with the last
+        end value. Each run sees its step's ``schedule.CurrentMetadata``."""
+        from pyfect.channel import _repeat
+
+        return _repeat.repeat(self, schedule)
+
+    def forever(
+        self,
+    ) -> Channel[OutElem_co, OutErr_co, Never, InElem_contra, InErr_contra, InDone_contra, Env_co]:
+        """Run the channel again each time it ends, until it fails."""
+        from pyfect.channel import _repeat
+
+        return _repeat.forever(self)
+
+    def schedule[SO, EE = Never, RR = Never](
+        self, schedule: Schedule[SO, OutElem_co, EE, RR]
+    ) -> Channel[
+        OutElem_co,
+        OutErr_co | EE,
+        OutDone_co | SO,
+        InElem_contra,
+        InErr_contra,
+        InDone_contra,
+        Env_co | RR,
+    ]:
+        """Step ``schedule`` with each item, writing it after the step's
+        delay; when the schedule stops, end with its output (dropping the
+        item that stopped it)."""
+        from pyfect.channel import _repeat
+
+        return _repeat.schedule(self, schedule)
+
+
+def _void(_: object) -> Effect[None]:
+    from pyfect.effect import void
+
+    return void

pyfect/channel/_loop.py

@@ -0,0 +1,100 @@
+"""The two primitives that keep pull loops fast: a loop that pulls until
+the pull fails, and a pull reading a Python iterator.
+
+Both run on the fiber's explicit stack, so a loop over millions of items
+never grows Python's stack, and each item costs one or two fiber steps.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Generator, Iterator
+from itertools import islice
+from typing import TYPE_CHECKING, Any, Never, final
+
+from pyfect._core import Effect, Step
+from pyfect.cause import Cause, Fail
+from pyfect.errors import Done
+from pyfect.exit import Failure, Success
+
+if TYPE_CHECKING:
+    from pyfect._fiber import Fiber
+
+
+@final
+class PullLoop(Effect[Never, Any, Any]):
+    """Run ``pull`` again and again, handing each item to ``step``, until it
+    fails; the failure (``Done`` included) is the loop's."""
+
+    __slots__ = ("pull", "step")
+
+    def __init__(self, pull: Effect[Any, Any, Any], step: Callable[[Any], object]) -> None:
+        self.pull = pull
+        self.step = step
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        fiber._push(self)
+        return self.pull
+
+    def _on_success(self, value: Any, fiber: Fiber[Any, Any]) -> Step:
+        self.step(value)
+        fiber._push(self)
+        return self.pull
+
+
+def _done(leftover: object) -> Failure[Done[Any]]:
+    return Failure(Cause((Fail(Done(leftover)),)))
+
+
+@final
+class IteratorPull(Effect[Any, Done[Any], Never]):
+    """The next item of ``iterator``; ``Done(return value)`` when it stops.
+    An exception from the iterator is a defect."""
+
+    __slots__ = ("iterator",)
+
+    def __init__(self, iterator: Iterator[Any]) -> None:
+        self.iterator = iterator
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        try:
+            return Success(next(self.iterator))
+        except StopIteration as stop:
+            return _done(stop.value)
+
+
+@final
+class ChunkPull(Effect[tuple[Any, ...], Done[Any], Never]):
+    """Up to ``size`` items of ``iterator`` as a non-empty tuple; ``Done``
+    once it stops. A generator's return value is the ``Done``'s leftover."""
+
+    __slots__ = ("ended", "generator", "iterator", "leftover", "size")
+
+    def __init__(self, iterator: Iterator[Any], size: int) -> None:
+        self.iterator = iterator
+        self.size = size
+        # Only a generator has a return value to keep; other iterators are
+        # read in C, a chunk at a time.
+        self.generator = isinstance(iterator, Generator)
+        self.ended = False
+        self.leftover: object = None
+
+    def _step(self, fiber: Fiber[Any, Any]) -> Step:
+        if self.ended:
+            return _done(self.leftover)
+        if not self.generator:
+            chunk = tuple(islice(self.iterator, self.size))
+            if len(chunk) < self.size:
+                self.ended = True
+            return Success(chunk) if chunk else _done(None)
+        items: list[Any] = []
+        try:
+            while len(items) < self.size:
+                items.append(next(self.iterator))
+        except StopIteration as stop:
+            if not items:
+                # As Effect's: the next pull asks the generator again.
+                return _done(stop.value)
+            self.ended = True
+            self.leftover = stop.value
+        return Success(tuple(items))