TermTint

A lightweight, zero-dependency Python library for simple colored and styled terminal output.

Why TermTint?

Normally, Python prints unstyled plain text in your terminal:

print("Success!")

If you want colored output, writing raw ANSI escape sequences manually can quickly make your code hard to read:

print("\033[32mSuccess!\033[0m")

TermTint solves this by providing a clean, simple, zero-dependency interface for colored terminal text without the overhead of heavy CLI frameworks:

from termtint import colored

print(colored("Success!", "green"))

Features

• Zero Runtime Dependencies: Uses only the Python standard library.
• Named, RGB & 256 Colors: 8 standard colors, 24-bit True Color (rgb=(r, g, b)), and 256-color ANSI (color256=n).
• 8 Text Styles: normal, bold, bright, dim, italic, underline, reverse, and strikethrough.
• Modern Windows Support: Native Virtual Terminal support on Windows 10/11.
• NO_COLOR Compliant: TermTint respects NO_COLOR in automatic mode.
• Redirect & Stream Aware: TermTint automatically avoids adding ANSI escape sequences when output is redirected to a file or pipe.
• Convenience Helpers: Direct print_green(), print_rgb(), print_256(), and other function helpers.
• Ultra-Lightweight: Minimal runtime overhead and simple code structure.

Installation

Install TermTint via PyPI using pip:

pip install termtint

Quick Start

from termtint import colored, print_green, print_red, print_rgb, print_256

# Standard named colors
print(colored("Operation succeeded", "green"))
print(colored("Disk space low", "yellow", style="bold"))
print(colored("Database error", "red", style="underline"))

# 24-bit True Color (RGB)
print(colored("Custom coral text", rgb=(255, 127, 80)))
print(colored("Styled sky blue", rgb=(135, 206, 235), style="italic"))

# 256-color ANSI
print(colored("Vibrant orange", color256=208))
print(colored("Hot pink", color256=198, style="bold"))

# Convenience print functions
print_green("System online")
print_red("Fatal crash occurred!", style="bold")
print_rgb((255, 165, 0), "Warning: battery at 15%")
print_256(196, "Critical temperature threshold exceeded")

Supported Colors

1. Named Terminal Colors

TermTint supports 8 standard terminal foreground colors:

Invalid color names raise a ValueError with a helpful error message.

2. RGB / True Color (24-bit)

Pass an (r, g, b) tuple with values from 0 to 255 to rgb=:

print(colored("Custom purple", rgb=(138, 43, 226)))
print(colored("Sunset orange", rgb=(255, 69, 0), style="bold"))

3. 256-Color ANSI

Pass an integer color index (0 to 255) to color256=:

print(colored("Bright red", color256=196))
print(colored("Electric blue", color256=33, style="underline"))

[!NOTE] color, rgb, and color256 are mutually exclusive. Specify exactly one color source per call.

Supported Styles

TermTint supports 8 standard text styles:

bold and bright map to the same ANSI escape code (1). All styles combine seamlessly with named colors, RGB, and 256-color output.

Convenience Print Functions

In addition to colored(), TermTint provides direct print functions for fast CLI output:

from termtint import (
    print_black,
    print_red,
    print_green,
    print_yellow,
    print_blue,
    print_magenta,
    print_cyan,
    print_white,
    print_rgb,
    print_256,
)

print_green("Success message")
print_red("Error message", style="bold")
print_yellow("Warning message", style="underline")
print_rgb((100, 200, 255), "Custom RGB notice")
print_256(214, "256-color amber alert")

All convenience functions support standard Python print() keyword arguments: sep, end, file, and flush.

Enabling & Disabling Colors

By default, TermTint uses automatic terminal detection. You can explicitly force or disable colors programmatically:

from termtint import enable_color, disable_color, reset_color_state, colored

# Force colors ON (e.g. CLI --color=always flag)
enable_color()
print(colored("Always colored", "cyan"))

# Force colors OFF (e.g. CLI --no-color flag)
disable_color()
print(colored("Plain text only", "cyan"))  # Output: "Plain text only"

# Reset back to automatic detection
reset_color_state()

Automatic Terminal & Stream Detection

TermTint automatically detects terminal capabilities using a multi-step check:

1. Explicit Toggle: Respects programmatic enable_color() or disable_color().
2. NO_COLOR Variable: TermTint respects NO_COLOR in automatic mode (no-color.org).
3. FORCE_COLOR Variable: If FORCE_COLOR=1, colors are forced on in automatic mode.
4. Destination Stream & TTY Check: If output is redirected (e.g. python script.py > output.txt) or a file-like stream is supplied (file=f), ANSI escape sequences are avoided automatically.
5. Dumb Terminal Check: If TERM=dumb, colors are disabled.

Windows Support

On Windows 10 and 11, TermTint automatically enables Virtual Terminal (VT) processing using standard-library ctypes bindings to the Win32 Console API. If VT mode cannot be enabled, TermTint safely falls back to plain text without crashing.

Colorama Comparison

TermTint is a focused, lightweight alternative for developers who primarily need simple colored terminal output, whereas Colorama provides broader historical ANSI translation.

Limitations

TermTint is intentionally small and focused. It is not a full terminal UI framework:

• No progress bars or spinners
• No table or layout formatters
• No cursor movement or screen clearing
• No markdown or syntax highlighting

If you require full TUI widgets or complex terminal graphics, consider tools like Rich or Textual.

Development

Set up TermTint locally:

git clone https://github.com/hasheramin5-cyber/TermTint.git
cd TermTint
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\Activate.ps1
pip install -e ".[dev]"

Run tests and linters:

# Run test suite
pytest

# Run linter
ruff check .

# Run micro-benchmarks
python benchmarks/benchmark.py

Documentation

Full documentation is available in the docs/ directory:

• API Reference
• Usage Guide
• Architecture Overview
• Development Guide
• Publishing Guide

License

TermTint is licensed under the MIT License.