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.

What you can do with it

Two complete programs are built on turbodesk and published on PyPI — Turbo Python and TurboVI. They are fully worked examples, developed alongside the library and meant to be used rather than demonstrated:

uvx --from turbopython-ide tp file.py   # Turbo Python: Turbo Pascal 7.0's IDE, for Python
uvx turbovi file.py                     # TurboVI: a vi clone that uses no widgets at all

Turbo Python is a desktop of overlapping windows with a menu bar, a debugger, a class browser and a language-server client. TurboVI is modes, counts, the operator-motion grammar, registers, marks, macros, :s, splits, find-in-project with a quickfix list, and crash recovery — drawing every cell from View combinators with no widget anywhere. The install for the IDE is turbopython-ide and the command is tp; the bare name turbopython on PyPI belongs to an unrelated project.

Version 0.4.0. 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,026 — pure functions, no I/O, about a second
uv run pytest -m integration   #   434 — 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
├── b_integration/   the runtime, widgets, dialogs, the painter
├── c_e2e/           pty-driven: alternate screen, keys, vi saving, a modal
├── examples/        the same tiers for the example apps, the gallery included
├── docs/            the prose and the manual, checked against the code
└── 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.