turbodesk 0.3.0__py3-none-any.whl

turbodesk/__init__.py

@@ -0,0 +1,31 @@
+"""turbodesk — terminal UIs as pure functions from state to an immutable view tree.
+
+An app is a function `(UI) -> View`. It re-runs whenever something marks the frame
+dirty; state lives in hooks on the `UI` handle.
+
+    from turbodesk import View, run
+
+    def app(ui):
+        return View.text("Hello world!").center(within=ui.size)
+
+    run(app)
+"""
+
+from __future__ import annotations
+
+from .runtime import UI, Drag, run
+from .theme import Theme
+from .view import Color, Pos, Region, Size, Style, View
+
+__all__ = [
+    "UI",
+    "Color",
+    "Drag",
+    "Pos",
+    "Region",
+    "Size",
+    "Style",
+    "Theme",
+    "View",
+    "run",
+]

turbodesk/ansi.py

@@ -0,0 +1,124 @@
+"""Parse ANSI-escaped text back into a `View`.
+
+The inverse of the renderer: takes what another program wrote to a terminal and turns
+it into styled cells. Useful for showing the output of a subprocess (`ls --color`,
+`git diff`, a captured tmux pane) inside a turbodesk app.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .view import Color, Style, View
+
+SGR = re.compile(r"\x1b\[([0-9;]*)m")
+OTHER_ESCAPES = re.compile(
+    r"\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[\[\(][0-9;?]*[A-Za-z]|\x1b."
+)
+
+
+def render(
+    text: str, *, base: Style | None = None, fill_width: int | None = None
+) -> View:
+    """Render escape-coded `text`.
+
+    `base` supplies the colours for spans that don't set their own. `fill_width` pads
+    every line out to that width, so a background colour covers the whole line.
+    """
+    base = base or Style()
+    lines = [_line(line, base, fill_width) for line in _clean(text).split("\n")]
+    return View.vcat(lines)
+
+
+def _clean(text: str) -> str:
+    """Drop escape sequences we don't interpret, keeping the SGR ones."""
+    return OTHER_ESCAPES.sub(
+        lambda m: m.group(0) if SGR.fullmatch(m.group(0)) else "", text
+    )
+
+
+def _line(line: str, base: Style, fill_width: int | None) -> View:
+    spans: list[View] = []
+    style = base
+    position = 0
+    width = 0
+
+    for match in SGR.finditer(line):
+        chunk = line[position : match.start()]
+        if chunk:
+            spans.append(View.text(chunk, style))
+            width += spans[-1].width
+        style = _apply(style, base, match.group(1))
+        position = match.end()
+
+    tail = line[position:]
+    if tail:
+        spans.append(View.text(tail, style))
+        width += spans[-1].width
+    if fill_width is not None and width < fill_width:
+        spans.append(View.text(" " * (fill_width - width), style))
+    return View.hcat(spans) if spans else View.text("", base)
+
+
+def _apply(style: Style, base: Style, params: str) -> Style:
+    """Fold one SGR sequence into `style`.
+
+    One case per code, spelled out, so this reads against the ANSI table it implements.
+    Codes we don't know fall through and change nothing, which is what a terminal does.
+    """
+    codes = [int(p) for p in params.split(";") if p] or [0]
+    index = 0
+    while index < len(codes):
+        code = codes[index]
+        match code:
+            case 0:
+                style = base
+            case 1:
+                style = style._replace(bold=True)
+            case 3:
+                style = style._replace(italic=True)
+            case 4:
+                style = style._replace(underline=True)
+            case 5:
+                style = style._replace(blink=True)
+            case 7:
+                style = style._replace(invert=True)
+            case 22:
+                style = style._replace(bold=False)
+            case 23:
+                style = style._replace(italic=False)
+            case 24:
+                style = style._replace(underline=False)
+            case 25:
+                style = style._replace(blink=False)
+            case 27:
+                style = style._replace(invert=False)
+            case 38:
+                color, index = _extended(codes, index)
+                style = style._replace(fg=color)
+            case 48:
+                color, index = _extended(codes, index)
+                style = style._replace(bg=color)
+            case 39:
+                style = style._replace(fg=base.fg)
+            case 49:
+                style = style._replace(bg=base.bg)
+            case _ if 30 <= code <= 37:
+                style = style._replace(fg=Color.ansi16(code - 30))
+            case _ if 40 <= code <= 47:
+                style = style._replace(bg=Color.ansi16(code - 40))
+            case _ if 90 <= code <= 97:
+                style = style._replace(fg=Color.ansi16(code - 82))
+            case _ if 100 <= code <= 107:
+                style = style._replace(bg=Color.ansi16(code - 92))
+        index += 1
+    return style
+
+
+def _extended(codes: list[int], index: int) -> tuple[Color | None, int]:
+    """Read a `38;5;n` or `38;2;r;g;b` colour, with the index it ended on."""
+    if index + 1 < len(codes) and codes[index + 1] == 5 and index + 2 < len(codes):
+        return Color.xterm256(codes[index + 2]), index + 2
+    if index + 1 < len(codes) and codes[index + 1] == 2 and index + 4 < len(codes):
+        return Color(*codes[index + 2 : index + 5]), index + 4
+    return None, index

