Metadata-Version: 2.1
Name: paintcan
Version: 0.1.0
Summary: A Pythonic library for creating beautiful, algorithmic color schemes.
Author-Email: "B.T. Franklin" <brandon.franklin@gmail.com>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Multimedia :: Graphics
Project-URL: Homepage, https://github.com/btfranklin/paintcan
Project-URL: Issues, https://github.com/btfranklin/paintcan/issues
Project-URL: Repository, https://github.com/btfranklin/paintcan.git
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# PaintCan

![PaintCan Social Preview](.github/social%20preview/paintcan_social_preview.jpg)

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