pyfect-dev 0.1.0__py3-none-any.whl

pyfect/_all.py

@@ -0,0 +1,242 @@
+"""``all`` and ``all_dict``: run several effects and collect the results.
+
+Both run like ``for_each`` (``concurrency`` included). ``discard=True``
+keeps no values. ``mode="result"`` runs every effect to the end and
+collects each outcome as ``Ok`` / ``Err``, so the combined effect has no
+typed errors (defects and interruptions still propagate).
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any, Literal, Never, overload
+
+from pyfect._concurrency import Concurrency, for_each
+from pyfect._core import Effect, _Suspend
+from pyfect._effect_args import require_effects
+from pyfect.result import Result
+
+type Mode = Literal["default", "result"]
+
+
+@overload
+def all[A1, EE = Never, RR = Never](
+    e1: Effect[A1, EE, RR],
+    /,
+    *,
+    concurrency: Concurrency = None,
+    discard: Literal[False] = False,
+    mode: Literal["default"] = "default",
+) -> Effect[tuple[A1], EE, RR]: ...
+@overload
+def all[A1, A2, EE = Never, RR = Never](
+    e1: Effect[A1, EE, RR],
+    e2: Effect[A2, EE, RR],
+    /,
+    *,
+    concurrency: Concurrency = None,
+    discard: Literal[False] = False,
+    mode: Literal["default"] = "default",
+) -> Effect[tuple[A1, A2], EE, RR]: ...
+@overload
+def all[A1, A2, A3, EE = Never, RR = Never](
+    e1: Effect[A1, EE, RR],
+    e2: Effect[A2, EE, RR],
+    e3: Effect[A3, EE, RR],
+    /,
+    *,
+    concurrency: Concurrency = None,
+    discard: Literal[False] = False,
+    mode: Literal["default"] = "default",
+) -> Effect[tuple[A1, A2, A3], EE, RR]: ...
+@overload
+def all[A1, A2, A3, A4, EE = Never, RR = Never](
+    e1: Effect[A1, EE, RR],
+    e2: Effect[A2, EE, RR],
+    e3: Effect[A3, EE, RR],
+    e4: Effect[A4, EE, RR],
+    /,
+    *,
+    concurrency: Concurrency = None,
+    discard: Literal[False] = False,
+    mode: Literal["default"] = "default",
+) -> Effect[tuple[A1, A2, A3, A4], EE, RR]: ...
+@overload
+def all[A1, A2, A3, A4, A5, EE = Never, RR = Never](
+    e1: Effect[A1, EE, RR],
+    e2: Effect[A2, EE, RR],
+    e3: Effect[A3, EE, RR],
+    e4: Effect[A4, EE, RR],
+    e5: Effect[A5, EE, RR],
+    /,
+    *,
+    concurrency: Concurrency = None,
+    discard: Literal[False] = False,
+    mode: Literal["default"] = "default",
+) -> Effect[tuple[A1, A2, A3, A4, A5], EE, RR]: ...
+@overload
+def all[A, EE = Never, RR = Never](
+    *effects: Effect[A, EE, RR],
+    concurrency: Concurrency = None,
+    discard: Literal[False] = False,
+    mode: Literal["default"] = "default",
+) -> Effect[tuple[A, ...], EE, RR]: ...
+@overload
+def all[A1, EE = Never, RR = Never](
+    e1: Effect[A1, EE, RR],
+    /,
+    *,
+    concurrency: Concurrency = None,
+    discard: Literal[False] = False,
+    mode: Literal["result"],
+) -> Effect[tuple[Result[A1, EE]], Never, RR]: ...
+@overload
+def all[A1, A2, EE = Never, RR = Never](
+    e1: Effect[A1, EE, RR],
+    e2: Effect[A2, EE, RR],
+    /,
+    *,
+    concurrency: Concurrency = None,
+    discard: Literal[False] = False,
+    mode: Literal["result"],
+) -> Effect[tuple[Result[A1, EE], Result[A2, EE]], Never, RR]: ...
+@overload
+def all[A1, A2, A3, EE = Never, RR = Never](
+    e1: Effect[A1, EE, RR],
+    e2: Effect[A2, EE, RR],
+    e3: Effect[A3, EE, RR],
+    /,
+    *,
+    concurrency: Concurrency = None,
+    discard: Literal[False] = False,
+    mode: Literal["result"],
+) -> Effect[tuple[Result[A1, EE], Result[A2, EE], Result[A3, EE]], Never, RR]: ...
+@overload
+def all[A1, A2, A3, A4, EE = Never, RR = Never](
+    e1: Effect[A1, EE, RR],
+    e2: Effect[A2, EE, RR],
+    e3: Effect[A3, EE, RR],
+    e4: Effect[A4, EE, RR],
+    /,
+    *,
+    concurrency: Concurrency = None,
+    discard: Literal[False] = False,
+    mode: Literal["result"],
+) -> Effect[tuple[Result[A1, EE], Result[A2, EE], Result[A3, EE], Result[A4, EE]], Never, RR]: ...
+@overload
+def all[A1, A2, A3, A4, A5, EE = Never, RR = Never](
+    e1: Effect[A1, EE, RR],
+    e2: Effect[A2, EE, RR],
+    e3: Effect[A3, EE, RR],
+    e4: Effect[A4, EE, RR],
+    e5: Effect[A5, EE, RR],
+    /,
+    *,
+    concurrency: Concurrency = None,
+    discard: Literal[False] = False,
+    mode: Literal["result"],
+) -> Effect[
+    tuple[Result[A1, EE], Result[A2, EE], Result[A3, EE], Result[A4, EE], Result[A5, EE]],
+    Never,
+    RR,
+]: ...
+@overload
+def all[A, EE = Never, RR = Never](
+    *effects: Effect[A, EE, RR],
+    concurrency: Concurrency = None,
+    discard: Literal[False] = False,
+    mode: Literal["result"],
+) -> Effect[tuple[Result[A, EE], ...], Never, RR]: ...
+@overload
+def all[EE = Never, RR = Never](
+    *effects: Effect[object, EE, RR],
+    concurrency: Concurrency = None,
+    discard: Literal[True],
+    mode: Literal["default"] = "default",
+) -> Effect[None, EE, RR]: ...
+@overload
+def all[RR = Never](
+    *effects: Effect[object, object, RR],
+    concurrency: Concurrency = None,
+    discard: Literal[True],
+    mode: Literal["result"],
+) -> Effect[None, Never, RR]: ...
+def all(
+    *effects: Effect[Any, Any, Any],
+    concurrency: Concurrency = None,
+    discard: bool = False,
+    mode: Mode = "default",
+) -> Effect[Any, Any, Any]:
+    """Run effects and collect their results as a tuple, in order."""
+    require_effects(effects, "effects")
+    collected = for_each(effects, _step_for(mode), concurrency=concurrency)
+    return collected.as_void() if discard else collected.map(tuple)
+
+
+@overload
+def all_dict[K, A, EE = Never, RR = Never](
+    effects: Mapping[K, Effect[A, EE, RR]],
+    *,
+    concurrency: Concurrency = None,
+    discard: Literal[False] = False,
+    mode: Literal["default"] = "default",
+) -> Effect[dict[K, A], EE, RR]: ...
+@overload
+def all_dict[K, A, EE = Never, RR = Never](
+    effects: Mapping[K, Effect[A, EE, RR]],
+    *,
+    concurrency: Concurrency = None,
+    discard: Literal[False] = False,
+    mode: Literal["result"],
+) -> Effect[dict[K, Result[A, EE]], Never, RR]: ...
+@overload
+def all_dict[EE = Never, RR = Never](
+    effects: Mapping[Any, Effect[object, EE, RR]],
+    *,
+    concurrency: Concurrency = None,
+    discard: Literal[True],
+    mode: Literal["default"] = "default",
+) -> Effect[None, EE, RR]: ...
+@overload
+def all_dict[RR = Never](
+    effects: Mapping[Any, Effect[object, object, RR]],
+    *,
+    concurrency: Concurrency = None,
+    discard: Literal[True],
+    mode: Literal["result"],
+) -> Effect[None, Never, RR]: ...
+def all_dict(
+    effects: Mapping[Any, Effect[Any, Any, Any]],
+    *,
+    concurrency: Concurrency = None,
+    discard: bool = False,
+    mode: Mode = "default",
+) -> Effect[Any, Any, Any]:
+    """Run the effects in a mapping and collect their results under the
+    same keys, in the mapping's order. The mapping is read each time the
+    effect runs."""
+    step = _step_for(mode)
+
+    def start() -> Effect[Any, Any, Any]:
+        keys = list(effects)
+        collected = for_each([effects[k] for k in keys], step, concurrency=concurrency)
+        if discard:
+            return collected.as_void()
+        return collected.map(lambda values: dict(zip(keys, values, strict=True)))
+
+    return _Suspend(start)
+
+
+def _step_for(
+    mode: Mode,
+) -> Callable[[Effect[Any, Any, Any]], Effect[Any, Any, Any]]:
+    return _identity if mode == "default" else _as_result
+
+
+def _identity[T](x: T) -> T:
+    return x
+
+
+def _as_result(eff: Effect[Any, Any, Any]) -> Effect[Any, Never, Any]:
+    return eff.result()

pyfect/_background.py

@@ -0,0 +1,28 @@
+"""Tasks nobody awaits.
+
+asyncio keeps only weak references to tasks: one started and dropped can
+be collected while it waits ("Task was destroyed but it is pending"), its
+work cut short. ``start`` keeps the task until it ends.
+``tests/test_background_tasks.py`` bans dropping the result of
+``create_task`` / ``ensure_future`` anywhere else.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Coroutine
+from typing import Any
+
+_running: set[asyncio.Task[Any]] = set()
+
+
+def start[A](coroutine: Coroutine[Any, Any, A], loop: asyncio.AbstractEventLoop) -> asyncio.Task[A]:
+    """Run ``coroutine`` as a task of ``loop`` (called on its thread), kept
+    until it ends."""
+    task = loop.create_task(coroutine)
+    _running.add(task)
+    task.add_done_callback(_running.discard)
+    return task
+
+
+__all__ = ["start"]

