0
# Progress Tracking
1

2
Progress bar and counter functionality with customizable formatting, rate calculations, ETAs, and visual styling. Supports both simple counters and progress bars with totals, as well as multicolored subcounters for complex progress visualization.
3

4
## Capabilities
5

6
### Progress Counters
7

8
Main counter class for tracking progress with optional totals, rate calculations, and extensive formatting options.
9

10
```python { .api }
11
class Counter:
12
    def __init__(self, **kwargs):
13
        """
14
        Progress counter with optional progress bar display.
15

16
        Parameters:
17
        - total: Total expected count (enables progress bar mode)
18
        - desc: Description text displayed before counter
19
        - unit: Unit label for rate calculations and display
20
        - count: Starting count value (default: 0)
21
        - enabled: Counter status (default: True)
22
        - manager: Manager instance (auto-created if None)
23
        - stream: Output stream (passed to auto-created manager)
24
        - color: Progress bar color (str or RGB tuple)
25
        - bar_format: Custom format string for progress bars
26
        - counter_format: Custom format string for simple counters
27
        - all_fields: Populate rate, interval, eta fields in subcounters (default: False)
28
        - fill: Fill character for counter_format (default: ' ')
29
        - fields: Additional user-defined fields for formatting (dict)
30
        - leave: Leave counter visible after closing (default: True)
31
        - min_delta: Minimum time between refreshes in seconds (default: 0.1)
32
        - offset: Number of non-printable characters to account for
33
        - series: Progression series characters for progress bar
34
        - **kwargs: Additional user-defined fields
35
        """
36

37
    def update(self, incr=1, force=False):
38
        """
39
        Update the counter by the specified increment.
40

41
        Parameters:
42
        - incr: Amount to increment count (default: 1)
43
        - force: Force refresh even if min_delta not reached (default: False)
44
        """
45

46
    def close(self, clear=False):
47
        """
48
        Close the counter and clean up display.
49

50
        Parameters:
51
        - clear: Remove counter from display (default: False)
52
        """
53

54
    def refresh(self, flush=True, elapsed=None):
55
        """
56
        Refresh counter display with current values.
57

58
        Parameters:
59
        - flush: Flush output streams (default: True)
60
        - elapsed: Override elapsed time calculation
61
        """
62

63
    def add_subcounter(self, color, count=0, all_fields=None):
64
        """
65
        Add a subcounter for multicolored progress segments.
66

67
        Parameters:
68
        - color: Color for this segment (str or RGB tuple)
69
        - count: Initial count for subcounter (default: 0)
70
        - all_fields: Include rate, interval, eta fields (default: None, uses parent setting)
71

72
        Returns:
73
        SubCounter instance
74
        """
75

76
    def format(self, width=None, elapsed=None):
77
        """
78
        Format counter for display.
79

80
        Parameters:
81
        - width: Width in columns to make progress bar
82
        - elapsed: Time since started. Automatically determined if None
83

84
        Returns:
85
        str: Formatted progress bar or counter
86
        """
87

88
    def clear(self, flush=True):
89
        """
90
        Clear counter display.
91

92
        Parameters:
93
        - flush: Flush output streams (default: True)
94
        """
95

96
    def reset(self):
97
        """
98
        Reset counter to its initial state.
99
        
100
        Resets count to initial value and clears all subcounters.
101
        """
102

103
    def __enter__(self):
104
        """Context manager entry. Returns self."""
105

106
    def __exit__(self, *args):
107
        """Context manager exit. Calls close()."""
108

109
    def __call__(self, iterable):
110
        """
111
        Iterate over iterable, updating counter for each item.
112

113
        Parameters:
114
        - iterable: Iterable to process
115

116
        Returns:
117
        Generator yielding items from iterable
118
        """
119

120
    @property
121
    def count(self):
122
        """Current count value."""
123

124
    @property
125
    def elapsed(self):
126
        """Elapsed time since counter creation."""
127

128
    @property
129
    def rate(self):
130
        """Current rate (count per second)."""
131

132
    @property
133
    def subcount(self):
134
        """Total count from all subcounters."""
135
```
136

137
### Sub Counters
138

139
Child counters for creating multicolored progress bar segments, useful for showing different types of progress within a single bar.
140

