🚀 Quick Start

Get colorful terminal output in 3 simple commands:

# 1. Install or upgrade Rcolor from PyPI
pip install -U Rcolor

# 2. Print an automatically optimized random colorful message
python -c "import Rcolor; print(Rcolor.auto_fg('✨ Hello Beautiful Terminal! ✨'))"

# 3. Print per-character rainbow output
python -c "import Rcolor; print(Rcolor.rainbow_fg('🌈 Dynamic Rainbow Console Output'))"

✨ Key Features

🖥️ Terminal Compatibility Matrix

Rcolor automatically detects console capabilities and delivers optimal rendering:

🧬 Detection & Downgrading Architecture

The ASCII diagram below illustrates how Rcolor determines color capabilities and renders output:

               +----------------------------------+
               |  User calls Rcolor function     |
               |  (e.g., auto_fg, foreground)    |
               +-----------------+----------------+
                                 |
                                 v
               +----------------------------------+
               | Check NO_COLOR or stdout != TTY  |
               +-----------------+----------------+
                                / \
                        YES    /   \   NO
               +--------------+     +-------------------+
               | Return plain |     | Check FORCE_COLOR |
               | text string  |     | or COLORTERM/TERM |
               +--------------+     +---------+---------+
                                              |
                   +--------------------------+--------------------------+
                   |                          |                          |
                   v                          v                          v
          [ TrueColor / 256 ]            [ 16-Color ]             [ Dumb / None ]
                   |                          |                          |
        +----------+----------+     +---------+----------+      +--------+---------+
        | Use 256-color code  |     | Map 256 color to   |      | Output plain     |
        | (\033[38;5;{id}m)   |     | nearest ANSI 16 via|      | string without   |
        |                     |     | RGB Euclidean dist |      | ANSI escapes     |
        +----------+----------+     +---------+----------+      +--------+---------+
                   |                          |                          |
                   +--------------------------+--------------------------+
                                              |
                                              v
                              +-------------------------------+
                              | Append clean '\033[0m' reset  |
                              +-------------------------------+

⚡ Benchmarks

Benchmarks measured on Python 3.14 comparing Rcolor v3.0.1 (legacy) vs Rcolor v3.1.0 (current):

To reproduce these measurements locally:

python benchmarks/bench.py

📖 Usage Guide

1. Basic Importing

import Rcolor

# Or import specific functions
from Rcolor import (
    foreground,
    background,
    style,
    rainbow_fg,
    standard_fg,
    standard_bg,
    standard_rainbow_fg,
    auto_fg,
    auto_bg,
    foreground_background,
    foreground_style,
    background_style,
    foreground_background_style,
)

2. Automatic Terminal-Aware Colors (auto_fg / auto_bg)

Recommended for general use. Chooses 256-color when available, standard 16-color on restricted consoles, and plain text in non-TTY environments:

import Rcolor

# Automatically styled foreground
print(Rcolor.auto_fg("This text adapts to your terminal capabilities!"))

# Automatically styled background
print(Rcolor.auto_bg("Highlighted text with automatic color selection!"))

3. Extended 256-Color Palette (foreground / background)

Applies a random color from the complete 256-color palette. If executed on a 16-color terminal, Rcolor automatically downsamples to the closest ANSI color:

# Random 256 foreground color
print(Rcolor.foreground("Vibrant 256-color foreground"))

# Random 256 background color
print(Rcolor.background("Vibrant 256-color background"))

4. Standard 16-Color Palette (standard_fg / standard_bg)

Guaranteed compatibility with all legacy ANSI terminals:

# Standard 16 ANSI foreground
print(Rcolor.standard_fg("Standard ANSI foreground color"))

# Standard 16 ANSI background
print(Rcolor.standard_bg("Standard ANSI background color"))

5. Font Styles (style)

Applies ANSI text attributes such as bold, dim, italic, and underline:

# Random text style
print(Rcolor.style("Bold, dim, italic, or underlined text!"))

6. Per-Character Rainbow Effects (rainbow_fg / standard_rainbow_fg)

Colorizes every character in the string individually:

# 256-color rainbow (with auto-downgrade)
print(Rcolor.rainbow_fg("Every single character has a unique random color!"))

# Standard 16-color rainbow
print(Rcolor.standard_rainbow_fg("Standard 16-color rainbow string!"))

7. Composite Styling & Readability Contrast Guard

Apply multiple ANSI attributes simultaneously. foreground_background automatically enforces a Contrast Guard based on WCAG 2.1 relative luminance, ensuring the foreground is always crisp and readable against the chosen background:

# Guaranteed readable foreground on background (min_contrast default is 4.0)
print(Rcolor.foreground_background("Always readable text!"))

# Customize contrast ratio (e.g. 7.0:1 for high contrast)
print(Rcolor.foreground_background("High contrast banner", min_contrast=7.0))

# Foreground + Font Style
print(Rcolor.foreground_style("Random foreground AND font style"))

# Background + Font Style
print(Rcolor.background_style("Random background AND font style"))

# Foreground + Background + Font Style with Contrast Guard
print(Rcolor.foreground_background_style("Full composite random styling!"))

8. Curated Tone Presets (neon, pastel, warm, cool)

Instead of pure white-noise randomness, style your console with cohesive aesthetic color themes:

# Vibrant electric neon tones
print(Rcolor.foreground("Neon cyan, lime, magenta & electric orange", tone="neon"))

# Soft, elegant pastel tones
print(Rcolor.foreground("Soft lavender, mint, pastel pink & baby blue", tone="pastel"))

# Warm sunset and amber tones
print(Rcolor.foreground("Rich red, orange, gold & amber tones", tone="warm"))

# Cool ocean and frost tones
print(Rcolor.foreground("Deep blue, cyan, teal & sapphire tones", tone="cool"))

# Tone presets work with auto_fg, auto_bg, and background too:
print(Rcolor.auto_fg("Automated neon theme", tone="neon"))
print(Rcolor.background("Pastel card background", tone="pastel"))

9. Smooth Linear Gradients & Multi-Stop Rainbow

Generate seamless character-by-character color transitions with TrueColor depth and automatic terminal fallback:

# 2-stop gradient from hex colors
print(Rcolor.gradient_fg("Smooth cyberpunk transition!", start="#ff007f", end="#00f0ff"))

# 2-stop gradient from RGB tuples
print(Rcolor.gradient_fg("Deep blue into lime green", start=(0, 0, 255), end=(0, 255, 0)))

# Built-in multi-stop presets: 'rainbow', 'neon', 'sunset', 'warm', 'cool', 'pastel', 'cyberpunk', 'ocean'
print(Rcolor.gradient_fg("Sunset horizon across characters", preset="sunset"))
print(Rcolor.gradient_fg("Electric cyberpunk aesthetic", preset="cyberpunk"))

# Instant smooth multi-stop rainbow text
print(Rcolor.gradient_rainbow("A gorgeous smooth rainbow gradient banner across your terminal!"))

10. ANSI Strip Utility (strip_color)

Cleanly calculate visible string lengths and align formatted CLI tables or progress boxes:

colored_banner = Rcolor.gradient_rainbow("Hello World")

# Strip ANSI codes for clean length measurement
plain_banner = Rcolor.strip_color(colored_banner)
print(len(plain_banner))  # Correctly prints 11, ignoring escape sequences!

🎨 Custom Palette Support

You can supply custom palettes at runtime using Rcolor.load_palette().

JSON Schema

Custom palettes must adhere to the following schema:

{
  "schema_version": 1,
  "standard": [
    {
      "id": 0,
      "name": "brand_blue",
      "fg": 34,
      "bg": 44,
      "rgb": [0, 102, 204],
      "hex": "#0066cc"
    }
  ],
  "extended": [
    {
      "id": 33,
      "name": "brand_accent",
      "rgb": [0, 153, 255],
      "hex": "#0099ff"
    }
  ],
  "styles": {
    "bold": 1,
    "underline": 4
  }
}

Loading a Custom Palette in Python

import Rcolor

# Load palette from a JSON file
Rcolor.load_palette("my_brand_palette.json")

# Or load from an in-memory dictionary
Rcolor.load_palette({
    "schema_version": 1,
    "standard": [{"id": 0, "name": "primary", "fg": 32, "bg": 42}],
    "extended": [{"id": 46, "name": "bright_green"}],
    "styles": {"bold": 1}
})

# Reset back to default built-in palette at any time
Rcolor.reset_palette()

print(Rcolor.foreground("Styled with custom palette!"))

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "RcolorPalette",
  "type": "object",
  "required": ["schema_version", "standard", "extended", "styles"],
  "properties": {
    "schema_version": { "type": "integer", "enum": [1] },
    "standard": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id", "name", "fg", "bg"],
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "fg": { "type": "integer" },
          "bg": { "type": "integer" },
          "rgb": { "type": "array", "items": { "type": "integer" } },
          "hex": { "type": "string" }
        }
      }
    },
    "extended": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id"],
        "properties": {
          "id": { "type": "integer", "minimum": 0, "maximum": 255 },
          "name": { "type": "string" },
          "rgb": { "type": "array", "items": { "type": "integer" } },
          "hex": { "type": "string" }
        }
      }
    },
    "styles": {
      "type": "object",
      "additionalProperties": { "type": "integer" }
    }
  }
}

📚 API Reference

🔍 Troubleshooting

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository on GitHub.
2. Create a branch:

   git checkout -b feature/my-feature
   

3. Install development dependencies:

   pip install -e .[dev]
   

4. Run the test suite:

   python -m unittest discover tests
   # or
   pytest
   

5. Run the benchmark:

   python benchmarks/bench.py
   

6. Commit & Push your changes, then submit a Pull Request.

python -m unittest discover tests

pytest -v

ruff check .
flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics

📷 Visual Assets Required

To complete the visual presentation in the README, please create and place the following image assets into docs/images/:

📄 License

This project is licensed under the terms of the MIT License.