tessl/pypi-hues

Colored terminal text made easy for Python and happiness.

—

Pending

Overview

Eval results

Files

Color and Style Optimization

Name: tessl/pypi-hues
Author: tessl

Low-level optimization functions for processing color stacks using deterministic push-down automaton algorithms. These functions are used internally by HueString to minimize ANSI escape sequences while maintaining visual consistency and preventing terminal color pollution.

Capabilities

String Colorization

Apply optimized ANSI escape sequences to a string based on a color/style stack.

def colorize(string: str, stack: tuple) -> str:
    """
    Apply optimal ANSI escape sequences to the string.
    
    Args:
        string (str): The text to colorize
        stack (tuple): Tuple of color/style codes to apply
        
    Returns:
        str: String with ANSI escape sequences applied, or original string if no codes
    """

Usage:

from hues.huestr import colorize
from hues.colortable import FG, BG, STYLE

# Apply red foreground and black background
result = colorize('Hello', (FG.red, BG.black))
print(result)  # \033[31;40mHello\033[0m

Reset Handling

Handle reset codes in color stacks, breaking the stack when a reset (zero) is encountered.

def zero_break(stack: tuple) -> tuple:
    """
    Handle Resets in input stack.
    Breaks the input stack if a Reset operator (zero) is encountered.
    
    Args:
        stack (tuple): Input stack of color/style codes
        
    Returns:
        tuple: Stack with everything before reset removed
    """

Usage:

from hues.dpda import zero_break
from hues.colortable import FG, STYLE

# Reset clears previous styles
stack = (FG.red, FG.blue, STYLE.reset, FG.green)
result = zero_break(stack)
print(result)  # (32,) - only green remains

Color Squashing

Remove duplicate colors of the same type, keeping only the last occurrence.

def annihilate(predicate: tuple, stack: tuple) -> tuple:
    """
    Squash and reduce the input stack.
    Removes elements matching predicate, keeping only the last match.
    
    Args:
        predicate (tuple): Tuple of codes to match and squash
        stack (tuple): Input stack of color/style codes
        
    Returns:
        tuple: Stack with duplicates removed, last match preserved
    """

def annihilator(predicate: tuple):
    """
    Build a partial annihilator for given predicate.
    
    Args:
        predicate (tuple): Codes to create annihilator for
        
    Returns:
        function: Partial function for annihilating those codes
    """

Usage:

from hues.dpda import annihilate, annihilator
from hues.colortable import FG

# Remove duplicate foreground colors, keep last
stack = (FG.red, FG.blue, FG.green)
result = annihilate(FG, stack)
print(result)  # (32,) - only green remains

# Create reusable annihilator
fg_annihilator = annihilator(FG)
result = fg_annihilator(stack)

Deduplication

Remove duplicate style codes while preserving order.

def dedup(stack: tuple) -> tuple:
    """
    Remove duplicates from the stack in first-seen order.
    
    Args:
        stack (tuple): Input stack of color/style codes
        
    Returns:
        tuple: Stack with duplicates removed, first occurrence kept
    """

Usage:

from hues.dpda import dedup
from hues.colortable import STYLE

# Remove duplicate styles
stack = (STYLE.bold, STYLE.italic, STYLE.bold, STYLE.underline)
result = dedup(stack)
print(result)  # (1, 3, 4) - bold appears only once

Function Application

Apply a sequence of optimization functions to a stack.

def apply(funcs: tuple, stack: tuple) -> tuple:
    """
    Apply functions to the stack, passing result to next function.
    
    Args:
        funcs (tuple): Tuple of functions to apply in sequence
        stack (tuple): Initial stack to process
        
    Returns:
        tuple: Final processed stack
    """

Usage:

from hues.dpda import apply, zero_break, dedup
from hues.colortable import FG, STYLE

# Apply multiple optimization steps
stack = (FG.red, STYLE.bold, STYLE.reset, FG.blue, STYLE.bold)
optimizations = (zero_break, dedup)
result = apply(optimizations, stack)
print(result)  # (34, 1) - blue and bold after reset

Optimization Pipeline

HueString uses a standard optimization pipeline to process color stacks:

zero_break: Handle reset codes, clearing previous styles
annihilator(FG + HI_FG): Squash foreground colors to last value
annihilator(BG + HI_BG): Squash background colors to last value
dedup: Remove duplicate style values

This ensures minimal ANSI sequences while maintaining the intended appearance:

from functools import partial
from hues.dpda import zero_break, annihilator, dedup, apply
from hues.colortable import FG, BG, HI_FG, HI_BG

OPTIMIZATION_STEPS = (
    zero_break,
    annihilator(FG + HI_FG),
    annihilator(BG + HI_BG), 
    dedup,
)
optimize = partial(apply, OPTIMIZATION_STEPS)

# This is how HueString optimizes color stacks
optimized = optimize((FG.red, FG.blue, BG.white, STYLE.bold, STYLE.bold))

Install with Tessl CLI