tuiro 0.1.0

Tiny terminal UI utility for clean, colorful build output.

tuiro

tuiro is a tiny terminal UI helper designed for clean, readable, and structured output in build scripts and command‑line tools. It provides simple utilities for sections, banners, status messages, command logging, and themed output without introducing heavy dependencies or complex abstractions.

tuiro began as an internal utility inside the TactileBrowser project (https://github.com/NellowTCS/TactileBrowser). It is now available as a standalone library for any script or tool that wants clear and consistent terminal output.

Features

• Lightweight and dependency‑free
• ANSI color support with optional CI mode
• Built‑in themes and user‑defined palettes
• Section and subsection headers
• Informational, warning, success, and error messages
• Command logging for build steps
• Centered banners with automatic terminal width detection
• A simple step context manager for build phases
• A minimal CLI for quick verification and theme testing

Installation

pip install tuiro

For development:

uv pip install -e .

Usage

Basic example:

from tuiro import TUI

tui = TUI()
tui.banner("Build")
tui.section("Environment")
tui.info("Checking dependencies")
tui.success("All checks passed")

Example output (colors omitted):

╔══════════════════════════════════════════════════════════╗
║                          Build                           ║
╚══════════════════════════════════════════════════════════╝

────────────────────────────────────────────────────────────
  Environment
────────────────────────────────────────────────────────────
[*] Checking dependencies
[OK] All checks passed

Themes

tuiro supports both built‑in themes and user‑defined palettes.

Built‑in themes

• default
• mono
• pastel

Use a theme by name:

tui = TUI(theme="pastel")

Custom palettes

Palettes live in tuiro.palette. Users can define their own palette by subclassing Palette:

from tuiro.palette import Palette
from tuiro.colors import Colors

class MyPalette(Palette):
    success = Colors.BRIGHT_GREEN
    info = Colors.BRIGHT_CYAN

Then pass it to TUI:

tui = TUI(theme=MyPalette)

or:

tui = TUI(theme=MyPalette())

Note: The CLI --theme flag accepts only built‑in theme names from PROFILES. Custom palettes must be provided from Python code.

CLI

tuiro includes a small demonstration CLI:

tuiro

Flags:

tuiro --ci
tuiro --no-color
tuiro --theme pastel
tuiro --help
tuiro --version

Behavior:

• --ci disables colors
• --no-color also disables colors
• If both are provided, colors remain disabled
• --theme NAME selects a built‑in theme
• --help lists available themes

Example:

tuiro --ci --theme mono

API

TUI(ci_mode: bool = False, theme: str | Palette = "default")

Creates a new terminal UI helper.

section(title: str)

Prints a high‑visibility section header.

subsection(title: str)

Prints a smaller subsection header.

banner(title: str)

Prints a centered banner.

Status messages

info(message: str)
success(message: str)
warning(message: str)
error(message: str)

command(cmd: str | list[str])

Prints a command being executed. Lists are joined with spaces.

result(label: str, value: str)

Prints a key‑value result line.

table(rows: list[tuple[str, str]])

Prints a simple two‑column table aligned on the left column.

step(title: str)

Context manager for build steps:

with tui.step("Compiling"):
    run_compiler()

License

MIT License. See (LICENSE)[LICENSE] for details.