Peelee

A comprehensive Python library for creating countless color palettes, themes, and advanced color manipulations.

Features

Advanced Palette Generation: Create sophisticated color palettes with configurable parameters
Theme Generation: Generate themes from templates with automatic color replacement
Color Utilities: Comprehensive color conversion and manipulation functions
Contrast Optimization: Automatic accessibility compliance with contrast ratio adjustments
Multiple Formats: Support for JSON, plain text, and custom palette formats
CLI Interface: Command-line tools for quick palette generation

Installation

pip install peelee

Or using Poetry:

poetry add peelee

Quick Start

Basic Palette Generation

from peelee import generate_palette, Palette

# Quick palette generation
palette = generate_palette()
print(palette)

# Advanced palette with custom parameters
custom_palette = Palette(
    colors_total=7,
    colors_gradations_total=60,
    dark_base_color="#2D2A35",
    palette_mode="DARK"
).generate_palette()

Color Utilities

from peelee.color_utils import hex2hls, convert_to_best_dark_color

# Color conversion
hls_color = hex2hls("#FF5733")
print(f"HLS: {hls_color}")

# Contrast optimization for accessibility
optimized_color = convert_to_best_dark_color(
    background_color="#2D2A35",
    foreground_color="#FFFFFF",
    min_contrast_ratio=7,
    max_contrast_ratio=21
)

Theme Generation

from peelee import generate_new_theme

# Generate theme from template
theme_files = generate_new_theme(
    original_theme_file="base_theme.json",
    theme_root="./output",
    theme_name="MyCustomTheme",
    palette_colors=custom_palette
)

print(f"Generated theme: {theme_files[0]}")

API Reference

Classes

Palette

Main class for palette generation with comprehensive configuration options.

Palette(
    colors_total=7,                    # Number of base colors
    colors_gradations_total=60,        # Color gradations per base color
    colors_min=10,                     # Minimum color value
    colors_max=40,                     # Maximum color value
    colors_saturation=0.55,            # Saturation level
    colors_lightness=0.05,             # Lightness level
    dark_colors_total=7,               # Dark color variants
    dark_colors_gradations_total=60,   # Dark color gradations
    dark_base_color="#2D2A35",         # Base color for dark themes
    palette_mode="DARK"                # DARK, LIGHT, or RANDOM
)

PaletteMode

Enumeration for palette modes:

PaletteMode.DARK: Dark color schemes
PaletteMode.LIGHT: Light color schemes
PaletteMode.RANDOM: Random color schemes

Functions

generate_palette(**kwargs)

Quick palette generation with optional parameters.

palette = generate_palette(
    colors_total=5,
    dark_base_color="#1E1E1E",
    palette_mode="DARK"
)

generate_new_theme(original_theme_file, theme_root, theme_name, **kwargs)

Generate new theme from template with automatic color replacement.

Parameters:

original_theme_file: Path to base theme file
theme_root: Output directory
theme_name: Name for generated theme
palette_colors: Custom palette colors (optional)

Returns: Tuple of (theme_file, template_file, palette_file, picked_palette_file)

Color Utilities

Conversion Functions

from peelee.color_utils import hex2hls, hls2hex, hex2rgb, rgb2hex

# Convert between color formats
hls = hex2hls("#FF5733")
hex_color = hls2hex((0.5, 0.5, 0.8))
rgb = hex2rgb("#FF5733")
hex_from_rgb = rgb2hex((255, 87, 51))

Color Manipulation

from peelee.color_utils import darken, lighten, set_hls_values

# Adjust color properties
darker = darken("#FF5733", 0.3)
lighter = lighten("#FF5733", 0.3)
adjusted = set_hls_values("#FF5733", hue=0.6, saturation=0.8)

Contrast Optimization

from peelee.color_utils import convert_to_best_dark_color, convert_to_best_light_color

# Optimize for dark themes
dark_optimized = convert_to_best_dark_color(
    background_color="#2D2A35",
    foreground_color="#FFFFFF",
    min_contrast_ratio=7,
    max_contrast_ratio=21
)

# Optimize for light themes
light_optimized = convert_to_best_light_color(
    foreground_color="#000000",
    background_color="#FFFFFF",
    min_contrast_ratio=7,
    max_contrast_ratio=21
)

