Skip to main content

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.2. 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,460 - pure functions, no I/O, about a second
uv run pytest -m integration   #   442 - 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 (614 tests) and TurboVI (617). A library change is not verified until those pass too.

Metadata

Release files for turbodesk 0.4.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for turbodesk 0.4.4
File Size Uploaded Provenance Actions
turbodesk-0.4.4.tar.gz 112.7 kB Without provenance Details for turbodesk-0.4.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for turbodesk 0.4.4
File Interpreter ABI Platform Actions
turbodesk-0.4.4-py3-none-any.whl Python 3 none any Details for turbodesk-0.4.4-py3-none-any.whl

Total release size: 241.5 kB

Release files / turbodesk-0.4.4.tar.gz

Download URL turbodesk-0.4.4.tar.gz
Size 112.7 kB
Tags Source
SHA-256 checksum
How to use checksums
ae869961deb4e2a9dc410bc146beaaeb6c1fc4ce6bda0511ed1a8f0e6f485341
BLAKE2b-256 checksum
How to use checksums
c204c6f1ac913b76a613e2fed252a16cf6e691ee75ff5bd17256fc9577a4b8b7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / turbodesk-0.4.4-py3-none-any.whl

Download URL turbodesk-0.4.4-py3-none-any.whl
Size 128.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d4f9f0c03cd937d1f6fcf56a73eebea5c4ab2245e899308f7fbefc732021513e
BLAKE2b-256 checksum
How to use checksums
89e5221fde8a473776c04590333f92b59992c0c4d1a91691a8b967d5b2408cb2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for turbodesk 0.4.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page