pyfect/_binary_codecs.py

@@ -0,0 +1,124 @@
+"""Base64, Base64Url and hex as Effect's ``effect/encoding`` modules define
+them, below both ``pyfect.encoding`` and the schema getters (which
+``pyfect.encoding`` imports). Text input is encoded as UTF-8 first
+(``TextEncoder``); decoded text is UTF-8 with bad bytes replaced and a
+leading byte-order mark dropped (``TextDecoder``)."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import re
+from dataclasses import dataclass
+from typing import Literal
+
+from pyfect._js import text_encode
+from pyfect.errors import TaggedError
+from pyfect.result import Err, Ok, Result
+
+
+@dataclass(eq=False)
+class EncodingError(TaggedError):
+    """Encoding or decoding failed: ``module`` names the encoding,
+    ``input`` is what it was given."""
+
+    kind: Literal["Decode", "Encode"]
+    module: str
+    input: object
+    message: str
+
+    def __str__(self) -> str:
+        return self.message
+
+
+type Binary = bytes | bytearray | memoryview | str
+
+
+def _bytes(value: Binary) -> bytes:
+    return text_encode(value) if isinstance(value, str) else bytes(value)
+
+
+def utf8_text(data: bytes) -> str:
+    """``new TextDecoder().decode(data)``."""
+    return data.decode("utf-8-sig", errors="replace")
+
+
+def _fail(module: str, text: str, message: str) -> Err[EncodingError]:
+    return Err(EncodingError(kind="Decode", module=module, input=text, message=message))
+
+
+def _strip_crlf(text: str) -> str:
+    return text.replace("\r", "").replace("\n", "")
+
+
+# --- Base64 ---------------------------------------------------------------------------
+
+
+def base64_encode(value: Binary) -> str:
+    return base64.b64encode(_bytes(value)).decode("ascii")
+
+
+_BASE64_CHARS = re.compile(r"[A-Za-z0-9+/=]*")
+_BASE64_CHAR = re.compile(r"[A-Za-z0-9+/=]")
+
+
+def base64_decode(text: str) -> Result[bytes, EncodingError]:
+    """CR and LF are ignored; the length must be a multiple of 4 and ``=``
+    only ends it."""
+    stripped = _strip_crlf(text)
+    length = len(stripped)
+    if length % 4:
+        return _fail("Base64", stripped, f"Length must be a multiple of 4, but is {length}")
+    index = stripped.find("=")
+    if index != -1 and (index < length - 2 or (index == length - 2 and stripped[-1] != "=")):
+        return _fail("Base64", stripped, "Found a '=' character, but it is not at the end")
+    if not _BASE64_CHARS.fullmatch(stripped):
+        bad = next(c for c in stripped if not _BASE64_CHAR.fullmatch(c))
+        return _fail("Base64", stripped, f"Invalid character {bad}")
+    return Ok(binascii.a2b_base64(stripped))
+
+
+# --- Base64Url ------------------------------------------------------------------------
+
+_TO_URL = str.maketrans("+/", "-_")
+_TO_STANDARD = str.maketrans("-_", "+/")
+_BASE64_URL = re.compile(r"[-_A-Za-z0-9]*?={0,2}")
+
+
+def base64_url_encode(value: Binary) -> str:
+    return base64_encode(value).replace("=", "").translate(_TO_URL)
+
+
+def base64_url_encode_padded(value: Binary) -> str:
+    return base64_encode(value).translate(_TO_URL)
+
+
+def base64_url_decode(text: str) -> Result[bytes, EncodingError]:
+    """CR and LF are ignored; the URL alphabet, padded or not."""
+    stripped = _strip_crlf(text)
+    length = len(stripped)
+    if length % 4 == 1:
+        return _fail("Base64Url", stripped, f"Length should be a multiple of 4, but is {length}")
+    if not _BASE64_URL.fullmatch(stripped):
+        return _fail("Base64Url", stripped, "Invalid input")
+    padded = stripped + {2: "==", 3: "="}.get(length % 4, "")
+    return base64_decode(padded.translate(_TO_STANDARD))
+
+
+# --- Hex ------------------------------------------------------------------------------
+
+_HEX = re.compile(rb"(?:[0-9a-fA-F]{2})*")
+
+
+def hex_encode(value: Binary) -> str:
+    return _bytes(value).hex()
+
+
+def hex_decode(text: str) -> Result[bytes, EncodingError]:
+    """Two hex digits, either case, per byte."""
+    data = text_encode(text)
+    if len(data) % 2:
+        return _fail("Hex", text, f"Length must be a multiple of 2, but is {len(data)}")
+    if not _HEX.fullmatch(data):
+        return _fail("Hex", text, "Invalid input")
+    return Ok(bytes.fromhex(data.decode("ascii")))

pyfect/_cached.py

@@ -0,0 +1,165 @@
+"""``Effect.cached`` and its TTL variants.
+
+A cache runs its source on a fiber of its own (with the context of the
+caller that started it), so callers can leave without killing a run others
+still wait on. Each caller waiting on a run is counted; when the last one
+leaves before the run is done, the run is interrupted and detached, so the
+next caller starts afresh. An interrupted run is never cached.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+from typing import Any, Final
+
+from pyfect._core import (
+    Effect,
+    Frame,
+    Step,
+    _FlatMap,
+    _FromExit,
+    _SetInterruptible,
+    _Sync,
+    _WithFiber,
+)
+from pyfect._fiber import Fiber
+from pyfect.cause import Cause
+from pyfect.clock import Clock, ClockService
+from pyfect.duration import Duration, Seconds, nanos_or_infinite, to_seconds
+from pyfect.exit import Exit, Failure, Success
+
+type TimeToLive[A, E] = Duration | Callable[[Exit[A, E]], Duration]
+
+_FOREVER: Final = Seconds(math.inf)
+
+
+def cached[A, E, R](source: Effect[A, E, R]) -> Effect[Effect[A, E, R]]:
+    return _Sync(lambda: memoize(source))
+
+
+def memoize[A, E, R](source: Effect[A, E, R]) -> Effect[A, E, R]:
+    """``cached`` made now: an effect that runs ``source`` once, the first
+    time it runs, and then gives back its exit."""
+    return _Cache(source, lambda _: _FOREVER).get
+
+
+def cached_invalidate_with_ttl[A, E, R](
+    source: Effect[A, E, R], time_to_live: TimeToLive[A, E]
+) -> Effect[tuple[Effect[A, E, R], Effect[None]]]:
+    if callable(time_to_live):
+        pick = time_to_live
+
+        def ttl(ex: Exit[A, E]) -> Seconds:
+            return to_seconds(pick(ex))
+    else:
+        fixed = to_seconds(time_to_live)
+
+        def ttl(ex: Exit[A, E]) -> Seconds:
+            return fixed
+
+    def make() -> tuple[Effect[A, E, R], Effect[None]]:
+        cache = _Cache(source, ttl)
+        return cache.get, cache.invalidate
+
+    return _Sync(make)
+
+
+class _Run:
+    """One evaluation of the source, and how many callers wait on it."""
+
+    __slots__ = ("awaiters", "done", "fiber")
+
+    def __init__(self, fiber: Fiber[Any, Any]) -> None:
+        self.fiber = fiber
+        self.awaiters = 0
+        self.done = False
+
+
+class _Cache[A, E, R]:
+    __slots__ = ("current", "exit", "expires_at", "get", "invalidate", "source", "ttl")
+
+    def __init__(self, source: Effect[A, E, R], ttl: Callable[[Exit[A, E]], Seconds]) -> None:
+        self.source = source
+        self.ttl = ttl
+        self.exit: Exit[A, E] | None = None
+        self.expires_at: int | float = 0  # monotonic nanoseconds
+        self.current: _Run | None = None
+        self.get: Effect[A, E, R] = _WithFiber(self._get)
+        self.invalidate: Effect[None] = _Sync(self._invalidate)
+
+    def _get(self, fiber: Fiber[Any, Any]) -> Effect[A, E, R]:
+        run = self.current
+        if run is not None:
+            # A run reading its own cache is not an awaiter: counting it
+            # would keep the run alive after every real caller left.
+            return run.fiber.join() if run.fiber is fiber else self._join(fiber, run)
+        clock: ClockService = fiber._context.lookup(Clock)[1]
+        if self.exit is not None and (clock.monotonic_nanos_unsafe() < self.expires_at):
+            return _FromExit(self.exit)
+        self.exit = None
+        run = _Run(Fiber(fiber._run_scheduler, fiber._context, None))
+        self.current = run
+        joined = self._join(fiber, run)
+        # Started at once, as in Effect: it runs right after this fiber parks.
+        run.fiber._drive_first(
+            self.source.on_exit(lambda ex: _Sync(lambda: self._publish(run, ex, clock)))
+        )
+        return joined
+
+    def _join(self, fiber: Fiber[Any, Any], run: _Run) -> Effect[A, E, R]:
+        run.awaiters += 1
+        fiber._push(_LeaveRun(self, run))
+        return run.fiber.join()
+
+    def _publish(self, run: _Run, ex: Exit[A, E], clock: ClockService) -> None:
+        run.done = True
+        if self.current is not run:
+            return  # invalidated: callers already on it get its exit, nobody else
+        self.current = None
+        if isinstance(ex, Failure) and ex.cause.has_interrupts:
+            return  # abandoned, not a result
+        ttl = self.ttl(ex)
+        self.expires_at = clock.monotonic_nanos_unsafe() + nanos_or_infinite(ttl)
+        self.exit = ex
+
+    def leave(self, run: _Run) -> Effect[None] | None:
+        """A caller stopped waiting on ``run``. Gives the effect that
+        abandons the run if that caller was the last one."""
+        run.awaiters -= 1
+        if run.awaiters > 0 or run.done:
+            return None
+        if self.current is run:
+            self.current = None
+        return run.fiber.interrupt()
+
+    def _invalidate(self) -> None:
+        self.current = None
+        self.exit = None
+
+
+class _LeaveRun(Frame):
+    """Pushed by a caller joining a run, so leaving is counted however the
+    join ends. Abandoning the run happens uninterruptibly, then the caller
+    ends as its join did."""
+
+    __slots__ = ("cache", "run")
+
+    def __init__(self, cache: _Cache[Any, Any, Any], run: _Run) -> None:
+        self.cache = cache
+        self.run = run
+
+    def _on_success(self, value: Any, fiber: Fiber[Any, Any]) -> Step:
+        return self._leave(Success(value), fiber)
+
+    def _on_failure(self, cause: Cause[Any], fiber: Fiber[Any, Any]) -> Step:
+        return self._leave(Failure(cause), fiber)
+
+    def _leave(self, ex: Exit[Any, Any], fiber: Fiber[Any, Any]) -> Step:
+        abandon = self.cache.leave(self.run)
+        if abandon is None:
+            return ex
+        # Stepped here, not returned: an interrupted fiber would turn a
+        # returned effect into a failure before it could run.
+        return _SetInterruptible(_FlatMap(abandon, lambda _: _FromExit(ex)), False)._step(fiber)