turbodesk/clipboard.py

@@ -0,0 +1,89 @@
+"""Reading and writing the system clipboard.
+
+Copying goes out over OSC 52 *and* a local helper, because neither works everywhere:
+OSC 52 is the only thing that crosses an ssh session, but several terminals ignore it
+(PuTTY, the VS Code integrated terminal), and a local helper can't reach the machine
+you're actually sitting at. Doing both covers more ground than either.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import os
+import shutil
+import sys
+
+PRIMARY = "primary"
+CLIPBOARD = "clipboard"
+
+# Each entry is (copy command, paste command); the first available one wins.
+HELPERS = (
+    (["pbcopy"], ["pbpaste"]),
+    (["wl-copy"], ["wl-paste", "--no-newline"]),
+    (["xclip", "-selection", "clipboard"], ["xclip", "-selection", "clipboard", "-o"]),
+    (["xsel", "--clipboard", "--input"], ["xsel", "--clipboard", "--output"]),
+)
+
+
+def osc52(text: str, selection: str = CLIPBOARD) -> str:
+    """The escape sequence that asks the terminal to set the clipboard."""
+    target = "p" if selection == PRIMARY else "c"
+    encoded = base64.b64encode(text.encode()).decode()
+    return f"\x1b]52;{target};{encoded}\x07"
+
+
+async def copy(text: str, selection: str = CLIPBOARD) -> bool:
+    """Copy `text`. True if a local helper took it; OSC 52 is always attempted."""
+    _write_escape(osc52(text, selection))
+    command = _helper(selection, index=0)
+    if command is None:
+        return False
+    process = await asyncio.create_subprocess_exec(
+        *command, stdin=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.DEVNULL
+    )
+    await process.communicate(text.encode())
+    return process.returncode == 0
+
+
+async def paste(selection: str = CLIPBOARD) -> str:
+    """Read the clipboard. Empty if no helper is installed.
+
+    There is no OSC 52 fallback: reading back requires the terminal to answer, and
+    enough of them refuse (it lets a remote host read your clipboard) that relying on
+    it would be worse than returning nothing.
+    """
+    command = _helper(selection, index=1)
+    if command is None:
+        return ""
+    process = await asyncio.create_subprocess_exec(
+        *command, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.DEVNULL
+    )
+    stdout, _ = await process.communicate()
+    return stdout.decode(errors="replace") if process.returncode == 0 else ""
+
+
+def _helper(selection: str, index: int) -> list[str] | None:
+    for pair in HELPERS:
+        command = list(pair[index])
+        if shutil.which(command[0]) is None:
+            continue
+        if selection == PRIMARY and command[0] in ("xclip", "xsel"):
+            command = [part.replace("clipboard", "primary") for part in command]
+        return command
+    return None
+
+
+def _write_escape(sequence: str) -> None:
+    """Escape sequences have to reach the terminal, not a redirected stdout."""
+    try:
+        fd = os.open("/dev/tty", os.O_WRONLY)
+    except OSError:
+        if sys.stdout.isatty():
+            sys.stdout.write(sequence)
+            sys.stdout.flush()
+        return
+    try:
+        os.write(fd, sequence.encode())
+    finally:
+        os.close(fd)

turbodesk/commands.py

@@ -0,0 +1,42 @@
+"""A command table: what the app can do right now, keyed by id.
+
+A Turbo Vision-style registry, stripped to the shape two callers already share. One
+table is read by the menu (to grey items and to run them), by the keyboard and by the
+status line, so a shortcut can never do something its own menu item says is
+unavailable. An id that is absent from the table greys; an id that is present runs.
+
+`dispatch` is the one piece of logic `examples/turbo_python` and `examples/windows.py`
+both hand-rolled identically: dismiss whatever is open, look the command up, run it.
+There is deliberately no `Command` record — the id is the dict key, and the label lives
+in the menu data, so nothing is duplicated.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+Command = Callable[[], None]
+"""A command's action. Takes and returns nothing: it closes over its own application
+state, which is what lets the same table drive a menu, a keyboard handler and a status
+line."""
+
+
+def dispatch(
+    table: dict[str, Command],
+    name: str,
+    *,
+    close: Callable[[], None],
+) -> bool:
+    """Run the command `name`, returning True if one existed.
+
+    `close` dismisses whatever was open — a pull-down, a popup — and runs first, because
+    picking a command always closes the thing it was picked from. Returns False when
+    `name` is absent, so a keyboard handler can leave the event to someone else without
+    pre-checking membership itself.
+    """
+    close()
+    action = table.get(name)
+    if action is None:
+        return False
+    action()
+    return True

