Metadata-Version: 2.3
Name: raztint
Version: 0.9.1
Summary: A zero-dependency Python library for consistent, semantic CLI output.
Keywords: terminal,color,colour,console,cli,ansi,terminal-colors,nerd-fonts,icons,text-coloring,cross-platform
License: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Maintainer: Raz
Maintainer-email: Raz <real.raz.dev@gmail.com>
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/razbuild/raztint
Project-URL: Documentation, https://github.com/razbuild/raztint/tree/master/docs
Project-URL: Repository, https://github.com/razbuild/raztint
Project-URL: Issues, https://github.com/razbuild/raztint/issues
Project-URL: Changelog, https://github.com/razbuild/raztint/releases
Description-Content-Type: text/markdown

<div align="center">

<img src="https://raw.githubusercontent.com/razbuild/raztint/main/assets/RazTint.svg" alt="RazTint Logo" width="120" />

# RazTint

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

<br>

[![Python Versions](https://img.shields.io/pypi/pyversions/raztint)](https://pypi.org/project/raztint/)
[![PyPI Version](https://img.shields.io/pypi/v/raztint)](https://pypi.org/project/raztint/)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen)](https://github.com/razbuild/raztint)
[![Codecov](https://img.shields.io/codecov/c/github/razbuild/raztint)](https://codecov.io/gh/razbuild/raztint)

</div>

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

<p align="center">
  <img src="https://raw.githubusercontent.com/razbuild/raztint/main/assets/preview.png" alt="RazTint preview: Nerd Font, Unicode, and ASCII icon modes with colored and styled output examples" width="644"/>
</p>

<p align="center">
<em>A simulated production log stream: 9 secrets detected, 9 secrets redacted, 0 leaked to the terminal.</em>
</p>

---

## Installation

Requires Python `3.10+`.

```bash
pip install raztint
# with uv
uv add raztint
```

From source:

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

---

## Quick Start

```python
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](docs/getting-started.md) for a full walkthrough, including `logging` integration.

---

## 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.

```python
# 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.

- **Redaction** masks `key=value` pairs such as `password=`, `api_key=`, and `token=`. Patterns are configurable, see [Security & Redaction](docs/redaction.md).

- **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

| Guide                                                                                             | Description                                             |
| --------------------------------------------------------------------------------------------------| ---------------------------------------------------------|
| [Getting Started](https://github.com/razbuild/raztint/blob/main/docs/getting-started.md)        | Functional usage, `paint()`, and the `tint` instance      |
| [API Reference](https://github.com/razbuild/raztint/blob/main/docs/api-reference.md)            | Colors, styles, icons, and `RazTint` class methods         |
| [Intents](https://github.com/razbuild/raztint/blob/main/docs/intents.md)                        | Semantic presets for common CLI messages                   |
| [Security & Redaction](https://github.com/razbuild/raztint/blob/main/docs/redaction.md)         | Masking tokens, credentials, and custom rules               |
| [Icons & Detection](https://github.com/razbuild/raztint/blob/main/docs/icons-and-detection.md)  | Icon modes and environment/font/color detection logic      |
| [Configuration](https://github.com/razbuild/raztint/blob/main/docs/configuration.md)            | Environment variables and runtime toggles                    |
| [Development](https://github.com/razbuild/raztint/blob/main/docs/development.md)                | Local setup, tests, and linting                              |
| [Tutorial](https://github.com/razbuild/raztint/blob/main/docs/tutorial.md)                      | Philosophy, detection walk-through, and best practices      |

**Examples:** [`showcase.py`](https://github.com/razbuild/raztint/blob/main/examples/showcase.py) · [`file_processor.py`](https://github.com/razbuild/raztint/blob/main/examples/file_processor.py) · [`redaction_demo.py`](https://github.com/razbuild/raztint/blob/main/examples/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.md](https://github.com/razbuild/.github/blob/main/CONTRIBUTING.md) for setup and guidelines.

---

## License

[![License](https://img.shields.io/pypi/l/raztint)](https://github.com/razbuild/raztint/blob/main/LICENSE)

<div align="center">
  <img src="https://raw.githubusercontent.com/razbuild/.github/main/assets/badge.svg" alt="Made by RazBuild" width="160">
</div>