# PaintCan

![PaintCan banner](https://raw.githubusercontent.com/btfranklin/paintcan/main/.github/social%20preview/paintcan_social_preview.jpg "PaintCan")

[![Build Status](https://github.com/btfranklin/paintcan/actions/workflows/python-package.yml/badge.svg)](https://github.com/btfranklin/paintcan/actions/workflows/python-package.yml) [![Supports Python versions 3.11+](https://img.shields.io/pypi/pyversions/paintcan.svg)](https://pypi.python.org/pypi/paintcan)

**PaintCan** is a high-quality, Pythonic library for working with HSBA colors and generating beautiful, algorithmic color schemes. It provides robust tools for color manipulation and harmony generation.

## Features

- **HSBAColor**: A value-type representation of color using Hue, Saturation, Brightness, and Alpha (0.0 - 1.0).
  - Cyclic Hue adjustment (wrapping).
  - Clamping and Overflow support for Saturation and Brightness.
  - Pythonic unpacking: `h, s, b, a = color`.
- **ColorScheme**: A collection of colors generated by color theory rules.
  - Supports the Sequence protocol (`len(scheme)`, `scheme[0]`, iteration).
  - 8 factory methods for generating harmonious schemes:
    - Analogous
    - Accented Analogous
    - Complementary
    - Compound
    - Monochromatic
    - Shades
    - Split Complementary
    - Triadic

## Installation

Using PDM:
```bash
pdm add paintcan
```

Using pip:
```bash
pip install paintcan
```

## Usage

### Working with HSBAColor

```python
from paintcan import HSBAColor

# Create a color (Red)
red = HSBAColor(hue=0.0, saturation=1.0, brightness=1.0, alpha=1.0)

# Adjust Hue (wraps around)
orange = red.adjust_hue(0.08)

# Get the complement (Cyan-ish)
cyan = red.complement()

# Pythonic Unpacking
h, s, b, a = cyan
print(f"Hue: {h}, Saturation: {s}")
```

### Generating Color Schemes

```python
from paintcan import HSBAColor, ColorScheme

# Start with a base color
base = HSBAColor(0.5, 0.8, 0.9, 1.0) # Cyan-ish

# Generate a Split Complementary scheme
scheme = ColorScheme.from_split_complementary(base)

# Access colors (behaves like a tuple)
print(f"Scheme has {len(scheme)} colors.")
theme = scheme.theme_color # First color is always the theme color

for color in scheme:
    print(color)
```

## Demo

To see the color schemes in action in your terminal (using ANSI colors):

```bash
# If installed via PDM/Dev
pdm run python -m paintcan

# If installed in your environment
python -m paintcan
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
