0
# Configuration
1
2
Global and local configuration system for customizing bar appearance, behavior, widgets, and output formatting. Supports both global defaults and per-bar customization with comprehensive validation and error handling.
3
4
## Capabilities
5
6
### Configuration Handler
7
8
Global configuration management object providing methods to set defaults, reset to factory settings, and create custom configuration contexts.
9
10
```python { .api }
11
config_handler.set_global(**options):
12
"""
13
Update global configuration for all subsequent alive bars.
14
15
Parameters:
16
- **options: Configuration options (see Configuration Options below)
17
18
Raises:
19
- ValueError: If invalid configuration keys or values are provided
20
"""
21
22
config_handler.reset():
23
"""Reset global configuration to factory defaults."""
24
25
config_handler.create_context(**options):
26
"""
27
Create immutable configuration context with optional customization.
28
29
Parameters:
30
- **options: Configuration options to override
31
32
Returns:
33
Config object with current global settings plus overrides
34
"""
35
```
36
37
#### Usage Examples
38
39
```python
40
from alive_progress import config_handler
41
42
# Set global defaults
43
config_handler.set_global(
44
length=50,
45
theme='smooth',
46
dual_line=True,
47
receipt_text=True
48
)
49
50
# All subsequent bars use these defaults
51
with alive_bar(1000) as bar:
52
# Uses global configuration
53
pass
54
55
# Reset to factory defaults
56
config_handler.reset()
57
```
58
59
### Configuration Options
60
61
#### Display Options
62
63
Control the visual appearance and layout of the progress bar.
64
65
```python { .api }
66
# Display configuration options
67
title: Optional[str] = None # Bar title
68
length: int = 40 # Bar length in characters
69
max_cols: int = 80 # Maximum columns if terminal size unavailable
70
dual_line: bool = False # Place text below bar instead of inline
71
```
72
73
**Usage Examples**:
74
```python
75
# Custom bar appearance
76
with alive_bar(1000,
77
title='Processing Data',
78
length=60,
79
dual_line=True) as bar:
80
for i in range(1000):
81
bar.text = f'Processing record {i+1}'
82
process_record(i)
83
bar()
84
```
85
86
#### Style Options
87
88
Customize visual styles including spinners, bars, and themes.
89
90
```python { .api }
91
# Style configuration options
92
spinner: Union[str, object, None] = None # Spinner style or factory
93
bar: Union[str, object, None] = None # Bar style or factory
94
unknown: Union[str, object] = None # Unknown mode spinner style
95
theme: str = 'smooth' # Predefined theme name
96
```
97
98
**Available Themes**: 'smooth', 'classic', 'ascii'
99
100
**Usage Examples**:
101
```python
102
# Using predefined theme
103
with alive_bar(1000, theme='classic') as bar:
104
pass
105
106
# Custom spinner and bar
107
with alive_bar(1000,
108
spinner='dots',
109
bar='filling') as bar:
110
pass
111
112
# Custom factories
113
from alive_progress.animations import scrolling_spinner_factory
114
115
custom_spinner = scrolling_spinner_factory(['◐', '◓', '◑', '◒'])
116
with alive_bar(1000, spinner=custom_spinner) as bar:
117
pass
118
```
119
120
#### Behavior Options
121
122
Control bar behavior, modes, and terminal interaction.
123
124
```python { .api }
125
# Behavior configuration options
126
manual: bool = False # Enable manual percentage mode
127
force_tty: Optional[bool] = None # Force terminal mode (None=auto, True=force, False=disable)
128
disable: bool = False # Disable all output completely
129
calibrate: Optional[int] = None # Calibration value for animation speed
130
```
131
132
**Usage Examples**:
133
```python
134
# Manual percentage mode
135
with alive_bar(manual=True, title='Training Model') as bar:
136
for epoch in range(100):
137
loss = train_epoch()
138
bar(epoch / 100) # Set percentage directly
139
140
# Force animations in Jupyter
141
with alive_bar(1000, force_tty=True) as bar:
142
pass
143
144
# Disable in production
145
with alive_bar(1000, disable=PRODUCTION_MODE) as bar:
146
pass
147
```
148
149
#### Widget Options
150
151
Configure the display widgets that show progress information.
152
153
```python { .api }
154
# Widget configuration options
155
monitor: Union[bool, str] = True # Progress monitor widget
156
elapsed: Union[bool, str] = True # Elapsed time widget
157
stats: Union[bool, str] = True # Statistics widget (rate/ETA)
158
receipt: bool = True # Show final receipt
159
receipt_text: bool = False # Include text in receipt
160
161
# Widget format strings
162
monitor_end: Union[bool, str] = True # Monitor widget in receipt
163
elapsed_end: Union[bool, str] = True # Elapsed widget in receipt
164
stats_end: Union[bool, str] = True # Stats widget in receipt
165
```
166
167
**Widget Format Strings**:
168
- Monitor: `{count}`, `{total}`, `{percent}`
169
- Elapsed: `{elapsed}`
170
- Stats: `{rate}`, `{eta}`
171
172
**Usage Examples**:
173
```python
174
# Custom widget formats
175
with alive_bar(1000,
176
monitor='{count} of {total} [{percent:.1%}]',
177
stats='Rate: {rate} | ETA: {eta}') as bar:
178
pass
179
180
# Disable specific widgets
181
with alive_bar(1000,
182
elapsed=False,
183
stats=False) as bar:
184
pass
185
```
186
187
#### Output Options
188
189
Control where and how the progress bar outputs information.
190
191
```python { .api }
192
# Output configuration options
193
file: TextIOWrapper = sys.stdout # Output file object
194
enrich_print: bool = True # Enrich print/logging output with bar position
195
enrich_offset: int = 0 # Offset for enriched messages
196
```
197
198
**Usage Examples**:
199
```python
200
import sys
201
202
# Output to stderr
203
with alive_bar(1000, file=sys.stderr) as bar:
204
pass
205
206
# Disable print enrichment
207
with alive_bar(1000, enrich_print=False) as bar:
208
print("This won't show bar position")
209
bar()
210
211
# Custom enrichment offset
212
with alive_bar(1000, enrich_offset=500) as bar:
213
bar(400)
214
print("This shows 'on 901:' instead of 'on 401:'")
215
```
216
217
#### Formatting Options
218
219
Configure number formatting, units, and scaling.
220
221
```python { .api }
222
# Formatting configuration options
223
unit: str = '' # Unit label for values
224
scale: Optional[str] = None # Scaling mode: 'SI', 'IEC', 'SI2', or None
225
precision: int = 1 # Decimal precision for scaled values
226
title_length: int = 0 # Fixed title length (0 for unlimited)
227
spinner_length: int = 0 # Fixed spinner length (0 for natural)
228
```
229
230
**Scaling Modes**:
231
- `'SI'`: Base 1000 (KB, MB, GB)
232
- `'IEC'`: Base 1024 (KiB, MiB, GiB)
233
- `'SI2'`: Base 1024 with SI prefixes (KB, MB, GB)
234
- `None`: No scaling
235
236
**Usage Examples**:
237
```python
238
# File processing with byte units
239
with alive_bar(total_bytes,
240
unit='B',
241
scale='IEC',
242
precision=2) as bar:
243
for chunk in file_chunks:
244
process_chunk(chunk)
245
bar(len(chunk))
246
247
# Fixed title length
248
with alive_bar(1000,
249
title='Very Long Processing Title',
250
title_length=20) as bar:
251
pass # Title truncated to 20 chars with ellipsis
252
```
253
254
#### Advanced Options
255
256
Advanced timing and control options for specialized use cases.
257
258
```python { .api }
259
# Advanced configuration options
260
refresh_secs: float = 0 # Refresh period in seconds (0 for reactive)
261
ctrl_c: bool = True # Allow CTRL+C interruption
262
```
263
264
**Usage Examples**:
265
```python
266
# Slower refresh rate for very fast processing
267
with alive_bar(1000000, refresh_secs=0.1) as bar:
268
for i in range(1000000):
269
fast_operation(i)
270
bar()
271
272
# Disable keyboard interruption
273
with alive_bar(1000, ctrl_c=False) as bar:
274
try:
275
for i in range(1000):
276
critical_operation(i)
277
bar()
278
except KeyboardInterrupt:
279
pass # CTRL+C captured but ignored
280
```
281
282
### Configuration Validation
283
284
The configuration system validates all options and provides helpful error messages.
285
286
```python
287
# Invalid configuration examples
288
try:
289
config_handler.set_global(length='invalid')
290
except ValueError as e:
291
print(e) # Expected an int between 3 and 1000
292
293
try:
294
with alive_bar(1000, theme='nonexistent') as bar:
295
pass
296
except ValueError as e:
297
print(e) # invalid theme name=nonexistent
298
299
try:
300
with alive_bar(1000, monitor='{invalid_field}') as bar:
301
pass
302
except ValueError as e:
303
print(e) # Expected only the fields: ('count', 'total', 'percent')
304
```
305
306
### Factory Reset and Context Management
307
308
```python
309
# Save current configuration
310
original_config = config_handler.create_context()
311
312
# Modify global settings
313
config_handler.set_global(theme='ascii', length=60)
314
315
# Use bars with modified settings
316
with alive_bar(1000) as bar:
317
pass
318
319
# Restore original settings
320
config_handler.set_global(**original_config._asdict())
321
322
# Or reset to factory defaults
323
config_handler.reset()
324
```
325
326
### Configuration Inheritance
327
328
Local bar options override global settings without affecting the global configuration.
329
330
```python
331
# Set global defaults
332
config_handler.set_global(theme='smooth', length=40)
333
334
# This bar uses global settings
335
with alive_bar(1000) as bar:
336
pass
337
338
# This bar overrides specific options
339
with alive_bar(1000, theme='classic', length=60) as bar:
340
pass
341
342
# Next bar uses global settings again
343
with alive_bar(1000) as bar:
344
pass
345
```