Configuration Options

Color Generation Parameters

colors_total: Number of base colors to generate (default: 7)
colors_gradations_total: Gradations per color (default: 60)
colors_min/max: RGB value range for colors (default: 10-40)
colors_saturation: Saturation level (default: 0.55)
colors_lightness: Lightness level (default: 0.05)

Dark Theme Parameters

dark_colors_total: Number of dark color variants (default: 7)
dark_colors_gradations_total: Dark color gradations (default: 60)
dark_colors_min/max: RGB range for dark colors (default: 20-40)
dark_base_color: Base color for dark themes

Advanced Options

color_gradations_division_rate: Color gradation distribution (default: 0.9)
reversed_color_offset_rate: Reversed color offset (default: 0.5)
force_base_color_code: Force specific color code override

CLI Usage

Generate palettes from command line:

python -m peelee --colors_total 5 --palette_mode DARK --dark_base_color "#2D2A35"

CLI Options

-t, --colors_total: Number of colors (default: 7)
-g, --colors_gradations: Color gradations (default: 60)
-b, --dark_base_color: Base color for dark themes
-p, --palette_mode: Palette mode (DARK/LIGHT/RANDOM)

Development

Requirements

Python 3.11+
loguru for logging

Setup

git clone https://github.com/wenijinew/peelee.git
cd peelee
poetry install
poetry shell

Testing

# Run tests
pytest

# Run with coverage
pytest --cov=peelee

# Run specific test
pytest tests/peelee_test.py

Code Quality

The project uses pre-commit hooks for code quality:

# Install pre-commit hooks
pre-commit install

# Run manually
pre-commit run --all-files

Tools used:

Black: Code formatting
isort: Import sorting
flake8: Linting
mypy: Type checking

Examples

Creating a Dark Theme Palette

from peelee import Palette

# Create a sophisticated dark theme palette
dark_palette = Palette(
    colors_total=8,
    colors_gradations_total=80,
    dark_base_color="#1E1E2E",
    dark_colors_saturation=0.2,
    dark_colors_lightness=0.1,
    palette_mode="DARK"
).generate_palette()

# Use in your application
for color_id, hex_color in dark_palette.items():
    print(f"{color_id}: {hex_color}")

Generating Multiple Theme Variants

from peelee import generate_new_theme
import os

base_colors = ["#FF6B6B", "#4ECDC4", "#45B7D1", "#96CEB4"]

for i, color in enumerate(base_colors):
    theme_files = generate_new_theme(
        original_theme_file="templates/base.json",
        theme_root=f"./themes/variant_{i+1}",
        theme_name=f"CustomTheme_{i+1}",
        palette_colors={"base_color": color}
    )
    print(f"Generated theme variant {i+1}: {theme_files[0]}")

License

MIT License - see LICENSE file for details.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request

Changelog

See CHANGELOG.md for version history and changes.

Support

Issues: GitHub Issues
Documentation: This README and inline code documentation
Version: 0.2.34

Metadata

Release files for peelee 0.2.57

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for peelee 0.2.57
File	Size	Uploaded
peelee-0.2.57.tar.gz	24.3 kB	Apr 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for peelee 0.2.57
File	Interpreter	ABI	Platform	Reset
peelee-0.2.57-py3-none-any.whl 24.2 kB Apr 7, 2026	Python 3	none	any	Details

Total release size: 48.5 kB

Release files / peelee-0.2.57.tar.gz

Download URL	peelee-0.2.57.tar.gz
Size	24.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`c98118e0a57a9ae74b69f695d0d1084a6afe308d6b1a3b7ce2975a6b20fc52ab`
BLAKE2b-256 checksum How to use checksums	`dc472fbab7f57e830d6e0e6b209e61f25582d69ad63c8b554cc7434edc9cd060`
Upload date	Apr 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.9.25`

Release files / peelee-0.2.57-py3-none-any.whl

Download URL	peelee-0.2.57-py3-none-any.whl
Size	24.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`00f4ecd80af4f0cb01ced7cda46c7bf484d158d60e2f12a221f7e44e54699edd`
BLAKE2b-256 checksum How to use checksums	`2a3bb789b57fcdda61d63256059f1f2bc640bfd8ecd81dfabddb793b62f91184`
Upload date	Apr 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.9.25`