chromaforge 1.0.1

Advanced terminal coloring library for Python - Beyond colorama and rich

ChromaForge

Advanced Terminal Coloring for Python - A modern, feature-rich terminal styling library that goes beyond colorama and rich.

Features

• True Color (24-bit RGB) - Full RGB color support for modern terminals
• Chainable API - Fluent interface for easy style composition
• Gradients - Beautiful text gradients with 12+ presets
• Animations - Typing effects, spinners, progress bars, and more
• UI Components - Boxes, tables, panels, and rules
• ANSI-Aware String Handling - Proper truncation, wrapping, and alignment
• Themes - 10 built-in themes including Monokai, Dracula, Nord
• Zero Dependencies - Pure Python, no external dependencies
• Cross-Platform - Windows, macOS, and Linux support

Installation

pip install chromaforge

Quick Start

from chromaforge import forge

# Simple colored text
print(forge("Hello World").red().bold())

# RGB colors
print(forge("Custom Color").rgb(255, 100, 50))

# Hex colors
print(forge("Hex Color").hex("#ff6b6b"))

# Chained styles
print(forge("Styled Text").blue().bold().underline().on_white())

# Gradients
print(forge("Rainbow Text").rainbow())

The Forge API

The forge() function is the main entry point for styling text:

from chromaforge import forge

# Basic colors
forge("Text").black()
forge("Text").red()
forge("Text").green()
forge("Text").yellow()
forge("Text").blue()
forge("Text").magenta()
forge("Text").cyan()
forge("Text").white()

# Bright colors
forge("Text").bright_red()
forge("Text").bright_green()
# ... and more

# Background colors
forge("Text").on_red()
forge("Text").on_blue()
forge("Text").on_rgb(50, 50, 50)

# Styles
forge("Text").bold()
forge("Text").dim()
forge("Text").italic()
forge("Text").underline()
forge("Text").strikethrough()
forge("Text").reverse()
forge("Text").blink()

# Chain everything
print(forge("Important!").red().bold().underline().on_yellow())

RGB, HSL, and Hex Colors

from chromaforge import forge, RGB, HSL, HEX

# RGB (0-255)
print(forge("RGB Color").rgb(255, 128, 64))

# HSL (hue: 0-360, saturation: 0-100, lightness: 0-100)
print(forge("HSL Color").hsl(180, 100, 50))

# Hex colors
print(forge("Hex Color").hex("#ff6b6b"))
print(forge("Short Hex").hex("#f66"))

# Background colors
print(forge("BG Color").on_rgb(30, 30, 50))
print(forge("BG Hex").on_hex("#1a1a2e"))

# Color objects
color = RGB(100, 200, 150)
print(f"RGB: {color.r}, {color.g}, {color.b}")
print(f"As Hex: {color.to_hex()}")
print(f"As HSL: {color.to_hsl()}")

# Color manipulation
lighter = color.lighten(0.2)
darker = color.darken(0.2)
blended = color.blend(RGB(255, 0, 0), 0.5)

Gradients

from chromaforge import forge, gradient, Gradient, rainbow, fire, ocean, sunset, neon

# Preset gradients
print(rainbow("Rainbow gradient text!"))
print(fire("Fire gradient text!"))
print(ocean("Ocean gradient text!"))
print(sunset("Sunset gradient text!"))
print(neon("Neon gradient text!"))

# Custom two-color gradient
print(gradient("Custom gradient", "#ff0000", "#0000ff"))

# Multi-color gradient
grad = Gradient(["#ff0000", "#ffff00", "#00ff00", "#0000ff"])
print(grad.apply("Multi-color gradient text"))

# Using forge
print(forge("Gradient").gradient("#ff6b6b", "#4ecdc4"))

Available Gradient Presets

Preset	Description
rainbow	Classic rainbow colors
fire	Yellow to red to dark red
ocean	Cyan to deep blue
forest	Light to dark green
sunset	Gold to purple
neon	Magenta, cyan, yellow cycle
pastel	Soft pastel colors
matrix	Green terminal style
synthwave	Pink, purple, blue
autumn	Gold, orange, brown
ice	White to blue
candy	Pink, white, green, blue

Styles

from chromaforge import Style, StyleBuilder

# Define reusable styles
error_style = Style(fg="red", bold=True)
warning_style = Style(fg="yellow", italic=True)
success_style = Style(fg="#00ff00", bold=True)

print(error_style("Error: Something went wrong!"))
print(warning_style("Warning: Check your input"))
print(success_style("Success: Operation completed"))

# Using StyleBuilder
style = (StyleBuilder()
    .foreground("#ff6b6b")
    .background("#2d2d2d")
    .bold()
    .underline()
    .build())

print(style("Styled with builder"))

# Combine styles
combined = error_style.combine(Style(underline=True))
print(combined("Combined style"))

UI Components

Box

from chromaforge import Box

# Simple box
box = Box("Hello World", style="rounded", color="cyan")
print(box)

# Box with title
box = Box(
    ["Line 1", "Line 2", "Line 3"],
    title="My Box",
    style="double",
    color="yellow"
)
print(box)

Box Styles: single, double, rounded, bold, ascii

Table

from chromaforge import Table

table = Table(
    headers=["Name", "Age", "City"],
    rows=[
        ["Alice", "30", "New York"],
        ["Bob", "25", "Los Angeles"],
        ["Charlie", "35", "Chicago"],
    ],
    style="rounded",
    color="cyan"
)
print(table)

Progress Bar

from chromaforge import Progress
import time

progress = Progress(total=100, width=40, show_percent=True)
for i in range(101):
    progress.update(i)
    time.sleep(0.02)
progress.finish("Complete!")

Spinner

from chromaforge import Spinner
import time

