pyfect-dev 0.1.0__py3-none-any.whl

pyfect/_hamt.py

@@ -0,0 +1,174 @@
+"""A persistent hash array mapped trie, the storage of ``HashMap`` and
+``HashSet`` (Effect's ``internal/hashMap.ts``).
+
+Entries are keyed by an ``equal_key`` (``pyfect._equal``), already hashable
+and ``==`` exactly when Effect's ``Equal.equals`` is. Every update copies
+only the nodes on the path to its entry, so it costs about
+``log32(size)`` and shares the rest with the old trie. ``None`` is the
+empty trie. Hashes are Effect's (``pyfect._effect_hash``), 32 bits read five
+at a time from the low end as Effect's trie reads them, so entries sit and
+iterate in Effect's order.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Iterator
+from typing import NamedTuple
+
+from pyfect._effect_hash import effect_hash
+from pyfect._js import same_value
+
+_BITS = 5
+_MASK = (1 << _BITS) - 1
+
+
+class Entry[K, V](NamedTuple):
+    hash: int
+    ident: Hashable
+    key: K
+    value: V
+
+
+class _Bitmap:
+    """Children by the 5 hash bits at its depth; ``bitmap`` marks which."""
+
+    __slots__ = ("bitmap", "children")
+
+    def __init__(self, bitmap: int, children: tuple[Node, ...]) -> None:
+        self.bitmap = bitmap
+        self.children = children
+
+
+class _Collision:
+    """Entries whose 64-bit hashes are all equal."""
+
+    __slots__ = ("entries", "hash")
+
+    def __init__(self, hash: int, entries: tuple[Entry[object, object], ...]) -> None:
+        self.hash = hash
+        self.entries = entries
+
+
+type Node = _Bitmap | _Collision | Entry[object, object]
+
+
+def hash_of(ident: Hashable) -> int:
+    return effect_hash(ident)
+
+
+def find(node: Node | None, hash: int, ident: Hashable) -> Entry[object, object] | None:
+    shift = 0
+    while True:
+        match node:
+            case None:
+                return None
+            case Entry():
+                return node if node.hash == hash and node.ident == ident else None
+            case _Collision():
+                if node.hash != hash:
+                    return None
+                return next((e for e in node.entries if e.ident == ident), None)
+            case _Bitmap():
+                bit = 1 << ((hash >> shift) & _MASK)
+                if not node.bitmap & bit:
+                    return None
+                node = node.children[(node.bitmap & (bit - 1)).bit_count()]
+                shift += _BITS
+
+
+def insert(node: Node | None, entry: Entry[object, object], shift: int = 0) -> Node:  # noqa: PLR0911
+    """``node`` with ``entry``, replacing the one of an equal ``ident``; the
+    same node when that entry already holds this value (``Object.is``, as
+    Effect's). An existing entry keeps its key."""
+    match node:
+        case None:
+            return entry
+        case Entry():
+            if node.hash == entry.hash and node.ident == entry.ident:
+                if same_value(node.value, entry.value):
+                    return node
+                return Entry(node.hash, node.ident, node.key, entry.value)
+            return _merge(node, entry, shift)
+        case _Collision():
+            if node.hash != entry.hash:
+                return _merge(node, entry, shift)
+            for i, old in enumerate(node.entries):
+                if old.ident == entry.ident:
+                    if same_value(old.value, entry.value):
+                        return node
+                    kept = Entry(old.hash, old.ident, old.key, entry.value)
+                    return _Collision(node.hash, (*node.entries[:i], kept, *node.entries[i + 1 :]))
+            return _Collision(node.hash, (*node.entries, entry))
+        case _Bitmap():
+            bit = 1 << ((entry.hash >> shift) & _MASK)
+            index = (node.bitmap & (bit - 1)).bit_count()
+            children = node.children
+            if not node.bitmap & bit:
+                return _Bitmap(node.bitmap | bit, (*children[:index], entry, *children[index:]))
+            child = insert(children[index], entry, shift + _BITS)
+            if child is children[index]:
+                return node
+            return _Bitmap(node.bitmap, (*children[:index], child, *children[index + 1 :]))
+
+
+def _merge(
+    old: Entry[object, object] | _Collision, entry: Entry[object, object], shift: int
+) -> Node:
+    """A node holding ``old`` and ``entry`` at depth ``shift``."""
+    if old.hash == entry.hash:
+        olds = old.entries if isinstance(old, _Collision) else (old,)
+        return _Collision(entry.hash, (*olds, entry))
+    a, b = (old.hash >> shift) & _MASK, (entry.hash >> shift) & _MASK
+    if a == b:
+        return _Bitmap(1 << a, (_merge(old, entry, shift + _BITS),))
+    pair: tuple[Node, ...] = (old, entry) if a < b else (entry, old)
+    return _Bitmap((1 << a) | (1 << b), pair)
+
+
+def remove(node: Node | None, hash: int, ident: Hashable, shift: int = 0) -> Node | None:  # noqa: PLR0911
+    """``node`` without the entry of ``ident``: the same node when it has
+    none, ``None`` when that leaves it empty."""
+    match node:
+        case None:
+            return None
+        case Entry():
+            return None if node.hash == hash and node.ident == ident else node
+        case _Collision():
+            if node.hash != hash:
+                return node
+            kept = tuple(e for e in node.entries if e.ident != ident)
+            if len(kept) == len(node.entries):
+                return node
+            return kept[0] if len(kept) == 1 else _Collision(node.hash, kept)
+        case _Bitmap():
+            bit = 1 << ((hash >> shift) & _MASK)
+            if not node.bitmap & bit:
+                return node
+            index = (node.bitmap & (bit - 1)).bit_count()
+            children = node.children
+            child = remove(children[index], hash, ident, shift + _BITS)
+            if child is children[index]:
+                return node
+            if child is None:
+                if len(children) == 1:
+                    return None
+                rest = (*children[:index], *children[index + 1 :])
+                if len(rest) == 1 and not isinstance(rest[0], _Bitmap):
+                    return rest[0]
+                return _Bitmap(node.bitmap & ~bit, rest)
+            if len(children) == 1 and not isinstance(child, _Bitmap):
+                return child
+            return _Bitmap(node.bitmap, (*children[:index], child, *children[index + 1 :]))
+
+
+def entries(node: Node | None) -> Iterator[Entry[object, object]]:
+    match node:
+        case None:
+            return
+        case Entry():
+            yield node
+        case _Collision():
+            yield from node.entries
+        case _Bitmap():
+            for child in node.children:
+                yield from entries(child)

pyfect/_interrupt_reason.py

@@ -0,0 +1,33 @@
+"""Why the runtime interrupted a fiber, when it knows (pyfect's addition to
+Effect's interrupt annotations).
+
+Effect interrupts a fiber forked into, or run through, a closed ``Scope``,
+``FiberMap``, ``FiberSet`` or ``FiberHandle``; pyfect does the same and
+annotates the interruption with ``InterruptReason``, which ``Interrupted``
+shows in its notes, so the closed owner is named where the run fails.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from typing import Any, Never
+
+from pyfect._core import Effect, _FailCause, _WithFiber
+from pyfect._released import closed_message
+from pyfect.cause import interrupt as interrupt_cause
+from pyfect.context import Context, Tag
+
+
+class InterruptReason(Tag[str]):
+    """The annotation an interruption the runtime sends gets: why."""
+
+
+def closed(owner: str, annotations: Context[Any] | None = None) -> Context[Any]:
+    """``annotations`` with the reason "``owner`` is closed"."""
+    reason = Context.make(InterruptReason, closed_message(owner))
+    return reason if annotations is None else annotations.merge(reason)
+
+
+def interrupt_closed(owner: str) -> Effect[Never]:
+    """Interrupt the current fiber because ``owner`` is closed."""
+    return _WithFiber(lambda fiber: _FailCause(interrupt_cause(fiber.id).annotate(closed(owner))))

pyfect/_isaac.py

@@ -0,0 +1,149 @@
+"""The ISAAC generator behind ``random.with_seed``, ported from Effect's
+``ISAAC_CSPRNG`` so a seed gives the same sequence as in Effect.
+
+Effect's copyright notices for this derivative work:
+Copyright (c) 2025 Effectful Technologies Inc, under MIT license.
+Copyright (c) 2018, William P. "Mac" McMeans, under BSD license.
+Original work copyright (c) 2012 Yves-Marie K. Rinquin, under MIT license.
+https://github.com/rubycon/isaac.js
+
+State words are unsigned 32-bit ints: JavaScript's int32 bit operations give
+the same bit patterns."""
+
+from __future__ import annotations
+
+import math
+
+from pyfect._js import text_encode
+
+_MASK = 0xFFFFFFFF
+_GOLDEN = 0x9E3779B9
+_MAX_SAFE = 2**53 - 1
+
+
+def _uint32(seed: float) -> int:
+    """JavaScript's ``ToUint32`` of the seed as a JavaScript number (a double:
+    an int rounds, and one too big for a float is infinite)."""
+    try:
+        x = float(seed)
+    except OverflowError:
+        return 0
+    return int(x) & _MASK if math.isfinite(x) else 0
+
+
+def _seed_words(seed: str | float) -> list[int]:
+    if not isinstance(seed, str):
+        return [_uint32(seed)]
+    data = text_encode(seed)
+    return [int.from_bytes(data[i : i + 4], "little") for i in range(0, len(data), 4)]
+
+
+class Isaac:
+    """A seeded ``RandomService``: the same seed gives the same sequence."""
+
+    __slots__ = ("_acc", "_counter", "_generation", "_last", "_memory", "_result")
+
+    def __init__(self, seed: str | float) -> None:
+        self._memory = [0] * 256
+        self._result = [0] * 256
+        self._acc = 0
+        self._last = 0
+        self._counter = 0
+        for i, word in enumerate(_seed_words(seed)):
+            self._result[i & 0xFF] = (self._result[i & 0xFF] + word) & _MASK
+        self._scramble()
+        self._next_block()
+        self._generation = 256
+
+    def _scramble(self) -> None:
+        s = [_GOLDEN] * 8
+
+        def mix() -> None:
+            a, b, c, d, e, f, g, h = s
+            a ^= (b << 11) & _MASK
+            d = (d + a) & _MASK
+            b = (b + c) & _MASK
+            b ^= c >> 2
+            e = (e + b) & _MASK
+            c = (c + d) & _MASK
+            c ^= (d << 8) & _MASK
+            f = (f + c) & _MASK
+            d = (d + e) & _MASK
+            d ^= e >> 16
+            g = (g + d) & _MASK
+            e = (e + f) & _MASK
+            e ^= (f << 10) & _MASK
+            h = (h + e) & _MASK
+            f = (f + g) & _MASK
+            f ^= g >> 4
+            a = (a + f) & _MASK
+            g = (g + h) & _MASK
+            g ^= (h << 8) & _MASK
+            b = (b + g) & _MASK
+            h = (h + a) & _MASK
+            h ^= a >> 9
+            c = (c + h) & _MASK
+            a = (a + b) & _MASK
+            s[:] = [a, b, c, d, e, f, g, h]
+
+        for _ in range(4):
+            mix()
+        memory = self._memory
+        for source in (self._result, memory):
+            for i in range(0, 256, 8):
+                for j in range(8):
+                    s[j] = (s[j] + source[i + j]) & _MASK
+                mix()
+                memory[i : i + 8] = s
+
+    def _next_block(self) -> None:
+        memory, result = self._memory, self._result
+        acc = self._acc
+        self._counter = (self._counter + 1) & _MASK
+        last = (self._last + self._counter) & _MASK
+        for i in range(256):
+            match i & 3:
+                case 0:
+                    acc ^= (acc << 13) & _MASK
+                case 1:
+                    acc ^= acc >> 6
+                case 2:
+                    acc ^= (acc << 2) & _MASK
+                case _:
+                    acc ^= acc >> 16
+            acc = (memory[(i + 128) & 0xFF] + acc) & _MASK
+            x = memory[i]
+            y = memory[i] = (memory[(x >> 2) & 0xFF] + acc + last) & _MASK
+            last = result[i] = (memory[(y >> 10) & 0xFF] + x) & _MASK
+        self._acc, self._last = acc, last
+
+    def _next_word(self) -> int:
+        if self._generation == 0:
+            self._next_block()
+            self._generation = 255
+        else:
+            self._generation -= 1
+        return self._result[self._generation]
+
+    def next_double_unsafe(self) -> float:
+        hi = self._next_word() & 0x1FFFFF
+        lo = self._next_word()
+        return (hi * 4294967296 + lo) / 2**53
+
+    def next_int_unsafe(self) -> int:
+        return safe_int_of(self.next_double_unsafe())
+
+
+def safe_int_of(draw: float) -> int:
+    """Effect's ``nextIntUnsafe`` from a draw in ``[0, 1)``, in its float arithmetic."""
+    return int(math.floor(draw * float(2 * _MAX_SAFE + 1)) + float(-_MAX_SAFE))
+
+
+def between_of(low: float, high: float, draw: float) -> float:
+    """Effect's ``nextBetween``: a draw in ``[0, 1)`` scaled to ``[low, high)``.
+    Rounding can reach the excluded bound even for a draw below 1; then the
+    float just below it."""
+    value = draw * (high - low) + low
+    if value != high or low >= high or not math.isfinite(high):
+        return value
+    return math.nextafter(high, -math.inf)

