pyfect-dev 0.1.0__py3-none-any.whl

pyfect/terminal/_keys.py

@@ -0,0 +1,113 @@
+"""Terminal input as key presses, named as Node's ``readline`` names them
+(``emitKeypressEvents``)."""
+
+from __future__ import annotations
+
+import re
+
+from pyfect.terminal._service import Key, UserInput
+
+# ESC [ or ESC O, optional parameters, a final letter or "~".
+_SEQUENCE = re.compile(r"\x1b(?:\[|O)([0-9;]*)([A-Za-z~])")
+
+_FINAL_NAMES = {
+    "A": "up",
+    "B": "down",
+    "C": "right",
+    "D": "left",
+    "E": "clear",
+    "F": "end",
+    "H": "home",
+    "P": "f1",
+    "Q": "f2",
+    "R": "f3",
+    "S": "f4",
+}
+
+_TILDE_NAMES = {
+    "1": "home",
+    "2": "insert",
+    "3": "delete",
+    "4": "end",
+    "5": "pageup",
+    "6": "pagedown",
+    "7": "home",
+    "8": "end",
+    "11": "f1",
+    "12": "f2",
+    "13": "f3",
+    "14": "f4",
+    "15": "f5",
+    "17": "f6",
+    "18": "f7",
+    "19": "f8",
+    "20": "f9",
+    "21": "f10",
+    "23": "f11",
+    "24": "f12",
+}
+
+_SINGLE_NAMES = {
+    "\r": "return",
+    "\n": "enter",
+    "\t": "tab",
+    "\b": "backspace",
+    "\x7f": "backspace",
+    "\x1b": "escape",
+    " ": "space",
+}
+
+
+def _modifiers(code: int) -> tuple[bool, bool, bool]:
+    """``(ctrl, meta, shift)`` from an xterm modifier parameter."""
+    bits = max(code - 1, 0)
+    return bool(bits & 4), bool(bits & 10), bool(bits & 1)
+
+
+def _sequence(params: str, final: str) -> Key:
+    parts = params.split(";") if params else []
+    ctrl, meta, shift = _modifiers(int(parts[1])) if len(parts) > 1 and parts[1] else (False,) * 3
+    if final == "~":
+        name = _TILDE_NAMES.get(parts[0] if parts else "", "undefined")
+    elif final == "Z":
+        return Key("tab", shift=True)
+    else:
+        name = _FINAL_NAMES.get(final, "undefined")
+    return Key("" if name == "undefined" else name, ctrl=ctrl, meta=meta, shift=shift)
+
+
+def _single(char: str, *, meta: bool = False) -> Key:
+    if char in _SINGLE_NAMES:
+        return Key(_SINGLE_NAMES[char], meta=meta)
+    code = ord(char)
+    if code < 0x20:
+        return Key(chr(code + 0x60), ctrl=True, meta=meta)
+    if char.isascii() and char.isalnum():
+        return Key(char.lower(), meta=meta, shift=char.isupper())
+    return Key("", meta=meta)
+
+
+def decode(text: str) -> list[UserInput]:
+    """The key presses in ``text``. A lone ESC is the escape key; ESC
+    before a character is that key with ``meta``."""
+    events: list[UserInput] = []
+    position = 0
+    while position < len(text):
+        sequence = _SEQUENCE.match(text, position)
+        if sequence is not None:
+            events.append(UserInput(None, _sequence(sequence.group(1), sequence.group(2))))
+            position = sequence.end()
+            continue
+        char = text[position]
+        if char == "\x1b" and position + 1 < len(text) and text[position + 1] != "\x1b":
+            following = text[position + 1]
+            events.append(UserInput(following, _single(following, meta=True)))
+            position += 2
+            continue
+        if char == "\r" and text.startswith("\n", position + 1):
+            events.append(UserInput("\r\n", Key("return")))
+            position += 2
+            continue
+        events.append(UserInput(char, _single(char)))
+        position += 1
+    return events

pyfect/terminal/_live.py

