khx_color_text

A comprehensive Python package for printing colored and styled text in the terminal with extensive customization options and cross-platform support.

🎉 Now available on PyPI! Install with: pip install khx_color_text

✨ Features

• 🎨 Multiple Color Formats: Predefined colors, hex codes (#FF0000), and RGB tuples (255, 0, 0)
• ✨ Text Styling: Bold, italic, underline, strikethrough, dim, and bright styles
• 🌈 Background Colors: Support for background colors in all color formats
• 🔧 Single API: One powerful cprint() function for all features
• 🖥️ Cross-platform: Works on Windows, macOS, and Linux
• 📦 Zero Dependencies: Uses only Python standard library and colorama
• 🎯 Type Safe: Full type hints and mypy support
• ⚡ CLI Tool: Feature-rich command-line interface
• 📏 Decorative Lines: Create beautiful terminal lines with cline() function
• 🔤 Character Names: IDE autocomplete support for 50+ line characters
• 📐 Auto-sizing: Automatic terminal width detection for perfect lines
• 📚 Rich Examples: Comprehensive documentation and examples

Installation

pip install khx_color_text

Quick Start

from khx_color_text import cprint, cline

# Basic colors
cprint("Hello, World!", "red")
cprint("Success message", "green")

# Hex colors
cprint("Custom orange", "#FF6B35")

# RGB colors
cprint("Custom purple", (138, 43, 226))

# With styling
cprint("Bold red text", "red", style="bold")
cprint("Multiple styles", "blue", style=["bold", "underline"])

# With background
cprint("Highlighted text", "white", bg_color="red")

# Complex combinations
cprint("Fancy text", "#00FF00", bg_color=(50, 50, 50), style=["bold", "italic"])

# NEW: Decorative lines
cline()  # Simple line filling terminal width
cline("*", color="#FF0000")  # Red asterisk line
cline("full_block", color="#00FF00")  # Green block line using character name
cline("wave_dash", width=50, color="#0000FF")  # Blue wave line with custom width

Color Support

Complete Color Palette

Basic Colors: red, green, blue, yellow, cyan, magenta, white, black
Bright Colors: bright_red, bright_green, bright_blue, bright_yellow, bright_cyan, bright_magenta, bright_white, bright_black
Aliases: orange, purple, pink, gray, grey

Bright Colors Example:

Hex Colors

• Hex Format: #FF0000, #f00 (3 or 6 digit hex)
• Full range: Any valid hex color supported

RGB Colors

• RGB Format: (255, 0, 0) (values 0-255)
• Precise control: 16.7 million colors available

Decorative Lines

NEW in v0.3.0: Create beautiful terminal lines with the cline() function!

from khx_color_text import cline

# Basic lines
cline()  # Fills entire terminal width
cline("*", color="#FF0000")  # Red asterisk line
cline("=", width=50, color="blue")  # Blue equals line, 50 chars wide

# Using character names (with IDE autocomplete!)
cline("full_block", color="#00FF00")  # █ Green block line
cline("wave_dash", color="#FF00FF")   # 〜 Purple wave line
cline("black_diamond", color="#FFFF00")  # ◆ Yellow diamond line
cline("infinity", color="#00FFFF")    # ∞ Cyan infinity line

# Advanced styling
cline("black_star", color="#FFD700", bg_color="#000080", style="bold")

Character Categories

• Basic ASCII: asterisk, dash, equals, underscore, etc.
• Unicode Box Drawing: horizontal, heavy_horizontal, double_horizontal
• Block Characters: full_block, dark_shade, medium_shade, light_shade
• Wave Patterns: tilde, wave_dash, almost_equal, triple_tilde
• Decorative: black_star, heart_suit, diamond_suit, black_diamond
• Geometric: black_up_triangle, black_down_triangle, black_left_pointer
• Mathematical: infinity, summation, integral, square_root

Features

• Auto-sizing: Lines automatically fill terminal width
• 50+ Characters: Extensive library of line characters
• IDE Support: Full autocomplete for character names
• Type Safe: Literal types for character names
• Flexible: Use direct characters or descriptive names

Text Styling

Available styles: bold, italic, underline, strikethrough, dim, bright

Style Combinations

Background Colors

# Single style
cprint("Bold text", "red", style="bold")

# Multiple styles
cprint("Bold and underlined", "blue", style=["bold", "underline"])

# Using TextStyle enum
from khx_color_text import TextStyle
cprint("Enum style", "green", style=TextStyle.BOLD)

CLI Usage

The package includes a powerful command-line tool khx-ct:

Advanced CLI Features

# Basic usage
khx-ct "Hello, World!" -c red

# Hex colors
khx-ct "Custom color" --hex "#FF6B35"

# RGB colors
khx-ct "RGB color" --rgb "255,107,53"

# With styling
khx-ct "Bold text" -c blue -s bold

# Multiple styles
khx-ct "Fancy text" -c green -s bold,underline

# With background
khx-ct "Highlighted" -c white --bg red

# Show examples
khx-ct --examples
khx-ct --advanced-examples
khx-ct --showcase

API Reference

cprint(text, color=None, bg_color=None, style=None, end="\n", sep=" ", file=None)

Print colored and styled text to the terminal.

Parameters:

• text (str): The text to print
• color (str | tuple, optional): Text color in various formats
• bg_color (str | tuple, optional): Background color
• style (str | list, optional): Text style(s)
• end (str): String appended after text (default: newline)
• sep (str): String between multiple arguments (default: space)
• file: File object to write to (default: sys.stdout)

cline(char="-", width=None, color=None, bg_color=None, style=None, fill_terminal=True)

NEW: Create decorative terminal lines with automatic width detection.

Parameters:

• char (str | CharacterName): Character to use or character name (default: "-")
• width (int, optional): Line width. If None, uses terminal width or 50
• color (str | tuple, optional): Text color in various formats
• bg_color (str | tuple, optional): Background color
• style (str | list, optional): Text style(s)
• fill_terminal (bool): Auto-fill terminal width when width is None (default: True)

Character Names: Full IDE autocomplete support for 50+ character names like:

• "asterisk" → *, "full_block" → █, "wave_dash" → 〜
• "infinity" → ∞, "black_star" → ★, "heart_suit" → ♥

Color Formats:

• Predefined: "red", "bright_green", "orange"
• Hex: "#FF0000", "#f00"
• RGB: (255, 0, 0)

Styles:

• Single: "bold", "italic", "underline"
• Multiple: ["bold", "underline"]
• Enum: TextStyle.BOLD

Examples

Comprehensive Usage Examples

Real-World Use Cases

Integration Examples

Error Handling

Basic Usage

Success Messages:

Error Messages:

Warning Messages:

Info Messages:

from khx_color_text import cprint

# Run basic examples
if __name__ == "__main__":
    cprint("Red text", "red")
    cprint("Green text", "green")
    cprint("Blue text", "blue")

Advanced Features

from khx_color_text import cprint, TextStyle

if __name__ == "__main__":
    # Hex colors
    cprint("Orange text", "#FF6B35")
    cprint("Purple text", "#8A2BE2")
    
    # RGB colors
    cprint("Custom red", (255, 0, 0))
    cprint("Custom blue", (0, 100, 200))
    
    # Styling
    cprint("Bold red", "red", style="bold")
    cprint("Italic blue", "blue", style="italic")
    cprint("Multiple styles", "green", style=["bold", "underline"])
    
    # Background colors
    cprint("White on red", "white", bg_color="red")
    cprint("Yellow on purple", "yellow", bg_color="#800080")
    
    # Complex combinations
    cprint("Ultimate text", "#00FF00", bg_color=(50, 50, 50), 
           style=[TextStyle.BOLD, TextStyle.ITALIC])

Installation & Quick Start

Feature Evolution

Testing

Run the test suite:

# Basic functionality tests
python tests/test_basic_functionality.py

# Advanced features tests  
python tests/test_advanced_features.py

# Color utility tests
python tests/test_color_utilities.py

How Previews Are Generated

The SVG previews above are generated using the scripts/gen_assets.py script. This script uses Rich Console to capture colored output and export it as SVG files. The previews are automatically regenerated on each push to the main branch via GitHub Actions.

To regenerate the previews locally:

pip install -e .[docs]
python scripts/gen_assets.py

Cross-Platform Support

This package uses colorama to ensure colored output works correctly on Windows, macOS, and Linux terminals.

Package Statistics

• PyPI: https://pypi.org/project/khx-color-text/
• Source Code: https://github.com/Khader-X/khx_color_text
• Documentation: https://khader-x.github.io/khx_color_text/
• Issues: https://github.com/Khader-X/khx_color_text/issues

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details.

Author

ABUELTAYEF Khader

• Email: abueltayef.khader@gmail.com
• GitHub Personal: @Khader20
• GitHub Organization: @Khader-X
• PyPI: Khader20