pyfect/_catch.py

@@ -0,0 +1,128 @@
+"""Recovery that removes the caught errors from ``E``: use with ``.pipe``.
+
+``catch_tag`` catches by class (one, or a tuple of any number), ``catch_if``
+by a ``TypeIs`` refinement. Both remove exactly what they catch::
+
+    eff.pipe(catch_tag((NotFound, Invalid), lambda e: succeed(None)))
+
+``catch_all`` is the method of that name for ``.pipe`` (Effect's
+``catch``): it removes every typed error.
+
+``or_else`` handles every other error. Annotate its parameter with those
+errors (it must be a ``def``; a lambda's parameter can't be inferred here)
+and pyright checks that it covers all of them.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Never, TypeIs, overload
+
+from pyfect._core import Effect, _catching_if, _MatchCause
+from pyfect._tags import Tags
+
+
+class _CatchSome[EC, B, E2, R2]:
+    """Removes ``EC`` from an effect's errors."""
+
+    __slots__ = ("handle",)
+
+    def __init__(self, handle: Callable[[Any], Effect[Any, Any, Any]]) -> None:
+        self.handle = handle
+
+    @overload
+    def __call__[A, R = Never](self, eff: Effect[A, EC, R]) -> Effect[A | B, E2, R | R2]: ...
+    @overload
+    def __call__[A, R = Never, ER = Never](
+        self, eff: Effect[A, EC | ER, R]
+    ) -> Effect[A | B, ER | E2, R | R2]: ...
+    def __call__(self, eff: Effect[Any, Any, Any]) -> Effect[Any, Any, Any]:
+        return _MatchCause(eff, self.handle, None)
+
+
+class _CatchAll[EC, EO, B, C, EE, RR]:
+    """Handles ``EC`` with one handler and ``EO``, which must be every other
+    error of the effect, with another."""
+
+    __slots__ = ("handle",)
+
+    def __init__(self, handle: Callable[[Any], Effect[Any, Any, Any]]) -> None:
+        self.handle = handle
+
+    def __call__[A, R = Never](self, eff: Effect[A, EC | EO, R]) -> Effect[A | B | C, EE, R | RR]:
+        return _MatchCause(eff, self.handle, None)
+
+
+class _CatchEvery[E, B, E2, R2]:
+    """Handles every typed error ``E`` of an effect."""
+
+    __slots__ = ("f",)
+
+    def __init__(self, f: Callable[[E], Effect[B, E2, R2]]) -> None:
+        self.f = f
+
+    def __call__[A, R = Never](self, eff: Effect[A, E, R]) -> Effect[A | B, E2, R | R2]:
+        return eff.catch_all(self.f)
+
+
+def catch_all[E, B, E2 = Never, R2 = Never](
+    f: Callable[[E], Effect[B, E2, R2]],
+) -> _CatchEvery[E, B, E2, R2]:
+    """``eff.catch_all(f)`` for ``.pipe``: recover from every typed error.
+    Defects and interruptions pass through. Annotate ``f``'s parameter (a
+    ``def``): pyright checks it covers every error of the effect."""
+    return _CatchEvery(f)
+
+
+@overload
+def catch_if[EB, B, E2 = Never, R2 = Never](
+    refinement: Callable[[Any], TypeIs[EB]], f: Callable[[EB], Effect[B, E2, R2]]
+) -> _CatchSome[EB, B, E2, R2]: ...
+@overload
+def catch_if[EB, EO, B, C, EE = Never, RR = Never](
+    refinement: Callable[[Any], TypeIs[EB]],
+    f: Callable[[EB], Effect[B, EE, RR]],
+    *,
+    or_else: Callable[[EO], Effect[C, EE, RR]],
+) -> _CatchAll[EB, EO, B, C, EE, RR]: ...
+def catch_if(
+    refinement: Callable[[Any], bool],
+    f: Callable[[Any], Effect[Any, Any, Any]],
+    *,
+    or_else: Callable[[Any], Effect[Any, Any, Any]] | None = None,
+) -> Any:
+    """Recover from the typed errors ``refinement`` accepts and remove them
+    from ``E``. For a plain ``bool`` predicate, use the ``catch_if`` method."""
+    handle = _catching_if(refinement, f, or_else)
+    if or_else is None:
+        return _CatchSome[Any, Any, Any, Any](handle)
+    return _CatchAll[Any, Any, Any, Any, Any, Any](handle)
+
+
+@overload
+def catch_tag[T, B, E2 = Never, R2 = Never](
+    tag: Tags[T], f: Callable[[T], Effect[B, E2, R2]]
+) -> _CatchSome[T, B, E2, R2]: ...
+@overload
+def catch_tag[T, EO, B, C, EE = Never, RR = Never](
+    tag: Tags[T],
+    f: Callable[[T], Effect[B, EE, RR]],
+    *,
+    or_else: Callable[[EO], Effect[C, EE, RR]],
+) -> _CatchAll[T, EO, B, C, EE, RR]: ...
+def catch_tag(
+    tag: Tags[Any],
+    f: Callable[[Any], Effect[Any, Any, Any]],
+    *,
+    or_else: Callable[[Any], Effect[Any, Any, Any]] | None = None,
+) -> Any:
+    """Recover from the errors that are instances of ``tag`` (a class or a
+    tuple of classes) and remove them from ``E``::
+
+    eff.pipe(catch_tag(NotFound, lambda e: succeed(None)))
+    """
+    handle = _catching_if(lambda e: isinstance(e, tag), f, or_else)
+    if or_else is None:
+        return _CatchSome[Any, Any, Any, Any](handle)
+    return _CatchAll[Any, Any, Any, Any, Any, Any](handle)