@@ -0,0 +1,223 @@
+"""The live ``Terminal``: standard input read as lines or key presses,
+standard output for display (the counterpart of Effect's Node terminal).
+
+Input is read from the file descriptor in short waits on a worker thread,
+straight into a buffer the terminal keeps, so an interrupted read loses
+nothing and later reads see every byte. Key input puts a TTY in raw mode
+while a ``read_input`` scope is open; ``read_line`` leaves it as it is."""
+
+from __future__ import annotations
+
+import codecs
+import os
+import select
+import sys
+import threading
+from collections.abc import Callable, Generator
+from typing import Any, Never, TextIO
+
+from pyfect._core import Effect
+from pyfect.effect import blocking, gen, sync, try_blocking
+from pyfect.errors import Done
+from pyfect.platform_error import PlatformError, bad_argument
+from pyfect.queue import Dequeue, Queue
+from pyfect.scope import Scope, acquire_release
+from pyfect.terminal._keys import decode
+from pyfect.terminal._service import QuitError, TerminalService, UserInput, default_should_quit
+
+_WAIT = 0.05
+"""Seconds one read waits for input before giving the fiber back."""
+
+
+class _Input:
+    """Bytes read from standard input that no reader has taken yet."""
+
+    __slots__ = ("_fd", "_filling", "_lock", "buffer", "ended")
+
+    def __init__(self, fd: Callable[[], int]) -> None:
+        self._fd = fd
+        self._lock = threading.Lock()
+        # One reader of the descriptor at a time, so bytes reach the buffer
+        # in the order they were read.
+        self._filling = threading.Lock()
+        self.buffer = bytearray()
+        self.ended = False
+
+    def fill(self) -> None:
+        """Wait a moment for input and keep what arrives (on a worker
+        thread)."""
+        with self._filling:
+            if self.ended:
+                return
+            try:
+                fd = self._fd()
+                if os.name != "nt" and not select.select([fd], [], [], _WAIT)[0]:
+                    return
+                data = os.read(fd, 4096)
+            except (OSError, ValueError):
+                data = b""
+            with self._lock:
+                if data:
+                    self.buffer += data
+                else:
+                    self.ended = True
+
+    def take_line(self) -> str | None:
+        """The next line without its line break; at the end of input, what
+        is left (an unterminated last line)."""
+        with self._lock:
+            end = self.buffer.find(b"\n")
+            if end >= 0:
+                line = bytes(self.buffer[:end])
+                del self.buffer[: end + 1]
+            elif self.ended and self.buffer:
+                line = bytes(self.buffer)
+                self.buffer.clear()
+            else:
+                return None
+        return line.decode(errors="replace").removesuffix("\r")
+
+    def take_all(self) -> bytes:
+        with self._lock:
+            data = bytes(self.buffer)
+            self.buffer.clear()
+            return data
+
+
+class _RawMode:
+    """A TTY's raw mode, held while any key reader needs it (libuv's raw
+    mode: no echo, no line editing, no signals)."""
+
+    __slots__ = ("_fd", "_saved", "_users")
+
+    def __init__(self, fd: Callable[[], int]) -> None:
+        self._fd = fd
+        self._users = 0
+        self._saved: list[Any] | None = None
+
+    def acquire(self) -> None:
+        self._users += 1
+        if self._users > 1:
+            return
+        try:
+            import termios
+
+            fd = self._fd()
+            if not os.isatty(fd):
+                return
+            saved = termios.tcgetattr(fd)
+            raw = termios.tcgetattr(fd)
+            raw[0] &= ~(termios.BRKINT | termios.ICRNL | termios.INPCK | termios.ISTRIP)
+            raw[0] &= ~termios.IXON
+            raw[1] |= termios.ONLCR
+            raw[2] |= termios.CS8
+            raw[3] &= ~(termios.ECHO | termios.ICANON | termios.IEXTEN | termios.ISIG)
+            termios.tcsetattr(fd, termios.TCSADRAIN, raw)
+            self._saved = saved
+        except (ImportError, OSError, ValueError):
+            return
+
+    def release(self) -> None:
+        self._users -= 1
+        if self._users > 0 or self._saved is None:
+            return
+        import termios
+
+        saved, self._saved = self._saved, None
+        try:
+            termios.tcsetattr(self._fd(), termios.TCSADRAIN, saved)
+        except (OSError, ValueError):
+            return
+
+
+def _size(output: TextIO) -> os.terminal_size | None:
+    try:
+        return os.get_terminal_size(output.fileno())
+    except (OSError, ValueError, AttributeError):
+        return None
+
+
+def live(
+    *,
+    should_quit: Callable[[UserInput], bool] = default_should_quit,
+    input: int | None = None,
+    output: TextIO | None = None,
+) -> TerminalService:
+    """A terminal over the file descriptor ``input`` and the text stream
+    ``output`` (standard input and output, looked up when used). A key
+    press for which ``should_quit`` is true ends ``read_input``'s queue
+    after it is delivered."""
+
+    def input_fd() -> int:
+        return sys.stdin.fileno() if input is None else input
+
+    def out() -> TextIO:
+        return sys.stdout if output is None else output
+
+    source = _Input(input_fd)
+    raw_mode = _RawMode(input_fd)
+    fill = blocking(source.fill)
+
+    def read_line() -> Generator[Effect[Any, QuitError], Any, str]:
+        while True:
+            line = source.take_line()
+            if line is not None:
+                return line
+            if source.ended:
+                return (yield from QuitError())
+            yield from fill
+
+    def read_input() -> Generator[Effect[Any, Never, Scope], Any, Dequeue[UserInput, Done]]:
+        queue = yield from Queue[UserInput, Done].unbounded()
+        yield from acquire_release(sync(raw_mode.acquire), lambda _a, _e: sync(raw_mode.release))
+        decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
+
+        def pump() -> Generator[Effect[Any], Any]:
+            while True:
+                data = source.take_all()
+                if data:
+                    for event in decode(decoder.decode(data)):
+                        yield from queue.offer(event)
+                        if should_quit(event):
+                            yield from queue.end()
+                            return
+                elif source.ended:
+                    yield from queue.end()
+                    return
+                else:
+                    yield from fill
+
+        yield from gen(pump).fork_scoped()
+        return queue
+
+    def write(text: str) -> None:
+        target = out()
+        target.write(text)
+        target.flush()
+
+    def display(text: str) -> Effect[None, PlatformError]:
+        return try_blocking(
+            lambda: write(text),
+            lambda cause: bad_argument(
+                module="Terminal",
+                method="display",
+                description="Failed to write prompt to stdout",
+                cause=cause,
+            ),
+        ).uninterruptible()
+
+    def columns() -> int:
+        size = _size(out())
+        return 0 if size is None else size.columns
+
+    def rows() -> int:
+        size = _size(out())
+        return 0 if size is None else size.lines
+
+    return TerminalService(
+        columns=sync(columns),
+        rows=sync(rows),
+        read_input=gen(read_input),
+        read_line=gen(read_line),
+        display=display,
+    )

