0
# Progress Indicators
1

2
Progress bars, dots, and mill/spinner indicators for long-running operations. Supports both iterator wrapping and manual progress updates with customizable appearance, automatic terminal width detection, and ETA calculations.
3

4
## Capabilities
5

6
### Progress Bar Iterator
7

8
Wrap iterables with a progress bar that automatically updates as items are processed.
9

10
```python { .api }
11
def bar(it, label='', width=32, hide=None, empty_char=' ', filled_char='#', expected_size=None, every=1):
12
    """
13
    Progress iterator that wraps iterables with a progress bar.
14
    
15
    Parameters:
16
    - it: iterable, items to iterate over
17
    - label: str, label to display before progress bar (default: '')
18
    - width: int, width of progress bar in characters (default: 32)
19
    - hide: bool, force hide progress bar (default: None, auto-detect TTY)
20
    - empty_char: str, character for empty portion of bar (default: ' ')
21
    - filled_char: str, character for filled portion of bar (default: '#')
22
    - expected_size: int, override length detection (default: None)
23
    - every: int, update frequency - update every N items (default: 1)
24
    
25
    Yields:
26
    items from the wrapped iterable
27
    """
28
```
29

30
### Manual Progress Bar
31

32
Progress bar class for manual control over progress updates and display.
33

34
```python { .api }
35
class Bar:
36
    def __init__(self, label='', width=32, hide=None, empty_char=' ', filled_char='#', expected_size=None, every=1):
37
        """
38
        Manual progress bar with customizable appearance and timing.
39
        
40
        Parameters:
41
        - label: str, label to display before progress bar (default: '')
42
        - width: int, width of progress bar in characters (default: 32)
43
        - hide: bool, force hide progress bar (default: None, auto-detect TTY)
44
        - empty_char: str, character for empty portion of bar (default: ' ')
45
        - filled_char: str, character for filled portion of bar (default: '#')
46
        - expected_size: int, total number of items expected (default: None)
47
        - every: int, update frequency - update every N calls (default: 1)
48
        """
49
    
50
    def show(self, progress, count=None):
51
        """
52
        Display progress bar at given progress level.
53
        
54
        Parameters:
55
        - progress: int, current progress value
56
        - count: int, optional override for expected_size
57
        """
58
    
59
    def done(self):
60
        """
61
        Complete the progress bar and show final state with elapsed time.
62
        Automatically called when using Bar as context manager.
63
        """
64
    
65
    def __enter__(self):
66
        """Context manager entry."""
67
    
68
    def __exit__(self, exc_type, exc_val, exc_tb):
69
        """Context manager exit - calls done() automatically."""
70
```
71

72
### Dots Progress Indicator
73

74
Simple progress indicator that prints dots for each processed item.
75

76
```python { .api }
77
def dots(it, label='', hide=None, every=1):
78
    """
79
    Progress iterator that prints a dot for each item being iterated.
80
    
81
    Parameters:
82
    - it: iterable, items to iterate over
83
    - label: str, label to display before dots (default: '')
84
    - hide: bool, force hide dots (default: None, auto-detect TTY)
85
    - every: int, print dot every N items (default: 1)
86
    
87
    Yields:
88
    items from the wrapped iterable
89
    """
90
```
91

92
### Mill/Spinner Progress Indicator
93

94
Rotating character spinner for indicating ongoing progress without known total.
95

96
```python { .api }
97
def mill(it, label='', hide=None, expected_size=None, every=1):
98
    """
99
    Progress iterator that prints a mill/spinner while iterating.
100
    
101
    Parameters:
102
    - it: iterable, items to iterate over
103
    - label: str, label to display before spinner (default: '')
104
    - hide: bool, force hide spinner (default: None, auto-detect TTY)
105
    - expected_size: int, override length detection (default: None)
106
    - every: int, update spinner every N items (default: 1)
107
    
108
    Yields:
109
    items from the wrapped iterable
110
    """
111
```
112

113
## Usage Examples
114

