0
# Core Progress Bars
1

2
Essential progress bar functionality that forms the foundation of tqdm. The core `tqdm` class provides iterator wrapping, manual updates, extensive customization options, and thread-safe operations.
3

4
## Capabilities
5

6
### Main Progress Bar Class
7

8
The core `tqdm` class that wraps iterables and provides progress tracking with extensive customization options for display formatting, update intervals, and output control.
9

10
```python { .api }
11
class tqdm(Comparable):
12
    """
13
    Decorate an iterable object, returning an iterator which acts exactly
14
    like the original iterable, but prints a dynamically updating
15
    progressbar every time a value is requested.
16
    
17
    Parameters:
18
    - iterable: Iterable to decorate with progress meter
19
    - desc: Prefix for progress meter description
20
    - total: The number of expected iterations
21
    - leave: If True, keeps all traces of the progressbar upon termination
22
    - file: Output stream (default: sys.stderr)
23
    - ncols: The width of the entire output message
24
    - mininterval: Minimum progress update interval in seconds (default: 0.1)
25
    - maxinterval: Maximum progress update interval in seconds (default: 10.0)
26
    - miniters: Minimum progress display update interval in iterations
27
    - ascii: If True, use ASCII characters for progress bar
28
    - disable: Whether to disable progress bar entirely
29
    - unit: String defining unit of each iteration (default: 'it')
30
    - unit_scale: If True, number of iterations will be scaled/formatted
31
    - dynamic_ncols: If True, constantly alters ncols to environment
32
    - smoothing: Exponential moving average smoothing factor (0-1)
33
    - bar_format: Custom format string for progress bar
34
    - initial: Initial counter value (default: 0)
35
    - position: Specify line offset to print progress bar
36
    - postfix: Specify additional stats as dict or str
37
    - unit_divisor: Divisor for unit scaling (default: 1000)
38
    - write_bytes: If True and unit_scale, write data size in bytes
39
    - lock_args: Passed to refresh/write lock
40
    - nrows: Screen height for positioning multiple bars
41
    - colour: Bar colour (e.g. 'green', '#00ff00')
42
    - delay: Don't display until at least delay seconds have elapsed
43
    - gui: Internal GUI parameter
44
    """
45
    def __init__(self, iterable=None, desc=None, total=None, leave=True,
46
                 file=None, ncols=None, mininterval=0.1, maxinterval=10.0,
47
                 miniters=None, ascii=None, disable=False, unit='it',
48
                 unit_scale=False, dynamic_ncols=False, smoothing=0.3,
49
                 bar_format=None, initial=0, position=None, postfix=None,
50
                 unit_divisor=1000, write_bytes=False, lock_args=None,
51
                 nrows=None, colour=None, delay=0.0, gui=False, **kwargs): ...
52
```
53

54
### Iterator Interface
55

56
Core iterator methods enabling `tqdm` to wrap any iterable while providing progress tracking functionality.
57

58
```python { .api }
59
def __iter__(self):
60
    """Backward-compatibility to use: for x in tqdm(iterable)"""
61

62
def __next__(self):
63
    """Implementation of iterator protocol"""
64

65
def __enter__(self):
66
    """Context manager entry"""
67
    
68
def __exit__(self, exc_type, exc_value, traceback):
69
    """Context manager exit with cleanup"""
70
```
71

72
### Progress Updates
73

74
Methods for manually controlling progress bar updates, useful when not using iterator interface or when processing doesn't follow simple iteration patterns.
75

76
```python { .api }
77
def update(self, n=1):
78
    """
79
    Manually update progress bar by n steps.
80
    
81
    Parameters:
82
    - n: Number of steps to increment (default: 1)
83
    
84
    Returns:
85
    True if progress display was updated, False otherwise
86
    """
87

88
def refresh(self, nolock=False):
89
    """Force refresh display, potentially interrupting output"""
90

91
def reset(self, total=None):
92
    """
93
    Resets to 0 iterations for repeated use.
94
    
95
    Parameters:
96
    - total: New total iterations (defaults to current total)
97
    """
98

99
def close(self):
100
    """Cleanup and close progress bar, removing it if leave=False"""
101

102
def clear(self, nolock=False):
103
    """Clear current progress bar display"""
104

105
def unpause(self):
106
    """Restart tqdm timer from last print time"""
107
```
108

109
### Display Customization
110

111
Methods for dynamically updating progress bar appearance and information display during execution.
112

113
```python { .api }
114
def set_description(self, desc=None, refresh=True):
115
    """
116
    Set/update description prefix.
117
    
118
    Parameters:
119
    - desc: New description string
120
    - refresh: Whether to refresh display immediately
121
    """
122

123
def set_description_str(self, desc=None, refresh=True):
124
    """Set/update description without parsing"""
125

126
def set_postfix(self, ordered_dict=None, refresh=True, **kwargs):
127
    """
128
    Set/update postfix (additional stats) displayed after progress bar.
129
    
130
    Parameters:
131
    - ordered_dict: Dict of stats to display
132
    - refresh: Whether to refresh display immediately
133
    - **kwargs: Additional stats as keyword arguments
134
    """
135

136
def set_postfix_str(self, s='', refresh=True):
137
    """Set postfix string directly without formatting"""
138

139
def moveto(self, n):
140
    """Move cursor to line n for multi-bar displays"""
141
```
142

