Metadata-Version: 2.3
Name: colored-messages
Version: 0.1.1
Summary: Minimal, dependency-free helpers for color-formatted terminal messages
Keywords: terminal,colors,ansi,cli,logging
Author: Nicolas Pourcelot
Author-email: Nicolas Pourcelot <nicolas.pourcelot@gmail.com>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
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: Topic :: Terminals
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Project-URL: Bug Tracker, https://github.com/wxgeo/colored-messages/issues
Project-URL: Homepage, https://github.com/wxgeo/colored-messages
Project-URL: Repository, https://github.com/wxgeo/colored-messages
Description-Content-Type: text/markdown

# colored_messages

A minimal, dependency-free Python library for printing color-formatted messages
in Linux/macOS terminals using ANSI escape codes.

## Features

- **Four ready-made print helpers** — `print_error`, `print_warning`, `print_info`,
  `print_success` — each with a colored `[Tag]` prefix, usable with zero
  configuration.
- **Low-level building blocks** — `term_color` for full control over every ANSI
  attribute (bold, dim, italic, underline, highlight, reverse, color).
- **Named color shortcuts** — `red()`, `green()`, `yellow()`, `blue()`, `bold()`
  for quick inline formatting.
- **No dependencies** — only the Python standard library is required.

## Installation

```bash
pip install colored-messages
```

## Quick start

```python
from colored_messages import print_error, print_warning, print_info, print_success

print_info("Loading configuration…")
print_success("Server started on port 8080")
print_warning("Disk usage above 80 %")
print_error("Connection refused")
```

Terminal output:

```
[Info]    Loading configuration…
[OK]      Server started on port 8080
[Warning] Disk usage above 80 %
[Error]   Connection refused          ← printed to stderr
```

Each tag is rendered in its matching color (blue / green / yellow / red).
`print_error` writes to `sys.stderr`; the other three write to `sys.stdout`.

## API reference

### Print helpers

| Function | Tag | Color | Bold tag | Stream |
|---|---|---|---|---|
| `print_info(msg)` | `[Info]` | Blue | No | stdout |
| `print_success(msg)` | `[OK]` | Green | Yes | stdout |
| `print_warning(msg)` | `[Warning]` | Yellow | No | stdout |
| `print_error(msg)` | `[Error]` | Red | Yes | stderr |

### `custom_print`

Print any message with a fully custom tag:

```python
from colored_messages import custom_print, TermColors

custom_print("Starting backup…", TermColors.CYAN, "Backup", bold=True)
# → [Backup] Starting backup…
```

Additional keyword arguments are forwarded to `print()` (e.g. `file=`, `end=`,
`flush=`).

### Named color shortcuts

```python
from colored_messages import red, green, yellow, blue, bold

print(f"Status: {green('OK')}")
print(f"Level:  {red('CRITICAL', bold=True)}")
print(f"Title:  {bold('Important notice')}")
```

Each shortcut accepts an optional `bold=True` keyword argument.

### `term_color` — full control

```python
from colored_messages import term_color, TermColors

s = term_color(
    "hello",
    color=TermColors.PURPLE,
    bold=True,
    underline=True,
    italic=True,
)
print(s)
```

Supported attributes:

| Keyword | SGR code | Effect |
|---|---|---|
| `bold=True` | 1 | Increased intensity |
| `dim=True` | 2 | Decreased intensity |
| `italic=True` | 3 | Italic text |
| `underline=True` | 4 | Single underline |
| `highlight=True` | 7 | Reverse video (swap fg/bg) |
| `reverse=True` | — | Use *color* as background instead of foreground |

### `bold` — preserve surrounding color

```python
from colored_messages import bold, term_color, TermColors

# The bold wrapper uses SGR 22 (normal intensity) instead of SGR 0 (full
# reset), so an outer color is not disturbed:
msg = term_color(f"prefix: {bold('important')} suffix", TermColors.BLUE)
print(msg)
```

### `TermColors`

```python
from colored_messages import TermColors

TermColors.GRAY    # 0
TermColors.RED     # 1
TermColors.GREEN   # 2
TermColors.YELLOW  # 3
TermColors.BLUE    # 4
TermColors.PURPLE  # 5
TermColors.CYAN    # 6
TermColors.WHITE   # 7
```

`TermColors` is an `IntEnum`, so its members can be used directly as integers.

## Development

This project uses [uv](https://github.com/astral-sh/uv) and
[just](https://github.com/casey/just).

```bash
# Run linter, type checker, and test suite
just test
```

Individual commands:

```bash
uv run ruff check --fix .   # lint & auto-fix
uv run mypy .               # type checking
uv run pytest tests         # unit tests
```

## License

MIT
