panda-color 0.1.3

A color library that supports RGB with swizzling and will support hex and hsv in the future

PandaColor

A lightweight and extensible Python color library with GLSL-style swizzling support.

PandaColor provides an intuitive interface for working with RGB colors, featuring swizzling patterns familiar to graphics programmers, comprehensive color manipulations, predefined color constants, and utilities for terminal output and web development.

---

Features

Core Functionality

• Multiple initialization methods: integers, strings, iterables, hex codes, or normalized floats
• GLSL-style swizzling: Access components with .r, .g, .b, .rgb, .rg, .gbr, etc.
• Comprehensive validation: Type checking and range validation for all color values
• Immutable variants: Create new colors with with_red(), with_green(), with_blue()
• Predefined color constants: 36 common colors ready to use

Color Manipulations

• Brightness: lighten(), darken()
• Color operations: invert(), grayscale(), blend()
• Utilities: clamp(), distance() between colors

Output Formats

• Web formats: CSS rgb(), rgba(), hex strings
• Data formats: tuples, lists, dictionaries, normalized floats
• Terminal colors: ANSI escape sequences with truecolor and 256-color fallback
• Luminance calculation: sRGB standard relative luminance

---

Installation

Install from PyPI:

pip install panda-color

Or install from source:

git clone https://github.com/ColinThePanda/pandacolor.git
cd pandacolor
pip install .

---

Quick Start

from panda_color import Color, RED, BLUE, GREEN

# Multiple ways to create colors
color1 = Color(255, 128, 0)           # RGB integers
color2 = Color([255, 128, 0])         # From list/tuple
color3 = Color("255, 128, 0")         # From string
color4 = Color.from_hex("#ff8000")    # From hex
color5 = Color.from_normalized(1.0, 0.5, 0.0)  # Normalized floats
color6 = Color.random()               # Random color

# Use predefined colors
print(RED.to_hex())     # #ff0000
print(BLUE.css_rgb())   # rgb(0, 0, 255)

# GLSL-style swizzling
print(color1.r)       # 255
print(color1.rgb)     # Color(255, 128, 0)
print(color1.rg)      # (255, 128)
print(color1.gbr)     # (128, 0, 255)

# Swizzling assignment
color1.r = 200        # Set red component
color1.gb = [64, 32]  # Set green and blue components

Predefined Color Constants

PandaColor includes 36 predefined colors for immediate use:

from panda_color import (
    # Basic colors
    BLACK, WHITE, RED, GREEN, BLUE, YELLOW, CYAN, MAGENTA,

    # Grays
    GRAY, LIGHT_GRAY, DARK_GRAY,

    # Extended colors
    ORANGE, PINK, PURPLE, BROWN, LIME, TEAL, NAVY, OLIVE, MAROON,

    # Named colors
    AQUA, CRIMSON, CORNFLOWER_BLUE, DARK_ORANGE, DARK_GREEN, DARK_RED,
    STEEL_BLUE, DARK_SLATE_GRAY, MEDIUM_PURPLE, FIREBRICK, SALMON,
    LIME_GREEN, SKY_BLUE, GOLD, SILVER
)

# Use them directly
print(f"Crimson: {CRIMSON.to_hex()}")        # #dc143c
print(f"Sky Blue: {SKY_BLUE.css_rgb()}")     # rgb(135, 206, 235)

Color Manipulations

from panda_color import Color, lighten, darken, invert, grayscale, blend, RED, BLUE

original = Color(100, 150, 200)

# Brightness adjustments
lighter = lighten(original, 0.3)    # 30% lighter
darker = darken(original, 0.5)      # 50% darker

# Color transformations
inverted = invert(original)         # Color complement
gray = grayscale(original)          # Grayscale conversion

# Blending colors
purple = blend(RED, BLUE, 0.5)      # 50/50 blend -> Color(127, 0, 127)

Output Formats

from panda_color import ORANGE

# Web formats
print(ORANGE.to_hex())           # #ffa500
print(ORANGE.css_rgb())          # rgb(255, 165, 0)
print(ORANGE.css_rgba(0.8))      # rgba(255, 165, 0, 0.8)

# Data formats
print(ORANGE.to_tuple())         # (255, 165, 0)
print(ORANGE.to_list())          # [255, 165, 0]
print(ORANGE.to_dict())          # {'r': 255, 'g': 165, 'b': 0}
print(ORANGE.normalized())       # (1.0, 0.6470588235294118, 0.0)

# Properties
print(ORANGE.luminance)          # 0.5515... (relative luminance)

Terminal Colors

from panda_color import RED, GREEN, BLUE, color_text, highlight_text