pyfect/terminal/_service.py

@@ -0,0 +1,73 @@
+"""The ``Terminal`` service and its input events."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Never
+
+from pyfect._core import Effect
+from pyfect._effect_args import require_effect
+from pyfect.context import Tag
+from pyfect.errors import Done, TaggedError
+from pyfect.platform_error import PlatformError
+from pyfect.queue import Dequeue
+from pyfect.scope import Scope
+
+
+@dataclass(frozen=True, slots=True)
+class Key:
+    """A key pressed: its name (``"a"``, ``"return"``, ``"up"``, ``""``
+    for punctuation) and the modifiers held."""
+
+    name: str
+    ctrl: bool = False
+    meta: bool = False
+    shift: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class UserInput:
+    """One key press: the character it typed (``None`` for an escape
+    sequence such as an arrow key) and the key."""
+
+    input: str | None
+    key: Key
+
+
+@dataclass(eq=False)
+class QuitError(TaggedError):
+    """The user quit a prompt (usually with Ctrl+C), or input ended."""
+
+    @property
+    def message(self) -> str:
+        return "QuitError"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TerminalService:
+    """Effect's ``Terminal``; the constructor is ``Terminal.make``.
+
+    ``read_input`` gives a queue of key presses for as long as its scope is
+    open; the queue ends when input ends or the user quits.
+    ``read_line`` reads one line without its line break."""
+
+    columns: Effect[int]
+    rows: Effect[int]
+    read_input: Effect[Dequeue[UserInput, Done], Never, Scope]
+    read_line: Effect[str, QuitError]
+    display: Callable[[str], Effect[None, PlatformError]]
+
+    def __post_init__(self) -> None:
+        for name in ("columns", "rows", "read_input", "read_line"):
+            require_effect(getattr(self, name), name)
+
+
+class Terminal(Tag[TerminalService]):
+    """The terminal a program talks to."""
+
+
+def default_should_quit(event: UserInput) -> bool:
+    """Escape, Ctrl+C and Ctrl+D quit, as in Effect's Node terminal."""
+    key = event.key
+    return key.name == "escape" or (key.ctrl and key.name in ("c", "d"))

pyfect/testing/__init__.py

