0
# Utilities
1

2
Helper functions and classes for time formatting, warnings, text justification, and HTML conversion. These utilities support the core functionality and provide additional tools for working with enlighten components.
3

4
## Capabilities
5

6
### Time Formatting
7

8
Format time durations in human-readable format for display in progress bars and status updates.
9

10
```python { .api }
11
def format_time(seconds):
12
    """
13
    Format time duration in human-readable format.
14

15
    Parameters:
16
    - seconds: Time duration in seconds (float)
17

18
    Returns:
19
    str: Formatted time string
20

21
    Formats time in one of these forms based on duration:
22
    - 01:56 (minutes:seconds)
23
    - 12h 01:56 (hours, minutes:seconds)
24
    - 1d 0h 01:56 (days, hours, minutes:seconds)
25
    """
26
```
27

28
### Text Justification
29

30
Enumerated constants for text alignment in progress bars and status displays.
31

32
```python { .api }
33
class Justify:
34
    """
35
    Text justification constants for alignment options.
36
    """
37
    CENTER = 'center'  # Center-align text
38
    LEFT = 'ljust'     # Left-align text (default)
39
    RIGHT = 'rjust'    # Right-align text
40
```
41

42
### Warning System
43

44
Custom warning class for enlighten-specific warnings and issues.
45

46
```python { .api }
47
class EnlightenWarning(Warning):
48
    """
49
    Generic warning class for Enlighten library warnings.
50
    
51
    Used for configuration issues, compatibility warnings,
52
    and other non-fatal problems in enlighten operations.
53
    """
54
```
55

56
### HTML Conversion
57

58
ANSI terminal code to HTML converter for Jupyter notebook display.
59

60
```python { .api }
61
class HTMLConverter:
62
    def __init__(self, term):
63
        """
64
        ANSI to HTML converter for notebook environments.
65

66
        Parameters:
67
        - term: Blessed Terminal instance
68
        """
69

70
    def to_html(self, text):
71
        """
72
        Convert ANSI-formatted text to HTML.
73

74
        Parameters:
75
        - text: String with ANSI escape codes
76

77
        Returns:
78
        str: HTML-formatted text with CSS classes
79

80
        Supported formatting:
81
        - Colors (8, 16, 256, RGB)
82
        - Bold, italic, underline
83
        - Blink animation
84
        - Hyperlinks
85
        """
86

87
    @property
88
    def style(self):
89
        """
90
        CSS style definitions for converted HTML.
91

92
        Returns:
93
        str: Complete CSS style block for HTML output
94
        """
95
```
96

97
### Internal Utilities
98

99
Additional utility classes and functions used internally by enlighten.
100

101
```python { .api }
102
class Lookahead:
103
    def __init__(self, iterator):
104
        """
105
        Iterator wrapper supporting look-ahead operations.
106

107
        Parameters:
108
        - iterator: Source iterator to wrap
109
        """
110

111
    def __getitem__(self, key):
112
        """
113
        Access future items without consuming them.
114

115
        Parameters:
116
        - key: Index or slice for look-ahead access
117

118
        Returns:
119
        Item(s) from future positions in iterator
120
        """
121

122
def warn_best_level(message, category):
123
    """
124
    Issue warning at appropriate stack level outside library.
125

126
    Parameters:
127
    - message: Warning message text
128
    - category: Warning category class
129
    """
130
```
131

132
## Usage Examples
133

134
### Time Formatting
135

136
```python
137
import enlighten
138

139
# Format various time durations
140
print(enlighten.format_time(65))     # "01:05"
141
print(enlighten.format_time(3665))   # "1h 01:05"
142
print(enlighten.format_time(90065))  # "1d 1h 01:05"
143

144
# Use in custom formatting
145
elapsed = 3725.5
146
formatted_time = enlighten.format_time(elapsed)
147
print(f"Operation completed in {formatted_time}")
148
# Output: "Operation completed in 1h 02:05"
149
```
150

151
### Text Justification
152

153
```python
154
import enlighten
155

156
# Create progress bar with center-aligned description
157
pbar = enlighten.Counter(
158
    total=100,
159
    desc='Centered Progress',
160
    justify=enlighten.Justify.CENTER
161
)
162

163
# Create status bar with right-aligned text
164
status = enlighten.StatusBar(
165
    justify=enlighten.Justify.RIGHT
166
)
167

168
# Available justification options
169
print(enlighten.Justify.LEFT)    # 'ljust'
170
print(enlighten.Justify.CENTER)  # 'center'
171
print(enlighten.Justify.RIGHT)   # 'rjust'
172
```
173

174
### Warning Handling
175

176
```python
177
import enlighten
178
import warnings
179

180
# Configure warning handling
181
warnings.filterwarnings('always', category=enlighten.EnlightenWarning)
182

183
# Enlighten will issue warnings for configuration issues
184
# For example, if trying to use features not supported in current environment
185
try:
186
    # Some operation that might trigger a warning
187
    manager = enlighten.Manager(some_unsupported_option=True)
188
except Exception as e:
189
    print(f"Configuration issue: {e}")
190
```
191

192
### HTML Conversion (Notebook Context)
193

194
```python
195
# Internal use in NotebookManager - normally not called directly
196
from blessed import Terminal
197
import enlighten._util
198

199
# Create HTML converter
200
term = Terminal()
201
converter = enlighten._util.HTMLConverter(term)
202

203
# Convert ANSI text to HTML
204
ansi_text = "\x1b[32mGreen text\x1b[0m with \x1b[1mbold\x1b[0m formatting"
205
html_output = converter.to_html(ansi_text)
206
css_styles = converter.style
207

208
# HTML output ready for notebook display
209
print(html_output)
210
print(css_styles)
211
```
212

213
### Custom Field Processing
214

215
```python
216
import enlighten
217
import time
218

219
# Using format_time in custom status formats
220
status = enlighten.StatusBar(
221
    status_format='Uptime: {uptime} | Status: {status}'
222
)
223

224
start_time = time.time()
225

226
for i in range(10):
227
    current_uptime = time.time() - start_time
228
    status.update(
229
        uptime=enlighten.format_time(current_uptime),
230
        status=f'Running task {i+1}'
231
    )
232
    time.sleep(1)
233

234
status.close()
235
```
236

237
### Iterator Look-ahead
238

239
```python
240
# Internal utility - normally not used directly
241
import enlighten._util
242

243
# Wrap iterator with look-ahead capability
244
data = range(10)
245
lookahead = enlighten._util.Lookahead(iter(data))
246

247
# Look ahead without consuming
248
print(lookahead[0])    # 0 (peek at next item)
249
print(lookahead[1:3])  # [1, 2] (peek at slice)
250

251
# Normal iteration still works
252
print(next(lookahead)) # 0 (consume first item)
253
print(next(lookahead)) # 1 (consume second item)
254
```
255

256
### Error Context
257

258
```python
259
import enlighten
260
import warnings
261

262
# Capture enlighten warnings in your application
263
with warnings.catch_warnings(record=True) as w:
264
    warnings.simplefilter("always", enlighten.EnlightenWarning)
265
    
266
    # Operations that might generate warnings
267
    manager = enlighten.get_manager()
268
    pbar = manager.counter(total=100)
269
    
270
    # Check for any warnings
271
    if w:
272
        for warning in w:
273
            if issubclass(warning.category, enlighten.EnlightenWarning):
274
                print(f"Enlighten warning: {warning.message}")
275
```