cligui

🇷🇺 Читать документацию на русском языке

Modern high-performance terminal graphics, 2D canvas and TUI engine in pure Python.

cligui turns any modern terminal into a pixel display: draw anti-aliased vector shapes, gradients, TTF text and live charts on an in-memory RGBA canvas, then show it as subpixel Braille, TrueColor half-blocks, quadrants — or as real HD pixels through the Kitty and Sixel graphics protocols. On top sits a component TUI (flex layout, panels, inputs, mouse, focus) driven by a diffing renderer that sends only the cells that changed, inside synchronized-output frames: smooth 60 FPS, no flicker.

The core is standard library only — pip install cligui-engine pulls in nothing else. Pillow is an optional extra for TTF/OTF fonts.

Features

Installation

pip install cligui-engine          # core: zero dependencies
pip install "cligui-engine[ttf]"   # + Pillow for TTF/OTF fonts

The distribution is named cligui-engine; the import name is cligui (import cligui).

Requires Python 3.10+. Works on Windows 10/11 (Windows Terminal, conhost), Linux and macOS terminals with VT support. Best experienced in Windows Terminal, WezTerm, kitty, Ghostty, iTerm2, foot or Alacritty.

Quick start

from cligui import Canvas2D, CellBuffer, HalfBlockRasterizer, LinearGradient, TerminalDriver

with TerminalDriver() as term:                       # raw mode + alt screen, always restored
    cols, rows = term.size()
    canvas = Canvas2D(cols, rows * 2)                 # half-block: 2 square pixels per cell
    canvas.fill_circle(cols // 2, rows, rows - 4, LinearGradient([0xFF5F6D, 0xFFC371]), aa=True)
    canvas.draw_text(2, 2, "Hello, cligui!", paint=0xFFFFFF)
    buf = CellBuffer(cols, rows)
    canvas.render(HalfBlockRasterizer(background=0x0D1117), buf)
    term.present(buf)                                 # one diffed, flicker-free frame
    term.read(timeout=5)                              # wait for a key

A full interactive app — a live chart with hover, a panel and a status bar:

import math
from cligui import App, Label, Panel, StatusBar, VStack
from cligui.charts import LineChart, Series
from cligui.ui import ChartWidget

data = [50 + 40 * math.sin(i / 6) for i in range(120)]
chart = ChartWidget(LineChart([Series(data, "cpu", fill=True, smooth="monotone")], ymin=0, ymax=100), mode="auto")
app = App(VStack([Label(" cligui demo"), Panel(chart, title="CPU", flex=1), StatusBar("q to quit", "60 FPS")], align="stretch"))
app.bind(lambda ev: ev.key == "q" and (app.quit() or True))
app.run()

mode="auto" picks Kitty or Sixel when the terminal supports them and falls back to character rendering otherwise (CLIGUI_GRAPHICS=kitty|sixel|none overrides detection).

Rendering modes

Examples

python examples/00_bench.py               # renderer benchmark
python examples/01_shapes.py              # primitives, anti-aliasing, gradients
python examples/01_chat_dashboard.py      # dashboard: logo, live chart, input, status bar
python examples/02_fonts_demo.py          # TTF typography on the canvas
python examples/03_charts_demo.py         # line/bar charts, sparklines, real-time data
python examples/04_whiteboard.py          # infinite whiteboard: pan, zoom, pen, Kitty/Sixel

Every demo supports --headless (benchmark without a terminal); most accept --mode.

Performance

Measured with --headless at 120×34 cells, CPython 3.14 (time per frame, including layout and drawing):

Unchanged frames cost 0 bytes; a typical animated dashboard frame is 3–8 KiB. Sixel is heavier (palette quantization in Python): ~16–40 FPS while panning a full HD canvas.

Security

cligui is designed to display untrusted data (logs, network output) safely:

• No escape injection. CellBuffer, Canvas2D.draw_text, window titles and — as a last line of defense — the DiffRenderer strip C0/DEL/C1 control characters, so a string such as "\x1b]52;c;…\x07" cannot rewrite your clipboard, clear the screen or retitle the window. cligui.core.strip_controls() is public.
• Bounded input. Escape sequences, terminal replies and bracketed paste are length-limited.
• Safe font loading. Explicit font paths must be font files, cannot escape the working directory (or a root= you pass) via .., and are size-limited; glyph masks are capped to prevent memory blow-ups from malformed fonts.
• Terminal always restored on normal exit, exceptions, Ctrl+C, SIGTERM/SIGHUP or a failed start-up: cursor shown, mouse tracking off, alternate screen left, console modes, code page and timer resolution restored on Windows, termios on POSIX.

Development

python -m unittest discover tests     # 270+ tests, < 1 s, no terminal needed
python scripts/verify_clean.py        # pre-release privacy check (exit code 0 = clean)
python -m build && twine check dist/*

Architecture decisions (ADR-1 … ADR-15) are documented in ARCHITECTURE.md (in Russian).

License

MIT