tca-python

Terminal Colors Architecture (TCA) theme support for Python, includes support for Textual.

Installation

pip install tca-python

For Textual integration:

pip install "tca-python[textual]"

Usage

Shared Theme Directory

TCA uses a shared directory for themes:

• Linux/BSD: $XDG_DATA_HOME/tca/themes (default: ~/.local/share/tca/themes)
• macOS: ~/Library/Application Support/tca/themes
• Windows: %APPDATA%\tca\themes

Themes in this directory can be loaded by name from anywhere.

Basic Theme Loading

from tca import load_theme

# Load from shared directory by name
theme = load_theme("dracula")

# Or load from an explicit path
theme = load_theme("/path/to/theme.toml")

# Access resolved colors directly
print(theme.ansi.red)         # "#ff5555"
print(theme.semantic.error)   # Error color
print(theme.ui.bg_primary)    # Background color

Listing Available Themes

from tca import list_theme_names, get_themes_dir

# Get themes directory path
themes_dir = get_themes_dir()
print(f"Themes directory: {themes_dir}")

# List all available themes
for name in list_theme_names():
    print(f"  - {name}")

Textual Integration

Install with the textual extra, then wrap any Theme with TextualTheme:

from tca import load_theme
from tca.textual import TextualTheme

theme = TextualTheme.from_theme(load_theme("dracula"))

# Create a Textual ColorSystem
color_system = theme.color_system()

# Access colors as Textual Color objects
error_color = theme.semantic_color("error")
bg_color    = theme.ui_color("bg_primary")
red_color   = theme.ansi_color("red")

# Get a full palette ramp as Textual Colors (int-indexed)
neutral = theme.get_palette_ramp("neutral")
print(neutral[0])  # darkest entry as textual.Color

# Use in a Textual app
from textual.app import App

class MyApp(App):
    def on_mount(self) -> None:
        self.styles.background = theme.ui.bg_primary

All Available Colors

ANSI Colors (16 total):

# Normal colors
theme.ansi.black, theme.ansi.red, theme.ansi.green, theme.ansi.yellow
theme.ansi.blue,  theme.ansi.magenta, theme.ansi.cyan, theme.ansi.white

# Bright colors
theme.ansi.bright_black,   theme.ansi.bright_red
theme.ansi.bright_green,   theme.ansi.bright_yellow
theme.ansi.bright_blue,    theme.ansi.bright_magenta
theme.ansi.bright_cyan,    theme.ansi.bright_white

Semantic Colors (6 total):

theme.semantic.error      # Error messages
theme.semantic.warning    # Warnings
theme.semantic.info       # Informational messages
theme.semantic.success    # Success messages
theme.semantic.highlight  # Highlighted text
theme.semantic.link       # Links

UI Colors (11 total):

theme.ui.bg_primary, theme.ui.bg_secondary           # Backgrounds
theme.ui.fg_primary, theme.ui.fg_secondary, theme.ui.fg_muted  # Foregrounds
theme.ui.border_primary, theme.ui.border_muted       # Borders
theme.ui.cursor_primary, theme.ui.cursor_muted       # Cursors
theme.ui.selection_bg,   theme.ui.selection_fg       # Selection

Palette Access:

# Integer-indexed ramp → hex string
neutral = theme.get_palette_ramp("neutral")
print(neutral[0])  # darkest entry
print(neutral[4])  # lightest entry

# Iterate all ramps
for ramp_name, ramp in theme.palette.items():
    print(f"{ramp_name}: {list(ramp)}")

Examples

See the examples directory:

python examples/basic.py ~/.local/share/tca/themes

API Reference

Loader Functions

• get_data_dir() -> Path — Get TCA data directory path
• get_themes_dir() -> Path — Get themes directory path
• list_theme_files() -> list[Path] — List all theme file paths
• list_theme_names() -> list[str] — List theme names (without extensions)
• find_theme(name: str) -> Path | None — Find theme by name
• load_theme_file(path_or_name: str) -> str — Load theme file as string
• load_theme(path_or_name: str | Path) -> Theme — Load and parse a theme
• load_theme_from_path(path: str | Path) -> Theme — Load theme from an exact path
• load_themes_from_dir(directory: Path) -> list[tuple[Path, Theme]] — Load all themes from a directory

Theme Class

All color fields are pre-resolved hex strings — no further method calls required.

theme.meta       # Meta — name, slug, author, version, description, is_dark
theme.ansi       # ANSI — 16 standard terminal colors
theme.semantic   # Semantic — error, warning, info, success, highlight, link
theme.ui         # UI — 11 interface colors (bg, fg, border, cursor, selection)
theme.base16     # Base16 — base00–base0f
theme.palette    # dict[str, ColorRamp] — named palette ramps

Additional method:

• theme.get_palette_ramp(name: str) -> dict[int, str] — Ramp as {index: hex} dict

TextualTheme Class

Extends Theme with helpers that return textual.color.Color objects.

• TextualTheme.from_theme(theme: Theme) -> TextualTheme
• theme.color_system() -> ColorSystem — Create Textual ColorSystem
• theme.ansi_color(name: str) -> Color — e.g. theme.ansi_color("red")
• theme.semantic_color(name: str) -> Color — e.g. theme.semantic_color("error")
• theme.ui_color(name: str) -> Color — e.g. theme.ui_color("bg_primary")
• theme.get_palette_ramp(name: str) -> dict[int, Color] — Ramp as Textual Colors

Related Projects

• tca-themes - Theme collection
• tca-rust - Rust implementation with CLI tools
• tca-go - Go implementation

TCA Specification

For the full TCA specification and theme format, see the tca-themes repository.

License

MIT