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).
  • Validates all components on construction.
  • Cyclic Hue adjustment (wrapping).
  • Clamping and full-interval Overflow support for Saturation and Brightness.
  • Pythonic unpacking: h, s, b, a = color.
• ColorScheme: A collection of colors generated by color theory rules.
  • Immutable and supports the Sequence protocol (len(scheme), scheme[0], slicing, iteration).
  • 8 factory methods for generating harmonious schemes:
    • Analogous
    • Accented Analogous
    • Complementary
    • Compound
    • Monochromatic
    • Shades
    • Split Complementary
    • Triadic

Installation

Using PDM:

pdm add paintcan

Using pip:

pip install paintcan

Usage

Working with HSBAColor

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

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):

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

# If installed in your environment
python -m paintcan

Development

The maintainer and agent docs live in docs/index.md. For local validation:

pdm install --group dev
pdm run check
pdm build

License

This project is licensed under the MIT License - see the LICENSE file for details.