raztint 0.9.0

Every CLI project eventually invents its own way to print "success" or "error." One module uses green text, another adds an emoji, a third does both differently. Output looks inconsistent, breaks in CI, and nobody notices until a log line leaks a password.

# before
print("\033[32mSuccess\033[0m")

# after
print(paint("Success", intent="success"))

RazTint defines a fixed mapping from intent (success, error, warning, …) to color and icon once, and every call site reuses that same mapping instead of picking its own.

Installation

Requires Python 3.10+.

pip install raztint

From source:

git clone https://github.com/razbuild/raztint.git
cd raztint
uv sync

Quick Start

from raztint import ok, paint

print(f"{ok()} File saved.")
print(paint("Connection failed.", color="red", icon="err"))

# intent sets color + icon together from one semantic name
print(paint("Deployment complete.", intent="success"))

# redact masks secrets before the string is printed
print(paint("password=1234", intent="debug", redact=True))  # password=****

Redaction on its own, without formatting:

from raztint import redact

print(redact("password=supersecret api_key=ghp_abc123"))
# password=**** api_key=****

More examples in Getting Started.

Preview

A simulated production log stream 9 secrets detected, 9 secrets redacted, 0 leaked to the terminal.

Features

• Intents: presets (success, error, warning, debug, …) that separate meaning from styling
• paint(): one call for color, background, styles, and icons
• Status icons: ok(), err(), warn(), info(), pending(), debug(), each with the three-tier fallback
• Redaction: pattern-based masking (key=value pairs like password=, api_key=, token=) applied as part of the formatting call, not a separate logging step; patterns are configurable, see Security & Redaction
• Environment detection: Nerd Font → Unicode → ASCII, cached; configurable via NO_COLOR, RAZTINT_FORCE_COLOR
• Typed: py.typed, full public API type hints
• Advanced styling: raw 16-color, 256-color, and True Color support, plus bold, italic, underline, dim, and strikethrough when semantic intents aren't enough.

Documentation

Example Scripts

Design Philosophy

RazTint is built around a single idea:

[!NOTE] Make terminal output consistent, meaningful, and safe by default.

RazTint is not a terminal UI framework. It focuses on high-quality console messaging with:

• ANSI color support
• Semantic logging helpers
• Automatic icon fallbacks
• Secret masking
• Zero external dependencies

By keeping its scope intentionally small, RazTint stays predictable, dependency-free, and easy to drop into existing CLI projects.

Logging Integration Example

RazTint only returns a formatted string, it doesn't hook into logging or replace a handler. Pass that string to print(), a logger, or anything else that accepts a string.

import logging
from logging import Logger, getLogger

from raztint import paint

logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
logger: Logger = getLogger(__name__)

logger.info(paint("Database migration completed.", intent="success", icon=None))
logger.warning(paint("Disk usage above 90%.", intent="warning", icon=None, styles="dim"))
logger.error(
    paint("Authentication failed for token=abc123", intent="error", redact=True, icon=None)
)

Known Limitations

• Python 3.10+ only.
• Font detection relies on OS tools (fc-list on Linux, system_profiler on macOS, PowerShell on Windows). Set RAZTINT_SKIP_SYSTEM_FONT_SCAN=1 in sandboxed environments.
• When NO_COLOR is set, all color output is suppressed regardless of other settings.

Contributing

PRs and issues are welcome. Open an issue first to discuss before starting work on a feature. See CONTRIBUTING.md for setup and guidelines.

License