@@ -0,0 +1,122 @@
+"""Deterministic tests, and a pytest plugin to write them as effects.
+
+A ``TestClock`` only moves when the test says so, with ``adjust`` or
+``set_time``; each move lets ready fibers run, then wakes sleepers in order
+and waits for each woken fiber to suspend, so timing tests are exact and
+take no real time::
+
+    @testing.effect
+    def test_timeout():
+        fiber = yield from fx.sleep(10).timeout(5).exit().fork()
+        yield from testing.adjust(5)
+        assert isinstance((yield from fiber.join()), fx.Failure)
+
+- ``effect`` / ``live``: pytest tests written as generators or effects,
+  with a ``TestClock`` and ``TestConsole`` (or the live ones) and a ``Scope``, a real-time
+  timeout that interrupts them and runs their finalizers, and
+  ``asyncio=True`` for effects that need an event loop.
+- ``layer_fixture``: build a layer once per pytest scope; tests that take
+  the fixture as ``Services[...]`` get its services.
+- ``effect_fixture``: run a scoped effect once per pytest scope; tests get
+  its value, and its finalizers run when the scope ends.
+- ``flaky``: retry a test effect that sometimes fails.
+- ``run_test`` / ``run_test_async``: run one effect with a ``TestClock``,
+  synchronously or on the running asyncio loop.
+- ``with_live``, ``TestClock.layer()``: the live clock inside a test, and a
+  test clock inside any program.
+- ``TestConsole``: a console recording every call; ``effect`` tests run
+  with a fresh one, read back with ``log_lines`` / ``error_lines``.
+- ``assert_exit_success`` and friends: failures print ``Cause.pretty()``;
+  ``assert_exit_fail(exit, error)`` compares a failure by its error alone.
+- ``TestCrypto``: a seeded, repeatable ``Crypto`` that keeps the real
+  digests.
+- ``SchemaAsserts``: decode, encode and make assertions for a schema.
+- ``prop`` / ``effect_prop`` / ``live_prop``: property tests over schemas
+  and Hypothesis strategies (``it.prop`` / ``it.effect.prop`` /
+  ``it.live.prop``).
+
+If every fiber ends up waiting with nothing to wake them, synchronous runs
+raise ``StalledError`` instead of hanging. A woken fiber that never suspends
+makes ``adjust`` warn with ``BusyFiberWarning`` and move on. ``adjust``
+waits for work handed to threads (``blocking``, SQLite, HTTP calls), not for
+events that may never come (socket reads, Postgres or Redis notifications,
+blocking Redis commands, worker messages, a child's exit).
+"""
+
+from pyfect._public import publish
+from pyfect.scheduler import StalledError
+from pyfect.testing._assertions import (
+    assert_exit_fail,
+    assert_exit_failure,
+    assert_exit_success,
+    assert_failure,
+    assert_success,
+)
+from pyfect.testing._clock import (
+    BusyFiberWarning,
+    ClockNotAdvancedWarning,
+    TestClock,
+    adjust,
+    set_time,
+    test_clock,
+    with_live,
+)
+from pyfect.testing._console import (
+    Entry,
+    TestConsole,
+    error_lines,
+    log_lines,
+    test_console,
+)
+from pyfect.testing._crypto import TestCrypto
+from pyfect.testing._decorators import TestBody, TestDecorator, effect, live
+from pyfect.testing._flaky import flaky
+from pyfect.testing._layers import Services, effect_fixture, layer_fixture
+from pyfect.testing._prop import Arbitrary, PropertyFalsifiedError, effect_prop, live_prop, prop
+from pyfect.testing._runners import run_test, run_test_async, run_test_async_exit, run_test_exit
+from pyfect.testing._runtime import TestTimeoutError
+from pyfect.testing._schema import SchemaAsserts, SchemaCheck
+
+__all__ = [
+    "Arbitrary",
+    "BusyFiberWarning",
+    "ClockNotAdvancedWarning",
+    "Entry",
+    "PropertyFalsifiedError",
+    "SchemaAsserts",
+    "SchemaCheck",
+    "Services",
+    "StalledError",
+    "TestBody",
+    "TestClock",
+    "TestConsole",
+    "TestCrypto",
+    "TestDecorator",
+    "TestTimeoutError",
+    "adjust",
+    "assert_exit_fail",
+    "assert_exit_failure",
+    "assert_exit_success",
+    "assert_failure",
+    "assert_success",
+    "effect",
+    "effect_fixture",
+    "effect_prop",
+    "error_lines",
+    "flaky",
+    "layer_fixture",
+    "live",
+    "live_prop",
+    "log_lines",
+    "prop",
+    "run_test",
+    "run_test_async",
+    "run_test_async_exit",
+    "run_test_exit",
+    "set_time",
+    "test_clock",
+    "test_console",
+    "with_live",
+]
+
+publish(globals())

