Metadata-Version: 2.4
Name: str2col
Version: 0.1.2
Summary: Map any value to a deterministic color
License: MIT
Project-URL: Homepage, https://github.com/roncofaber/str2col
Keywords: color,hash,terminal,ansi,cli
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"

# str2col

Deterministically map any value to a color.

```python
from str2col import Str2Col, str2col

# one-off
str2col("hello")              # "#41eaa0"
str2col("hello", fmt="rgb")   # (65, 234, 160)

# reusable converter with constraints
conv = Str2Col(seed="myapp", hue_range=(180, 300), sat_range=(0.5, 0.8))
conv.to_hex("label A")        # "#..."
conv.to_rgb("label A")        # (R, G, B)
conv.to_hsl("label A")        # (hue, sat, light)
conv.to_ansi_fg("label A")    # "\033[38;2;...m"
conv.to_ansi_bg("label A")    # "\033[48;2;...m"
```

Supported types: strings, ints, floats, `None`.

## Install

```bash
pip install str2col
```

## CLI

```bash
str2col hello
str2col hello --format rgb
str2col hello --format ansi_fg --text "hello world"
echo "hello" | str2col
```

Options:

| Flag | Default | Description |
|------|---------|-------------|
| `--format` / `-f` | `hex` | `hex`, `rgb`, `rgb_float`, `hsl`, `ansi_fg`, `ansi_bg` |
| `--seed` | none | shift the color mapping |
| `--hue-range MIN MAX` | `0 360` | restrict hue (degrees) |
| `--sat-range MIN MAX` | `0.4 0.9` | restrict saturation |
| `--light-range MIN MAX` | `0.35 0.65` | restrict lightness |
| `--text TEXT` | none | print TEXT in the computed color |

## How it works

The input is coerced to a string and hashed with MD5. Three independent 4-byte chunks of the digest are mapped into the configured HSL ranges, then converted to the requested output format via Python's `colorsys` module.