141
```python { .api }
142
class SubCounter:
143
    def __init__(self, parent, color=None, count=0, all_fields=False):
144
        """
145
        Child counter for multicolored progress bar segments.
146

147
        Parameters:
148
        - parent: Parent Counter instance
149
        - color: Segment color (str or RGB tuple)
150
        - count: Initial count (default: 0)
151
        - all_fields: Calculate rate, interval, eta fields (default: False)
152
        """
153

154
    def update(self, incr=1, force=False):
155
        """
156
        Update the subcounter and trigger parent refresh.
157

158
        Parameters:
159
        - incr: Amount to increment (default: 1)
160
        - force: Force refresh even if min_delta not reached
161
        """
162

163
    def update_from(self, source, incr=1, force=False):
164
        """
165
        Transfer count from another counter to this subcounter.
166

167
        Parameters:
168
        - source: Source Counter or SubCounter to transfer from
169
        - incr: Amount to transfer (default: 1)
170
        - force: Force refresh even if min_delta not reached
171
        
172
        Source must be the parent Counter or a peer SubCounter.
173
        """
174

175
    @property
176
    def count(self):
177
        """Current subcounter count."""
178

179
    @property
180
    def parent(self):
181
        """Parent Counter instance."""
182
```
183

184
## Usage Examples
185

186
### Basic Progress Bar
187

188
```python
189
import enlighten
190
import time
191

192
# Create a progress bar with known total
193
pbar = enlighten.Counter(total=100, desc='Processing', unit='items')
194

195
for i in range(100):
196
    time.sleep(0.1)  # Simulate work
197
    pbar.update()
198

199
pbar.close()
200
```
201

202
### Simple Counter
203

204
```python
205
import enlighten
206
import time
207

208
# Create a counter without total (no progress bar)
209
counter = enlighten.Counter(desc='Processed', unit='records')
210

211
for i in range(50):
212
    time.sleep(0.2)
213
    counter.update()
214

215
counter.close()
216
```
217

218
### Custom Formatting
219

220
```python
221
import enlighten
222

223
# Custom progress bar format
224
pbar = enlighten.Counter(
225
    total=100,
226
    desc='Custom',
227
    unit='ops',
228
    bar_format='{desc}{desc_pad}{percentage:3.0f}%|{bar}| {count}/{total} [{elapsed}<{eta}]'
229
)
230

231
# Custom counter format
232
counter = enlighten.Counter(
233
    desc='Events',
234
    unit='evt',
235
    counter_format='{desc}{desc_pad}{count} {unit} [{elapsed}, {rate:.1f}/s]{fill}'
236
)
237
```
238

239
### Multicolored Progress Bars
240

241
```python
242
import enlighten
243
import time
244

245
# Create main progress bar
246
pbar = enlighten.Counter(total=100, desc='Multi-colored', unit='items')
247

248
# Add colored segments
249
red_sub = pbar.add_subcounter('red')
250
green_sub = pbar.add_subcounter('green')
251
blue_sub = pbar.add_subcounter('blue')
252

253
# Update different segments
254
for i in range(100):
255
    if i < 40:
256
        red_sub.update()
257
    elif i < 70:
258
        green_sub.update()
259
    else:
260
        blue_sub.update()
261
    time.sleep(0.1)
262

263
pbar.close()
264
```
265

266
### Advanced Counter Options
267

268
```python
269
import enlighten
270

271
# Counter with all options
272
pbar = enlighten.Counter(
273
    total=1000,
274
    desc='Advanced Progress',
275
    unit='items',
276
    initial=50,                    # Start at 50
277
    color='blue',                  # Bar color
278
    justify=enlighten.Justify.CENTER,  # Center description
279
    leave=True,                    # Keep visible after completion
280
    min_delta=0.5,                 # Minimum time between updates
281
    offset=2,                      # Display position offset
282
    additional_fields={'stage': 'Processing'}  # Custom fields
283
)
284

285
# Update with custom increments
286
pbar.update(10)  # Add 10 to count
287
pbar.update(5)   # Add 5 more
288

289
# Force refresh regardless of min_delta
290
pbar.update(0, force=True)
291
```
292

293
### Integration with Manager
294

295
```python
296
import enlighten
297
import time
298

299
# Use manager for multiple bars
300
manager = enlighten.get_manager()
301

302
# Create multiple progress bars
303
download_bar = manager.counter(total=100, desc='Downloading', unit='MB')
304
process_bar = manager.counter(total=50, desc='Processing', unit='files')
305

306
# Simulate concurrent operations
307
for i in range(100):
308
    download_bar.update()
309
    if i % 2 == 0:
310
        process_bar.update()
311
    time.sleep(0.1)
312

313
manager.stop()
314
```