turbodesk/debug.py

@@ -0,0 +1,44 @@
+"""Print debugging for a program that owns the screen.
+
+`print` inside a turbodesk app writes into the alternate screen and is destroyed on the
+next frame. This writes to a file instead:
+
+    from turbodesk import debug
+    debug.log("visited", location, len(history))
+
+and in another terminal:
+
+    tail -f turbodesk.log
+
+Set `$TURBODESK_LOG` to put it somewhere else. Logging is off when the file cannot be
+opened, so leaving calls in never breaks anything.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import time
+from pathlib import Path
+
+DEFAULT_FILE = "turbodesk.log"
+_started = time.monotonic()
+
+
+def log_file() -> Path:
+    return Path(os.environ.get("TURBODESK_LOG", DEFAULT_FILE))
+
+
+def log(*parts: object) -> None:
+    """Append a timestamped line. Never raises."""
+    stamp = f"{time.monotonic() - _started:8.3f}"
+    line = f"{stamp}  {' '.join(str(part) for part in parts)}\n"
+    # A log that cannot be written is not worth an exception.
+    with contextlib.suppress(OSError), log_file().open("a") as handle:
+        handle.write(line)
+
+
+def clear() -> None:
+    """Start a fresh log, so a run's output is not buried under the last one's."""
+    with contextlib.suppress(OSError):
+        log_file().write_text("")

turbodesk/events.py

@@ -0,0 +1,261 @@
+"""Input events, and the terminal escape-sequence parser that produces them."""
+
+from __future__ import annotations
+
+import codecs
+import re
+import time
+from enum import Enum
+from typing import Literal, NamedTuple
+
+from .view import Pos
+
+
+class Mod(Enum):
+    META = "meta"
+    CTRL = "ctrl"
+    SHIFT = "shift"
+
+
+class Key(Enum):
+    ESCAPE = "escape"
+    ENTER = "enter"
+    TAB = "tab"
+    BACKSPACE = "backspace"
+    INSERT = "insert"
+    DELETE = "delete"
+    HOME = "home"
+    END = "end"
+    UP = "up"
+    DOWN = "down"
+    LEFT = "left"
+    RIGHT = "right"
+    PAGE_UP = "page_up"
+    PAGE_DOWN = "page_down"
+    F1 = "f1"
+    F2 = "f2"
+    F3 = "f3"
+    F4 = "f4"
+    F5 = "f5"
+    F6 = "f6"
+    F7 = "f7"
+    F8 = "f8"
+    F9 = "f9"
+    F10 = "f10"
+    F11 = "f11"
+    F12 = "f12"
+
+
+class MouseKind(Enum):
+    LEFT = "left"
+    MIDDLE = "middle"
+    RIGHT = "right"
+    SCROLL_UP = "scroll_up"
+    SCROLL_DOWN = "scroll_down"
+    DRAG = "drag"
+    HOVER = "hover"
+    RELEASE = "release"
+
+
+class KeyPress(NamedTuple):
+    key: str | Key
+    mods: frozenset[Mod] = frozenset()
+
+
+class Mouse(NamedTuple):
+    kind: MouseKind
+    pos: Pos
+    mods: frozenset[Mod] = frozenset()
+
+
+PastePhase = Literal["start", "end"]
+
+
+class Paste(NamedTuple):
+    phase: PastePhase
+
+
+Event = KeyPress | Mouse | Paste
+
+_CSI = re.compile(r"\x1b\[([0-9;<]*)([A-Za-z~])")
+_SGR_MOUSE = re.compile(r"\x1b\[<([0-9]+);([0-9]+);([0-9]+)([Mm])")
+
+_CSI_KEYS = {
+    "A": Key.UP,
+    "B": Key.DOWN,
+    "C": Key.RIGHT,
+    "D": Key.LEFT,
+    "H": Key.HOME,
+    "F": Key.END,
+    "P": Key.F1,
+    "Q": Key.F2,
+    "R": Key.F3,
+    "S": Key.F4,
+}
+_TILDE_KEYS = {
+    1: Key.HOME,
+    2: Key.INSERT,
+    3: Key.DELETE,
+    4: Key.END,
+    5: Key.PAGE_UP,
+    6: Key.PAGE_DOWN,
+    15: Key.F5,
+    17: Key.F6,
+    18: Key.F7,
+    19: Key.F8,
+    20: Key.F9,
+    21: Key.F10,
+    23: Key.F11,
+    24: Key.F12,
+}
+_CONTROL_KEYS = {"\r": Key.ENTER, "\n": Key.ENTER, "\t": Key.TAB, "\x7f": Key.BACKSPACE}
+
+
+def _xterm_mods(param: int) -> frozenset[Mod]:
+    """xterm encodes modifiers as 1 + bitmask in the second CSI parameter."""
+    bits = param - 1
+    mods = set()
+    if bits & 1:
+        mods.add(Mod.SHIFT)
+    if bits & 2:
+        mods.add(Mod.META)
+    if bits & 4:
+        mods.add(Mod.CTRL)
+    return frozenset(mods)
+
+
+def _with_meta(event: Event | None) -> Event | None:
+    """Add Alt to a key press that arrived behind an ESC prefix."""
+    if not isinstance(event, KeyPress):
+        return event
+    return event._replace(mods=event.mods | {Mod.META})
+
+
+ESCAPE_TIMEOUT = 0.03
+
+
+class Parser:
+    """Incremental parser: feed it bytes, get events back.
+
+    A lone ESC is ambiguous — it may be the Escape key, or the start of an arrow key or
+    an Alt combination — so it is held back until `flush()` sees that nothing followed
+    it for `ESCAPE_TIMEOUT`. Every terminal application needs this timer; vim calls it
+    `ttimeoutlen` and defaults it to about the same.
+
+    A key that genuinely arrives within the timeout reads as Alt, which is also what
+    vim does, and is why pasting into a terminal editor without bracketed paste goes
+    wrong in the same way.
+    """
+
+    def __init__(self) -> None:
+        self._decoder = codecs.getincrementaldecoder("utf-8")("replace")
+        self._buffer = ""
+        self._escape_since: float | None = None
+
+    def feed(self, data: bytes) -> list[Event]:
+        self._buffer += self._decoder.decode(data)
+        events = self._drain()
+        pending = self._buffer in ("\x1b", "\x1b\x1b")
+        self._escape_since = time.monotonic() if pending else None
+        return events
+
+    def flush(self) -> list[Event]:
+        """Resolve a dangling ESC into an Escape key press once its timeout expires.
+
+        `ESC ESC` waits too, because it is the start of a meta-prefixed sequence as
+        often as it is Alt-Escape; nothing more arriving settles which.
+        """
+        if self._buffer not in ("\x1b", "\x1b\x1b") or self._escape_since is None:
+            return []
+        if time.monotonic() - self._escape_since < ESCAPE_TIMEOUT:
+            return []
+        mods = frozenset({Mod.META}) if self._buffer == "\x1b\x1b" else frozenset()
+        self._buffer = ""
+        self._escape_since = None
+        return [KeyPress(Key.ESCAPE, mods)]
+
+    def _drain(self) -> list[Event]:
+        events: list[Event] = []
+        while self._buffer:
+            event, consumed = self._parse_one(self._buffer)
+            if consumed == 0:  # incomplete sequence; wait for more bytes
+                break
+            self._buffer = self._buffer[consumed:]
+            if event is not None:
+                events.append(event)
+        return events
+
+    def _parse_one(self, buf: str) -> tuple[Event | None, int]:
+        if buf[0] != "\x1b":
+            return self._parse_char(buf[0]), 1
+
+        if len(buf) == 1:
+            return None, 0
+        if buf[1] == "\x1b":
+            # `ESC ESC …`: a terminal in metaSendsEscape mode prefixes the *whole*
+            # sequence, so Alt-F9 arrives as ESC + F9's own escape rather than as
+            # `CSI 20;3~`. Parse what follows and put the Alt back on it. Without
+            # this the inner sequence is taken as literal text and `[20~` is typed
+            # into whatever has focus.
+            inner, consumed = self._parse_one(buf[1:])
+            if consumed == 0:
+                return None, 0
+            return _with_meta(inner), consumed + 1
+        if buf[1] == "O" and len(buf) >= 3:
+            key = _CSI_KEYS.get(buf[2])
+            return (KeyPress(key) if key else None), 3
+        if buf[1] != "[":
+            return KeyPress(buf[1], frozenset({Mod.META})), 2
+
+        mouse = _SGR_MOUSE.match(buf)
+        if mouse:
+            return self._parse_mouse(mouse), mouse.end()
+
+        csi = _CSI.match(buf)
+        if not csi:
+            return (None, 0) if len(buf) < 16 else (None, 1)  # give up on garbage
+        params, final = csi.group(1), csi.group(2)
+        return self._parse_csi(params, final), csi.end()
+
+    def _parse_csi(self, params: str, final: str) -> Event | None:
+        numbers = [int(p) for p in params.split(";") if p.isdigit()]
+        mods = _xterm_mods(numbers[1]) if len(numbers) > 1 else frozenset()
+
+        if final == "Z":  # xterm sends CSI Z for a back-tab
+            return KeyPress(Key.TAB, frozenset({Mod.SHIFT}))
+        if final == "~":
+            if numbers and numbers[0] in (200, 201):
+                return Paste("start" if numbers[0] == 200 else "end")
+            key = _TILDE_KEYS.get(numbers[0]) if numbers else None
+            return KeyPress(key, mods) if key else None
+        key = _CSI_KEYS.get(final)
+        return KeyPress(key, mods) if key else None
+
+    def _parse_mouse(self, match: re.Match[str]) -> Mouse:
+        button, x, y = (int(match.group(i)) for i in (1, 2, 3))
+        final = match.group(4)
+        mods = set()
+        if button & 4:
+            mods.add(Mod.SHIFT)
+        if button & 8:
+            mods.add(Mod.META)
+        if button & 16:
+            mods.add(Mod.CTRL)
+
+        if button & 64:
+            kind = MouseKind.SCROLL_UP if button & 1 == 0 else MouseKind.SCROLL_DOWN
+        elif final == "m":
+            kind = MouseKind.RELEASE
+        elif button & 32:
+            kind = MouseKind.HOVER if button & 3 == 3 else MouseKind.DRAG
+        else:
+            kind = (MouseKind.LEFT, MouseKind.MIDDLE, MouseKind.RIGHT)[button & 3]
+        return Mouse(kind, Pos(x - 1, y - 1), frozenset(mods))
+
+    def _parse_char(self, char: str) -> Event:
+        if char in _CONTROL_KEYS:
+            return KeyPress(_CONTROL_KEYS[char])
+        code = ord(char)
+        if code < 0x20:  # Ctrl-<letter>
+            return KeyPress(chr(code + 0x60), frozenset({Mod.CTRL}))
+        return KeyPress(char)