pyfect-dev 0.1.0__py3-none-any.whl

pyfect/_round_robin.py

@@ -0,0 +1,73 @@
+"""Keyed queues served in turn, one item per turn.
+
+The cursor survives additions and removals the way a JavaScript ``Map``
+iterator does (Effect's ``PartitionedSemaphore`` relies on it): a key added
+later is reached in this round, and a key removed and added again moves to
+the end.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Hashable
+
+
+class _Queue[K, V]:
+    __slots__ = ("items", "key", "slot")
+
+    def __init__(self, key: K, slot: int) -> None:
+        self.key = key
+        self.slot = slot
+        # A dict as an insertion-ordered set: removal from the middle is O(1).
+        self.items: dict[V, None] = {}
+
+
+class RoundRobin[K: Hashable, V: Hashable]:
+    __slots__ = ("_cursor", "_holes", "_queues", "_ring")
+
+    def __init__(self) -> None:
+        self._queues: dict[K, _Queue[K, V]] = {}
+        self._ring: list[_Queue[K, V] | None] = []
+        self._cursor = 0
+        self._holes = 0
+
+    def add(self, key: K, item: V) -> None:
+        queue = self._queues.get(key)
+        if queue is None:
+            queue = self._queues[key] = _Queue(key, len(self._ring))
+            self._ring.append(queue)
+        queue.items[item] = None
+
+    def remove(self, key: K, item: V) -> None:
+        queue = self._queues.get(key)
+        if queue is None or item not in queue.items:
+            return
+        del queue.items[item]
+        if queue.items:
+            return
+        del self._queues[key]
+        self._ring[queue.slot] = None
+        self._holes += 1
+        if self._holes * 2 > len(self._ring):
+            self._compact()
+
+    def next(self) -> tuple[K, V] | None:
+        """The next key and the head of its queue, or ``None`` if all are
+        empty. Does not remove it."""
+        for _ in range(2):
+            while self._cursor < len(self._ring):
+                queue = self._ring[self._cursor]
+                self._cursor += 1
+                if queue is not None:
+                    return queue.key, next(iter(queue.items))
+            self._cursor = 0
+            self._compact()
+        return None
+
+    def _compact(self) -> None:
+        live_before_cursor = sum(q is not None for q in self._ring[: self._cursor])
+        live = [q for q in self._ring if q is not None]
+        for slot, queue in enumerate(live):
+            queue.slot = slot
+        self._ring = list[_Queue[K, V] | None](live)
+        self._cursor = live_before_cursor
+        self._holes = 0

pyfect/_some.py

@@ -0,0 +1,17 @@
+"""``Some``, on its own so ``pyfect.result`` and ``pyfect.option`` can both
+use it without importing each other."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+A_co = TypeVar("A_co", covariant=True)
+
+
+@dataclass(frozen=True, slots=True)
+class Some(Generic[A_co]):
+    value: A_co
+
+
+type Option[A] = Some[A] | None

pyfect/_stack.py

@@ -0,0 +1,52 @@
+"""Recursion that goes as deep as its data: ``with_fresh_stack`` runs a step
+of a recursive walk on a new thread once the caller's stack is nearly full.
+
+Python counts frames per thread and stops at ``sys.getrecursionlimit()``
+(about 1000), where JavaScript's stack takes about ten times as many. A
+walk whose depth comes from its input (a recursive schema decoding a deep
+value, an issue tree from one) calls ``with_fresh_stack`` at the node that
+recurses (``Suspend``), so each thread holds a bounded slice of the walk.
+"""
+
+from __future__ import annotations
+
+import contextvars
+import sys
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+
+_HEADROOM = 400
+"""Frames left to the caller when the walk moves to a new thread: room for
+one level of a recursive structure between two calls."""
+
+MAX_FRESH_STACKS = 300
+"""Fresh stacks one walk may nest (each about ``getrecursionlimit() -
+_HEADROOM`` frames, so far deeper than JavaScript's stack). Past it the walk
+raises ``RecursionError``: a walk that never ends (a cycle) fails instead
+of starting threads until the process runs out of them."""
+
+_depth: contextvars.ContextVar[int] = contextvars.ContextVar("pyfect_fresh_stacks", default=0)
+
+
+def stack_nearly_full() -> bool:
+    """Whether the next level of a walk belongs on a fresh stack."""
+    try:
+        sys._getframe(max(sys.getrecursionlimit() - _HEADROOM, 1))  # pyright: ignore[reportPrivateUsage]
+    except ValueError:
+        return False
+    return True
+
+
+def with_fresh_stack[A](f: Callable[[], A]) -> A:
+    """``f()``, on a new thread (with the caller's context variables) when
+    the stack is too deep for another level of the walk. Its result or
+    exception is the caller's."""
+    if not stack_nearly_full():
+        return f()
+    depth = _depth.get() + 1
+    if depth > MAX_FRESH_STACKS:
+        raise RecursionError("maximum recursion depth exceeded (pyfect fresh stacks)")
+    context = contextvars.copy_context()
+    context.run(_depth.set, depth)
+    with ThreadPoolExecutor(1, thread_name_prefix="pyfect-deep-stack") as executor:
+        return executor.submit(context.run, f).result()

