String Coloring

Chainable API for creating colored terminal text with ANSI escape sequences. The HueString class extends Python's built-in string class to support color and style attributes that can be chained together.

Capabilities

HueString Creation

Create colored strings using the huestr class (alias for HueString). Strings can be chained with color, background, and style attributes.

class huestr(str):
    """
    String class with chainable color and style attributes.
    
    Args:
        string (str): The text content
        hue_stack (tuple, optional): Internal color/style stack
    """
    def __init__(self, string: str, hue_stack: tuple = tuple()): ...

Usage:

from hues import huestr

# Create a colored string
text = huestr('Hello World')
colored = text.red.bold.bg_yellow

Color Rendering

Convert the styled string to ANSI-escaped text for terminal output.

@property
def colorized(self) -> str:
    """
    Returns the string with ANSI escape sequences applied.
    
    Returns:
        str: ANSI-escaped string ready for terminal output
    """

Usage:

colored_text = huestr('Warning').yellow.bold
print(colored_text.colorized)  # Outputs: \033[1;33mWarning\033[0m

Low-Level Color Functions

Direct colorization functions for advanced usage.

def colorize(string: str, stack: tuple) -> str:
    """
    Apply optimal ANSI escape sequences to a string.
    
    Args:
        string (str): Text to colorize
        stack (tuple): Stack of color/style codes
        
    Returns:
        str: ANSI-escaped string
    """

Dynamic Color Attributes

All color and style attributes are available as chainable properties on HueString instances:

Foreground Colors

• black, red, green, yellow, blue, magenta, cyan, white

Background Colors

• bg_black, bg_red, bg_green, bg_yellow, bg_blue, bg_magenta, bg_cyan, bg_white

Bright Foreground Colors

• bright_black, bright_red, bright_green, bright_yellow, bright_blue, bright_magenta, bright_cyan, bright_white

Bright Background Colors

• bg_bright_black, bg_bright_red, bg_bright_green, bg_bright_yellow, bg_bright_blue, bg_bright_magenta, bg_bright_cyan, bg_bright_white

Text Styles

• reset - Reset all formatting
• bold - Bold text
• italic - Italic text
• underline - Underlined text
• defaultfg - Default foreground color
• defaultbg - Default background color

Usage Examples

Basic Coloring

from hues import huestr

# Simple color
text = huestr('Success').green
print(text.colorized)

# Color with background
text = huestr('Error').red.bg_white
print(text.colorized)

Style Chaining

# Multiple styles can be chained in any order
text = huestr('Important').bold.red.bg_yellow.underline
print(text.colorized)

# Order doesn't matter due to optimization
text1 = huestr('Test').red.bold.green  # green overrides red
text2 = huestr('Test').bold.green.red  # red overrides green

Reset Handling

# Reset clears all previous styles
text = huestr('Mixed').red.bold.reset.blue
print(text.colorized)  # Only blue is applied

Optimization

Hues uses a push-down automaton to optimize color sequences:

1. Reset Handling: reset breaks the chain, clearing all previous styles
2. Color Squashing: Multiple foreground/background colors are reduced to the last one
3. Deduplication: Duplicate style codes are removed
4. Self-Closing: All strings automatically reset at the end to prevent color pollution

This ensures minimal ANSI escape sequences while maintaining the desired appearance.