cuia 0.1.0

🧉🌿 A delightful tiny framework for building reliable text-based applications

cuia 🧉

A delightful tiny framework for building reliable text-based applications.

cuia is a tiny Python library for building interactive terminal user interfaces that are easy to use, fast and have a small memory footprint.

cuia is inspired by Bubble Tea (written in Go) and, in particular, employs the Elm architecture (TEA, named after the Elm programming language). This means that cuia applications are as dynamic and easy to write (and use) as they could be.

Features

• 🧵 Simple: your user interface is a string of characters
• 💬 Interaction-focused
• ♻️ Easily integrate with other libraries
• 🕹️ Use the same escape code sequences as you would with Colorama
• 🖥️ Support for Unix variants out of the box: curses under the hood by default (and probably works on Windows and DOS if a compatible curses library is available)
• 🤬 Only one dependency: cusser (for wrapping the curses library)
• 🐍 Python 3.8+

Installation

$ pip install cuia

Usage

In [1]: import asyncio

In [2]: from dataclasses import dataclass

In [3]: from cuia import Program, Store

In [4]: @dataclass
   ...: class Hello(Store):
   ...:
   ...:     x: int = 0
   ...:     y: int = 0
   ...:
   ...:     def __str__(self):
   ...:         return f"\033[{self.x};{self.y}H\033[1mHello, 🌍!"
   ...:

In [5]: program = Program(Hello(34, 12))

In [6]: asyncio.run(program.start())

How does it work

cuia is inspired by Bubble Tea (written in Go) and, on the surface, looks much like it. In particular, cuia employs the Elm architecture (TEA, named after the Elm programming language). What it means in terms of output is that a cuia application creates a new screen representation of the user interface (in fact, as a regular Python string) at each step. It might look as a serious memory overhead but, in fact, it will never use more than 100kb to hold those string representations, even on large screens[^how-big].

But, contrary to Bubble Tea, cuia is built on top of curses. curses is a standard Python library (written in C) that wraps the famous ncurses library (written in C as well). ncurses does efficient screen updates and is thus quite fast. It works by comparing the contents of a screen buffer to the contents of the actual screen and only updating where the contents have changed. So, in general, cuia works in a similar way to virtual DOM tree updates (a technique commonly used in JavaScript web frameworks such as React), except that it is a string buffer that is updated, instead of a virtual DOM tree.

[^how-big]: My 22" desktop can't make a terminal larger than 211x55 characters. A single string representation would require a little over 10kb of storage in Python. It would then take ten string representations to be hold in memory at a single point in time for it to go beyond 100kb.