pyfect/_stack_frame.py

@@ -0,0 +1,114 @@
+"""Stack frames: where spans and traced functions were written, recorded on
+the causes of failures inside them (Effect's ``References.CurrentStackFrame``
+and ``Cause.StackTrace`` / ``InterruptorStackTrace``).
+
+Apart from ``pyfect.tracer`` so the fiber runtime can read the current frame
+without importing the span functions.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from types import CodeType
+from typing import final
+
+from pyfect.context import Reference, Tag
+
+type CaptureStackTrace = bool | Callable[[], str | None]
+"""Effect's ``captureStackTrace``: ``True`` records the call site, ``False``
+records nothing, a function gives the location when it is first read."""
+
+
+@dataclass(frozen=True, slots=True, eq=False)
+class StackFrame:
+    """One frame: a name, its location (read lazily, ``None`` if unknown, in
+    the form ``"at function (file:line)"``) and the frame it runs inside."""
+
+    name: str
+    stack: Callable[[], str | None] = field(repr=False)
+    parent: StackFrame | None = None
+
+
+class CurrentStackFrame(Reference[StackFrame | None]):
+    """The innermost frame the fiber runs in: a span from ``with_span`` or a
+    call of an ``@fx.fn`` function. ``None`` outside every frame."""
+
+    @classmethod
+    def default(cls) -> StackFrame | None:
+        return None
+
+
+class StackTrace(Tag[StackFrame]):
+    """The annotation a failure's reasons get: the frame it happened in."""
+
+
+class InterruptorStackTrace(Tag[StackFrame]):
+    """The annotation an interruption gets: the frame of the fiber that
+    interrupted."""
+
+
+def _no_location() -> None:
+    return None
+
+
+@final
+class _CallSite:
+    """A call site, rendered when first read. Keeps the code object and the
+    line, never the frame, so the caller's locals are not kept alive."""
+
+    __slots__ = ("_code", "_line", "_text")
+
+    def __init__(self, code: CodeType, line: int) -> None:
+        self._code = code
+        self._line = line
+        self._text: str | None = None
+
+    def __call__(self) -> str:
+        if self._text is None:
+            code = self._code
+            self._text = f"at {code.co_qualname} ({code.co_filename}:{self._line})"
+        return self._text
+
+
+def call_site(depth: int) -> Callable[[], str | None]:
+    """The location of the caller ``depth`` frames above the function
+    calling this one (1 is that function's caller)."""
+    frame = sys._getframe(depth + 1)  # pyright: ignore[reportPrivateUsage]
+    return _CallSite(frame.f_code, frame.f_lineno)
+
+
+def stack_of(capture: CaptureStackTrace, depth: int) -> Callable[[], str | None]:
+    """The location a frame records for ``capture``: the call site ``depth``
+    frames above the caller when ``True``."""
+    if capture is True:
+        return call_site(depth + 1)
+    if capture is False:
+        return _no_location
+    return capture
+
+
+def push(name: str, stack: Callable[[], str | None]) -> Callable[[StackFrame | None], StackFrame]:
+    """The update that runs inside a new frame ``name``."""
+    return lambda parent: StackFrame(name, stack, parent)
+
+
+_LOCATION = re.compile(r"\((.*)\)")
+
+
+def render(frame: StackFrame | None) -> list[str]:
+    """Effect's trace lines for ``frame`` and its parents (ten at most):
+    ``    at name (location)``."""
+    lines: list[str] = []
+    while frame is not None and len(lines) < 10:
+        location = frame.stack()
+        if location is None:
+            lines.append(f"    at {frame.name}")
+        else:
+            inner = _LOCATION.search(location)
+            where = inner.group(1) if inner else location.removeprefix("at ")
+            lines.append(f"    at {frame.name} ({where})")
+        frame = frame.parent
+    return lines

