Metadata-Version: 2.4
Name: colorbrew
Version: 0.5.0
Summary: A lightweight, zero-dependency Python library for color manipulation.
Project-URL: Homepage, https://github.com/zfoq/colorbrew
Project-URL: Repository, https://github.com/zfoq/colorbrew
Author: Dawid Prus
License-Expression: MIT
License-File: LICENSE
Keywords: accessibility,color,css,hex,hsl,palette,rgb,wcag
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# ColorBrew

A lightweight, zero-dependency Python library for working with colors.

## Features

- Parse colors from hex strings (`#3498db`, `#fff`, `3498db`)
- Parse CSS function strings (`rgb(52, 152, 219)`, `hsl(204, 70%, 53%)`)
- Parse CSS named colors (`cornflowerblue`, `red`, etc.)
- Convert between hex, RGB, HSL, and CMYK formats
- Input validation with clear error messages
- 148 built-in CSS named colors
- Immutable `Color` class with format properties and dunder methods
- CSS/HTML-ready output (`rgb()`, `rgba()`, `hsl()`, `hsla()`, hex)
- Format string support (`f"{color:rgb}"`, `f"{color:hsl}"`)
- Reverse name lookup — find the closest CSS named color with distance score
- Color manipulation — lighten, darken, saturate, desaturate, rotate hue, invert, grayscale, mix
- Photoshop-style blend modes — multiply, screen, overlay, soft light, hard light, difference
- Palette generation — complementary, analogous, triadic, split-complementary, tetradic
- WCAG accessibility — luminance, contrast ratio, AA/AAA compliance checks
- Color temperature — warm/cool/neutral classification, Kelvin estimation

## Installation

```bash
pip install colorbrew
```

Requires Python 3.12+. Zero runtime dependencies.

## Quick Start

```python
from colorbrew import Color

# Create from any format
c = Color("#3498db")
c = Color(52, 152, 219)
c = Color("rgb(52, 152, 219)")
c = Color("cornflowerblue")

# Alternate constructors
c = Color.from_hsl(204, 70, 53)
c = Color.from_cmyk(76, 31, 0, 14)
c = Color.from_name("cornflowerblue")

# Access format properties
c.rgb                       # (52, 152, 219)
c.hex                       # "#3498db"
c.hsl                       # (204, 70, 53)
c.cmyk                      # (76, 31, 0, 14)

# CSS output
c.css_rgb                   # "rgb(52, 152, 219)"
c.css_hsl                   # "hsl(204, 70%, 53%)"
c.css_hex                   # "#3498db"
c.css_rgba(0.5)             # "rgba(52, 152, 219, 0.5)"
c.css_hsla(0.8)             # "hsla(204, 70%, 53%, 0.8)"

# Format strings
f"{c:rgb}"                  # "rgb(52, 152, 219)"
f"{c:hsl}"                  # "hsl(204, 70%, 53%)"
f"{c:hex}"                  # "#3498db"

# Reverse name lookup
match = c.closest_name
match.name                  # "steelblue"
match.distance              # 10.7703
match.exact                 # False

# Manipulation (all return new Color instances)
c.lighten(20)               # lighter color
c.darken(10)                # darker color
c.saturate(15)              # more vivid
c.desaturate(15)            # more muted
c.rotate(180)               # shift hue
c.invert()                  # RGB inverse
c.grayscale()               # remove saturation
c.mix(Color("red"), 0.5)    # blend two colors

# Blend modes
c.blend(Color("white"), "multiply")   # multiply blend
c.blend(Color("black"), "screen")     # screen blend

# Palette generation
c.complementary()              # opposite hue
c.analogous()                  # 3 neighboring hues
c.triadic()                    # 2 colors at 120° intervals
c.split_complementary()        # 2 colors flanking the complement
c.tetradic()                   # 3 colors at 90° intervals

# Accessibility (WCAG 2.1)
c.luminance                    # relative luminance (0.0-1.0)
c.contrast(Color("white"))     # contrast ratio (1.0-21.0)
c.meets_aa(Color("white"))     # True if passes WCAG AA
c.meets_aaa(Color("white"))    # True if passes WCAG AAA

# Color temperature
c.temperature                  # "warm", "cool", or "neutral"
c.kelvin                       # estimated Kelvin (1000-40000)

# Iteration and comparison
r, g, b = c                 # unpack RGB
Color("#ff0000") == Color("red")  # True
```

## Development

```bash
uv sync
uv run pytest
uv run ruff check src/
```

## License

MIT
