0
# Enlighten
1

2
A Python console progress bar library that allows writing to stdout and stderr without redirection. Enlighten supports multiple concurrent progress bars, extensive customization options, real-time rate calculations, multicolored subcounters, and experimental Jupyter Notebook compatibility.
3

4
## Package Information
5

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

10
## Core Imports
11

12
```python
13
import enlighten
14
```
15

16
Standard pattern for most use cases:
17

18
```python
19
from enlighten import get_manager
20
```
21

22
For specific components:
23

24
```python
25
from enlighten import Counter, Manager, StatusBar, SubCounter, EnlightenWarning, Justify, format_time
26
```
27

28
Optional import (may not be available in all environments):
29

30
```python
31
from enlighten import NotebookManager
32
```
33

34
## Basic Usage
35

36
```python
37
import enlighten
38
import time
39

40
# Get a manager instance (auto-detects TTY vs notebook environment)
41
manager = enlighten.get_manager()
42

43
# Create a progress bar
44
pbar = manager.counter(total=100, desc='Processing', unit='items')
45

46
# Update progress
47
for i in range(100):
48
    time.sleep(0.1)  # Simulate work
49
    pbar.update()
50

51
# Clean up
52
manager.stop()
53
```
54

55
## Architecture
56

57
Enlighten uses a manager-counter architecture:
58

59
- **Manager**: Controls the display and coordinates multiple progress bars
60
- **Counter**: Individual progress bars that track operations
61
- **StatusBar**: Text-based status displays
62
- **SubCounter**: Child counters for multicolored progress segments
63

64
The library automatically detects the environment (TTY vs Jupyter notebook) and uses the appropriate manager implementation for optimal display.
65

66
## Capabilities
67

68
### Manager Operations
69

70
Core manager functionality for creating and controlling progress bar displays, including TTY detection, multiple concurrent bars, and environment-specific rendering.
71

72
```python { .api }
73
def get_manager(stream=None, counter_class=Counter, **kwargs): ...
74

75
class Manager:
76
    def __init__(self, stream=None, counter_class=Counter, status_bar_class=StatusBar, 
77
                 set_scroll=True, companion_stream=None, enabled=True, 
78
                 no_resize=False, threaded=None, width=None, **kwargs): ...
79
    def counter(self, position=None, **kwargs): ...
80
    def status_bar(self, *args, **kwargs): ...
81
    def write(self, output='', flush=True, counter=None, **kwargs): ...
82
    def remove(self, counter): ...
83
    def stop(self): ...
84
    def __enter__(self): ...
85
    def __exit__(self, *args): ...
86

87
class NotebookManager:
88
    def __init__(self, counter_class=Counter, status_bar_class=StatusBar, 
89
                 enabled=True, width=100, **kwargs): ...
90
    def counter(self, **kwargs): ...
91
    def status_bar(self, *args, **kwargs): ...
92
    def write(self, output='', flush=True, counter=None, **kwargs): ...
93
    def remove(self, counter): ...
94
    def stop(self): ...
95
    def __enter__(self): ...
96
    def __exit__(self, *args): ...
97
```
98

99
[Manager Operations](./manager-operations.md)
100

101
### Progress Tracking
102

103
Progress bar and counter functionality with customizable formatting, rate calculations, ETAs, and visual styling options.
104

105
```python { .api }
106
class Counter:
107
    def __init__(self, total=None, desc=None, unit=None, count=0, enabled=True, 
108
                 manager=None, stream=None, color=None, bar_format=None, 
109
                 counter_format=None, all_fields=False, fill=' ', fields=None, 
110
                 leave=True, min_delta=0.1, offset=0, series=None, **kwargs): ...
111
    def update(self, incr=1, force=False, **fields): ...
112
    def add_subcounter(self, color, count=0, all_fields=None): ...
113
    def format(self, width=None, elapsed=None): ...
114
    def refresh(self, flush=True, elapsed=None): ...
115
    def clear(self, flush=True): ...
116
    def close(self, clear=False): ...
117
    def reset(self): ...
118
    def __enter__(self): ...
119
    def __exit__(self, *args): ...
120
    def __call__(self, iterable): ...
121
    @property
122
    def count(self): ...
123
    @property
124
    def elapsed(self): ...
125
    @property
126
    def rate(self): ...
127
    @property
128
    def subcount(self): ...
129

130
class SubCounter:
131
    def __init__(self, parent, color=None, count=0, all_fields=False): ...
132
    def update(self, incr=1, force=False): ...
133
    def update_from(self, source, incr=1, force=False): ...
134
    @property
135
    def count(self): ...
136
    @property
137
    def parent(self): ...
138
```
139

140
[Progress Tracking](./progress-tracking.md)
141

142
### Status Display
143

144
Status bar functionality for displaying text-based status updates with formatting and justification options.
145

146
```python { .api }
147
class StatusBar:
148
    def __init__(self, enabled=True, color=None, fields=None, fill=' ',
149
                 justify=Justify.LEFT, leave=True, min_delta=0.1,
150
                 status_format='{message}', manager=None, **kwargs): ...
151
    def update(self, *args, force=False, **kwargs): ...
152
    def format(self, width=None, elapsed=None): ...
153
    def refresh(self, flush=True, elapsed=None): ...
154
    def clear(self, flush=True): ...
155
    def close(self, clear=False): ...
156
    def reset(self): ...
157
    def __enter__(self): ...
158
    def __exit__(self, *args): ...
159
    def __call__(self, iterable): ...
160
    @property
161
    def elapsed(self): ...
162
```
163

164
[Status Display](./status-display.md)
165

166
### Utilities
167

168
Helper functions and classes for time formatting, warnings, text justification, and HTML conversion.
169

170
```python { .api }
171
def format_time(seconds): ...
172
def warn_best_level(message, category): ...
173

174
class Justify:
175
    CENTER = 'center'
176
    LEFT = 'ljust'
177
    RIGHT = 'rjust'
178

179
class EnlightenWarning(Warning): ...
180

181
class HTMLConverter:
182
    def __init__(self, term): ...
183
    def to_html(self, text): ...
184
    @property
185
    def style(self): ...
186

187
class Lookahead:
188
    def __init__(self, iterator): ...
189
    def __getitem__(self, key): ...
190
```
191

192
[Utilities](./utilities.md)
193

194
## Types
195

196
```python { .api }
197
# Type aliases for common parameter types
198
StreamType = typing.TextIO
199
ColorType = typing.Union[str, typing.Tuple[int, int, int]]
200
```