pyfect/_string_hash.py

@@ -0,0 +1,35 @@
+"""Effect's ``Hash.string``: the djb2 hash of a string's UTF-16 code units,
+with JavaScript's 32-bit integer arithmetic and ``Hash.optimize``. Hash
+rings and shard ids depend on the exact values, so they match Effect's."""
+
+from __future__ import annotations
+
+import sys
+from array import array
+from collections.abc import Sequence
+
+_UTF16_NATIVE = "utf-16-le" if sys.byteorder == "little" else "utf-16-be"
+
+
+def _int32(n: int) -> int:
+    n &= 0xFFFFFFFF
+    return n - 0x1_0000_0000 if n & 0x8000_0000 else n
+
+
+def optimize(n: int) -> int:
+    """``(n & 0xbfffffff) | ((n >>> 1) & 0x40000000)`` as a signed int32."""
+    u = n & 0xFFFFFFFF
+    return _int32((u & 0xBFFFFFFF) | ((u >> 1) & 0x40000000))
+
+
+def string_hash(text: str) -> int:
+    """Effect's ``Hash.string(text)``."""
+    # Unsigned 32-bit arithmetic: the same bits as JavaScript's int32 ops.
+    if text.isascii():
+        units: Sequence[int] = text.encode("ascii")
+    else:
+        units = array("H", text.encode(_UTF16_NATIVE, "surrogatepass"))
+    h = 5381
+    for unit in reversed(units):
+        h = ((h * 33) & 0xFFFFFFFF) ^ unit
+    return optimize(h)

pyfect/_subscriber_queue.py

@@ -0,0 +1,47 @@
+"""The queue a subscription to an outside publisher (a PostgreSQL
+``LISTEN``, a Redis ``SUBSCRIBE``) hands the program.
+
+It holds at most ``capacity`` messages the program has not taken. A
+publisher that gets further ahead fails the subscription with a
+``FellBehind`` cause (the messages already held are taken first), the way
+Redis drops a subscriber whose output buffer is full: memory stays bounded
+and nothing is lost silently.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Final
+
+from pyfect.cause import fail as fail_cause
+from pyfect.queue import Queue
+
+DEFAULT_CAPACITY: Final = 1024
+
+
+class FellBehind(Exception):
+    """The program left ``capacity`` messages untaken while more arrived."""
+
+    def __init__(self, what: str, capacity: int) -> None:
+        super().__init__(
+            f"{what}: the subscriber fell behind, holding {capacity} messages it had not "
+            "taken; take faster or pass a larger capacity"
+        )
+
+
+def check_capacity(capacity: int) -> int:
+    """``capacity`` when it can hold a message; raises ``ValueError``."""
+    if isinstance(capacity, bool) or capacity < 1:
+        raise ValueError(f"capacity must be a positive int, got {capacity!r}")
+    return capacity
+
+
+def offer[A, E](queue: Queue[A, E], items: Sequence[A], behind: Callable[[], E]) -> bool:
+    """Add ``items`` to ``queue`` (a ``Queue.dropping(capacity)``) without
+    waiting; when they do not all fit, fail
+    ``queue`` with ``behind()`` and give ``False``: stop delivering. Call on
+    the queue's fibers' scheduler thread."""
+    if not queue.offer_all_unsafe(items):
+        return True
+    queue.fail_cause_unsafe(fail_cause(behind()))
+    return False

pyfect/_tags.py

@@ -0,0 +1,14 @@
+"""``Tags[T]``: the classes a ``catch_tag`` or ``tap_error_tag`` matches.
+
+One class, or a tuple of any number of them (Effect's ``catchTag`` takes
+any number of tags). ``T`` is solved as the union of the classes::
+
+    eff.pipe(fx.catch_tag((A, B, C, D), lambda e: ...))  # e: A | B | C | D
+
+Every combinator taking classes to match uses this alias, so none caps
+how many it takes (``tests/test_tag_tuples.py``).
+"""
+
+type Tags[T] = type[T] | tuple[type[T], ...]
+
+__all__ = ["Tags"]

pyfect/_tracer_ref.py

@@ -0,0 +1,21 @@
+"""``CurrentTracer``, apart from ``pyfect.tracer`` so the fiber runtime can
+read a tracer's context hook without importing the span functions."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pyfect.context import Reference
+
+if TYPE_CHECKING:
+    from pyfect.tracer import Tracer
+
+
+class CurrentTracer(Reference["Tracer"]):
+    """The tracer spans are made with. ``native_tracer`` by default."""
+
+    @classmethod
+    def default(cls) -> Tracer:
+        from pyfect.tracer._native import native_tracer
+
+        return native_tracer

