chromaconsole

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

Install

pip install chromaconsole

Quick Start

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)

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

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

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

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

# 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

# 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

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.

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