0
# Status Display
1

2
Status bar functionality for displaying text-based status updates with formatting and justification options. Status bars provide a way to show textual information that updates in place, complementing progress bars for comprehensive user feedback.
3

4
## Capabilities
5

6
### Status Bars
7

8
Text-based status displays with formatting, justification, and dynamic field support.
9

10
```python { .api }
11
class StatusBar:
12
    def __init__(self, enabled=True, color=None, fields=None, fill=' ',
13
                 justify=Justify.LEFT, leave=True, min_delta=0.1,
14
                 status_format='{message}', manager=None, **kwargs):
15
        """
16
        Status bar for text-based status updates.
17

18
        Parameters:
19
        - enabled: Status bar enabled state (default: True)
20
        - color: Status bar color (str or RGB tuple)
21
        - fields: Additional fields for formatting (dict)
22
        - fill: Fill character for justification (default: ' ')
23
        - justify: Text justification (Justify.LEFT/CENTER/RIGHT)
24
        - leave: Leave status visible after closing (default: True)
25
        - min_delta: Minimum time between refreshes in seconds (default: 0.1)
26
        - status_format: Format string for status display
27
        - manager: Manager instance (auto-created if None)
28
        - **kwargs: Additional configuration options
29
        """
30

31
    def update(self, *args, **kwargs):
32
        """
33
        Update status bar with new content.
34

35
        Parameters:
36
        - *args: Direct status text (joined with spaces)
37
        - **kwargs: Field values for formatted status
38

39
        When args are provided, they are converted to strings and joined.
40
        When args are empty, status_format is used with kwargs as field values.
41
        """
42

43
    def close(self, clear=False):
44
        """
45
        Close the status bar and clean up display.
46

47
        Parameters:
48
        - clear: Remove status bar from display (default: False)
49
        """
50

51
    def format(self, width=None, elapsed=None):
52
        """
53
        Format status bar for display.
54

55
        Parameters:
56
        - width: Width in columns to make status bar
57
        - elapsed: Time since started. Automatically determined if None
58

59
        Returns:
60
        str: Formatted status bar
61
        """
62

63
    def refresh(self, flush=True, elapsed=None):
64
        """
65
        Refresh status bar display with current values.
66

67
        Parameters:
68
        - flush: Flush output streams (default: True)
69
        - elapsed: Override elapsed time calculation
70
        """
71

72
    def clear(self, flush=True):
73
        """
74
        Clear status bar display.
75

76
        Parameters:
77
        - flush: Flush output streams (default: True)
78
        """
79

80
    def reset(self):
81
        """Reset status bar to its initial state."""
82

83
    def __enter__(self):
84
        """Context manager entry. Returns self."""
85

86
    def __exit__(self, *args):
87
        """Context manager exit. Calls close()."""
88

89
    def __call__(self, iterable):
90
        """
91
        Iterate over iterable, updating status bar for each item.
92

93
        Parameters:
94
        - iterable: Iterable to process
95

96
        Returns:
97
        Generator yielding items from iterable
98
        """
99

100
    @property
101
    def elapsed(self):
102
        """Elapsed time since status bar creation."""
103
```
104

105
## Usage Examples
106

107
### Basic Status Updates
108

109
```python
110
import enlighten
111
import time
112

113
# Create a status bar
114
status = enlighten.StatusBar()
115

116
# Update with direct text
117
status.update('Starting process...')
118
time.sleep(1)
119

120
status.update('Loading configuration...')
121
time.sleep(1)
122

123
status.update('Processing data...')
124
time.sleep(2)
125

126
status.update('Complete!')
127
status.close()
128
```
129

130
### Multiple Arguments
131

132
```python
133
import enlighten
134

135
# Status bar with multiple text arguments
136
status = enlighten.StatusBar()
137

138
# Arguments are joined with spaces
139
status.update('Status:', 'Processing', 'file', 'data.txt')
140
# Displays: "Status: Processing file data.txt"
141

142
status.update('Error code:', 404, 'Not found')
143
# Displays: "Error code: 404 Not found"
144

145
status.close()
146
```
147

148
### Formatted Status
149

150
```python
151
import enlighten
152
import time
153

154
# Status bar with custom format
155
status = enlighten.StatusBar(
156
    status_format='Stage: {stage} | Progress: {progress}% | Time: {elapsed}'
157
)
158

159
# Update using format fields
160
for i in range(5):
161
    status.update(
162
        stage=f'Phase {i+1}',
163
        progress=i * 20
164
    )
165
    time.sleep(1)
166

167
status.close()
168
```
169

170
### Styled Status Bars
171

172
```python
173
import enlighten
174

175
# Status bar with color and justification
176
status = enlighten.StatusBar(
177
    color='green',
178
    justify=enlighten.Justify.CENTER,
179
    fill='-'
180
)
181

182
status.update('Centered status with green color')
183
time.sleep(2)
184

185
status.close()
186
```
187

188
### Integration with Progress Bars
189

190
```python
191
import enlighten
192
import time
193

194
# Create manager for coordinated display
195
manager = enlighten.get_manager()
196

197
# Create progress bar and status bar
198
pbar = manager.counter(total=100, desc='Processing', unit='items')
199
status = manager.status_bar()
200

201
# Update both progress and status
202
for i in range(100):
203
    # Update progress
204
    pbar.update()
205
    
206
    # Update status with current operation
207
    if i < 25:
208
        status.update('Initializing...')
209
    elif i < 50:
210
        status.update('Loading data...')
211
    elif i < 75:
212
        status.update('Processing...')
213
    else:
214
        status.update('Finalizing...')
215
    
216
    time.sleep(0.1)
217

218
# Final status
219
status.update('Complete!')
220
manager.stop()
221
```
222

223
### Dynamic Status Fields
224

225
```python
226
import enlighten
227
import time
228
import random
229

230
# Status with dynamic fields
231
status = enlighten.StatusBar(
232
    status_format='Server: {server} | Requests: {requests} | Errors: {errors} | Uptime: {elapsed}'
233
)
234

235
# Simulate server monitoring
236
requests = 0
237
errors = 0
238

239
for i in range(20):
240
    requests += random.randint(5, 15)
241
    if random.random() < 0.1:  # 10% chance of error
242
        errors += 1
243
    
244
    status.update(
245
        server='web-01',
246
        requests=requests,
247
        errors=errors
248
    )
249
    time.sleep(0.5)
250

251
status.close()
252
```
253

254
### Status with Custom Fields
255

256
```python
257
import enlighten
258

259
# Status bar with additional custom fields
260
status = enlighten.StatusBar(
261
    fields={'app': 'MyApp', 'version': '1.0'},
262
    status_format='{app} v{version} | {stage} | Elapsed: {elapsed}'
263
)
264

265
# Update with stage information
266
for stage in ['Init', 'Load', 'Process', 'Save', 'Done']:
267
    status.update(stage=stage)
268
    time.sleep(1)
269

270
status.close()
271
```