pyfect/testing/_assertions.py

@@ -0,0 +1,92 @@
+"""Assertions on ``Exit`` and ``Result`` that show the whole ``Cause``.
+
+A failed ``assert ex == Success(1)`` only prints the reprs; these print
+``Cause.pretty()``, tracebacks included."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from types import MappingProxyType
+from typing import Any
+
+from pyfect.cause import Cause, Fail, Reason
+from pyfect.exit import Exit, Failure, Success
+from pyfect.result import Err, Ok, Result
+
+
+def describe_exit(ex: Exit[Any, Any]) -> str:
+    """``Success(value)``, or ``Failure`` followed by the pretty cause."""
+    if isinstance(ex, Success):
+        return repr(ex)
+    return f"Failure with cause:\n{_pretty(ex.cause)}"
+
+
+def _pretty(cause: Cause[Any]) -> str:
+    return cause.pretty() or "(empty cause)"
+
+
+def assert_exit_success[A](ex: Exit[A, Any], expected: A) -> None:
+    """``ex`` is ``Success(expected)``."""
+    if isinstance(ex, Failure):
+        raise AssertionError(f"expected Success({expected!r}), got {describe_exit(ex)}")
+    if ex.value != expected:
+        raise AssertionError(f"expected Success({expected!r}), got Success({ex.value!r})")
+
+
+def assert_exit_failure[E](ex: Exit[Any, E], expected: Cause[E]) -> None:
+    """``ex`` is a ``Failure`` whose cause equals ``expected``, annotations
+    included (``assert_exit_fail`` compares by error)."""
+    if isinstance(ex, Failure) and ex.cause == expected:
+        return
+    lines = [f"expected Failure with cause:\n{_pretty(expected)}\ngot {describe_exit(ex)}"]
+    if isinstance(ex, Failure):
+        lines.extend(annotation_difference(ex.cause, expected, ("got", "expected")))
+    raise AssertionError("\n".join(lines))
+
+
+def assert_exit_fail[E](ex: Exit[Any, E], expected: E) -> None:
+    """``ex`` failed with ``expected`` and nothing else: ``exit.fail(expected)``,
+    compared without annotations such as the span the failure happened in."""
+    want: Cause[E] = Cause((Fail(expected),))
+    if isinstance(ex, Failure) and _bare(ex.cause) == want:
+        return
+    raise AssertionError(f"expected Failure with cause:\n{_pretty(want)}\ngot {describe_exit(ex)}")
+
+
+_NONE: MappingProxyType[Any, object] = MappingProxyType({})
+
+
+def _bare[E](cause: Cause[E]) -> Cause[E]:
+    reasons: tuple[Reason[E], ...] = tuple(replace(r, annotations=_NONE) for r in cause.reasons)
+    return Cause(reasons)
+
+
+def _annotations(reason: Reason[Any]) -> str:
+    items = reason.annotations.items()
+    return ", ".join(f"{key.__name__}: {value!r}" for key, value in items) or "none"
+
+
+def annotation_difference(
+    left: Cause[Any], right: Cause[Any], sides: tuple[str, str] = ("left", "right")
+) -> list[str]:
+    """When two unequal causes are equal but for their reasons' annotations,
+    lines showing each side's annotations; else no lines."""
+    if left == right or _bare(left) != _bare(right):
+        return []
+    lines = ["The causes are equal but for their annotations:"]
+    for side, cause in zip(sides, (left, right), strict=True):
+        lines.extend(f"  {side} {r!r} annotations: {_annotations(r)}" for r in cause.reasons)
+    lines.append("Compare by error with testing.assert_exit_fail(exit, error).")
+    return lines
+
+
+def assert_success[A](result: Result[A, Any], expected: A) -> None:
+    """``result`` is ``Ok(expected)``."""
+    if result != Ok(expected):
+        raise AssertionError(f"expected Ok({expected!r}), got {result!r}")
+
+
+def assert_failure[E](result: Result[Any, E], expected: E) -> None:
+    """``result`` is ``Err(expected)``."""
+    if result != Err(expected):
+        raise AssertionError(f"expected Err({expected!r}), got {result!r}")