pyfect/_iterables.py

@@ -0,0 +1,231 @@
+"""Effects over iterables of values or effects: ``first_success_of``,
+``filter``, ``filter_map``, ``filter_map_effect``, ``partition``,
+``validate``, ``reduce``, ``find_first``, ``find_first_filter``."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Iterator
+from typing import Any, Literal, Never, TypeIs, overload
+
+from pyfect._concurrency import Concurrency, for_each
+from pyfect._core import Effect, _FailCause, _Succeed, _Suspend
+from pyfect.cause import die, fail
+from pyfect.option import Option, Some
+from pyfect.result import Err, Ok, Result
+
+
+def first_success_of[A, EE = Never, RR = Never](
+    effects: Iterable[Effect[A, EE, RR]],
+) -> Effect[A, EE, RR]:
+    """Run the effects in order until one succeeds. If all fail, fail with
+    the last one's error; later effects never run. ``effects`` is read each
+    time the effect runs, and an empty one is a defect."""
+
+    def start() -> Effect[A, EE, RR]:
+        it = iter(effects)
+        first = next(it, None)
+        if first is None:
+            return _FailCause(die(ValueError("Received an empty collection of effects")))
+        return _try_next(first, it)
+
+    return _Suspend(start)
+
+
+def _try_next[A, E, R](
+    current: Effect[A, E, R], rest: Iterator[Effect[A, E, R]]
+) -> Effect[A, E, R]:
+    following = next(rest, None)
+    if following is None:
+        return current
+    return current.catch_all(lambda _: _try_next(following, rest))
+
+
+@overload
+def filter[A, B](items: Iterable[A], predicate: Callable[[A], TypeIs[B]]) -> Effect[list[B]]: ...
+@overload
+def filter[A](items: Iterable[A], predicate: Callable[[A], bool]) -> Effect[list[A]]: ...
+@overload
+def filter[A, E = Never, R = Never](
+    items: Iterable[A],
+    predicate: Callable[[A], Effect[bool, E, R]],
+    *,
+    concurrency: Concurrency = None,
+) -> Effect[list[A], E, R]: ...
+def filter(
+    items: Iterable[Any],
+    predicate: Callable[[Any], bool | Effect[bool, Any, Any]],
+    *,
+    concurrency: Concurrency = None,
+) -> Effect[list[Any], Any, Any]:
+    """Keep the items that pass ``predicate``, in order. An effectful
+    predicate runs like ``for_each``, ``concurrency`` included."""
+
+    def keep(item: Any) -> Effect[tuple[bool, Any], Any, Any]:
+        verdict = predicate(item)
+        if isinstance(verdict, Effect):
+            return verdict.map(lambda passed: (passed, item))
+        return _Succeed((verdict, item))
+
+    return for_each(items, keep, concurrency=concurrency).map(
+        lambda checked: [item for passed, item in checked if passed]
+    )
+
+
+def filter_map[A, B](
+    items: Iterable[A], filter: Callable[[A], Result[B, object]]
+) -> Effect[list[B]]:
+    """The values of the items ``filter`` maps to ``Ok(value)``, in order;
+    ``Err`` items are dropped. ``items`` is read each time the effect runs."""
+
+    def run() -> Effect[list[B]]:
+        return _Succeed([r.value for r in map(filter, items) if isinstance(r, Ok)])
+
+    return _Suspend(run)
+
+
+def filter_map_effect[A, B, E = Never, R = Never](
+    items: Iterable[A],
+    filter: Callable[[A], Effect[Result[B, object], E, R]],
+    *,
+    concurrency: Concurrency = None,
+) -> Effect[list[B], E, R]:
+    """``filter_map`` with an effectful filter, run like ``for_each``. The
+    values are collected as each filter finishes, so with ``concurrency``
+    they come in completion order, as in Effect."""
+
+    def run() -> Effect[list[B], E, R]:
+        out: list[B] = []
+
+        def keep(item: A) -> Effect[None, E, R]:
+            def record(result: Result[B, object]) -> None:
+                if isinstance(result, Ok):
+                    out.append(result.value)
+
+            return filter(item).map(record)
+
+        return for_each(items, keep, concurrency=concurrency).as_(out)
+
+    return _Suspend(run)
+
+
+def partition[T, B, E = Never, R = Never](
+    items: Iterable[T],
+    f: Callable[[T], Effect[B, E, R]],
+    *,
+    concurrency: Concurrency = None,
+) -> Effect[tuple[list[B], list[E]], Never, R]:
+    """Run ``f`` on every item, like ``for_each``, without stopping at
+    failures: the values that succeeded and the typed errors, each in
+    order. Defects and interruptions still propagate."""
+    return for_each(items, lambda item: f(item).result(), concurrency=concurrency).map(_split)
+
+
+def _split[B, E](results: list[Result[B, E]]) -> tuple[list[B], list[E]]:
+    passes = [r.value for r in results if isinstance(r, Ok)]
+    fails = [r.error for r in results if isinstance(r, Err)]
+    return passes, fails
+
+
+@overload
+def validate[T, B, R = Never](
+    items: Iterable[T],
+    f: Callable[[T], Effect[B, Never, R]],
+    *,
+    concurrency: Concurrency = None,
+    discard: Literal[False] = False,
+) -> Effect[list[B], Never, R]: ...
+@overload
+def validate[T, R = Never](
+    items: Iterable[T],
+    f: Callable[[T], Effect[object, Never, R]],
+    *,
+    concurrency: Concurrency = None,
+    discard: Literal[True],
+) -> Effect[None, Never, R]: ...
+@overload
+def validate[T, B, E = Never, R = Never](
+    items: Iterable[T],
+    f: Callable[[T], Effect[B, E, R]],
+    *,
+    concurrency: Concurrency = None,
+    discard: Literal[False] = False,
+) -> Effect[list[B], tuple[E, *tuple[E, ...]], R]: ...
+@overload
+def validate[T, E = Never, R = Never](
+    items: Iterable[T],
+    f: Callable[[T], Effect[object, E, R]],
+    *,
+    concurrency: Concurrency = None,
+    discard: Literal[True],
+) -> Effect[None, tuple[E, *tuple[E, ...]], R]: ...
+def validate(
+    items: Iterable[Any],
+    f: Callable[[Any], Effect[Any, Any, Any]],
+    *,
+    concurrency: Concurrency = None,
+    discard: bool = False,
+) -> Effect[Any, Any, Any]:
+    """Like ``partition``, but fail with every typed error (never an empty
+    tuple) if any item failed; otherwise succeed with the values, or with
+    ``None`` when ``discard`` is set."""
+
+    def decide(split: tuple[list[Any], list[Any]]) -> Effect[Any, Any, Never]:
+        passes, fails = split
+        if fails:
+            return _FailCause(fail((fails[0], *fails[1:])))
+        return _Succeed(None if discard else passes)
+
+    return partition(items, f, concurrency=concurrency).flat_map(decide)
+
+
+def reduce[A, Z, E = Never, R = Never](
+    items: Iterable[A], zero: Callable[[], Z], f: Callable[[Z, A], Effect[Z, E, R]]
+) -> Effect[Z, E, R]:
+    """Fold ``items`` from the left with an effectful ``f``, one at a time,
+    stopping at the first failure. ``items`` is read now, as Effect reads
+    it; ``zero()`` is called each time the effect runs."""
+    elements = list(items)
+
+    def start() -> Effect[Z, E, R]:
+        state: Effect[Z, E, R] = _Succeed(zero())
+        for item in elements:
+            state = _fold(state, f, item)
+        return state
+
+    return _Suspend(start)
+
+
+def _fold[A, Z, E, R](
+    state: Effect[Z, E, R], f: Callable[[Z, A], Effect[Z, E, R]], item: A
+) -> Effect[Z, E, R]:
+    return state.flat_map(lambda acc: f(acc, item))
+
+
+def find_first[A, E = Never, R = Never](
+    items: Iterable[A], predicate: Callable[[A], Effect[bool, E, R]]
+) -> Effect[Option[A], E, R]:
+    """The first item for which ``predicate`` succeeds with ``True``
+    (``Some(item)``), checking one at a time and stopping there; ``None``
+    if there is none. ``items`` is read each time the effect runs."""
+    return find_first_filter(
+        items, lambda item: predicate(item).map(lambda keep: Ok(item) if keep else Err(item))
+    )
+
+
+def find_first_filter[A, B, E = Never, R = Never](
+    items: Iterable[A], filter: Callable[[A], Effect[Result[B, object], E, R]]
+) -> Effect[Option[B], E, R]:
+    """The value of the first item ``filter`` passes (``Ok(value)``), as
+    ``Some(value)``, checking one at a time and stopping there; ``None`` if
+    every item is rejected (``Err``)."""
+
+    def check(it: Iterator[A]) -> Effect[Option[B], E, R]:
+        for item in it:
+            return filter(item).flat_map(lambda passed: _found(passed, it))
+        return _Succeed(None)
+
+    def _found(passed: Result[B, object], it: Iterator[A]) -> Effect[Option[B], E, R]:
+        return _Succeed(Some(passed.value)) if isinstance(passed, Ok) else check(it)
+
+    return _Suspend(lambda: check(iter(items)))