0
# Hues
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: hues
7
- **Language**: Python
8
- **Installation**: `pip install hues`
9

10
## Core Imports
11

12
```python
13
import hues
14
```
15

16
For direct access to string coloring:
17

18
```python
19
from hues import huestr
20
```
21

22
For low-level optimization functions:
23

24
```python
25
from hues.huestr import colorize
26
from hues.dpda import zero_break, dedup, annihilator, apply
27
```
28

29
For color constants:
30

31
```python
32
from hues.colortable import FG, BG, HI_FG, HI_BG, STYLE, KEYWORDS
33
```
34

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

37
## Basic Usage
38

39
```python
40
import hues
41

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

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

52
# Direct console output
53
hues.console('Custom message with', ('colored part', hues.console.conf.hues.success))
54
```
55

56
## Architecture
57

58
Hues is built around two main components:
59

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

65
## Capabilities
66

67
### String Coloring
68

69
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.
70

71
```python { .api }
72
class huestr(str):
73
    def __init__(self, string: str, hue_stack: tuple = tuple()): ...
74
    @property
75
    def colorized(self) -> str: ...
76
    # Dynamic color/style attributes: red, blue, bold, underline, etc.
77

78
__version__: tuple  # Version tuple (0, 2, 2)
79
```
80

81
[String Coloring](./string-coloring.md)
82

83
### Console Logging
84

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

87
```python { .api }
88
def log(*args, **kwargs): ...
89
def info(*args): ...
90
def warn(*args): ...
91
def error(*args): ...
92
def success(*args): ...
93
```
94

95
[Console Logging](./console-logging.md)
96

97
### Color and Style Optimization
98

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

101
```python { .api }
102
def colorize(string: str, stack: tuple) -> str: ...
103
def zero_break(stack: tuple) -> tuple: ...
104
def dedup(stack: tuple) -> tuple: ...
105
def annihilator(predicate: tuple): ...
106
def apply(funcs: tuple, stack: tuple): ...
107
```
108

109
[Optimization Functions](./optimization.md)
110

111
### Color and Style Constants
112

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

115
```python { .api }
116
# Color constants
117
FG: namedtuple  # Foreground colors (30-37)
118
BG: namedtuple  # Background colors (40-47) 
119
HI_FG: namedtuple  # High intensity foreground (90-97)
120
HI_BG: namedtuple  # High intensity background (100-107)
121
STYLE: namedtuple  # Text style codes
122
KEYWORDS: namedtuple  # Combined keyword mapping
123
```
124

125
[Color Constants](./color-constants.md)
126

127
## Available Colors and Styles
128

129
**Colors**: black, red, green, yellow, blue, magenta, cyan, white  
130
**Background Colors**: bg_black, bg_red, bg_green, bg_yellow, bg_blue, bg_magenta, bg_cyan, bg_white  
131
**Bright Colors**: bright_black, bright_red, bright_green, bright_yellow, bright_blue, bright_magenta, bright_cyan, bright_white  
132
**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  
133
**Styles**: reset, bold, italic, underline
134

135
## Configuration
136

137
Hues uses YAML configuration files (`.hues.yml`) loaded from:
138
1. Current working directory (recursive up to root)
139
2. User home directory
140
3. Package defaults
141

142
Example configuration:
143
```yaml
144
hues:
145
  default: defaultfg
146
  time: magenta
147
  info: cyan
148
  success: green
149
  error: red
150
  warn: yellow
151
labels:
152
  info: INFO
153
  warn: WARNING
154
  error: ERROR
155
  success: SUCCESS
156
options:
157
  show_time: yes
158
  time_format: '%H:%M:%S'
159
  add_newline: yes
160
  theme: simple  # 'simple' or 'powerline'
161
```