115
```python
116
from clint.textui.progress import bar, dots, mill, Bar
117
import time
118

119
# Basic progress bar with iterator
120
items = range(100)
121
for item in bar(items, label='Processing: '):
122
    time.sleep(0.1)  # Simulate work
123
    # Process item
124

125
# Custom progress bar appearance
126
for item in bar(items, label='Custom: ', width=50, 
127
                filled_char='█', empty_char='░'):
128
    time.sleep(0.05)
129
    # Process item
130

131
# Manual progress bar
132
with Bar(label='Manual Progress: ', expected_size=100) as progress_bar:
133
    for i in range(100):
134
        # Do some work
135
        time.sleep(0.05)
136
        progress_bar.show(i + 1)
137

138
# Dots progress indicator
139
large_dataset = range(1000)
140
for item in dots(large_dataset, label='Loading data', every=10):
141
    # Process item (prints dot every 10 items)
142
    pass
143

144
# Mill/spinner for unknown progress
145
unknown_items = some_generator()
146
for item in mill(unknown_items, label='Processing: '):
147
    # Process item with spinner
148
    pass
149
```
150

151
## Advanced Usage
152

153
```python
154
from clint.textui.progress import Bar, bar
155
import requests
156

157
# Download progress with actual size
158
def download_file(url, filename):
159
    response = requests.get(url, stream=True)
160
    total_size = int(response.headers.get('Content-Length', 0))
161
    
162
    with open(filename, 'wb') as f:
163
        with Bar(label=f'Downloading {filename}: ', 
164
                 expected_size=total_size) as progress_bar:
165
            downloaded = 0
166
            for chunk in response.iter_content(chunk_size=8192):
167
                if chunk:
168
                    f.write(chunk)
169
                    downloaded += len(chunk)
170
                    progress_bar.show(downloaded)
171

172
# Nested progress bars for complex operations
173
def process_files(file_list):
174
    for file_path in bar(file_list, label='Files: '):
175
        with open(file_path, 'r') as f:
176
            lines = f.readlines()
177
            
178
        # Process each line with its own progress bar
179
        processed_lines = []
180
        for line in bar(lines, label=f'  {file_path}: ', width=20):
181
            # Process line
182
            processed_line = line.strip().upper()
183
            processed_lines.append(processed_line)
184
            time.sleep(0.01)
185

186
# Custom update frequency for performance
187
huge_dataset = range(1000000)
188
for item in bar(huge_dataset, label='Big data: ', every=1000):
189
    # Only update progress every 1000 items for better performance
190
    pass
191

192
# Progress bar with error handling
193
def safe_processing(items):
194
    progress_bar = Bar(label='Safe processing: ', expected_size=len(items))
195
    
196
    try:
197
        for i, item in enumerate(items):
198
            try:
199
                # Process item that might fail
200
                result = risky_operation(item)
201
                progress_bar.show(i + 1)
202
            except Exception as e:
203
                # Handle individual item errors
204
                print(f"Error processing item {i}: {e}")
205
                continue
206
    finally:
207
        progress_bar.done()
208

209
# Conditional progress display
210
def process_with_conditional_progress(items, show_progress=True):
211
    if show_progress:
212
        iterator = bar(items, label='Processing: ')
213
    else:
214
        iterator = items
215
    
216
    for item in iterator:
217
        # Process item
218
        pass
219
```
220

221
## Progress Bar Features
222

223
### Automatic TTY Detection
224
- Progress bars are automatically hidden when output is piped or redirected
225
- Use `hide=False` to force display or `hide=True` to force hide
226

227
### ETA Calculation
228
- Progress bars automatically calculate and display estimated time remaining
229
- Uses simple moving average over the last 9 intervals for accuracy
230
- Updates ETA every second to avoid excessive calculation
231

232
### Terminal Width Adaptation
233
- Progress bars adapt to terminal width automatically
234
- Manual width override available via `width` parameter
235

236
### Customization Options
237
- Custom characters for filled and empty portions
238
- Adjustable update frequency for performance optimization
239
- Custom labels and formatting options
240

241
```python
242
# Force progress display even when piped
243
for item in bar(items, hide=False):
244
    pass
245

246
# High-performance mode with reduced updates
247
for item in bar(huge_list, every=100, label='Fast: '):
248
    pass
249

250
# Custom appearance
251
for item in bar(items, filled_char='●', empty_char='○', width=60):
252
    pass
253
```