Metadata-Version: 2.4
Name: chromaconsole
Version: 1.0.0
Summary: Fast C-based terminal coloring module
Author-email: Umit Tasdelen <umittadelen1277@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/umittadelen/chromaconsole
Project-URL: Bug Tracker, https://github.com/umittadelen/chromaconsole/issues
Project-URL: Repository, https://github.com/umittadelen/chromaconsole.git
Project-URL: Documentation, https://github.com/umittadelen/chromaconsole#readme
Keywords: terminal,color,coloring,ansi,console
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: C
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# chromaconsole

Fast C-based terminal coloring for Python with **zero runtime dependencies**.

## Install

```bash
pip install chromaconsole
```

## Quick Start

```python
from chromaconsole import Color, BColor, Style

# Foreground colors
print(Color.red() + "Red text" + Color.reset())
print(Color.blue() + "Blue text" + Color.reset())

# Background colors
print(BColor.green() + "Green background" + Color.reset())

# Hex colors (supports #rrggbb)
print(Color.hex('#ff69b4') + "Pink text" + Color.reset())
print(BColor.hex('#00ffff') + "Cyan background" + Color.reset())

# Text styling
print(Style.bold() + "Bold text" + Color.reset())
print(Style.italic() + "Italic text" + Color.reset())

# Combine it all
print(Style.bold() + Color.hex('#ff69b4') + "Bold Pink!" + Color.reset())
```

## Features

- ⚡ Pure C implementation for speed
- 🎨 **Hex colors** with `#rrggbb` format
- 🌈 **RGB colors** with 0-255 values
- 🎭 **HSL colors** with proper color space conversion
- 📝 **40+ text styles** (bold, italic, underline, blink, invert, framed, and more)
- 🎯 **Foreground and background** color support
- 🚀 **Zero dependencies** (pure C extension)
- 📦 **Python 3.6+** compatible

## Color Support

### Foreground Colors (Text)

```python
from chromaconsole import Color

# Basic colors (8 colors)
Color.black(), Color.red(), Color.green(), Color.yellow()
Color.blue(), Color.magenta(), Color.cyan(), Color.white()

# Bright colors (8 colors)
Color.bright_black(), Color.bright_red(), Color.bright_green(), Color.bright_yellow()
Color.bright_blue(), Color.bright_magenta(), Color.bright_cyan(), Color.bright_white()

# Custom colors
Color.hex('#ff69b4')        # Hex color
Color.rgb(255, 127, 80)     # RGB (0-255 each)
Color.hsl(30, 1.0, 0.5)     # HSL (H: 0-360, S: 0-1, L: 0-1)

# Special
Color.default()             # Terminal default
Color.reset()               # Reset all colors/styles
```

### Background Colors

```python
from chromaconsole import BColor

# Basic backgrounds (8 colors)
BColor.black(), BColor.red(), BColor.green(), BColor.yellow()
BColor.blue(), BColor.magenta(), BColor.cyan(), BColor.white()

# Bright backgrounds (8 colors)
BColor.bright_black(), BColor.bright_red(), BColor.bright_green(), BColor.bright_yellow()
BColor.bright_blue(), BColor.bright_magenta(), BColor.bright_cyan(), BColor.bright_white()

# Custom backgrounds
BColor.hex('#ff69b4')       # Hex background color
BColor.rgb(255, 127, 80)    # RGB background (0-255 each)
BColor.hsl(30, 1.0, 0.5)    # HSL background

# Special
BColor.default()            # Terminal default background
```

### Text Styles

