pyfect-dev 0.1.0__py3-none-any.whl

pyfect/channel/_text.py

@@ -0,0 +1,176 @@
+"""Text channels: decoding and encoding chunks of bytes, and splitting
+chunks of text into lines. Each reads and writes tuples (Effect's
+non-empty arrays) and passes upstream's failure and end through."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from typing import Any, Never
+
+from pyfect._core import Effect, _FailCause, _Succeed, _Suspend, _Sync
+from pyfect._js import text_decoder, text_encode
+from pyfect.cause import Cause
+from pyfect.cause import fail as fail_cause
+from pyfect.channel._base import AnyPull, end_with
+from pyfect.channel._channel import Channel, from_transform
+from pyfect.pull import catch_done, match_effect
+from pyfect.scope import CloseableScope
+
+
+def decode_text[E = Never, D = None](
+    encoding: str = "utf-8", *, fatal: bool = False, ignore_bom: bool = False
+) -> Channel[tuple[str, ...], E, D, tuple[bytes, ...], E, D]:
+    """Decode chunks of bytes, keeping a character split across chunks
+    whole. Bad bytes become U+FFFD, or a defect with ``fatal``. A UTF-8
+    byte-order mark is dropped unless ``ignore_bom`` (WHATWG
+    ``TextDecoder``)."""
+
+    def transform(upstream: AnyPull, _scope: CloseableScope) -> Effect[AnyPull]:
+        def build() -> AnyPull:
+            decoder = text_decoder(encoding, fatal=fatal, ignore_bom=ignore_bom)
+            pull: AnyPull
+
+            def decoded(chunks: tuple[bytes, ...]) -> tuple[str, ...]:
+                return tuple(decoder.decode(chunk) for chunk in chunks)
+
+            def flush(leftover: Any) -> AnyPull:
+                nonlocal pull
+                pull = end_with(leftover)
+                last = decoder.decode(b"", final=True)
+                return _Succeed((last,)) if last else pull
+
+            pull = catch_done(upstream.map(decoded), flush)
+            return _Suspend(lambda: pull)
+
+        return _Sync(build)
+
+    channel: Channel[tuple[str, ...], E, D, tuple[bytes, ...], E, D] = from_transform(transform)
+    return channel
+
+
+def encode_text[E = Never, D = None]() -> Channel[tuple[bytes, ...], E, D, tuple[str, ...], E, D]:
+    """Encode chunks of text as UTF-8."""
+
+    def encoded(chunks: tuple[str, ...]) -> tuple[bytes, ...]:
+        return tuple(text_encode(chunk) for chunk in chunks)
+
+    channel: Channel[tuple[bytes, ...], E, D, tuple[str, ...], E, D] = from_transform(
+        lambda upstream, _scope: _Succeed(upstream.map(encoded))
+    )
+    return channel
+
+
+class _LineSplitter:
+    """Splits text into lines at ``\\n``, ``\\r\\n`` and ``\\r``, carrying an
+    unfinished line (and a ``\\r`` that may start a ``\\r\\n``) across
+    chunks."""
+
+    __slots__ = ("_pending", "mid_crlf", "pending_length")
+
+    def __init__(self) -> None:
+        self._pending: list[str] = []  # pieces, joined once the line ends: linear time
+        self.pending_length = 0
+        self.mid_crlf = False
+
+    def _line(self, end: str) -> str:
+        if not self._pending:
+            return end
+        self._pending.append(end)
+        line = "".join(self._pending)
+        self._pending = []
+        self.pending_length = 0
+        return line
+
+    def split(self, chunks: tuple[str, ...]) -> tuple[str, ...]:
+        lines: list[str] = []
+        for text in chunks:
+            if not text:
+                continue
+            start = 0
+            if self.mid_crlf:
+                if text.startswith("\n"):
+                    start = 1
+                self.mid_crlf = False
+            while True:
+                cr = text.find("\r", start)
+                lf = text.find("\n", start)
+                if cr == -1 and lf == -1:
+                    break
+                if cr == -1 or (lf != -1 and lf < cr):
+                    lines.append(self._line(text[start:lf]))
+                    start = lf + 1
+                else:
+                    lines.append(self._line(text[start:cr]))
+                    if cr + 1 == len(text):
+                        self.mid_crlf = True
+                        start = len(text)
+                    else:
+                        start = cr + (2 if lf == cr + 1 else 1)
+            if start < len(text):
+                self._pending.append(text[start:])
+                self.pending_length += len(text) - start
+        return tuple(lines)
+
+    def flush(self) -> str:
+        last = self._line("")
+        self.mid_crlf = False
+        return last
+
+
+class LineTooLongError(Exception):
+    """A line passed ``split_lines_within``'s limit."""
+
+    def __init__(self, max_length: int) -> None:
+        super().__init__(f"Line exceeds {max_length} characters")
+        self.max_length = max_length
+
+
+def _splitter(max_length: int | None) -> Channel[Any, Any, Any, Any, Any, Any, Any]:
+    def transform(upstream: AnyPull, _scope: CloseableScope) -> Effect[AnyPull]:
+        def build() -> AnyPull:
+            lines = _LineSplitter()
+            ended: list[Any] = []
+
+            def written(chunks: tuple[str, ...]) -> AnyPull:
+                split = lines.split(chunks)
+                if max_length is not None and (
+                    lines.pending_length > max_length
+                    or any(len(line) > max_length for line in split)
+                ):
+                    return _FailCause(fail_cause(LineTooLongError(max_length)))
+                return _Succeed(split) if split else pull_or_flush
+
+            def done(leftover: Any) -> AnyPull:
+                ended.append(leftover)
+                last = lines.flush()
+                return _Succeed((last,)) if last else end_with(leftover)
+
+            def failed(cause: Cause[Any]) -> AnyPull:
+                return _FailCause(cause)
+
+            def next_pull() -> AnyPull:
+                if ended:
+                    return end_with(ended[0])
+                return match_effect(upstream, on_success=written, on_failure=failed, on_done=done)
+
+            pull_or_flush = _Suspend(next_pull)
+            return pull_or_flush
+
+        return _Sync(build)
+
+    return from_transform(transform)
+
+
+def split_lines[E = Never, D = None]() -> Channel[tuple[str, ...], E, D, tuple[str, ...], E, D]:
+    """Split chunks of text into lines, without their line breaks; the
+    text after the last break is the last line."""
+    return _splitter(None)
+
+
+def split_lines_within[E = Never, D = None](
+    max_length: int,
+) -> Channel[tuple[str, ...], E | LineTooLongError, D, tuple[str, ...], E, D]:
+    """``split_lines`` for text from a peer you do not control: a line
+    longer than ``max_length`` characters fails with ``LineTooLongError``
+    as soon as that much of it has arrived, so memory stays bounded."""
+    return _splitter(max_length)

