Hues

A Python library for colored terminal text output using ANSI escape sequences. Hues provides both chainable colored strings and console logging with configurable themes, featuring automatic optimization to prevent terminal color pollution.

Package Information

• Package Name: hues
• Language: Python
• Installation: pip install hues

Core Imports

import hues

For direct access to string coloring:

from hues import huestr

For low-level optimization functions:

from hues.huestr import colorize
from hues.dpda import zero_break, dedup, annihilator, apply

For color constants:

from hues.colortable import FG, BG, HI_FG, HI_BG, STYLE, KEYWORDS

Note: The original hues package documentation uses hue() in examples, but the actual implementation only exports huestr. Use huestr for all string coloring functionality.

Basic Usage

import hues

# Console logging with colored labels
hues.info('Application started successfully')
hues.warn('Low disk space detected')
hues.error('Failed to connect to database')
hues.success('Operation completed')

# Chainable colored strings
colored_text = hues.huestr('Hello World').red.bold.bg_yellow
print(colored_text.colorized)

# Direct console output
hues.console('Custom message with', ('colored part', hues.console.conf.hues.success))

Architecture

Hues is built around two main components:

• String Coloring: HueString class provides chainable color/style attributes with push-down automaton optimization
• Console Logging: Configurable console classes (SimpleConsole, PowerlineConsole) with themed output
• Configuration: YAML-based configuration system for colors, labels, and formatting options
• Optimization: Deterministic color stack optimization to minimize ANSI escape sequences

Capabilities

String Coloring

Chainable API for creating colored text with ANSI escape sequences. Supports all 16 ANSI colors, high-intensity variants, background colors, and text styles with automatic optimization.

class huestr(str):
    def __init__(self, string: str, hue_stack: tuple = tuple()): ...
    @property
    def colorized(self) -> str: ...
    # Dynamic color/style attributes: red, blue, bold, underline, etc.

__version__: tuple  # Version tuple (0, 2, 2)

String Coloring

Console Logging

Configurable console output with colored labels, timestamps, and themed formatting. Supports simple and powerline display themes with YAML configuration.

def log(*args, **kwargs): ...
def info(*args): ...
def warn(*args): ...
def error(*args): ...
def success(*args): ...

Console Logging

Color and Style Optimization

Low-level optimization functions for color stack processing using deterministic push-down automaton algorithms. These functions minimize ANSI escape sequences while maintaining visual consistency.

def colorize(string: str, stack: tuple) -> str: ...
def zero_break(stack: tuple) -> tuple: ...
def dedup(stack: tuple) -> tuple: ...
def annihilator(predicate: tuple): ...
def apply(funcs: tuple, stack: tuple): ...

Optimization Functions

Color and Style Constants

ANSI color code constants and keyword mappings for direct access to escape sequence values.

# Color constants
FG: namedtuple  # Foreground colors (30-37)
BG: namedtuple  # Background colors (40-47) 
HI_FG: namedtuple  # High intensity foreground (90-97)
HI_BG: namedtuple  # High intensity background (100-107)
STYLE: namedtuple  # Text style codes
KEYWORDS: namedtuple  # Combined keyword mapping

Color Constants

Available Colors and Styles

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 Colors: bright_black, bright_red, bright_green, bright_yellow, bright_blue, bright_magenta, bright_cyan, bright_white
Bright Backgrounds: bg_bright_black, bg_bright_red, bg_bright_green, bg_bright_yellow, bg_bright_blue, bg_bright_magenta, bg_bright_cyan, bg_bright_white
Styles: reset, bold, italic, underline

Configuration

Hues uses YAML configuration files (.hues.yml) loaded from:

1. Current working directory (recursive up to root)
2. User home directory
3. Package defaults

Example configuration:

hues:
  default: defaultfg
  time: magenta
  info: cyan
  success: green
  error: red
  warn: yellow
labels:
  info: INFO
  warn: WARNING
  error: ERROR
  success: SUCCESS
options:
  show_time: yes
  time_format: '%H:%M:%S'
  add_newline: yes
  theme: simple  # 'simple' or 'powerline'