pyfect-dev 0.1.0__py3-none-any.whl

pyfect/_effect_eager.py

@@ -0,0 +1,103 @@
+"""``Effect`` methods that apply at once to an effect already holding its
+exit (``succeed``, ``fail``, ``fail_cause``), and otherwise build the lazy
+form (Effect's ``*Eager`` variants)."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Never, cast
+
+from pyfect import _core
+from pyfect._effect_base import A_co, E_co, EffectBase, R_co, as_effect
+from pyfect.cause import Cause, Fail
+
+if TYPE_CHECKING:
+    from pyfect._core import Effect
+
+
+class EagerMethods(EffectBase[A_co, E_co, R_co]):
+    __slots__ = ()
+
+    def map_eager[B](self, f: Callable[[A_co], B]) -> Effect[B, E_co, R_co]:
+        effect = as_effect(self)
+        if isinstance(effect, _core._Succeed):
+            return _core._Succeed(f(effect.value))
+        return cast("Effect[B, E_co, R_co]", effect) if _failed(effect) else effect.map(f)
+
+    def map_error_eager[E2](self, f: Callable[[E_co], E2]) -> Effect[A_co, E2, R_co]:
+        effect = as_effect(self)
+        if isinstance(effect, _core._Succeed):
+            return cast("Effect[A_co, E2, R_co]", effect)
+        if isinstance(effect, _core._FailCause):
+            return _core._FailCause(effect.cause.map(f))
+        return effect.map_error(f)
+
+    def map_both_eager[B, E2](
+        self, *, on_failure: Callable[[E_co], E2], on_success: Callable[[A_co], B]
+    ) -> Effect[B, E2, R_co]:
+        effect = as_effect(self)
+        if isinstance(effect, _core._Succeed):
+            return _core._Succeed(on_success(effect.value))
+        if isinstance(effect, _core._FailCause):
+            return _core._FailCause(effect.cause.map(on_failure))
+        return effect.map_both(on_failure=on_failure, on_success=on_success)
+
+    def flat_map_eager[B, E2 = Never, R2 = Never](
+        self, f: Callable[[A_co], Effect[B, E2, R2]]
+    ) -> Effect[B, E_co | E2, R_co | R2]:
+        effect = as_effect(self)
+        if isinstance(effect, _core._Succeed):
+            return f(effect.value)
+        return cast("Effect[B, E_co, R_co]", effect) if _failed(effect) else effect.flat_map(f)
+
+    def catch_eager[B, E2 = Never, R2 = Never](
+        self, f: Callable[[E_co], Effect[B, E2, R2]]
+    ) -> Effect[A_co | B, E2, R_co | R2]:
+        effect = as_effect(self)
+        if isinstance(effect, _core._Succeed):
+            return cast("Effect[A_co, E2, R_co]", effect)
+        if isinstance(effect, _core._FailCause):
+            found = effect.cause.find_recoverable_error()
+            return f(found.error) if isinstance(found, Fail) else _core._FailCause(found)
+        return effect.catch_all(f)
+
+    def match_eager[B, C](
+        self, *, on_failure: Callable[[E_co], B], on_success: Callable[[A_co], C]
+    ) -> Effect[B | C, Never, R_co]:
+        effect = as_effect(self)
+        if isinstance(effect, _core._Succeed):
+            return _core._Succeed(on_success(effect.value))
+        if isinstance(effect, _core._FailCause):
+            found = effect.cause.find_recoverable_error()
+            if isinstance(found, Fail):
+                return _core._Succeed(on_failure(found.error))
+            return _core._FailCause(found)
+        return effect.match(on_failure=on_failure, on_success=on_success)
+
+    def match_cause_eager[B, C](
+        self, *, on_failure: Callable[[Cause[E_co]], B], on_success: Callable[[A_co], C]
+    ) -> Effect[B | C, Never, R_co]:
+        effect = as_effect(self)
+        if isinstance(effect, _core._Succeed):
+            return _core._Succeed(on_success(effect.value))
+        if isinstance(effect, _core._FailCause):
+            return _core._Succeed(on_failure(effect.cause))
+        return effect.match_cause(on_failure=on_failure, on_success=on_success)
+
+    def match_cause_effect_eager[B, C, EE = Never, RR = Never](
+        self,
+        *,
+        on_failure: Callable[[Cause[E_co]], Effect[B, EE, RR]],
+        on_success: Callable[[A_co], Effect[C, EE, RR]],
+    ) -> Effect[B | C, EE, R_co | RR]:
+        effect = as_effect(self)
+        if isinstance(effect, _core._Succeed):
+            return on_success(effect.value)
+        if isinstance(effect, _core._FailCause):
+            return on_failure(effect.cause)
+        return effect.match_cause_effect(on_failure=on_failure, on_success=on_success)
+
+
+def _failed(effect: Effect[Any, Any, Any]) -> bool:
+    return isinstance(effect, _core._FailCause)

pyfect/_effect_errors.py

@@ -0,0 +1,344 @@
+"""``Effect`` methods that handle errors: mapping, recovering from and
+tapping typed errors, defects and whole causes.
+
+Every handler is a ``_MatchCause``. Typed recovery goes through
+``_recovering``, so a defect always wins over a typed error.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Literal, Never, overload
+
+from pyfect import _core
+from pyfect._effect_base import A_co, E_co, EffectBase, R_co, as_effect
+from pyfect._tags import Tags
+from pyfect.cause import Cause, Fail
+from pyfect.cause import die as die_cause
+from pyfect.cause import fail as fail_cause
+from pyfect.exit import Success
+from pyfect.result import Err, Ok, Result
+
+if TYPE_CHECKING:
+    from pyfect._core import Effect
+    from pyfect._fiber import Fiber
+    from pyfect.logger import Severity
+
+
+class ErrorMethods(EffectBase[A_co, E_co, R_co]):
+    __slots__ = ()
+
+    def map_error[E2](self, f: Callable[[E_co], E2]) -> Effect[A_co, E2, R_co]:
+        def on_failure(cause: Cause[E_co]) -> Effect[Never, E2, Never]:
+            return _core._FailCause(cause.map(f))
+
+        return _core._MatchCause(as_effect(self), on_failure, None)
+
+    def map_both[B, E2](
+        self, *, on_failure: Callable[[E_co], E2], on_success: Callable[[A_co], B]
+    ) -> Effect[B, E2, R_co]:
+        """``map_error`` and ``map`` at once."""
+        return _core._MatchCause(
+            as_effect(self),
+            lambda c: _core._FailCause(c.map(on_failure)),
+            lambda a: Success(on_success(a)),
+        )
+
+    def catch_all[B, E2 = Never, R2 = Never](
+        self, f: Callable[[E_co], Effect[B, E2, R2]]
+    ) -> Effect[A_co | B, E2, R_co | R2]:
+        """Recover from every typed error. Defects and interruptions pass
+        through. To handle one error class, use ``pipe(catch_tag(...))``."""
+        return _core._MatchCause(as_effect(self), _recovering(f), None)
+
+    @overload
+    def catch_if[B, E2 = Never, R2 = Never](
+        self, predicate: Callable[[E_co], bool], f: Callable[[E_co], Effect[B, E2, R2]]
+    ) -> Effect[A_co | B, E_co | E2, R_co | R2]: ...
+    @overload
+    def catch_if[B, C, EE = Never, RR = Never](
+        self,
+        predicate: Callable[[E_co], bool],
+        f: Callable[[E_co], Effect[B, EE, RR]],
+        *,
+        or_else: Callable[[E_co], Effect[C, EE, RR]],
+    ) -> Effect[A_co | B | C, EE, R_co | RR]: ...
+    def catch_if(
+        self,
+        predicate: Callable[[Any], bool],
+        f: Callable[[Any], Effect[Any, Any, Any]],
+        *,
+        or_else: Callable[[Any], Effect[Any, Any, Any]] | None = None,
+    ) -> Effect[Any, Any, Any]:
+        """Recover from the typed errors that pass ``predicate``; ``or_else``,
+        if given, handles the rest. To remove the caught errors from ``E``,
+        use ``pipe(catch_if(refinement, ...))`` with a ``TypeIs`` refinement."""
+        return _core._MatchCause(as_effect(self), _catching_if(predicate, f, or_else), None)
+
+    @overload
+    def catch_filter[EB, B, X, E2 = Never, R2 = Never](
+        self, filter: Callable[[E_co], Result[EB, X]], f: Callable[[EB], Effect[B, E2, R2]]
+    ) -> Effect[A_co | B, E_co | E2, R_co | R2]: ...
+    @overload
+    def catch_filter[EB, X, B, C, EE = Never, RR = Never](
+        self,
+        filter: Callable[[E_co], Result[EB, X]],
+        f: Callable[[EB], Effect[B, EE, RR]],
+        *,
+        or_else: Callable[[X], Effect[C, EE, RR]],
+    ) -> Effect[A_co | B | C, EE, R_co | RR]: ...
+    def catch_filter(
+        self,
+        filter: Callable[[Any], Result[Any, Any]],
+        f: Callable[[Any], Effect[Any, Any, Any]],
+        *,
+        or_else: Callable[[Any], Effect[Any, Any, Any]] | None = None,
+    ) -> Effect[Any, Any, Any]:
+        """Recover with ``f(value)`` from a typed error ``filter`` maps to
+        ``Ok(value)``. One it maps to ``Err(rest)`` goes to ``or_else(rest)``,
+        or keeps failing with the original error."""
+
+        def handle(cause: Cause[Any]) -> Effect[Any, Any, Any]:
+            found = cause.find_recoverable_error()
+            if not isinstance(found, Fail):
+                return _core._FailCause(found)
+            match filter(found.error):
+                case Ok(value):
+                    return f(value)
+                case Err(rest):
+                    return _core._FailCause(cause) if or_else is None else or_else(rest)
+
+        return _core._MatchCause(as_effect(self), handle, None)
+
+    def catch_cause[B, E2 = Never, R2 = Never](
+        self, f: Callable[[Cause[E_co]], Effect[B, E2, R2]]
+    ) -> Effect[A_co | B, E2, R_co | R2]:
+        """Recover from any failure, including defects. Interruption still
+        wins: an interrupted fiber skips this handler."""
+        return _core._MatchCause(as_effect(self), f, None)
+
+    def catch_cause_if[B, E2 = Never, R2 = Never](
+        self,
+        predicate: Callable[[Cause[E_co]], bool],
+        f: Callable[[Cause[E_co]], Effect[B, E2, R2]],
+    ) -> Effect[A_co | B, E_co | E2, R_co | R2]:
+        """``catch_cause`` for the causes that pass ``predicate``."""
+        return _core._MatchCause(
+            as_effect(self), lambda c: f(c) if predicate(c) else _core._FailCause(c), None
+        )
+
+    def catch_cause_filter[EB, X, B, E2 = Never, R2 = Never](
+        self,
+        filter: Callable[[Cause[E_co]], Result[EB, Cause[X]]],
+        f: Callable[[EB, Cause[E_co]], Effect[B, E2, R2]],
+    ) -> Effect[A_co | B, X | E2, R_co | R2]:
+        """Recover with ``f(value, cause)`` from a failure ``filter`` maps to
+        ``Ok(value)``; one it maps to ``Err(rest)`` fails with ``rest``."""
+
+        def handle(cause: Cause[E_co]) -> Effect[Any, Any, Any]:
+            match filter(cause):
+                case Ok(value):
+                    return f(value, cause)
+                case Err(rest):
+                    return _core._FailCause(rest)
+
+        return _core._MatchCause(as_effect(self), handle, None)
+
+    def catch_defect[B, E2 = Never, R2 = Never](
+        self, f: Callable[[object], Effect[B, E2, R2]]
+    ) -> Effect[A_co | B, E_co | E2, R_co | R2]:
+        """Recover from the first defect. Typed errors pass through."""
+
+        def on_failure(cause: Cause[E_co]) -> Effect[Any, Any, Any]:
+            defect = cause.find_defect()
+            return f(defect.value) if isinstance(defect, Ok) else _core._FailCause(cause)
+
+        return _core._MatchCause(as_effect(self), on_failure, None)
+
+    def or_else_succeed[B](self, f: Callable[[E_co], B]) -> Effect[A_co | B, Never, R_co]:
+        """Succeed with ``f(error)`` instead of failing."""
+        return self.catch_all(lambda e: _core._Sync(lambda: f(e)))
+
+    def eventually(self) -> Effect[A_co, Never, R_co]:
+        """Run again after each typed failure, yielding in between, until it
+        succeeds."""
+        loop: Effect[A_co, Never, R_co] = self.catch_all(
+            lambda _: _core._FlatMap(_core._YieldNow(), lambda _: loop)
+        )
+        return loop
+
+    def flip(self) -> Effect[E_co, A_co, R_co]:
+        """Swap the error and the value: fail with the value, succeed with
+        the error. Defects and interruptions stay failures."""
+        return _core._MatchCause(as_effect(self), _recovering(_core._Succeed), _fail)
+
+    def sandbox(self) -> Effect[A_co, Cause[E_co], R_co]:
+        """Fail with the whole ``Cause``, defects and interruptions included,
+        as the typed error."""
+        return _core._MatchCause(as_effect(self), _fail, None)
+
+    def or_die(self) -> Effect[A_co, Never, R_co]:
+        """Die with the first typed error instead of failing with it."""
+        return self.catch_all(lambda e: _core._FailCause(die_cause(e)))
+
+    def tap_error[E2 = Never, R2 = Never](
+        self, f: Callable[[E_co], Effect[object, E2, R2]]
+    ) -> Effect[A_co, E_co | E2, R_co | R2]:
+        def on_failure(cause: Cause[E_co]) -> Effect[Any, Any, Any]:
+            found = cause.find_fail()
+            if not isinstance(found, Fail):
+                return _core._FailCause(cause)
+            return _core._FlatMap(f(found.error), lambda _: _core._FailCause(cause))
+
+        return _core._MatchCause(as_effect(self), on_failure, None)
+
+    def tap_cause[E2 = Never, R2 = Never](
+        self, f: Callable[[Cause[E_co]], Effect[object, E2, R2]]
+    ) -> Effect[A_co, E_co | E2, R_co | R2]:
+        return _core._MatchCause(
+            as_effect(self), lambda c: _core._FlatMap(f(c), lambda _: _core._FailCause(c)), None
+        )
+
+    def tap_cause_if[E2 = Never, R2 = Never](
+        self,
+        predicate: Callable[[Cause[E_co]], bool],
+        f: Callable[[Cause[E_co]], Effect[object, E2, R2]],
+    ) -> Effect[A_co, E_co | E2, R_co | R2]:
+        """``tap_cause`` for the causes that pass ``predicate``."""
+
+        def on_failure(cause: Cause[E_co]) -> Effect[Any, Any, Any]:
+            if not predicate(cause):
+                return _core._FailCause(cause)
+            return _core._FlatMap(f(cause), lambda _: _core._FailCause(cause))
+
+        return _core._MatchCause(as_effect(self), on_failure, None)
+
+    def tap_cause_filter[EB, E2 = Never, R2 = Never](
+        self,
+        filter: Callable[[Cause[E_co]], Result[EB, object]],
+        f: Callable[[EB, Cause[E_co]], Effect[object, E2, R2]],
+    ) -> Effect[A_co, E_co | E2, R_co | R2]:
+        """Run ``f(value, cause)`` for a failure ``filter`` maps to
+        ``Ok(value)``, then keep failing with the cause."""
+
+        def on_failure(cause: Cause[E_co]) -> Effect[Any, Any, Any]:
+            match filter(cause):
+                case Ok(value):
+                    return _core._FlatMap(f(value, cause), lambda _: _core._FailCause(cause))
+                case Err():
+                    return _core._FailCause(cause)
+
+        return _core._MatchCause(as_effect(self), on_failure, None)
+
+    def tap_defect[E2 = Never, R2 = Never](
+        self, f: Callable[[object], Effect[object, E2, R2]]
+    ) -> Effect[A_co, E_co | E2, R_co | R2]:
+        """Run ``f(defect)`` for the first defect, then keep failing."""
+
+        def on_failure(cause: Cause[E_co]) -> Effect[Any, Any, Any]:
+            defect = cause.find_defect()
+            if isinstance(defect, Err):
+                return _core._FailCause(cause)
+            return _core._FlatMap(f(defect.value), lambda _: _core._FailCause(cause))
+
+        return _core._MatchCause(as_effect(self), on_failure, None)
+
+    def tap_error_tag[T, E2 = Never, R2 = Never](
+        self, tag: Tags[T], f: Callable[[T], Effect[object, E2, R2]]
+    ) -> Effect[A_co, E_co | E2, R_co | R2]:
+        """``tap_error`` for the errors that are instances of ``tag`` (a
+        class or a tuple of classes)."""
+        return self.tap_error(lambda e: f(e) if isinstance(e, tag) else _core._Succeed(None))
+
+    def ignore(
+        self, *, log: bool | Severity = False, message: str | None = None
+    ) -> Effect[None, Never, R_co]:
+        """Discard the value and any typed error. With ``log``, log the
+        failure's cause first, after ``message`` if given, at the current
+        log level (``True``) or the level given."""
+        if log is False:
+            return _core._MatchCause(as_effect(self), _ignore_failure, _succeed_none)
+        write = _cause_logger(log, message)
+
+        def on_failure(cause: Cause[Any]) -> Effect[None]:
+            found = cause.find_recoverable_error()
+            return write(cause) if isinstance(found, Fail) else _core._FailCause(found)
+
+        return _core._MatchCause(as_effect(self), on_failure, _succeed_none)
+
+    def ignore_cause(
+        self, *, log: bool | Severity = False, message: str | None = None
+    ) -> Effect[None, Never, R_co]:
+        """Discard the value and the whole cause: typed errors, defects and
+        interrupts. ``log`` and ``message`` as for ``ignore``."""
+        on_failure = _succeed_none if log is False else _cause_logger(log, message)
+        return _core._MatchCause(as_effect(self), on_failure, _succeed_none)
+
+    def with_error_reporting(self, *, defects_only: bool = False) -> Effect[A_co, E_co, R_co]:
+        """Send the cause of a failure to the ``CurrentErrorReporters``
+        (with ``defects_only``, only a cause with a defect), then fail with
+        it as before."""
+        from pyfect.error_reporter import report_unsafe
+
+        def report(fiber: Fiber[Any, Any], cause: Cause[Any]) -> Effect[None]:
+            report_unsafe(fiber, cause, defects_only=defects_only)
+            return _core._Succeed(None)
+
+        return as_effect(self).on_error(
+            lambda cause: _core._WithFiber(lambda fiber: report(fiber, cause))
+        )
+
+
+def _cause_logger(
+    log: Literal[True] | Severity, message: str | None
+) -> Callable[[Cause[Any]], Effect[None]]:
+    from pyfect.logger import log_with_level
+
+    level = None if log is True else log
+    prefix = () if message is None else (message,)
+    return lambda cause: log_with_level(level, *prefix, cause)
+
+
+def _fail[E](error: E) -> Effect[Never, E]:
+    return _core._FailCause(fail_cause(error))
+
+
+def _succeed_none(_: object) -> Effect[None]:
+    return _core._Succeed(None)
+
+
+def _recovering(
+    f: Callable[[Any], Effect[Any, Any, Any]],
+) -> Callable[[Cause[Any]], Effect[Any, Any, Any]]:
+    """A failure handler that passes the recoverable typed error to ``f``.
+    Every typed recovery goes through this, so a defect always wins: the
+    cause is then re-failed with its typed errors elected to defects."""
+
+    def handle(cause: Cause[Any]) -> Effect[Any, Any, Any]:
+        found = cause.find_recoverable_error()
+        return f(found.error) if isinstance(found, Fail) else _core._FailCause(found)
+
+    return handle
+
+
+_ignore_failure = _recovering(_succeed_none)
+
+
+def _catching_if(
+    predicate: Callable[[Any], bool],
+    f: Callable[[Any], Effect[Any, Any, Any]],
+    or_else: Callable[[Any], Effect[Any, Any, Any]] | None,
+) -> Callable[[Cause[Any]], Effect[Any, Any, Any]]:
+    """The failure handler of ``catch_if`` and ``catch_tag``. An error that
+    fails ``predicate`` goes to ``or_else``, or re-fails with the whole cause."""
+
+    def handle(cause: Cause[Any]) -> Effect[Any, Any, Any]:
+        found = cause.find_recoverable_error()
+        if not isinstance(found, Fail):
+            return _core._FailCause(found)
+        if predicate(found.error):
+            return f(found.error)
+        return _core._FailCause(cause) if or_else is None else or_else(found.error)
+
+    return handle