pyfect/_tx_ops.py

@@ -0,0 +1,77 @@
+"""Single-step transactional reads and writes over ``TxRef`` values, the
+building blocks of the transactional collections.
+
+Each runs in the running transaction, or as a transaction of its own, in one
+fiber step, so a read-then-write needs no ``tx`` wrapper to be atomic.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from pyfect._core import Effect
+from pyfect.option import Option
+from pyfect.transaction import Transaction, TransactionMeta, transactional, tx
+from pyfect.tx_ref import TxRef
+
+
+def read[A, B](ref: TxRef[A], f: Callable[[A], B]) -> Effect[B]:
+    """``f`` of the ref's value in the transaction."""
+    return transactional(lambda state: f(state._entry(ref)._value))
+
+
+def read2[A, B, C](first: TxRef[A], second: TxRef[B], f: Callable[[A, B], C]) -> Effect[C]:
+    """``f`` of two refs' values, read in one transaction."""
+    return transactional(lambda state: f(state._entry(first)._value, state._entry(second)._value))
+
+
+def update_reading[A, B](ref: TxRef[A], other: TxRef[B], f: Callable[[A, B], A]) -> Effect[None]:
+    """Replace ``ref``'s value with ``f(value, other's value)``, both read
+    in one transaction."""
+
+    def run(state: TransactionMeta) -> None:
+        source = state._entry(other)._value
+        entry = state._entry(ref)
+        entry._value = f(entry._value, source)
+        entry._written = True
+
+    return transactional(run)
+
+
+def modify_or_skip[A, B](ref: TxRef[A], f: Callable[[A], tuple[B, Option[A]]]) -> Effect[B]:
+    """Like ``TxRef.modify``, but ``f`` says whether to write: ``Some(value)``
+    writes ``value`` (waking the ref's waiters even when it is the current
+    value), ``None`` leaves the ref unwritten (Effect's ``remove`` /
+    ``modify`` on a missing key)."""
+
+    def run(state: TransactionMeta) -> B:
+        entry = state._entry(ref)
+        result, value = f(entry._value)
+        if value is not None:
+            entry._value = value.value
+            entry._written = True
+        return result
+
+    return transactional(run)
+
+
+def decide[A, E](f: Callable[[TransactionMeta], Effect[A, E, Transaction]]) -> Effect[A, E]:
+    """``f``'s verdict, in the running transaction or one of its own. ``f``
+    reads and writes refs with ``value`` and ``write`` in one step and
+    returns the outcome: a success, a failure, or ``tx_retry``."""
+    return tx(Transaction().flat_map(f))
+
+
+def value[A](state: TransactionMeta, ref: TxRef[A]) -> A:
+    """The ref's value in the transaction."""
+    entry: Any = state._entry(ref)
+    return entry._value
+
+
+def write[A](state: TransactionMeta, ref: TxRef[A], new: A) -> None:
+    """Write ``new`` to the ref in the transaction."""
+    entry = state._entry(ref)
+    entry._value = new
+    entry._written = True

