turbodesk 0.3.0__tar.gz

turbodesk-0.3.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: turbodesk
+Version: 0.3.0
+Summary: Terminal UIs as pure functions from state to an immutable view tree
+Keywords: terminal,tui,console,immediate-mode,widgets,ansi,curses
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Topic :: Terminals
+Classifier: Typing :: Typed
+Requires-Dist: rich>=13.0
+Requires-Dist: pygments>=2.0 ; extra == 'syntax'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://turbodesk.lab.abilian.com
+Project-URL: Documentation, https://turbodesk.lab.abilian.com
+Provides-Extra: syntax
+Description-Content-Type: text/markdown
+
+# turbodesk
+
+Terminal UIs as pure functions from state to an immutable view tree.
+
+```python
+from turbodesk import View, run
+
+def app(ui):
+    return View.text("Hello world!").center(within=ui.size)
+
+run(app)
+```
+
+An app is a function `(UI) -> View`. It re-runs whenever a frame is marked dirty (state changed, an event arrived, the terminal resized, a timer fired), and the renderer diffs by row before writing escape codes. State lives in hooks on the `ui` handle.
+
+```sh
+uv sync                             # or: pip install -e .
+python examples/hello_world.py
+python examples/theme_gallery.py    # 19 colour flavours, ← → to browse
+python examples/charts.py           # line, scatter and bar charts
+python examples/focus.py            # three key-hungry widgets, one keyboard
+python examples/filter.py           # type to filter a list
+python examples/logs.py             # colourised output, tail -f style
+python examples/embed.py htop       # another TUI, embedded (needs tmux)
+python examples/vi somefile.py      # a vi clone, built on the core alone
+python examples/frogmouth README.md # a Markdown browser, ported from Textual
+```
+
+One dependency ([Rich](https://rich.readthedocs.io/), for glyph-width measurement and for drawing Rich renderables into a view), Python 3.12+, POSIX only.
+
+Version 0.3. [What is stable](https://turbodesk.lab.abilian.com/stability/) says which parts of the API are safe to build on now and which are still moving.
+
+## What's here
+
+- `src/turbodesk/`: the core — views, styles, events, terminal, render loop, themes, layout arithmetic, overlapping windows, a command table, key naming, syntax spans, Markdown, ANSI parsing, clipboard
+- `src/turbodesk/widgets/`: dialogs, button, checkbox, radio set, selection list, textbox, listbox, table, tabs, progress bar, spinner, rule, border, frame, scroller, tree, directory tree, menu bar, status line, charts, editor, ncdu, tmux pane
+- `examples/`: all 17 bonsai_term examples, ported and running, plus demos, a vi clone and a Markdown browser. **[Start here](examples/README.md)**, inventory, API and design notes.
+- **[COMPONENTS.md](notes/components.md)**: the bonsai_term_components port, what moved, what changed shape, what was left out.
+
+## Documentation
+
+```bash
+make docs-serve      # live reload
+make docs            # build to docs/site/
+make docs-check      # strict: a broken cross-reference fails the build
+```
+
+The docs are their own project under `docs/`, with their own Makefile (`cd docs && make`
+works too).
+
+Built with [Zensical](https://pypi.org/project/zensical/). `docs/` has a guide, a
+comparison with Textual and other frameworks grounded in two real ports, and notes on
+the internals.
+
+## Tests
+
+A pyramid, run with `make test` or `uv run pytest`:
+
+```sh
+uv run pytest -m unit          # 2,008 — pure functions, no I/O, about a second
+uv run pytest -m integration   #   432 — widgets and apps through a UI
+uv run pytest -m e2e           #     7 — real programs on a pty
+uv run pytest -m "not slow"    # skips the pty and tmux tests
+```
+
+```
+tests/
+├── a_unit/          views, styles, events, markdown, typography, fuzzy matching,
+│                    and the vi showcase's grammar
+├── b_integration/   the runtime, widgets, dialogs, every example, the whole apps
+├── c_e2e/           pty-driven: alternate screen, keys, vi saving, a modal
+└── conftest.py      ui / render / screen / scratch_data_dir fixtures
+```
+
+The two products built on turbodesk live in their own repositories and have their own
+suites — Turbo Python (594 tests) and TurboVI (395) — and a library change is not
+verified until those pass too.

turbodesk-0.3.0/README.md

@@ -0,0 +1,77 @@
+# turbodesk
+
+Terminal UIs as pure functions from state to an immutable view tree.
+
+```python
+from turbodesk import View, run
+
+def app(ui):
+    return View.text("Hello world!").center(within=ui.size)
+
+run(app)
+```
+
+An app is a function `(UI) -> View`. It re-runs whenever a frame is marked dirty (state changed, an event arrived, the terminal resized, a timer fired), and the renderer diffs by row before writing escape codes. State lives in hooks on the `ui` handle.
+
+```sh
+uv sync                             # or: pip install -e .
+python examples/hello_world.py
+python examples/theme_gallery.py    # 19 colour flavours, ← → to browse
+python examples/charts.py           # line, scatter and bar charts
+python examples/focus.py            # three key-hungry widgets, one keyboard
+python examples/filter.py           # type to filter a list
+python examples/logs.py             # colourised output, tail -f style
+python examples/embed.py htop       # another TUI, embedded (needs tmux)
+python examples/vi somefile.py      # a vi clone, built on the core alone
+python examples/frogmouth README.md # a Markdown browser, ported from Textual
+```
+
+One dependency ([Rich](https://rich.readthedocs.io/), for glyph-width measurement and for drawing Rich renderables into a view), Python 3.12+, POSIX only.
+
+Version 0.3. [What is stable](https://turbodesk.lab.abilian.com/stability/) says which parts of the API are safe to build on now and which are still moving.
+
+## What's here
+
+- `src/turbodesk/`: the core — views, styles, events, terminal, render loop, themes, layout arithmetic, overlapping windows, a command table, key naming, syntax spans, Markdown, ANSI parsing, clipboard
+- `src/turbodesk/widgets/`: dialogs, button, checkbox, radio set, selection list, textbox, listbox, table, tabs, progress bar, spinner, rule, border, frame, scroller, tree, directory tree, menu bar, status line, charts, editor, ncdu, tmux pane
+- `examples/`: all 17 bonsai_term examples, ported and running, plus demos, a vi clone and a Markdown browser. **[Start here](examples/README.md)**, inventory, API and design notes.
+- **[COMPONENTS.md](notes/components.md)**: the bonsai_term_components port, what moved, what changed shape, what was left out.
+
+## Documentation
+
+```bash
+make docs-serve      # live reload
+make docs            # build to docs/site/
+make docs-check      # strict: a broken cross-reference fails the build
+```
+
+The docs are their own project under `docs/`, with their own Makefile (`cd docs && make`
+works too).
+
+Built with [Zensical](https://pypi.org/project/zensical/). `docs/` has a guide, a
+comparison with Textual and other frameworks grounded in two real ports, and notes on
+the internals.
+
+## Tests
+
+A pyramid, run with `make test` or `uv run pytest`:
+
+```sh
+uv run pytest -m unit          # 2,008 — pure functions, no I/O, about a second
+uv run pytest -m integration   #   432 — widgets and apps through a UI
+uv run pytest -m e2e           #     7 — real programs on a pty
+uv run pytest -m "not slow"    # skips the pty and tmux tests
+```
+
+```
+tests/
+├── a_unit/          views, styles, events, markdown, typography, fuzzy matching,
+│                    and the vi showcase's grammar
+├── b_integration/   the runtime, widgets, dialogs, every example, the whole apps
+├── c_e2e/           pty-driven: alternate screen, keys, vi saving, a modal
+└── conftest.py      ui / render / screen / scratch_data_dir fixtures
+```
+
+The two products built on turbodesk live in their own repositories and have their own
+suites — Turbo Python (594 tests) and TurboVI (395) — and a library change is not
+verified until those pass too.

turbodesk-0.3.0/pyproject.toml

@@ -0,0 +1,101 @@
+[project]
+name = "turbodesk"
+version = "0.3.0"
+description = "Terminal UIs as pure functions from state to an immutable view tree"
+requires-python = ">=3.12"
+readme = "README.md"
+license = "Apache-2.0"
+keywords = ["terminal", "tui", "console", "immediate-mode", "widgets", "ansi", "curses"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS :: MacOS X",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: User Interfaces",
+    "Topic :: Terminals",
+    "Typing :: Typed",
+]
+# No `License ::` classifier: `license` above is an SPDX expression (PEP 639), and
+# PyPI rejects a distribution that carries both.
+
+# Rich renders content — measuring glyph widths, and `turbodesk.rich` for anyone with
+# renderables already. It does not render *views*: handlers, tags and hit-testing are
+# turbodesk's, and Rich's segment stream has no notion of them. Its heavy parts
+# (pygments, markdown-it) are lazy — importing the core costs about 20ms.
+dependencies = ["rich>=13.0"]
+
+[project.optional-dependencies]
+# Syntax colouring for `editor()`, via `turbodesk.widgets.syntax`.
+syntax = ["pygments>=2.0"]
+
+[project.urls]
+Homepage = "https://turbodesk.lab.abilian.com"
+Documentation = "https://turbodesk.lab.abilian.com"
+# The sourcehut repository is not public yet: `https://git.sr.ht/~sfermigier/turbodesk`
+# answers 404 today, and a project URL that 404s is worse than an absent one. Uncomment
+# both on the day the repository is published, and before the release that follows.
+# Repository = "https://git.sr.ht/~sfermigier/turbodesk"
+# Issues = "https://todo.sr.ht/~sfermigier/turbodesk"
+
+[build-system]
+requires = ["uv_build>=0.11.33,<0.12.0"]
+build-backend = "uv_build"
+
+# Linting lives in ruff.toml.
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# The library from src/; the example apps by the flat names they import each other by.
+pythonpath = ["src", "examples", "examples/vi", "examples/frogmouth", "examples/termon", "examples/fm", "examples/browser"]
+addopts = "--strict-markers --import-mode=importlib"
+markers = [
+    "unit: isolated and fast — no I/O, no event loop",
+    "integration: components wired together, may touch the filesystem",
+    "e2e: drives a real terminal through a pty",
+    "slow: needs an external program or wall-clock time",
+]
+
+[tool.mypy]
+# Read by zuban too. Same search path as pytest and the other checkers.
+mypy_path = "src:examples:examples/vi:examples/frogmouth:examples/termon:examples/fm:examples/browser"
+
+[tool.ty.src]
+# Vendored Textual apps awaiting a port. They are someone else's code with their own
+# toolchain; checking them here only reports on Textual, not on turbodesk.
+exclude = ["porting/"]
+
+[tool.ty.environment]
+# The same search path pytest gets above: the example apps import each other by flat
+# name, so a checker looking only at src/ cannot resolve `state`, `keymap`, `store`…
+extra-paths = ["src", "examples", "examples/vi", "examples/frogmouth", "examples/termon", "examples/fm", "examples/browser"]
+
+[tool.pyrefly]
+project-includes = [
+    "**/*.py*",
+    "**/*.ipynb",
+]
+project-excludes = [
+    "**/.venv/**",
+    "porting/**", # see [tool.ty.src] above
+]
+search-path = ["src", "examples", "examples/vi", "examples/frogmouth", "examples/termon", "examples/fm", "examples/browser", "tests"]
+
+[dependency-groups]
+dev = [
+    "mypy>=2.3.0",
+    "nox>=2026.7.11",
+    "pre-commit>=4.6.1",
+    "pyrefly>=1.2.0",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.16.1",
+    "ty>=0.0.66",
+    "types-pygments>=2.20.0.20260728",
+    "zensical>=0.0.53",
+    "zuban>=0.9.1",
+]

turbodesk-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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("")