pyfect/channel/_transform_methods.py

@@ -0,0 +1,415 @@
+"""``Channel`` methods that transform what a channel writes or how it ends:
+mapping, flat-mapping, filtering, folding, concatenating and piping."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any, Never, TypeIs, overload
+
+from pyfect.channel._base import (
+    ChannelBase,
+    Env_co,
+    InDone_contra,
+    InElem_contra,
+    InErr_contra,
+    OutDone_co,
+    OutElem_co,
+    OutErr_co,
+    require_channel,
+)
+
+if TYPE_CHECKING:
+    from pyfect._concurrency import Concurrency
+    from pyfect._core import Effect
+    from pyfect.channel._channel import Channel
+    from pyfect.errors import Done
+    from pyfect.pull import Pull
+    from pyfect.result import Result
+    from pyfect.take import Take
+
+
+class TransformMethods(
+    ChannelBase[
+        OutElem_co, OutErr_co, OutDone_co, InElem_contra, InErr_contra, InDone_contra, Env_co
+    ]
+):
+    __slots__ = ()
+
+    # --- mapping ------------------------------------------------------------
+
+    def map[B](
+        self, f: Callable[[OutElem_co], B]
+    ) -> Channel[B, OutErr_co, OutDone_co, InElem_contra, InErr_contra, InDone_contra, Env_co]:
+        """Apply ``f`` to each item written."""
+        from pyfect.channel import _combinators
+
+        return _combinators.map_(self, f)
+
+    def map_effect[B, E2 = Never, R2 = Never](
+        self,
+        f: Callable[[OutElem_co], Effect[B, E2, R2]],
+        *,
+        concurrency: Concurrency = None,
+        unordered: bool = False,
+    ) -> Channel[
+        B, OutErr_co | E2, OutDone_co, InElem_contra, InErr_contra, InDone_contra, Env_co | R2
+    ]:
+        """Write what ``f(item)`` succeeds with, failing with its error.
+        With ``concurrency`` above 1, up to that many run at once; their
+        results keep upstream's order unless ``unordered``."""
+        from pyfect.channel import _combinators
+
+        return _combinators.map_effect(self, f, concurrency, unordered=unordered)
+
+    def tap[E2 = Never, R2 = Never](
+        self, f: Callable[[OutElem_co], Effect[object, E2, R2]], *, concurrency: Concurrency = None
+    ) -> Channel[
+        OutElem_co,
+        OutErr_co | E2,
+        OutDone_co,
+        InElem_contra,
+        InErr_contra,
+        InDone_contra,
+        Env_co | R2,
+    ]:
+        """Run ``f`` on each item, then write the item."""
+        from pyfect.channel import _combinators
+
+        return _combinators.map_effect(self, lambda a: f(a).as_(a), concurrency)
+
+    def map_done[D2](
+        self, f: Callable[[OutDone_co], D2]
+    ) -> Channel[OutElem_co, OutErr_co, D2, InElem_contra, InErr_contra, InDone_contra, Env_co]:
+        """Apply ``f`` to the value the channel ends with."""
+        from pyfect.channel import _combinators
+
+        return _combinators.map_done(self, f)
+
+    def map_done_effect[D2, E2 = Never, R2 = Never](
+        self, f: Callable[[OutDone_co], Effect[D2, E2, R2]]
+    ) -> Channel[
+        OutElem_co, OutErr_co | E2, D2, InElem_contra, InErr_contra, InDone_contra, Env_co | R2
+    ]:
+        """End with what ``f(done)`` succeeds with, or fail with its error."""
+        from pyfect.channel import _combinators
+
+        return _combinators.map_done_effect(self, f)
+
+    def map_input[I2, R2 = Never](
+        self, f: Callable[[I2], Effect[InElem_contra, InErr_contra, R2]]
+    ) -> Channel[OutElem_co, OutErr_co, OutDone_co, I2, InErr_contra, InDone_contra, Env_co | R2]:
+        """Read upstream items through ``f``."""
+        from pyfect.channel import _combinators
+
+        return _combinators.map_input(self, f)
+
+    def map_input_error[IE2, R2 = Never](
+        self, f: Callable[[IE2], Effect[InErr_contra, InErr_contra, R2]]
+    ) -> Channel[OutElem_co, OutErr_co, OutDone_co, InElem_contra, IE2, InDone_contra, Env_co | R2]:
+        """Read upstream's failures through ``f``; the channel sees the
+        error ``f`` succeeds or fails with."""
+        from pyfect.channel import _combinators
+
+        return _combinators.map_input_error(self, f)
+
+    # --- flat-mapping ---------------------------------------------------------
+
+    def flat_map[O2, E2 = Never, R2 = Never](
+        self,
+        f: Callable[
+            [OutElem_co], Channel[O2, E2, Any, InElem_contra, InErr_contra, InDone_contra, R2]
+        ],
+        *,
+        concurrency: Concurrency = None,
+        buffer_size: int = 16,
+    ) -> Channel[
+        O2, OutErr_co | E2, OutDone_co, InElem_contra, InErr_contra, InDone_contra, Env_co | R2
+    ]:
+        """Write the items of ``f(item)`` for each item, one channel after
+        another; with ``concurrency`` above 1, up to that many at once,
+        their items merged through a buffer of ``buffer_size``."""
+        from pyfect.channel import _combinators, _merge
+
+        if _combinators.is_sequential(concurrency):
+            return _combinators.flat_map(self, f)
+        return _merge.merge_all(_combinators.map_(self, f), concurrency, buffer_size, switch=False)
+
+    def flatten[O2, E, D, I, IE, ID, R, E2 = Never, R2 = Never](
+        self: TransformMethods[Channel[O2, E2, Any, I, IE, ID, R2], E, D, I, IE, ID, R],
+    ) -> Channel[O2, E | E2, D, I, IE, ID, R | R2]:
+        """Write the items of each channel this channel writes, in turn."""
+        from pyfect.channel import _combinators
+
+        return _combinators.flat_map(self, _identity)
+
+    def flatten_array[A, E, D, I, IE, ID, R](
+        self: TransformMethods[Sequence[A], E, D, I, IE, ID, R],
+    ) -> Channel[A, E, D, I, IE, ID, R]:
+        """Write the items of each sequence one by one."""
+        from pyfect.channel import _filters
+
+        return _filters.flatten_array(self)
+
+    def flatten_take[A, E, D, I, IE, ID, R, E2 = Never, D2 = None](
+        self: TransformMethods[Take[A, E2, D2], E, D, I, IE, ID, R],
+    ) -> Channel[tuple[A, ...], E | E2, D2, I, IE, ID, R]:
+        """Replay each ``Take``: write its items, or fail or end as it says."""
+        from pyfect.channel import _combinators
+        from pyfect.take import to_pull
+
+        return _combinators.map_effect(self, to_pull, None)
+
+    def drain(
+        self,
+    ) -> Channel[Never, OutErr_co, OutDone_co, InElem_contra, InErr_contra, InDone_contra, Env_co]:
+        """Run the channel for its effects, writing nothing."""
+        from pyfect.channel import _combinators
+
+        return _combinators.drain(self)
+
+    # --- filtering and folding ------------------------------------------------
+
+    @overload
+    def filter[B](
+        self, predicate: Callable[[OutElem_co], TypeIs[B]]
+    ) -> Channel[B, OutErr_co, OutDone_co, InElem_contra, InErr_contra, InDone_contra, Env_co]: ...
+    @overload
+    def filter(
+        self, predicate: Callable[[OutElem_co], bool]
+    ) -> Channel[
+        OutElem_co, OutErr_co, OutDone_co, InElem_contra, InErr_contra, InDone_contra, Env_co
+    ]: ...
+    def filter(
+        self, predicate: Callable[[Any], bool]
+    ) -> Channel[Any, Any, Any, Any, Any, Any, Any]:
+        """Write only the items that pass ``predicate``."""
+        from pyfect.channel import _filters
+
+        return _filters.filter_(self, predicate)
+
+    def filter_effect[E2 = Never, R2 = Never](
+        self, predicate: Callable[[OutElem_co], Effect[bool, E2, R2]]
+    ) -> Channel[
+        OutElem_co,
+        OutErr_co | E2,
+        OutDone_co,
+        InElem_contra,
+        InErr_contra,
+        InDone_contra,
+        Env_co | R2,
+    ]:
+        """Write only the items whose ``predicate`` succeeds with ``True``."""
+        from pyfect.channel import _filters
+
+        return _filters.filter_effect(self, predicate)
+
+    def filter_array[A, E, D, I, IE, ID, R](
+        self: TransformMethods[tuple[A, ...], E, D, I, IE, ID, R], predicate: Callable[[A], bool]
+    ) -> Channel[tuple[A, ...], E, D, I, IE, ID, R]:
+        """Keep the items of each tuple that pass ``predicate``, skipping
+        tuples left empty."""
+        from pyfect.channel import _filters
+
+        return _filters.filter_array(self, predicate)
+
+    def filter_array_effect[A, E, D, I, IE, ID, R, E2 = Never, R2 = Never](
+        self: TransformMethods[tuple[A, ...], E, D, I, IE, ID, R],
+        predicate: Callable[[A], Effect[bool, E2, R2]],
+    ) -> Channel[tuple[A, ...], E | E2, D, I, IE, ID, R | R2]:
+        """``filter_array`` with an effectful ``predicate``."""
+        from pyfect.channel import _filters
+
+        return _filters.filter_array_effect(self, predicate)
+
+    def filter_map[B](
+        self, f: Callable[[OutElem_co], Result[B, object]]
+    ) -> Channel[B, OutErr_co, OutDone_co, InElem_contra, InErr_contra, InDone_contra, Env_co]:
+        """Write ``value`` for each item ``f`` maps to ``Ok(value)``; skip
+        the items it maps to ``Err``."""
+        from pyfect.channel import _filters
+
+        return _filters.filter_map(self, f)
+
+    def filter_map_effect[B, E2 = Never, R2 = Never](
+        self, f: Callable[[OutElem_co], Effect[Result[B, object], E2, R2]]
+    ) -> Channel[
+        B, OutErr_co | E2, OutDone_co, InElem_contra, InErr_contra, InDone_contra, Env_co | R2
+    ]:
+        """``filter_map`` with an effectful ``f``."""
+        from pyfect.channel import _filters
+
+        return _filters.filter_map_effect(self, f)
+
+    def filter_map_array[A, B, E, D, I, IE, ID, R](
+        self: TransformMethods[tuple[A, ...], E, D, I, IE, ID, R],
+        f: Callable[[A], Result[B, object]],
+    ) -> Channel[tuple[B, ...], E, D, I, IE, ID, R]:
+        """``filter_map`` on the items of each tuple, skipping tuples left
+        empty."""
+        from pyfect.channel import _filters
+
+        return _filters.filter_map_array(self, f)
+
+    def filter_map_array_effect[A, B, E, D, I, IE, ID, R, E2 = Never, R2 = Never](
+        self: TransformMethods[tuple[A, ...], E, D, I, IE, ID, R],
+        f: Callable[[A], Effect[Result[B, object], E2, R2]],
+    ) -> Channel[tuple[B, ...], E | E2, D, I, IE, ID, R | R2]:
+        """``filter_map_array`` with an effectful ``f``."""
+        from pyfect.channel import _filters
+
+        return _filters.filter_map_array_effect(self, f)
+
+    def scan[S](
+        self, initial: S, f: Callable[[S, OutElem_co], S]
+    ) -> Channel[S, OutErr_co, OutDone_co, InElem_contra, InErr_contra, InDone_contra, Env_co]:
+        """Write ``initial``, then each state ``f`` folds the items into."""
+        from pyfect.channel import _filters
+        from pyfect.effect import sync
+
+        return _filters.scan_effect(self, initial, lambda s, a: sync(lambda: f(s, a)))
+
+    def scan_effect[S, E2 = Never, R2 = Never](
+        self, initial: S, f: Callable[[S, OutElem_co], Effect[S, E2, R2]]
+    ) -> Channel[
+        S, OutErr_co | E2, OutDone_co, InElem_contra, InErr_contra, InDone_contra, Env_co | R2
+    ]:
+        """``scan`` with an effectful ``f``."""
+        from pyfect.channel import _filters
+
+        return _filters.scan_effect(self, initial, f)
+
+    @overload
+    def map_accum[S, B](
+        self,
+        initial: Callable[[], S],
+        f: Callable[[S, OutElem_co], tuple[S, Sequence[B]]],
+        *,
+        on_halt: Callable[[S], Sequence[B]] | None = None,
+    ) -> Channel[B, OutErr_co, OutDone_co, InElem_contra, InErr_contra, InDone_contra, Env_co]: ...
+    @overload
+    def map_accum[S, B, E2 = Never, R2 = Never](
+        self,
+        initial: Callable[[], S],
+        f: Callable[[S, OutElem_co], Effect[tuple[S, Sequence[B]], E2, R2]],
+        *,
+        on_halt: Callable[[S], Sequence[B]] | None = None,
+    ) -> Channel[
+        B, OutErr_co | E2, OutDone_co, InElem_contra, InErr_contra, InDone_contra, Env_co | R2
+    ]: ...
+    def map_accum(
+        self,
+        initial: Callable[[], Any],
+        f: Callable[[Any, Any], Any],
+        *,
+        on_halt: Callable[[Any], Sequence[Any]] | None = None,
+    ) -> Channel[Any, Any, Any, Any, Any, Any, Any]:
+        """Thread a state through the items: ``f(state, item)`` gives the
+        next state and the items to write (or an effect of both). When
+        upstream stops, ``on_halt(state)`` gives the last items to write."""
+        from pyfect.channel import _filters
+
+        return _filters.map_accum(self, initial, f, on_halt)
+
+    # --- sequencing -----------------------------------------------------------
+
+    def concat_with[O2, E2 = Never, D2 = None, R2 = Never](
+        self,
+        f: Callable[
+            [OutDone_co], Channel[O2, E2, D2, InElem_contra, InErr_contra, InDone_contra, R2]
+        ],
+    ) -> Channel[
+        OutElem_co | O2, OutErr_co | E2, D2, InElem_contra, InErr_contra, InDone_contra, Env_co | R2
+    ]:
+        """When this channel ends, go on with ``f(done)`` on the same
+        upstream. This channel's resources are released first."""
+        from pyfect.channel import _combinators
+
+        return _combinators.concat_with(self, f)
+
+    def concat[O2, E2 = Never, D2 = None, R2 = Never](
+        self, that: Channel[O2, E2, D2, InElem_contra, InErr_contra, InDone_contra, R2]
+    ) -> Channel[
+        OutElem_co | O2, OutErr_co | E2, D2, InElem_contra, InErr_contra, InDone_contra, Env_co | R2
+    ]:
+        """Write this channel's items, then ``that``'s, ending as ``that``."""
+        from pyfect.channel import _combinators
+
+        require_channel(that, "that")
+        return _combinators.concat_with(self, lambda _: that)
+
+    def or_else_if_empty[O2, E2 = Never, D2 = None, R2 = Never](
+        self,
+        f: Callable[
+            [OutDone_co], Channel[O2, E2, D2, InElem_contra, InErr_contra, InDone_contra, R2]
+        ],
+    ) -> Channel[
+        OutElem_co | O2,
+        OutErr_co | E2,
+        OutDone_co | D2,
+        InElem_contra,
+        InErr_contra,
+        InDone_contra,
+        Env_co | R2,
+    ]:
+        """Go on with ``f(done)`` if this channel ends without writing."""
+        from pyfect.channel import _combinators
+
+        return _combinators.or_else_if_empty(self, f)
+
+    @overload
+    def combine[O2, E2, D2, S, B, L = None, RR = Never](
+        self,
+        that: Channel[O2, E2, D2, InElem_contra, InErr_contra, InDone_contra, RR],
+        initial: Callable[[], S],
+        f: Callable[
+            [S, Pull[OutElem_co, OutErr_co, OutDone_co], Pull[O2, E2, D2]],
+            Effect[tuple[B, S], Done[L], RR],
+        ],
+    ) -> Channel[B, Never, L, InElem_contra, InErr_contra, InDone_contra, Env_co | RR]: ...
+    @overload
+    def combine[O2, E2, D2, S, B, L = None, EE = Never, RR = Never](
+        self,
+        that: Channel[O2, E2, D2, InElem_contra, InErr_contra, InDone_contra, RR],
+        initial: Callable[[], S],
+        f: Callable[
+            [S, Pull[OutElem_co, OutErr_co, OutDone_co], Pull[O2, E2, D2]],
+            Effect[tuple[B, S], EE | Done[L], RR],
+        ],
+    ) -> Channel[B, EE, L, InElem_contra, InErr_contra, InDone_contra, Env_co | RR]: ...
+    def combine(
+        self,
+        that: Channel[Any, Any, Any, Any, Any, Any, Any],
+        initial: Callable[[], Any],
+        f: Callable[[Any, Any, Any], Effect[tuple[Any, Any], Any, Any]],
+    ) -> Channel[Any, Any, Any, Any, Any, Any, Any]:
+        """Write what ``f(state, left, right)`` makes from the two pulls,
+        threading its state. ``f`` ends the channel by failing with
+        ``Done``."""
+        from pyfect.channel import _combinators
+
+        require_channel(that, "that")
+        return _combinators.combine(self, that, initial, f)
+
+    def pipe_to[O2, E2 = Never, D2 = None, R2 = Never](
+        self, that: Channel[O2, E2, D2, OutElem_co, OutErr_co, OutDone_co, R2]
+    ) -> Channel[O2, E2, D2, InElem_contra, InErr_contra, InDone_contra, Env_co | R2]:
+        """Feed this channel's output to ``that`` as its upstream."""
+        from pyfect.channel import _combinators
+
+        require_channel(that, "that")
+        return _combinators.pipe_to(self, that)
+
+    def pipe_to_or_fail[O2, E2 = Never, D2 = None, R2 = Never](
+        self, that: Channel[O2, E2, D2, OutElem_co, Never, OutDone_co, R2]
+    ) -> Channel[O2, OutErr_co | E2, D2, InElem_contra, InErr_contra, InDone_contra, Env_co | R2]:
+        """``pipe_to`` for a ``that`` that cannot see upstream failures: they
+        pass through ``that`` untouched (its error handlers never see them)
+        and fail the channel."""
+        from pyfect.channel import _upstream
+
+        require_channel(that, "that")
+        return _upstream.pipe_to_or_fail(self, that)
+
+
+def _identity[T](value: T) -> T:
+    return value

