RazTint

Semantic formatting for Python CLIs with built-in secret redaction.

Keep your CLI output consistent. Write what a message means, not how it should look. RazTint handles colors, icons, and common secret redaction for you.

Preview

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

Installation

Requires Python 3.10+.

pip install raztint
# with uv
uv add raztint

From source:

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

Quick Start

from raztint import paint, ok

# icon shortcut
print(f"{ok()} Build passed.")

print(paint("Connection failed.", intent="error"))

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

paint() returns a plain string. Pass it to print(), a logging handler, or anywhere else a string works.

See Getting Started for installation and common usage.

Why RazTint

• Semantic output instead of ANSI escape codes
• Automatic secret redaction before rendering
• Works anywhere a string is accepted

The problem

CLI output drifts over time. One module prints green for success, another adds an emoji, a third does both differently. Six months in, nothing agrees.

Debug logging is often where secrets slip through. A stray print(f"token={token}") is easy to add while troubleshooting and easy to forget. It ends up in your terminal or your logs.

# before: every call site invents its own formatting, and secrets slip through
print(f"\033[31mAuth failed for token={token}\033[0m")

# after: one call, styled and redacted
print(paint(f"Auth failed for token={token}", intent="error", redact=True))
# Auth failed for token=****

Core features

• Semantic intents success, error, warning, debug, and more. Use semantic names instead of choosing colors manually.

• State-aware output case() maps application states to semantic intents, while transient() provides temporary terminal output for in-progress operations.

• Redaction masks key=value pairs such as password=, api_key=, and token=. Patterns are configurable, see Security and Redaction.

• Icon helpers ok(), err(), warn(), info(), pending(), debug(). Falls back from Nerd Font to Unicode to ASCII depending on the terminal.

• Manual control raw 16/256/True Color and text styles, for the cases intents don't cover.

• Type hints throughout ships with py.typed. Respects NO_COLOR and RAZTINT_FORCE_COLOR.

Design philosophy

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

RazTint is not a terminal UI framework. It doesn't hook into logging or replace a handler. It stays a formatting layer, on purpose:

• ANSI color support
• Semantic logging helpers
• Automatic icon fallback
• Secret redaction
• Zero external dependencies

A small scope keeps RazTint focused.

Documentation

Examples: showcase.py · file_processor.py · redaction_demo.py

Known limitations

• Python 3.10+ only.
• Font detection relies on OS tools (fc-list, system_profiler, PowerShell). Set RAZTINT_SKIP_SYSTEM_FONT_SCAN=1 in sandboxed environments.
• Setting NO_COLOR suppresses all color output, regardless of other settings.

Contributing

PRs and issues are welcome. Open an issue first to discuss any new feature.

See Contributing Guide for setup and guidelines.

License