# Colored text output (with automatic fallback support)
print(color_text(RED, "This text is red!"))
print(highlight_text(GREEN, "This has a green background!"))

# Combine with predefined colors
print(color_text(BLUE, "Blue text"))

Sequence Protocol

Colors support iteration and indexing:

from panda_color import PURPLE

# Iteration
for component in PURPLE:
    print(component)  # 128, 0, 128

# Indexing
print(PURPLE[0])  # 128 (red)
print(PURPLE[1])  # 0 (green)
print(PURPLE[2])  # 128 (blue)

# Length
print(len(PURPLE))  # 3

Immutable Variants

Create new colors based on existing ones:

from panda_color import BLUE

red_blue = BLUE.with_red(255)     # Color(255, 0, 255) - magenta
light_blue = BLUE.with_green(128) # Color(0, 128, 255) - lighter blue

---

API Reference

Color Class

Constructor

• Color() - Black color (0, 0, 0)
• Color(r, g, b) - RGB integers (0-255)
• Color(iterable) - From list, tuple, etc.
• Color(string) - Parse "r, g, b" format
• Color(color) - Copy constructor

Class Methods

• Color.from_hex(hex_string) - From hex string (#RRGGBB or RRGGBB)
• Color.from_normalized(r, g, b) - From normalized floats (0.0-1.0)
• Color.random() - Generate random color

Properties

• .r, .g, .b - Individual components (with setters)
• .rgb - RGB as Color object (with setter)
• .luminance - Relative luminance (0.0-1.0)

Methods

• .to_hex() - Hex string (#RRGGBB)
• .to_tuple() - RGB as tuple
• .to_list() - RGB as list
• .to_dict() - RGB as dictionary
• .css_rgb() - CSS rgb() format
• .css_rgba(alpha) - CSS rgba() format
• .normalized() - Normalized floats (0.0-1.0)
• .with_red(r), .with_green(g), .with_blue(b) - Immutable variants

Utility Functions

from panda_color import (
    lighten, darken, invert, grayscale, blend, clamp, distance,
    color_text, highlight_text, to_ansi256
)

lighten(color, factor)          # Lighten by factor (0.0-1.0)
darken(color, factor)           # Darken by factor (0.0-1.0)
invert(color)                   # Color complement
grayscale(color)                # Grayscale conversion
blend(color1, color2, factor)   # Blend two colors
clamp(color)                    # Clamp to valid RGB range
distance(color1, color2)        # Euclidean distance in RGB space

# Terminal output
color_text(color, text)         # Colored text (foreground)
highlight_text(color, text)     # Highlighted text (background)
to_ansi256(color)              # Convert to ANSI 256-color code

Color Constants

All predefined colors are available as constants:

from panda_color import (
    BLACK, WHITE, RED, GREEN, BLUE, YELLOW, CYAN, MAGENTA,
    GRAY, LIGHT_GRAY, DARK_GRAY, ORANGE, PINK, PURPLE, BROWN,
    LIME, TEAL, NAVY, OLIVE, MAROON, AQUA, CRIMSON,
    CORNFLOWER_BLUE, DARK_ORANGE, DARK_GREEN, DARK_RED,
    STEEL_BLUE, DARK_SLATE_GRAY, MEDIUM_PURPLE, FIREBRICK,
    SALMON, LIME_GREEN, SKY_BLUE, GOLD, SILVER
)

---

Examples

Web Development

from panda_color import BLUE, lighten, darken

primary = BLUE
secondary = lighten(primary, 0.2)
accent = darken(primary, 0.3)

print(f"Primary: {primary.css_rgb()}")      # rgb(0, 0, 255)
print(f"Secondary: {secondary.css_rgb()}")  # rgb(51, 51, 255)
print(f"Accent: {accent.css_rgb()}")        # rgb(0, 0, 178)

Terminal Applications

from panda_color import RED, GREEN, YELLOW, color_text

print(color_text(RED, "❌ Error: Something went wrong"))
print(color_text(GREEN, "✅ Success: Operation completed"))
print(color_text(YELLOW, "⚠️  Warning: Check your input"))

Color Analysis

from panda_color import Color, distance, grayscale

color1 = Color(255, 100, 50)
color2 = Color(200, 150, 100)

print(f"Distance: {distance(color1, color2):.2f}")
print(f"Color1 luminance: {color1.luminance:.3f}")
print(f"Grayscale: {grayscale(color1).to_hex()}")

---

Roadmap

• Integration utilities for OpenGL/shader workflows
• HSV and HSL color space support
• Auto-generated color palettes

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

License

MIT © 2025 Colin Politi
See LICENSE for details.