143
### Information Access
144

145
Methods to retrieve current progress state and formatting information programmatically.
146

147
```python { .api }
148
def format_dict(self):
149
    """
150
    Return current status as a formatted dictionary.
151
    
152
    Returns:
153
    Dict containing: n, total, elapsed, ncols, nrows, prefix, ascii, unit, 
154
    unit_scale, rate, bar_format, postfix, unit_divisor, initial, colour
155
    """
156

157
def display(self, msg=None, pos=None):
158
    """
159
    Use print() to display message, temporarily clearing progress bar.
160
    
161
    Parameters:
162
    - msg: Message to display (defaults to current progress)
163
    - pos: Position for display (defaults to current position)
164
    """
165

166
@property
167
def format_meter(self):
168
    """Current progress bar string representation"""
169
```
170

171
### Class Methods - Thread Safety
172

173
Thread-safe operations for concurrent environments, enabling safe output and lock management across multiple threads.
174

175
```python { .api }
176
@classmethod
177
def write(cls, s, file=None, end="\n", nolock=False):
178
    """
179
    Print message via tqdm, clearing all progress bars temporarily.
180
    
181
    Parameters:
182
    - s: String message to print
183
    - file: Output stream (defaults to sys.stderr)
184
    - end: String appended after last value (default: newline)
185
    - nolock: If True, don't acquire/release lock
186
    """
187

188
@classmethod
189
def external_write_mode(cls, file=None, nolock=False):
190
    """
191
    Context manager for temporarily disabling progress bars for external writes.
192
    
193
    Parameters:
194
    - file: Output stream to manage
195
    - nolock: If True, don't acquire lock
196
    
197
    Yields:
198
    Context where external writes won't interfere with progress bars
199
    """
200

201
@classmethod
202
def set_lock(cls, lock):
203
    """Set lock for thread-safe operations"""
204
    
205
@classmethod
206
def get_lock(cls):
207
    """Get current lock object"""
208
```
209

210
### Class Methods - Integrations
211

212
High-level integration methods for popular libraries and common use cases.
213

214
```python { .api }
215
@classmethod
216
def pandas(cls, **tqdm_kwargs):
217
    """
218
    Register tqdm instance for pandas operations.
219
    Enables .progress_apply() and similar methods on DataFrames.
220
    
221
    Parameters:
222
    - **tqdm_kwargs: Arguments passed to tqdm constructor
223
    
224
    Returns:
225
    Deprecated TqdmPandas instance (for backward compatibility)
226
    """
227

228
@classmethod  
229
def wrapattr(cls, stream, method, total=None, bytes=True, **tqdm_kwargs):
230
    """
231
    Stream attribute wrapper with progress bar.
232
    
233
    Parameters:
234
    - stream: IO stream object
235
    - method: Attribute name to wrap (e.g., 'read', 'write')
236
    - total: Total expected bytes/calls
237
    - bytes: If True, update by bytes; if False, by method calls
238
    - **tqdm_kwargs: Additional tqdm arguments
239
    
240
    Returns:
241
    Wrapped stream object
242
    """
243
```
244

245
### Static Methods - Formatting
246

247
Utility methods for consistent number and time formatting across tqdm displays.
248

249
```python { .api }
250
@staticmethod
251
def format_sizeof(num, suffix='', divisor=1000):
252
    """
253
    Format numbers with metric prefixes (k, M, G, T, P, E, Z, Y).
254
    
255
    Parameters:
256
    - num: Number to format
257
    - suffix: Unit suffix (e.g., 'B' for bytes)
258
    - divisor: Base for scaling (1000 or 1024)
259
    
260
    Returns:
261
    Formatted string with appropriate prefix
262
    """
263

264
@staticmethod
265
def format_interval(t):
266
    """
267
    Format time intervals as human-readable strings.
268
    
269
    Parameters:
270
    - t: Time interval in seconds
271
    
272
    Returns:
273
    Formatted time string (e.g., '1:23:45', '2.5s')
274
    """
275

276
@staticmethod
277
def format_num(n):
278
    """
279
    Intelligent number formatting with appropriate precision.
280
    
281
    Parameters:
282
    - n: Number to format
283
    
284
    Returns:
285
    Formatted number string
286
    """
287

288
@staticmethod
289
def status_printer(file):
290
    """
291
    Create status printer function for custom output streams.
292
    
293
    Parameters:
294
    - file: Output stream
295
    
296
    Returns:
297
    Function(s) -> prints status to file
298
    """
299
```
300

301
### Range Shortcut Function
302

