0
# String Coloring
1
2
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.
3
4
## Capabilities
5
6
### HueString Creation
7
8
Create colored strings using the `huestr` class (alias for HueString). Strings can be chained with color, background, and style attributes.
9
10
```python { .api }
11
class huestr(str):
12
"""
13
String class with chainable color and style attributes.
14
15
Args:
16
string (str): The text content
17
hue_stack (tuple, optional): Internal color/style stack
18
"""
19
def __init__(self, string: str, hue_stack: tuple = tuple()): ...
20
```
21
22
**Usage:**
23
```python
24
from hues import huestr
25
26
# Create a colored string
27
text = huestr('Hello World')
28
colored = text.red.bold.bg_yellow
29
```
30
31
### Color Rendering
32
33
Convert the styled string to ANSI-escaped text for terminal output.
34
35
```python { .api }
36
@property
37
def colorized(self) -> str:
38
"""
39
Returns the string with ANSI escape sequences applied.
40
41
Returns:
42
str: ANSI-escaped string ready for terminal output
43
"""
44
```
45
46
**Usage:**
47
```python
48
colored_text = huestr('Warning').yellow.bold
49
print(colored_text.colorized) # Outputs: \033[1;33mWarning\033[0m
50
```
51
52
### Low-Level Color Functions
53
54
Direct colorization functions for advanced usage.
55
56
```python { .api }
57
def colorize(string: str, stack: tuple) -> str:
58
"""
59
Apply optimal ANSI escape sequences to a string.
60
61
Args:
62
string (str): Text to colorize
63
stack (tuple): Stack of color/style codes
64
65
Returns:
66
str: ANSI-escaped string
67
"""
68
```
69
70
## Dynamic Color Attributes
71
72
All color and style attributes are available as chainable properties on HueString instances:
73
74
### Foreground Colors
75
- `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`
76
77
### Background Colors
78
- `bg_black`, `bg_red`, `bg_green`, `bg_yellow`, `bg_blue`, `bg_magenta`, `bg_cyan`, `bg_white`
79
80
### Bright Foreground Colors
81
- `bright_black`, `bright_red`, `bright_green`, `bright_yellow`, `bright_blue`, `bright_magenta`, `bright_cyan`, `bright_white`
82
83
### Bright Background Colors
84
- `bg_bright_black`, `bg_bright_red`, `bg_bright_green`, `bg_bright_yellow`, `bg_bright_blue`, `bg_bright_magenta`, `bg_bright_cyan`, `bg_bright_white`
85
86
### Text Styles
87
- `reset` - Reset all formatting
88
- `bold` - Bold text
89
- `italic` - Italic text
90
- `underline` - Underlined text
91
- `defaultfg` - Default foreground color
92
- `defaultbg` - Default background color
93
94
## Usage Examples
95
96
### Basic Coloring
97
```python
98
from hues import huestr
99
100
# Simple color
101
text = huestr('Success').green
102
print(text.colorized)
103
104
# Color with background
105
text = huestr('Error').red.bg_white
106
print(text.colorized)
107
```
108
109
### Style Chaining
110
```python
111
# Multiple styles can be chained in any order
112
text = huestr('Important').bold.red.bg_yellow.underline
113
print(text.colorized)
114
115
# Order doesn't matter due to optimization
116
text1 = huestr('Test').red.bold.green # green overrides red
117
text2 = huestr('Test').bold.green.red # red overrides green
118
```
119
120
### Reset Handling
121
```python
122
# Reset clears all previous styles
123
text = huestr('Mixed').red.bold.reset.blue
124
print(text.colorized) # Only blue is applied
125
```
126
127
## Optimization
128
129
Hues uses a push-down automaton to optimize color sequences:
130
131
1. **Reset Handling**: `reset` breaks the chain, clearing all previous styles
132
2. **Color Squashing**: Multiple foreground/background colors are reduced to the last one
133
3. **Deduplication**: Duplicate style codes are removed
134
4. **Self-Closing**: All strings automatically reset at the end to prevent color pollution
135
136
This ensures minimal ANSI escape sequences while maintaining the desired appearance.