chromakitx 1.0.0
A comprehensive color manipulation library for Python
Requires Python: >=3.12
Keywords: color, rgb, hsl, hsv, hex, ansi, terminal

# ChromaKit

A modern, type-safe Python library for terminal color formatting with support for ANSI, CSS, Xterm, and custom RGB/HSL/Hex colors.

## Features

- **Type-Safe**: Full type hints and strict typing throughout the codebase
- **Protocol-Based Architecture**: Extensible design using Python protocols
- **Multiple Color Formats**: Support for ANSI, CSS, Xterm, and custom colors
- **Color Conversions**: Convert between RGB, HSL, and Hex formats
- **Text Styling**: Apply bold, italic, underline, and other text styles
- **Zero Dependencies**: Only uses Python standard library
- **Immutable Data**: All color models are immutable dataclasses
- **Comprehensive Testing**: Full test coverage for all components

## Installation

```bash
pip install chromakit
```

## Quick Start

```python
from chromakit import Color, AnsiColor, CustomColor, RGB, TextStyle

red = Color(AnsiColor.Red)
print(f"{red}This text is red{Color(TextStyle.RESET)}")

custom = Color(CustomColor(RGB(255, 165, 0)))
print(f"{custom}This is orange{Color(TextStyle.RESET)}")
```

## Usage

### Basic ANSI Colors

```python
from chromakit import Color, AnsiColor, TextStyle

red = Color(AnsiColor.Red)
green = Color(AnsiColor.Green)
blue = Color(AnsiColor.Blue)

print(f"{red}Error message{Color(TextStyle.RESET)}")
print(f"{green}Success message{Color(TextStyle.RESET)}")
print(f"{blue}Info message{Color(TextStyle.RESET)}")
```

### CSS Named Colors

```python
from chromakit import Color, CssColor, TextStyle

coral = Color(CssColor.Coral)
turquoise = Color(CssColor.Turquoise)
gold = Color(CssColor.Gold)

print(f"{coral}Coral text{Color(TextStyle.RESET)}")
print(f"{turquoise}Turquoise text{Color(TextStyle.RESET)}")
```

### Custom Colors

Create custom colors using RGB, HSL, or Hex formats:

```python
from chromakit import Color, CustomColor, RGB, HSL, HexColor, TextStyle

rgb_color = Color(CustomColor(RGB(255, 165, 0)))
print(f"{rgb_color}Orange from RGB{Color(TextStyle.RESET)}")

hex_color = Color(CustomColor(HexColor("#FF1493")))
print(f"{hex_color}Deep pink from Hex{Color(TextStyle.RESET)}")

hsl_color = Color(CustomColor(HSL(0.6, 1.0, 0.5)))
print(f"{hsl_color}Blue from HSL{Color(TextStyle.RESET)}")
```

### Color Conversions

```python
from chromakit import CustomColor, RGB, HexColor
from chromakit.utils import hex_to_rgb

rgb = hex_to_rgb("#FF6B6B")
print(f"RGB: {rgb}")

custom = CustomColor(RGB(128, 0, 128))
print(f"RGB: {custom.rgb}")
print(f"HSL: {custom.hsl}")
print(f"Hex: {custom.hex.value}")
```

### Text Styling

```python
from chromakit import Color, TextStyle, TextStyle

bold = Color(TextStyle.BOLD)
italic = Color(TextStyle.ITALIC)
underline = Color(TextStyle.UNDERLINE)

print(f"{bold}Bold text{Color(TextStyle.RESET)}")
print(f"{italic}Italic text{Color(TextStyle.RESET)}")
print(f"{underline}Underlined text{Color(TextStyle.RESET)}")
```

### String Concatenation

```python
from chromakit import Color, AnsiColor, TextStyle

red = Color(AnsiColor.Red)
blue = Color(AnsiColor.Blue)

message = red + "Error: " + Color(TextStyle.RESET) + "Something went wrong"
print(message)

combined = "Status: " + blue + "OK" + Color(TextStyle.RESET)
print(combined)
```

### Color Lookup by Name

```python
from chromakit import Color, AnsiColor, CssColor, TextStyle

red = Color(AnsiColor.from_name("Red"))
bright_cyan = Color(AnsiColor.from_name("bright-cyan"))
cornflower = Color(CssColor.from_name("CornflowerBlue"))

print(f"{red}Red{Color(TextStyle.RESET)}")
print(f"{bright_cyan}Bright Cyan{Color(TextStyle.RESET)}")
print(f"{cornflower}Cornflower Blue{Color(TextStyle.RESET)}")
```

## Architecture

### Core Components

- **`Color`**: Main wrapper class for all color types
- **`ColorFormattable`**: Protocol defining the format interface
- **`NameResolvable`**: Protocol for color name lookup
- **`ColorProvider`**: Combined protocol for complete color functionality

### Color Types

- **`AnsiColor`**: Standard ANSI terminal colors (16 colors)
- **`CssColor`**: 140+ CSS named colors
- **`XtermColor`**: Extended 256-color Xterm palette
- **`TextStyle`**: Text styling options (bold, italic, etc.)
- **`CustomColor`**: User-defined colors via RGB/HSL/Hex

### Data Models

- **`RGB`**: Immutable RGB color representation (0-255 per channel)
- **`HSL`**: Immutable HSL color representation (0.0-1.0 per component)
- **`HexColor`**: Immutable hexadecimal color representation

### Utilities

- **`hex_to_rgb()`**: Convert hex string to RGB
- **`hsl_to_rgb()`**: Convert HSL to RGB
- **`rgb_to_hsl()`**: Convert RGB to HSL
- **`rgb_to_hex()`**: Convert RGB to hex string

## Error Handling

ChromaKit provides specific exceptions for different error cases:

```python
from chromakit.exceptions import ColorError, InvalidColorError, ColorConversionError

try:
    color = AnsiColor.from_name("InvalidName")
except InvalidColorError as e:
    print(f"Invalid color: {e}")

try:
    rgb = RGB(300, 0, 0)
except ValueError as e:
    print(f"Invalid RGB value: {e}")
```

## Examples

Check the `examples/` directory for complete usage examples:

- `basic_usage.py`: Basic color usage and text formatting
- `advanced_usage.py`: Color conversions, palettes, and advanced features

Run examples:

```bash
python examples/basic_usage.py
python examples/advanced_usage.py
```

## Testing

Run tests with pytest:

```bash
pytest tests/
```

## Type Checking

ChromaKit is fully typed and passes strict type checking:

```bash
mypy chromakit/
```

## Design Principles

1. **Type Safety**: Every variable and method is strictly typed
2. **Immutability**: All data models are immutable for safety
3. **Protocol-Based**: Extensible architecture using protocols
4. **Single Responsibility**: Each module has one clear purpose
5. **Pattern Matching**: Modern Python patterns for cleaner code
6. **No Side Effects**: Pure functions for conversions and utilities

## Requirements

- Python 3.10+
- No external dependencies

## License

MIT License

## Contributing

Contributions are welcome. Please ensure:

- All code is strictly typed
- Tests cover new functionality
- Code follows existing patterns and conventions
- No external dependencies are added

## Version

Current version: 2.0.0