# As context manager
with Spinner("Loading", style="dots", color="cyan") as spinner:
    time.sleep(3)
spinner.stop("Done!")

# Manual control
spinner = Spinner("Processing", style="moon")
spinner.start()
time.sleep(2)
spinner.stop("Finished!")

Spinner Styles: dots, line, circle, square, arrow, bounce, pulse, dots2, moon, clock

Panel

from chromaforge import Panel

panel = Panel(
    "This is important information that you should read.",
    title="Notice",
    subtitle="v1.0",
    border_color="yellow",
    style="rounded"
)
print(panel)

Rule (Divider)

from chromaforge import Rule

print(Rule("Section Title", color="cyan"))
print(Rule(style="double"))
print(Rule("Left Aligned", align="left"))

Columns

from chromaforge import Columns

cols = Columns(
    ["Item 1", "Item 2", "Item 3", "Item 4", "Item 5", "Item 6"],
    num_columns=3,
    padding=4
)
print(cols)

Effects & Animations

from chromaforge import typing, pulse, shimmer, glitch
from chromaforge.core import RGB

# Typewriter effect
typing("Hello, World!", delay=0.05, color="green")

# Pulsing text
pulse("ALERT!", duration=3.0, color=RGB(255, 0, 0))

# Shimmering rainbow
shimmer("Sparkle!", duration=5.0)

# Glitch effect
glitch("ERROR 404", duration=2.0, intensity=0.3)

More Effects

from chromaforge.effects import bounce, countdown, wave, loading_dots, matrix_rain

# Bouncing text
bounce("Ping!", width=40, duration=3.0)

# Countdown
countdown(5, "GO!", RGB(255, 0, 0), RGB(0, 255, 0))

# Wave animation
wave("Hello Wave!", duration=3.0, amplitude=2)

# Loading dots
loading_dots("Processing", duration=3.0)

# Matrix rain effect
matrix_rain(width=60, height=15, duration=10.0)

Themes

from chromaforge import Theme, set_theme, get_theme, THEMES, use_theme

# Use a built-in theme
use_theme("dracula")
theme = get_theme()

print(theme.primary_text("Primary color"))
print(theme.success_text("Success message"))
print(theme.error_text("Error message"))
print(theme.warning_text("Warning message"))

# Available themes
print(list(THEMES.keys()))
# ['default', 'monokai', 'dracula', 'nord', 'solarized_dark',
#  'gruvbox', 'ocean', 'forest', 'cyberpunk', 'sunset']

# Create custom theme
custom_theme = Theme(
    name="my_theme",
    primary=RGB(100, 200, 255),
    secondary=RGB(255, 100, 200),
    success=RGB(100, 255, 100),
    error=RGB(255, 100, 100),
)
set_theme(custom_theme)

Terminal Utilities

from chromaforge import (
    Terminal, clear, clear_line, move_cursor,
    hide_cursor, show_cursor, supports_color,
    supports_truecolor, get_terminal_size
)

# Check terminal capabilities
print(f"Color support: {supports_color()}")
print(f"True color: {supports_truecolor()}")
print(f"Size: {get_terminal_size()}")

# Terminal operations
term = Terminal()
term.clear()
term.move_to(10, 5)
term.set_title("My App")

# Fullscreen mode
with term.fullscreen():
    term.move_to(1, 1)
    print("Fullscreen mode!")
    input("Press Enter to exit...")

ANSI-Aware String Handling

ChromaForge properly handles ANSI escape sequences in string operations:

from chromaforge.terminal import ANSIString, truncate, wrap_text

# Create an ANSI string
text = "\033[31mHello\033[0m \033[32mWorld\033[0m"
s = ANSIString(text)

# Get visible length (ignoring ANSI codes)
print(s.visible_length())  # 11

# Truncate with proper ANSI handling
print(truncate(text, 8, "..."))  # Properly closes color codes

# Slice with ANSI preservation
print(s[0:5])  # Gets "Hello" with its red color intact

# Wrap text preserving colors
lines = wrap_text(text, 40)

# Center/justify with ANSI preservation
print(s.center(20))
print(s.ljust(20))
print(s.rjust(20))

Color Functions

from chromaforge import red, green, blue, yellow, rgb, hex_color
from chromaforge.colors import blend, lighten, darken, complement, grayscale, get_color

# Quick color functions
print(red("Red text"))
print(green("Green text"))
print(blue("Blue text"))

# RGB and Hex
print(rgb("Custom", 255, 128, 64))
print(hex_color("Hex color", "#ff6b6b"))

# Color manipulation
from chromaforge.core import RGB

color = RGB(100, 150, 200)
print(f"Original: {color}")
print(f"Lighter: {lighten(color, 0.3)}")
print(f"Darker: {darken(color, 0.3)}")
print(f"Complement: {complement(color)}")
print(f"Grayscale: {grayscale(color)}")

# Blend two colors
blended = blend(RGB(255, 0, 0), RGB(0, 0, 255), 0.5)
print(f"Blended: {blended}")  # Purple

# Named colors from palette
coral = get_color("coral")
turquoise = get_color("turquoise")

Comparison with Other Libraries

Feature	ChromaForge	Colorama	Rich
True Color (24-bit)	✅	❌	✅
Gradients	✅	❌	❌
Chainable API	✅	❌	❌
Animations	✅	❌	✅
ANSI-aware truncation	✅	❌	✅
Zero dependencies	✅	✅	❌
Themes	✅	❌	✅
HSL colors	✅	❌	❌
Color manipulation	✅	❌	❌

License

MIT License - see LICENSE for details.

Links

• GitHub: https://github.com/AeonLtd/chromaforge
• PyPI: https://pypi.org/project/chromaforge/
• Issues: https://github.com/AeonLtd/chromaforge/issues