turbodesk

Terminal UIs as pure functions from state to an immutable view tree.

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.

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, for glyph-width measurement and for drawing Rich renderables into a view), Python 3.12+, POSIX only.

Version 0.3. What is stable 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, inventory, API and design notes.
• COMPONENTS.md: the bonsai_term_components port, what moved, what changed shape, what was left out.

Documentation

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. 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:

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.