pyfect/_unsubscripted.py

@@ -0,0 +1,23 @@
+"""``Unsubscripted``: the default type argument of a class whose constructors
+honour a subscript.
+
+``Ref[int | None].make(None)`` makes a ``Ref[int | None]``, and ``Ref.make(None)``
+infers a ``Ref[None]``. Pyright gives a class written without type arguments
+``Unknown`` ones, which no overload can tell from a subscript, so the class's
+type parameters default to this marker: an overload for ``type[Ref[Unsubscripted]]``
+infers from the arguments, the next takes the subscript
+(research/typing/ctor_1_subscript.py). A bare annotation (``r: Ref``) gets the marker
+too, so using it is a type error naming ``Unsubscripted``.
+"""
+
+from typing import Never, final
+
+
+@final
+class Unsubscripted:
+    """Never instantiated: it only stands for a missing type argument."""
+
+    __slots__ = ()
+
+    def __new__(cls) -> Never:
+        raise TypeError("Unsubscripted only stands for a missing type argument")

pyfect/_url.py

@@ -0,0 +1,54 @@
+"""The URL value every pyfect API gives back, and URL parsing as WHATWG's
+``URL.canParse`` sees it, for ``config.url`` and the schema codecs."""
+
+from __future__ import annotations
+
+import re
+from urllib.parse import SplitResult, urlsplit
+
+_SCHEME = re.compile(r"[A-Za-z][A-Za-z0-9+.\-]*")
+_SPECIAL_SCHEMES = frozenset({"http", "https", "ws", "wss", "ftp"})
+# Schemes whose URLs always have an authority (``//``), even an empty one.
+_AUTHORITY_SCHEMES = _SPECIAL_SCHEMES | {"file"}
+
+
+class Url(SplitResult):
+    """A URL: a ``urllib.parse.SplitResult`` whose ``str()`` is the URL
+    written out (``f"{url}/items"`` builds a URL), as JavaScript's ``URL``
+    writes its ``href``. ``Url(*urlsplit(text))`` makes one from text that
+    is not checked; ``http.url.from_string`` parses and normalizes it."""
+
+    __slots__ = ()
+
+    def __str__(self) -> str:
+        return write(self)
+
+
+def write(url: SplitResult) -> str:
+    """``url`` written out, as ``URL.href``."""
+    authority = f"//{url.netloc}" if url.netloc or url.scheme in _AUTHORITY_SCHEMES else ""
+    query = f"?{url.query}" if url.query else ""
+    fragment = f"#{url.fragment}" if url.fragment else ""
+    return f"{url.scheme}:{authority}{url.path}{query}{fragment}"
+
+
+def as_url(url: SplitResult) -> Url:
+    """``url`` as a ``Url`` (itself when it is one)."""
+    return url if isinstance(url, Url) else Url._make(url)
+
+
+def parse_url(text: str) -> Url | None:
+    """``text`` as a URL: an absolute one with a valid scheme, a host for
+    the special schemes and a numeric port in range; ``None`` otherwise."""
+    if any(ch <= " " or ch == "\x7f" for ch in text):
+        return None
+    try:
+        url = urlsplit(text)
+        _ = url.port  # raises ValueError for a port that is not a number in range
+    except ValueError:
+        return None
+    if not _SCHEME.fullmatch(url.scheme):
+        return None
+    if url.scheme.lower() in _SPECIAL_SCHEMES and not url.hostname:
+        return None
+    return Url._make(url)

pyfect/_waiters.py