303
Convenience function combining `range()` with tqdm for simple counting loops with progress bars.
304

305
```python { .api }
306
def trange(*args, **kwargs):
307
    """
308
    Shortcut for tqdm(range(*args), **kwargs).
309
    
310
    Parameters:
311
    - *args: Arguments passed to range()
312
    - **kwargs: Arguments passed to tqdm constructor
313
    
314
    Returns:
315
    tqdm instance wrapping range iterator
316
    """
317
```
318

319
## Usage Examples
320

321
### Basic Iterator Wrapping
322

323
```python
324
from tqdm import tqdm
325
import time
326

327
# Wrap any iterable
328
data = range(1000)
329
for item in tqdm(data, desc="Processing"):
330
    time.sleep(0.001)  # Simulate work
331

332
# Direct iteration with custom formatting
333
for i in tqdm(range(1000), unit="items", unit_scale=True):
334
    pass
335
```
336

337
### Manual Progress Updates
338

339
```python
340
from tqdm import tqdm
341
import time
342

343
# Manual updates with known total
344
pbar = tqdm(total=100, desc="Manual Progress")
345
for i in range(100):
346
    # Do some work
347
    time.sleep(0.01)
348
    pbar.update(1)
349
pbar.close()
350

351
# Context manager ensures cleanup
352
with tqdm(total=1000, desc="Batch Processing") as pbar:
353
    batch_size = 50
354
    for batch_start in range(0, 1000, batch_size):
355
        # Process batch
356
        time.sleep(0.1)
357
        pbar.update(batch_size)
358
```
359

360
### Dynamic Updates and Customization
361

362
```python
363
from tqdm import tqdm
364
import time
365
import random
366

367
# Dynamic description and postfix
368
pbar = tqdm(range(100), desc="Training")
369
for epoch in pbar:
370
    # Simulate training metrics
371
    loss = random.uniform(0.1, 1.0)
372
    accuracy = random.uniform(0.8, 0.99)
373
    
374
    # Update description and postfix
375
    pbar.set_description(f"Epoch {epoch}")
376
    pbar.set_postfix({
377
        'loss': f'{loss:.3f}',
378
        'acc': f'{accuracy:.2%}'
379
    })
380
    time.sleep(0.05)
381
```
382

383
### Thread-Safe Operations
384

385
```python
386
from tqdm import tqdm
387
import threading
388
import time
389

390
def worker(worker_id):
391
    for i in tqdm(range(100), desc=f"Worker {worker_id}", position=worker_id):
392
        time.sleep(0.01)
393
        # Thread-safe printing
394
        if i % 20 == 0:
395
            tqdm.write(f"Worker {worker_id}: checkpoint at {i}")
396

397
# Create multiple worker threads
398
threads = []
399
for i in range(3):
400
    t = threading.Thread(target=worker, args=(i,))
401
    threads.append(t)
402
    t.start()
403

404
for t in threads:
405
    t.join()
406
```
407

408
### Custom Bar Formatting
409

410
```python
411
from tqdm import tqdm
412
import time
413

414
# Custom bar format
415
custom_format = "{desc}: {percentage:3.0f}%|{bar:50}| {n_fmt}/{total_fmt} [{elapsed}<{remaining}, {rate_fmt}]"
416

417
for i in tqdm(range(1000), desc="Custom Format", bar_format=custom_format):
418
    time.sleep(0.001)
419

420
# Minimal format
421
minimal_format = "{desc} {percentage:3.0f}% {bar}"
422
for i in tqdm(range(500), desc="Minimal", bar_format=minimal_format):
423
    time.sleep(0.002)
424
```
425

426
## Exception Classes
427

428
### TqdmTypeError
429

430
```python { .api }
431
class TqdmTypeError(TypeError):
432
    """Type-related errors in tqdm configuration or usage"""
433
```
434

435
### TqdmKeyError  
436

437
```python { .api }
438
class TqdmKeyError(KeyError):
439
    """Key-related errors in tqdm parameter specification"""
440
```
441

442
### TqdmWarning
443

444
```python { .api }
445
class TqdmWarning(Warning):
446
    """
447
    Base class for all tqdm warnings.
448
    Used for non-external-code-breaking errors, such as garbled printing.
449
    """
450
    def __init__(self, msg, fp_write=None, *a, **k): ...
451
```
452

453
### TqdmExperimentalWarning
454

455
```python { .api }
456
class TqdmExperimentalWarning(TqdmWarning, FutureWarning):
457
    """Warnings for experimental features that may change in future versions"""
458
```
459

460
### TqdmDeprecationWarning
461

462
```python { .api }
463
class TqdmDeprecationWarning(TqdmWarning, DeprecationWarning):
464
    """Warnings for deprecated features scheduled for removal"""
465
```
466

467
### TqdmMonitorWarning
468

469
```python { .api }
470
class TqdmMonitorWarning(TqdmWarning, RuntimeWarning):
471
    """Runtime warnings from the TMonitor monitoring thread"""
472
```