pyfect/channel/_upstream.py

@@ -0,0 +1,67 @@
+"""``pipe_to_or_fail``: piping into a channel that must not see upstream
+failures.
+
+Upstream's failure reaches the downstream channel as a defect,
+``Die(Done(cause))``, which no typed handler catches; once the downstream
+pull fails, the defect is unwrapped back into the original cause.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from pyfect._core import Effect, _FailCause
+from pyfect.cause import Cause, Die, Reason, from_reasons
+from pyfect.cause import die as die_cause
+from pyfect.channel._base import AnyChannel, AnyPull, is_done
+from pyfect.channel._channel import Channel, from_transform
+from pyfect.errors import Done
+from pyfect.pull import is_done_cause
+from pyfect.scope import CloseableScope
+
+
+def _hidden(reason: Reason[Any]) -> Cause[Any] | None:
+    """The upstream cause ``reason`` hides, if it is a hidden one."""
+    if isinstance(reason, Die) and is_done(reason.defect):
+        value: object = reason.defect.value
+        return cast("Cause[Any]", value) if isinstance(value, Cause) else None
+    return None
+
+
+def has_upstream_failure(cause: Cause[Any]) -> bool:
+    return any(_hidden(reason) is not None for reason in cause.reasons)
+
+
+def upstream_failure_to_defect(pull: AnyPull) -> AnyPull:
+    def hide(cause: Cause[Any]) -> AnyPull:
+        return _FailCause(cause if is_done_cause(cause) else die_cause(Done(cause)))
+
+    return pull.catch_cause(hide)
+
+
+def unwrap_upstream_failure(cause: Cause[Any]) -> Cause[Any]:
+    if not has_upstream_failure(cause):
+        return cause
+    reasons: list[Reason[Any]] = []
+    for reason in cause.reasons:
+        hidden = _hidden(reason)
+        reasons.extend((reason,) if hidden is None else hidden.reasons)
+    return from_reasons(reasons)
+
+
+def restore_upstream_failure(pull: AnyPull) -> AnyPull:
+    return pull.catch_cause(lambda cause: _FailCause(unwrap_upstream_failure(cause)))
+
+
+def pipe_to_or_fail(
+    self: AnyChannel, that: AnyChannel
+) -> Channel[Any, Any, Any, Any, Any, Any, Any]:
+    def transform(upstream: AnyPull, scope: CloseableScope) -> Effect[AnyPull]:
+        return self._transform(upstream, scope).flat_map(
+            lambda pull: that._transform(upstream_failure_to_defect(pull), scope).map(
+                restore_upstream_failure
+            )
+        )
+
+    return from_transform(transform)