unicode-animations 0.2.0

Pre-built Unicode braille spinner animations as raw frame data

unicode-animations

Python port of gunnargray-dev/unicode-animations.

18 pre-built Unicode braille spinner animations, a ready-to-use live_spinner context manager for CLI apps, and grid utilities for building custom spinners. Zero dependencies — stdlib only.

Install

uv add unicode-animations

Quick start

from unicode_animations import live_spinner
import time

with live_spinner("helix", text="Loading...", color="cyan"):
    time.sleep(3)

Usage

Live spinner for CLI apps

LiveSpinner runs animation in a background thread and cleans up automatically:

from unicode_animations import live_spinner

# As a context manager
with live_spinner("dna", text="Downloading...", color="green"):
    do_work()

# Manual control
from unicode_animations import LiveSpinner

sp = LiveSpinner("helix", text="Processing...", color="cyan")
sp.start()
# ... do work ...
sp.stop(symbol="✓")  # stop with a final symbol

Parameters:

Parameter	Type	Default	Description
name_or_spinner	str | Spinner	required	A spinner name or a Spinner instance
text	str	""	Status text shown next to the spinner
color	str | None	None	ANSI color: red, green, yellow, blue, magenta, cyan, white
stream	IO[str] | None	stderr	Output stream (non-TTY streams get a text-only fallback)
scale	int	1	Scale factor (2 or 3) for bigger rendering

Raw frame data

from unicode_animations import spinners

spinner = spinners["helix"]
print(spinner.frames)    # tuple of animation frames
print(spinner.interval)  # ms between frames

Custom spinners with the grid API

from unicode_animations import make_grid, grid_to_braille, braille_to_grid

grid = make_grid(4, 2)   # 4 rows x 2 cols (one braille char)
grid[0][0] = True
grid[3][1] = True
print(grid_to_braille(grid))  # ⡁

# Decode back to grid
grid = braille_to_grid("⡁")
print(grid[0][0])  # True

Scaling spinners

from unicode_animations import spinners, scale_spinner

big = scale_spinner(spinners["helix"], factor=2)  # 2x bigger
print(big.frames[0])  # multi-line braille output

CLI demo

python -m unicode_animations                          # cycle through all
python -m unicode_animations helix                    # preview one
python -m unicode_animations helix --color cyan       # with color
python -m unicode_animations helix --scale 2          # bigger
python -m unicode_animations --list                   # list all names
python -m unicode_animations --list --scale 2         # list with scaled samples
python -m unicode_animations --duration 5             # set preview duration

Available spinners

braille · braillewave · dna · scan · rain · scanline · pulse · snake · sparkle · cascade · columns · orbit · breathe · waverows · checkerboard · helix · fillsweep · diagswipe

License

MIT