@@ -0,0 +1,127 @@
+"""A list of parked fibers waiting for a state change.
+
+Waiters are woken to *retry*, never handed a value: whatever they wait
+for is taken in their own step. That way an interrupt that lands between
+the wake-up and the retry cannot lose anything. Spurious wake-ups are
+harmless: a woken fiber that finds nothing simply waits again.
+
+``wait`` takes the condition the caller is waiting for and checks it again as
+the fiber parks: a fiber can pause between its own check and the park, and a
+notify landing in that gap would otherwise find nobody to wake. The list keeps
+the condition, and ``notify_ready`` wakes every waiter whose condition holds,
+as Effect's ``releaseTakers`` does. There is no "wake exactly one": a woken
+fiber can pause for its step budget before it retries and be interrupted
+there, and a wake-up spent on it would leave the waiter behind it parked next
+to the item it was waiting for.
+
+A wake-up resumes the fiber at once (fibers resume synchronously, as in
+Effect). Where Effect defers it to a scheduled task instead (a queue's
+``scheduleReleaseTaker``, a semaphore release), use ``notify_ready_soon``
+or ``wake_soon``, so the notifier finishes its step first.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+import contextlib
+from collections import deque
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from pyfect._core import Effect, _Callback, _Succeed, _Sync
+
+if TYPE_CHECKING:
+    from pyfect.scheduler import Scheduler
+
+
+class _Waiter:
+    __slots__ = ("ready", "wake")
+
+    def __init__(self, ready: Callable[[], bool], wake: Callable[[], None]) -> None:
+        self.ready = ready
+        self.wake = wake
+
+
+def wake_soon(task: Callable[[], None]) -> None:
+    """Run ``task`` in a task scheduled on the running fiber's scheduler
+    (Effect's ``fiber.currentDispatcher.scheduleTask``), or now when no
+    fiber is running here."""
+    from pyfect._fiber import current_fiber
+
+    fiber = current_fiber()
+    if fiber is None:
+        task()
+    else:
+        fiber._scheduler.schedule(task)
+
+
+class WaitList:
+    __slots__ = ("_soon", "_waiters")
+
+    def __init__(self) -> None:
+        self._waiters: deque[_Waiter] = deque()
+        # Whether a ``notify_ready_soon`` task is pending.
+        self._soon = False
+
+    def wait(self, ready: Callable[[], bool]) -> Effect[None]:
+        """Park until notified, or not at all if ``ready()`` already holds."""
+
+        def register(resume: Callable[[Effect[None]], None]) -> Effect[None] | None:
+            if ready():
+                resume(_Succeed(None))
+                return None
+
+            waiter = _Waiter(ready, lambda: resume(_Succeed(None)))
+            self._waiters.append(waiter)
+            return _Sync(lambda: self._discard(waiter))
+
+        return _Callback(register)
+
+    def notify_ready(self) -> None:
+        """Wake every waiter whose condition holds now."""
+        ready: list[_Waiter] = []
+        parked: deque[_Waiter] = deque()
+        for waiter in self._waiters:
+            (ready if waiter.ready() else parked).append(waiter)
+        self._waiters = parked
+        for waiter in ready:
+            waiter.wake()
+
+    def notify_ready_soon(self, scheduler: Scheduler | None = None) -> None:
+        """``notify_ready`` in a task on ``scheduler``, else as ``wake_soon``;
+        several calls before it runs share it, as Effect's
+        ``scheduleReleaseTaker``."""
+        if self._soon or not self._waiters:
+            return
+        self._soon = True
+
+        def flush() -> None:
+            self._soon = False
+            self.notify_ready()
+
+        if scheduler is not None:
+            scheduler.schedule(flush)
+            return
+        from pyfect._fiber import current_fiber
+        from pyfect.scheduler import SyncOnlyScheduler
+
+        # Effect's queue holds the dispatcher of the fiber that made it, whichever
+        # fiber offers: under a ``run_sync`` the root flushes it.
+        fiber = current_fiber()
+        run = None if fiber is None else fiber._scheduler
+        if isinstance(run, SyncOnlyScheduler):
+            run.schedule_as_root(flush)
+        else:
+            wake_soon(flush)
+
+    def notify_all(self) -> None:
+        waiters, self._waiters = self._waiters, deque()
+        for waiter in waiters:
+            waiter.wake()
+
+    def __len__(self) -> int:
+        return len(self._waiters)
+
+    def _discard(self, waiter: _Waiter) -> None:
+        with contextlib.suppress(ValueError):
+            self._waiters.remove(waiter)