```python
from chromaconsole import Style

# Basic styles
Style.bold()                    # Bold/bright text
Style.dim()                     # Dim/faint text
Style.italic()                  # Italic text
Style.underlined()              # Underlined text
Style.slowblink()               # Slow blink (5/sec)
Style.rapidblink()              # Rapid blink (150+/sec)

# Effects
Style.invert()                  # Swap foreground/background
Style.hidden()                  # Conceal text
Style.strikethrough()           # Strikethrough text

# Fonts (0-19, terminal dependent)
Style.default_font()            # Font 0 (default)
Style.alternative_font(1)       # Fonts 1-9
Style.fraktur()                 # Fraktur (Gothic) font

# Framing/Encircling
Style.framed()                  # Box drawing (if supported)
Style.encircled()               # Surrounded by circle
Style.overlined()               # Line above text

# Script styles
Style.superscript()             # Superscript text
Style.subscript()               # Subscript text

# Negation/Reset styles
Style.not_bold()                # Disable bold
Style.not_italic()              # Disable italic
Style.not_underlined()          # Disable underline
Style.not_blink()               # Disable blink
Style.not_reversed()            # Disable invert
Style.not_crossed_out()         # Disable strikethrough
Style.not_overlined()           # Disable overline

# Meta
Style.reset()                   # Reset all styles
```

## Examples

### Basic Colors and Styles

```python
from chromaconsole import Color, BColor, Style

# Simple colored output
print(Color.red() + "Error!" + Color.reset())
print(Color.green() + "Success!" + Color.reset())

# Background colors
print(BColor.yellow() + Color.black() + "Warning" + Color.reset())

# Styled text
print(Style.bold() + "Important" + Color.reset())
print(Style.italic() + "Emphasized" + Color.reset())
```

### Hex, RGB, and HSL Colors

```python
# Hex colors
print(Color.hex('#ff69b4') + "Pink" + Color.reset())
print(BColor.hex('#00ffff') + "Cyan BG" + Color.reset())

# RGB colors (0-255)
print(Color.rgb(255, 100, 150) + "Custom RGB" + Color.reset())
print(BColor.rgb(100, 150, 255) + "Blue BG" + Color.reset())

# HSL colors (H: 0-360, S: 0-1, L: 0-1)
print(Color.hsl(0, 1.0, 0.5) + "Pure Red" + Color.reset())
print(Color.hsl(120, 0.6, 0.4) + "Forest Green" + Color.reset())
```

### Combined Foreground + Background + Styles

```python
# All together
text = Style.bold() + Color.hex('#ff69b4') + BColor.hex('#000000') + "Bold Pink on Black!" + Color.reset()
print(text)

# Layered styles
text = Style.bold() + Style.italic() + Color.red() + "Bold Italic Red!" + Color.reset()
print(text)
```

### Logging Example

```python
def log_info(msg):
    print(f"[{Color.blue()}INFO{Color.reset()}] {msg}")

def log_error(msg):
    print(f"[{Color.red()}ERROR{Color.reset()}] {msg}")

def log_success(msg):
    print(f"[{Color.green()}✓{Color.reset()}] {msg}")

log_info("Starting...")
log_success("Connected")
log_error("Failed!")
```

## API Reference

### Color Class

Methods return ANSI escape sequences for text colors.

- **Hex**: `Color.hex(color: str) -> str` - e.g., `Color.hex('#ff69b4')`
- **RGB**: `Color.rgb(r: int, g: int, b: int) -> str` - values 0-255
- **HSL**: `Color.hsl(h: float, s: float, l: float) -> str` - h: 0-360, s: 0-1, l: 0-1
- **Basic colors**: `Color.black()`, `Color.red()`, `Color.green()`, `Color.yellow()`, `Color.blue()`, `Color.magenta()`, `Color.cyan()`, `Color.white()`
- **Bright colors**: `Color.bright_black()`, `Color.bright_red()`, ... (8 colors)
- **Special**: `Color.default()`, `Color.reset()`

### BColor Class (Background)

Methods return ANSI escape sequences for background colors. Identical API to Color class:

- **Hex**: `BColor.hex(color: str) -> str`
- **RGB**: `BColor.rgb(r: int, g: int, b: int) -> str`
- **HSL**: `BColor.hsl(h: float, s: float, l: float) -> str`
- **Basic backgrounds**: 8 colors like BColor
- **Bright backgrounds**: 8 bright colors
- **Special**: `BColor.default()`

