Skip to content

What is stable

turbodesk is at 0.3, and version numbers here follow Semantic Versioning. Before 1.0 that means a minor release may break something; the point of this page is to say exactly where, so you can tell which parts of the library you are safe to build on today.

The core, frozen at 1.0

These have two complete applications and two ports from other frameworks behind them, and they have not changed shape in months. Since 0.3 the two applications are separate products (Turbo Python and TurboVI), which is a stronger test of this list rather than a weaker one: they upgrade turbodesk deliberately and notice what moved. 1.0 will freeze them, and after it they change only in a major release:

  • View and its combinators: text, rect, blank, hcat, vcat, zcat, pad, crop, center, colored, tagged, find, and the handler methods.
  • The value types: Style, Color, Size, Pos, Region.
  • UI's hook and event surface: state, reducer, scope, every, task, spawn, now, on_event, on_drag, focus, focus_group, prefer_focus, open_modal, notify, exit, suspend, set_cursor, set_theme.
  • run, and turbodesk.testing.
  • The widget signatures in the catalogue, which a test already compares against inspect.signature on every commit.

Still moving

The Turbo Vision layer. turbodesk.windows, turbodesk.shell, widgets/frame, widgets/menu and widgets/statusline are newer, and most of them have one application and one demo rather than two applications. Since 0.3 that application is Turbo Python, in its own repository, and examples/windows.py is the only caller left in this one.

turbodesk.fuzzy, new in 0.3: match and ranked score a subsequence match and say which characters matched. The functions are small and unlikely to change, and what may change is the scoring — which of two candidates comes first is a judgement, and it has already been corrected twice. Depend on the ranking being stable within a release, not across one.

They may change in a minor release, 1.0 included. That is deliberate. The rule this library follows is that a module earns its shape from a second caller, and these are still collecting theirs. Pin an exact version if you depend on them, and read the changelog before upgrading.

Themes and colours

Role names are stable: the twenty-six Catppuccin roles are what a widget should ask for, and a flavour that did not carry all of them would not be a flavour. The RGB values behind them are not: a flavour may be corrected, and flavours may be added.

What is explicitly not an API

  • Anything named with a leading underscore.
  • The escape sequences on the wire. terminal.py may change what it writes at any time, which is the point of having a painter.
  • The exact cells a widget draws. A snapshot of your own screen is your test, and turbodesk.testing.snapshot exists for that; a widget's internal layout is free to improve.
  • examples/. They are demonstrations and a test bed, and they move with whatever they are demonstrating.

Moved, with the old spelling still working

turbodesk.widgets.syntax is now turbodesk.syntax, and Highlight moved with it. Both old spellings keep working. They will go in a later release, and this page will say which one before they do.

Deprecations

Anything frozen that has to change gets a release where the old spelling still works and warns, before the release that removes it. A DeprecationWarning names the replacement.

Python and platforms

requires-python = ">=3.12". A minor release may add a version; dropping one is a major release.

POSIX only: turbodesk uses termios and tty directly and there is no Windows support today. Continuous integration covers Linux (Ubuntu and Alpine) and FreeBSD. macOS is supported and exercised by hand rather than by CI, because the build service this project uses offers no macOS image.