peelee 0.2.55

A python library to create countless palettes.

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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. 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