### Style Class

Methods return ANSI escape sequences for text styles. All return strings that can be concatenated.

- **Core**: `bold()`, `dim()`, `italic()`, `underlined()`, `slowblink()`, `rapidblink()`, `invert()`, `hidden()`, `strikethrough()`
- **Fonts**: `default_font()`, `alternative_font(n)`, `fraktur()`
- **Framing**: `framed()`, `encircled()`, `overlined()`, `neither_framed_nor_encircled()`, `not_overlined()`
- **Script**: `superscript()`, `subscript()`, `neither_superscript_nor_subscript()`
- **Negations**: `not_bold()`, `normal_intensity()`, `not_italic()`, `not_underlined()`, `not_blink()`, `proportional_spacing()`, `not_reversed()`, `reveal()`, `not_crossed_out()`, `not_proportional_spacing()`
- **Meta**: `reset()`

### Module Functions

#### `ccprint(text: str, color: str = None) -> None`

Print text with optional hex color.

```python
from chromaconsole import ccprint
ccprint('Colored!', color='#ff69b4')
```

## Technical Details

### Architecture

- **C Core** (`chromaconsole_module.c`): 85+ functions generating ANSI escape codes
- **Helper Functions** (`include/common.h`): Reusable color conversion utilities
  - `hex_to_ansi()` - Parse hex colors and generate ANSI codes
  - `rgb_to_ansi()` - Convert RGB to ANSI escape sequences
  - `hsl_to_ansi()` - Convert HSL to RGB to ANSI with full color space math
  - `get_ansi_code()` - Format simple ANSI codes
- **Color Functions** (`include/colors.h`): 48 color and background functions
- **Style Functions** (`include/styles.h`): 40+ text styling functions
- **Python Wrapper** (`chromaconsole/__init__.py`): Classes providing Pythonic API

### Color Space Conversions

- **Hex**: Direct parsing of `#rrggbb` format via `sscanf`
- **RGB**: 24-bit ANSI codes via `\x1b[38;2;R;G;Bm` (foreground) or `\x1b[48;2;R;G;Bm` (background)
- **HSL**: Full HSL-to-RGB conversion with chroma/lightness calculations, then to ANSI

### Build System

- **Setuptools** with C extension support
- **Compiler**: MSVC (Windows), GCC/Clang (Unix)
- **Dependencies**: Python.h only (C89/C99)
- **No external libraries**: Uses standard C library only

### Distribution

- **Wheels** (.whl): Pre-compiled binaries, no compilation on install, headers not included
- **Source** (.tar.gz): Full source with headers via MANIFEST.in, user compiles on install

## Performance

Benchmark estimates (rough, varies by terminal):
- Color function calls: < 1µs (direct C constant returns)
- Hex parsing: 1-2µs (single sscanf call)
- RGB to ANSI: < 1µs (simple formatting)
- HSL to ANSI: 5-10µs (color space math, still fast)

Pure Python alternatives typically run 10-100x slower.

## Compatibility

- **Python**: 3.6+ (f-strings used)
- **Terminals**: Any with ANSI escape code support (xterm, Windows 10+, macOS Terminal, etc.)
- **Operating Systems**: Windows, macOS, Linux, Unix

### Windows Note

Windows 10+ natively supports ANSI codes. Older Windows versions may need configuration.

## License

MIT License - See LICENSE file

## Contributing

Contributions welcome! Potential areas:
- Additional color models (CMYK, etc.)
- Terminal capability detection
- Fallback palettes for limited terminals
- Performance profiling and optimization
- Cross-platform testing

## Changelog

### v1.0.0
- ✨ C extension core with 85+ functions
- 🎨 Hex, RGB, and HSL color support
- 🎭 40+ text styling functions
- 📝 Foreground and background colors
- ⚙️ Underline color support
- 🚀 Zero dependencies