pyfect/_effect_folding.py

@@ -0,0 +1,110 @@
+"""``Effect`` methods that fold both outcomes into a value or a next effect:
+``match*``, ``option``, ``as_some``, ``is_failure`` / ``is_success``,
+``exit`` and ``result``."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Never
+
+from pyfect import _core
+from pyfect._effect_base import A_co, E_co, EffectBase, R_co, as_effect
+from pyfect._effect_errors import _recovering, _succeed_none
+from pyfect.cause import Cause
+from pyfect.exit import Exit, Failure, Success
+from pyfect.result import Err, Ok
+
+if TYPE_CHECKING:
+    from pyfect._core import Effect
+    from pyfect.option import Option, Some
+
+
+class FoldingMethods(EffectBase[A_co, E_co, R_co]):
+    __slots__ = ()
+
+    def match[B, C](
+        self, *, on_failure: Callable[[E_co], B], on_success: Callable[[A_co], C]
+    ) -> Effect[B | C, Never, R_co]:
+        return _core._MatchCause(
+            as_effect(self),
+            _recovering(lambda e: _core._Succeed(on_failure(e))),
+            lambda a: _core._Succeed(on_success(a)),
+        )
+
+    def match_cause[B, C](
+        self, *, on_failure: Callable[[Cause[E_co]], B], on_success: Callable[[A_co], C]
+    ) -> Effect[B | C, Never, R_co]:
+        """``match`` over the whole ``Cause``: defects reach ``on_failure``
+        too. Interruption still propagates."""
+        return _core._MatchCause(
+            as_effect(self),
+            lambda c: _core._Succeed(on_failure(c)),
+            lambda a: _core._Succeed(on_success(a)),
+        )
+
+    def option(self) -> Effect[Option[A_co], Never, R_co]:
+        """Succeed with ``Some(value)``, or ``None`` on a typed error.
+        Defects and interruptions still propagate."""
+        from pyfect.option import Some
+
+        return _core._MatchCause(
+            as_effect(self), _recovering(_succeed_none), lambda a: _core._Succeed(Some(a))
+        )
+
+    def as_some(self) -> Effect[Some[A_co], E_co, R_co]:
+        """Succeed with ``Some(value)``."""
+        from pyfect.option import Some
+
+        return _core._Map(as_effect(self), Some)
+
+    def is_failure(self) -> Effect[bool, Never, R_co]:
+        """Whether it fails with a typed error. Defects and interruptions
+        still propagate."""
+        return self.match(on_failure=_true, on_success=_false)
+
+    def is_success(self) -> Effect[bool, Never, R_co]:
+        """Whether it succeeds. Defects and interruptions still propagate."""
+        return self.match(on_failure=_false, on_success=_true)
+
+    def match_effect[B, C, EE = Never, RR = Never](
+        self,
+        *,
+        on_failure: Callable[[E_co], Effect[B, EE, RR]],
+        on_success: Callable[[A_co], Effect[C, EE, RR]],
+    ) -> Effect[B | C, EE, R_co | RR]:
+        return _core._MatchCause(as_effect(self), _recovering(on_failure), on_success)
+
+    def match_cause_effect[B, C, EE = Never, RR = Never](
+        self,
+        *,
+        on_failure: Callable[[Cause[E_co]], Effect[B, EE, RR]],
+        on_success: Callable[[A_co], Effect[C, EE, RR]],
+    ) -> Effect[B | C, EE, R_co | RR]:
+        return _core._MatchCause(as_effect(self), on_failure, on_success)
+
+    def exit(self) -> Effect[Exit[A_co, E_co], Never, R_co]:
+        """Succeed with the outcome as a value. Interruption still
+        propagates; it is not something a fiber can catch."""
+        return _core._MatchCause(
+            as_effect(self),
+            lambda c: _core._Succeed(Failure(c)),
+            lambda a: _core._Succeed(Success(a)),
+        )
+
+    def result(self) -> Effect[Ok[A_co] | Err[E_co], Never, R_co]:
+        """Succeed with ``Ok(value)`` or ``Err(error)``. Defects and
+        interruptions still propagate."""
+        return _core._MatchCause(
+            as_effect(self),
+            _recovering(lambda e: _core._Succeed(Err(e))),
+            lambda a: _core._Succeed(Ok(a)),
+        )
+
+
+def _true(_: object) -> bool:
+    return True
+
+
+def _false(_: object) -> bool:
+    return False

pyfect/_effect_hash.py

@@ -0,0 +1,140 @@
+"""Effect's ``Hash.hash`` on the keys ``pyfect._equal.equal_key`` makes, so a
+``HashMap`` / ``HashSet`` places its entries, and iterates them, as Effect's
+does.
+
+Strings, numbers, booleans, ``None`` (``null``), bytes (a ``Uint8Array``),
+lists and tuples (arrays), dicts (objects when every key is a string, else
+``Map``) and sets get Effect's hash. Other values have no JavaScript
+counterpart and use their own ``__hash__`` (Effect's ``Hash.symbol``).
+Results are unsigned 32-bit (``hash >>> 0``), the bits Effect's trie reads.
+"""
+
+from __future__ import annotations
+
+import math
+import struct
+from collections.abc import Hashable
+from functools import lru_cache
+from typing import cast
+
+from pyfect._string_hash import string_hash
+
+_U32 = 0xFFFFFFFF
+
+
+def _imul(a: int, b: int) -> int:
+    return (a * b) & _U32
+
+
+def _mix(h: int) -> int:
+    h &= _U32
+    h ^= h >> 16
+    h = _imul(h, 0x85EBCA6B)
+    h ^= h >> 13
+    h = _imul(h, 0xC2B2AE35)
+    return h ^ (h >> 16)
+
+
+def _optimize(h: int) -> int:
+    h &= _U32
+    return (h & 0xBFFFFFFF) | ((h >> 1) & 0x40000000)
+
+
+def _combine(a: int, b: int) -> int:
+    return _mix(_imul(a, 0x9E3779B1) + _imul(b, 0x85EBCA6B))
+
+
+@lru_cache(maxsize=1 << 14)
+def _string(text: str) -> int:
+    return string_hash(text) & _U32
+
+
+def _number(n: float) -> int:
+    if math.isnan(n):
+        n = math.nan
+    elif -(1 << 31) <= n < (1 << 31) and n == int(n):
+        return _optimize(int(n))
+    high, low = struct.unpack(">II", struct.pack(">d", n))
+    return _optimize(_combine(high, low))
+
+
+def _int(n: int) -> int:
+    if -(1 << 31) <= n < (1 << 31):
+        return _optimize(n)
+    if _is_float(n):
+        return _number(float(n))  # a JavaScript number, equal to its float
+    return _string(str(n))  # a BigInt
+
+
+def _is_float(n: int) -> bool:
+    # Exactly a finite float: at most 53 significant bits, below 2**1024.
+    # (``float(n) == n`` raises OverflowError past the float range.)
+    odd = n >> ((n & -n).bit_length() - 1)
+    return n.bit_length() <= 1024 and odd.bit_length() <= 53
+
+
+def _array(items: tuple[Hashable, ...]) -> int:
+    h = 6151
+    for item in items:
+        h = _combine(h, effect_hash(item))
+    return _optimize(h)
+
+
+_MAP_SEED = _string("Map")
+_SET_SEED = _string("Set")
+_NULL = _optimize(_mix(_string("null")))
+_TRUE = _optimize(_mix(_string("true")))
+_FALSE = _optimize(_mix(_string("false")))
+
+
+def _mapping(pairs: frozenset[tuple[Hashable, Hashable]]) -> int:
+    h = 12289 if all(type(k) is str for k, _ in pairs) else _MAP_SEED
+    for key, value in pairs:
+        h ^= _combine(effect_hash(key), effect_hash(value))
+    return _optimize(h)
+
+
+def _set(items: frozenset[Hashable]) -> int:
+    h = _SET_SEED
+    for item in items:
+        h ^= _combine(_SET_SEED, effect_hash(item))
+    return _optimize(h)
+
+
+def effect_hash(ident: Hashable) -> int:
+    """Effect's ``Hash.hash`` of the value ``ident`` (an ``equal_key``)
+    stands for."""
+    match ident:
+        case str():
+            return _string(ident)
+        case int():
+            return _int(ident)
+        case float():
+            return _number(ident)
+        case None:
+            return _NULL
+        case _:
+            return _other(ident)
+
+
+def _other(ident: Hashable) -> int:
+    kind = type(ident)
+    if kind is bytes:
+        return _array(tuple(cast("bytes", ident)))
+    if kind is tuple:
+        return _tagged(cast("tuple[object, Hashable]", ident))
+    return hash(ident) & _U32
+
+
+def _tagged(ident: tuple[object, Hashable]) -> int:
+    # ``equal_key``'s tagged forms; every tuple key is one of them.
+    tag, payload = ident
+    if tag is bool:
+        return _TRUE if payload else _FALSE
+    if tag is float:
+        return _number(math.nan)
+    if tag is tuple:
+        return _array(cast("tuple[Hashable, ...]", payload))
+    if tag is dict:
+        return _mapping(cast("frozenset[tuple[Hashable, Hashable]]", payload))
+    return _set(cast("frozenset[Hashable]", payload))