Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/lib/python3.8/site-packages/tqdm-4.67.1.dist-info/METADATA @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 69:33d812a61356
1 Metadata-Version: 2.1
2 Name: tqdm
3 Version: 4.67.1
4 Summary: Fast, Extensible Progress Meter
5 Maintainer-email: tqdm developers <devs@tqdm.ml>
6 License: MPL-2.0 AND MIT
7 Project-URL: homepage, https://tqdm.github.io
8 Project-URL: repository, https://github.com/tqdm/tqdm
9 Project-URL: changelog, https://tqdm.github.io/releases
10 Project-URL: wiki, https://github.com/tqdm/tqdm/wiki
11 Keywords: progressbar,progressmeter,progress,bar,meter,rate,eta,console,terminal,time
12 Classifier: Development Status :: 5 - Production/Stable
13 Classifier: Environment :: Console
14 Classifier: Environment :: MacOS X
15 Classifier: Environment :: Other Environment
16 Classifier: Environment :: Win32 (MS Windows)
17 Classifier: Environment :: X11 Applications
18 Classifier: Framework :: IPython
19 Classifier: Framework :: Jupyter
20 Classifier: Intended Audience :: Developers
21 Classifier: Intended Audience :: Education
22 Classifier: Intended Audience :: End Users/Desktop
23 Classifier: Intended Audience :: Other Audience
24 Classifier: Intended Audience :: System Administrators
25 Classifier: License :: OSI Approved :: MIT License
26 Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
27 Classifier: Operating System :: MacOS
28 Classifier: Operating System :: MacOS :: MacOS X
29 Classifier: Operating System :: Microsoft
30 Classifier: Operating System :: Microsoft :: MS-DOS
31 Classifier: Operating System :: Microsoft :: Windows
32 Classifier: Operating System :: POSIX
33 Classifier: Operating System :: POSIX :: BSD
34 Classifier: Operating System :: POSIX :: BSD :: FreeBSD
35 Classifier: Operating System :: POSIX :: Linux
36 Classifier: Operating System :: POSIX :: SunOS/Solaris
37 Classifier: Operating System :: Unix
38 Classifier: Programming Language :: Python
39 Classifier: Programming Language :: Python :: 3
40 Classifier: Programming Language :: Python :: 3.7
41 Classifier: Programming Language :: Python :: 3.8
42 Classifier: Programming Language :: Python :: 3.9
43 Classifier: Programming Language :: Python :: 3.10
44 Classifier: Programming Language :: Python :: 3.11
45 Classifier: Programming Language :: Python :: 3.12
46 Classifier: Programming Language :: Python :: 3 :: Only
47 Classifier: Programming Language :: Python :: Implementation
48 Classifier: Programming Language :: Python :: Implementation :: IronPython
49 Classifier: Programming Language :: Python :: Implementation :: PyPy
50 Classifier: Programming Language :: Unix Shell
51 Classifier: Topic :: Desktop Environment
52 Classifier: Topic :: Education :: Computer Aided Instruction (CAI)
53 Classifier: Topic :: Education :: Testing
54 Classifier: Topic :: Office/Business
55 Classifier: Topic :: Other/Nonlisted Topic
56 Classifier: Topic :: Software Development :: Build Tools
57 Classifier: Topic :: Software Development :: Libraries
58 Classifier: Topic :: Software Development :: Libraries :: Python Modules
59 Classifier: Topic :: Software Development :: Pre-processors
60 Classifier: Topic :: Software Development :: User Interfaces
61 Classifier: Topic :: System :: Installation/Setup
62 Classifier: Topic :: System :: Logging
63 Classifier: Topic :: System :: Monitoring
64 Classifier: Topic :: System :: Shells
65 Classifier: Topic :: Terminals
66 Classifier: Topic :: Utilities
67 Requires-Python: >=3.7
68 Description-Content-Type: text/x-rst
69 License-File: LICENCE
70 Requires-Dist: colorama; platform_system == "Windows"
71 Provides-Extra: dev
72 Requires-Dist: pytest>=6; extra == "dev"
73 Requires-Dist: pytest-cov; extra == "dev"
74 Requires-Dist: pytest-timeout; extra == "dev"
75 Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
76 Requires-Dist: nbval; extra == "dev"
77 Provides-Extra: discord
78 Requires-Dist: requests; extra == "discord"
79 Provides-Extra: slack
80 Requires-Dist: slack-sdk; extra == "slack"
81 Provides-Extra: telegram
82 Requires-Dist: requests; extra == "telegram"
83 Provides-Extra: notebook
84 Requires-Dist: ipywidgets>=6; extra == "notebook"
85
86 |Logo|
87
88 tqdm
89 ====
90
91 |Py-Versions| |Versions| |Conda-Forge-Status| |Docker| |Snapcraft|
92
93 |Build-Status| |Coverage-Status| |Branch-Coverage-Status| |Codacy-Grade| |Libraries-Rank| |PyPI-Downloads|
94
95 |LICENCE| |OpenHub-Status| |binder-demo| |awesome-python|
96
97 ``tqdm`` derives from the Arabic word *taqaddum* (تقدّم) which can mean "progress,"
98 and is an abbreviation for "I love you so much" in Spanish (*te quiero demasiado*).
99
100 Instantly make your loops show a smart progress meter - just wrap any
101 iterable with ``tqdm(iterable)``, and you're done!
102
103 .. code:: python
104
105 from tqdm import tqdm
106 for i in tqdm(range(10000)):
107 ...
108
109 ``76%|████████████████████████        | 7568/10000 [00:33<00:10, 229.00it/s]``
110
111 ``trange(N)`` can be also used as a convenient shortcut for
112 ``tqdm(range(N))``.
113
114 |Screenshot|
115 |Video| |Slides| |Merch|
116
117 It can also be executed as a module with pipes:
118
119 .. code:: sh
120
121 $ seq 9999999 | tqdm --bytes | wc -l
122 75.2MB [00:00, 217MB/s]
123 9999999
124
125 $ tar -zcf - docs/ | tqdm --bytes --total `du -sb docs/ | cut -f1` \
126 > backup.tgz
127 32%|██████████▍ | 8.89G/27.9G [00:42<01:31, 223MB/s]
128
129 Overhead is low -- about 60ns per iteration (80ns with ``tqdm.gui``), and is
130 unit tested against performance regression.
131 By comparison, the well-established
132 `ProgressBar <https://github.com/niltonvolpato/python-progressbar>`__ has
133 an 800ns/iter overhead.
134
135 In addition to its low overhead, ``tqdm`` uses smart algorithms to predict
136 the remaining time and to skip unnecessary iteration displays, which allows
137 for a negligible overhead in most cases.
138
139 ``tqdm`` works on any platform
140 (Linux, Windows, Mac, FreeBSD, NetBSD, Solaris/SunOS),
141 in any console or in a GUI, and is also friendly with IPython/Jupyter notebooks.
142
143 ``tqdm`` does not require any dependencies (not even ``curses``!), just
144 Python and an environment supporting ``carriage return \r`` and
145 ``line feed \n`` control characters.
146
147 ------------------------------------------
148
149 .. contents:: Table of contents
150 :backlinks: top
151 :local:
152
153
154 Installation
155 ------------
156
157 Latest PyPI stable release
158 ~~~~~~~~~~~~~~~~~~~~~~~~~~
159
160 |Versions| |PyPI-Downloads| |Libraries-Dependents|
161
162 .. code:: sh
163
164 pip install tqdm
165
166 Latest development release on GitHub
167 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
168
169 |GitHub-Status| |GitHub-Stars| |GitHub-Commits| |GitHub-Forks| |GitHub-Updated|
170
171 Pull and install pre-release ``devel`` branch:
172
173 .. code:: sh
174
175 pip install "git+https://github.com/tqdm/tqdm.git@devel#egg=tqdm"
176
177 Latest Conda release
178 ~~~~~~~~~~~~~~~~~~~~
179
180 |Conda-Forge-Status|
181
182 .. code:: sh
183
184 conda install -c conda-forge tqdm
185
186 Latest Snapcraft release
187 ~~~~~~~~~~~~~~~~~~~~~~~~
188
189 |Snapcraft|
190
191 There are 3 channels to choose from:
192
193 .. code:: sh
194
195 snap install tqdm # implies --stable, i.e. latest tagged release
196 snap install tqdm --candidate # master branch
197 snap install tqdm --edge # devel branch
198
199 Note that ``snap`` binaries are purely for CLI use (not ``import``-able), and
200 automatically set up ``bash`` tab-completion.
201
202 Latest Docker release
203 ~~~~~~~~~~~~~~~~~~~~~
204
205 |Docker|
206
207 .. code:: sh
208
209 docker pull tqdm/tqdm
210 docker run -i --rm tqdm/tqdm --help
211
212 Other
213 ~~~~~
214
215 There are other (unofficial) places where ``tqdm`` may be downloaded, particularly for CLI use:
216
217 |Repology|
218
219 .. |Repology| image:: https://repology.org/badge/tiny-repos/python:tqdm.svg
220 :target: https://repology.org/project/python:tqdm/versions
221
222 Changelog
223 ---------
224
225 The list of all changes is available either on GitHub's Releases:
226 |GitHub-Status|, on the
227 `wiki <https://github.com/tqdm/tqdm/wiki/Releases>`__, or on the
228 `website <https://tqdm.github.io/releases>`__.
229
230
231 Usage
232 -----
233
234 ``tqdm`` is very versatile and can be used in a number of ways.
235 The three main ones are given below.
236
237 Iterable-based
238 ~~~~~~~~~~~~~~
239
240 Wrap ``tqdm()`` around any iterable:
241
242 .. code:: python
243
244 from tqdm import tqdm
245 from time import sleep
246
247 text = ""
248 for char in tqdm(["a", "b", "c", "d"]):
249 sleep(0.25)
250 text = text + char
251
252 ``trange(i)`` is a special optimised instance of ``tqdm(range(i))``:
253
254 .. code:: python
255
256 from tqdm import trange
257
258 for i in trange(100):
259 sleep(0.01)
260
261 Instantiation outside of the loop allows for manual control over ``tqdm()``:
262
263 .. code:: python
264
265 pbar = tqdm(["a", "b", "c", "d"])
266 for char in pbar:
267 sleep(0.25)
268 pbar.set_description("Processing %s" % char)
269
270 Manual
271 ~~~~~~
272
273 Manual control of ``tqdm()`` updates using a ``with`` statement:
274
275 .. code:: python
276
277 with tqdm(total=100) as pbar:
278 for i in range(10):
279 sleep(0.1)
280 pbar.update(10)
281
282 If the optional variable ``total`` (or an iterable with ``len()``) is
283 provided, predictive stats are displayed.
284
285 ``with`` is also optional (you can just assign ``tqdm()`` to a variable,
286 but in this case don't forget to ``del`` or ``close()`` at the end:
287
288 .. code:: python
289
290 pbar = tqdm(total=100)
291 for i in range(10):
292 sleep(0.1)
293 pbar.update(10)
294 pbar.close()
295
296 Module
297 ~~~~~~
298
299 Perhaps the most wonderful use of ``tqdm`` is in a script or on the command
300 line. Simply inserting ``tqdm`` (or ``python -m tqdm``) between pipes will pass
301 through all ``stdin`` to ``stdout`` while printing progress to ``stderr``.
302
303 The example below demonstrate counting the number of lines in all Python files
304 in the current directory, with timing information included.
305
306 .. code:: sh
307
308 $ time find . -name '*.py' -type f -exec cat \{} \; | wc -l
309 857365
310
311 real 0m3.458s
312 user 0m0.274s
313 sys 0m3.325s
314
315 $ time find . -name '*.py' -type f -exec cat \{} \; | tqdm | wc -l
316 857366it [00:03, 246471.31it/s]
317 857365
318
319 real 0m3.585s
320 user 0m0.862s
321 sys 0m3.358s
322
323 Note that the usual arguments for ``tqdm`` can also be specified.
324
325 .. code:: sh
326
327 $ find . -name '*.py' -type f -exec cat \{} \; |
328 tqdm --unit loc --unit_scale --total 857366 >> /dev/null
329 100%|█████████████████████████████████| 857K/857K [00:04<00:00, 246Kloc/s]
330
331 Backing up a large directory?
332
333 .. code:: sh
334
335 $ tar -zcf - docs/ | tqdm --bytes --total `du -sb docs/ | cut -f1` \
336 > backup.tgz
337 44%|██████████████▊ | 153M/352M [00:14<00:18, 11.0MB/s]
338
339 This can be beautified further:
340
341 .. code:: sh
342
343 $ BYTES=$(du -sb docs/ | cut -f1)
344 $ tar -cf - docs/ \
345 | tqdm --bytes --total "$BYTES" --desc Processing | gzip \
346 | tqdm --bytes --total "$BYTES" --desc Compressed --position 1 \
347 > ~/backup.tgz
348 Processing: 100%|██████████████████████| 352M/352M [00:14<00:00, 30.2MB/s]
349 Compressed: 42%|█████████▎ | 148M/352M [00:14<00:19, 10.9MB/s]
350
351 Or done on a file level using 7-zip:
352
353 .. code:: sh
354
355 $ 7z a -bd -r backup.7z docs/ | grep Compressing \
356 | tqdm --total $(find docs/ -type f | wc -l) --unit files \
357 | grep -v Compressing
358 100%|██████████████████████████▉| 15327/15327 [01:00<00:00, 712.96files/s]
359
360 Pre-existing CLI programs already outputting basic progress information will
361 benefit from ``tqdm``'s ``--update`` and ``--update_to`` flags:
362
363 .. code:: sh
364
365 $ seq 3 0.1 5 | tqdm --total 5 --update_to --null
366 100%|████████████████████████████████████| 5.0/5 [00:00<00:00, 9673.21it/s]
367 $ seq 10 | tqdm --update --null # 1 + 2 + ... + 10 = 55 iterations
368 55it [00:00, 90006.52it/s]
369
370 FAQ and Known Issues
371 --------------------
372
373 |GitHub-Issues|
374
375 The most common issues relate to excessive output on multiple lines, instead
376 of a neat one-line progress bar.
377
378 - Consoles in general: require support for carriage return (``CR``, ``\r``).
379
380 * Some cloud logging consoles which don't support ``\r`` properly
381 (`cloudwatch <https://github.com/tqdm/tqdm/issues/966>`__,
382 `K8s <https://github.com/tqdm/tqdm/issues/1319>`__) may benefit from
383 ``export TQDM_POSITION=-1``.
384
385 - Nested progress bars:
386
387 * Consoles in general: require support for moving cursors up to the
388 previous line. For example,
389 `IDLE <https://github.com/tqdm/tqdm/issues/191#issuecomment-230168030>`__,
390 `ConEmu <https://github.com/tqdm/tqdm/issues/254>`__ and
391 `PyCharm <https://github.com/tqdm/tqdm/issues/203>`__ (also
392 `here <https://github.com/tqdm/tqdm/issues/208>`__,
393 `here <https://github.com/tqdm/tqdm/issues/307>`__, and
394 `here <https://github.com/tqdm/tqdm/issues/454#issuecomment-335416815>`__)
395 lack full support.
396 * Windows: additionally may require the Python module ``colorama``
397 to ensure nested bars stay within their respective lines.
398
399 - Unicode:
400
401 * Environments which report that they support unicode will have solid smooth
402 progressbars. The fallback is an ``ascii``-only bar.
403 * Windows consoles often only partially support unicode and thus
404 `often require explicit ascii=True <https://github.com/tqdm/tqdm/issues/454#issuecomment-335416815>`__
405 (also `here <https://github.com/tqdm/tqdm/issues/499>`__). This is due to
406 either normal-width unicode characters being incorrectly displayed as
407 "wide", or some unicode characters not rendering.
408
409 - Wrapping generators:
410
411 * Generator wrapper functions tend to hide the length of iterables.
412 ``tqdm`` does not.
413 * Replace ``tqdm(enumerate(...))`` with ``enumerate(tqdm(...))`` or
414 ``tqdm(enumerate(x), total=len(x), ...)``.
415 The same applies to ``numpy.ndenumerate``.
416 * Replace ``tqdm(zip(a, b))`` with ``zip(tqdm(a), b)`` or even
417 ``zip(tqdm(a), tqdm(b))``.
418 * The same applies to ``itertools``.
419 * Some useful convenience functions can be found under ``tqdm.contrib``.
420
421 - `No intermediate output in docker-compose <https://github.com/tqdm/tqdm/issues/771>`__:
422 use ``docker-compose run`` instead of ``docker-compose up`` and ``tty: true``.
423
424 - Overriding defaults via environment variables:
425 e.g. in CI/cloud jobs, ``export TQDM_MININTERVAL=5`` to avoid log spam.
426 This override logic is handled by the ``tqdm.utils.envwrap`` decorator
427 (useful independent of ``tqdm``).
428
429 If you come across any other difficulties, browse and file |GitHub-Issues|.
430
431 Documentation
432 -------------
433
434 |Py-Versions| |README-Hits| (Since 19 May 2016)
435
436 .. code:: python
437
438 class tqdm():
439 """
440 Decorate an iterable object, returning an iterator which acts exactly
441 like the original iterable, but prints a dynamically updating
442 progressbar every time a value is requested.
443 """
444
445 @envwrap("TQDM_") # override defaults via env vars
446 def __init__(self, iterable=None, desc=None, total=None, leave=True,
447 file=None, ncols=None, mininterval=0.1,
448 maxinterval=10.0, miniters=None, ascii=None, disable=False,
449 unit='it', unit_scale=False, dynamic_ncols=False,
450 smoothing=0.3, bar_format=None, initial=0, position=None,
451 postfix=None, unit_divisor=1000, write_bytes=False,
452 lock_args=None, nrows=None, colour=None, delay=0):
453
454 Parameters
455 ~~~~~~~~~~
456
457 * iterable : iterable, optional
458 Iterable to decorate with a progressbar.
459 Leave blank to manually manage the updates.
460 * desc : str, optional
461 Prefix for the progressbar.
462 * total : int or float, optional
463 The number of expected iterations. If unspecified,
464 len(iterable) is used if possible. If float("inf") or as a last
465 resort, only basic progress statistics are displayed
466 (no ETA, no progressbar).
467 If ``gui`` is True and this parameter needs subsequent updating,
468 specify an initial arbitrary large positive number,
469 e.g. 9e9.
470 * leave : bool, optional
471 If [default: True], keeps all traces of the progressbar
472 upon termination of iteration.
473 If ``None``, will leave only if ``position`` is ``0``.
474 * file : ``io.TextIOWrapper`` or ``io.StringIO``, optional
475 Specifies where to output the progress messages
476 (default: sys.stderr). Uses ``file.write(str)`` and ``file.flush()``
477 methods. For encoding, see ``write_bytes``.
478 * ncols : int, optional
479 The width of the entire output message. If specified,
480 dynamically resizes the progressbar to stay within this bound.
481 If unspecified, attempts to use environment width. The
482 fallback is a meter width of 10 and no limit for the counter and
483 statistics. If 0, will not print any meter (only stats).
484 * mininterval : float, optional
485 Minimum progress display update interval [default: 0.1] seconds.
486 * maxinterval : float, optional
487 Maximum progress display update interval [default: 10] seconds.
488 Automatically adjusts ``miniters`` to correspond to ``mininterval``
489 after long display update lag. Only works if ``dynamic_miniters``
490 or monitor thread is enabled.
491 * miniters : int or float, optional
492 Minimum progress display update interval, in iterations.
493 If 0 and ``dynamic_miniters``, will automatically adjust to equal
494 ``mininterval`` (more CPU efficient, good for tight loops).
495 If > 0, will skip display of specified number of iterations.
496 Tweak this and ``mininterval`` to get very efficient loops.
497 If your progress is erratic with both fast and slow iterations
498 (network, skipping items, etc) you should set miniters=1.
499 * ascii : bool or str, optional
500 If unspecified or False, use unicode (smooth blocks) to fill
501 the meter. The fallback is to use ASCII characters " 123456789#".
502 * disable : bool, optional
503 Whether to disable the entire progressbar wrapper
504 [default: False]. If set to None, disable on non-TTY.
505 * unit : str, optional
506 String that will be used to define the unit of each iteration
507 [default: it].
508 * unit_scale : bool or int or float, optional
509 If 1 or True, the number of iterations will be reduced/scaled
510 automatically and a metric prefix following the
511 International System of Units standard will be added
512 (kilo, mega, etc.) [default: False]. If any other non-zero
513 number, will scale ``total`` and ``n``.
514 * dynamic_ncols : bool, optional
515 If set, constantly alters ``ncols`` and ``nrows`` to the
516 environment (allowing for window resizes) [default: False].
517 * smoothing : float, optional
518 Exponential moving average smoothing factor for speed estimates
519 (ignored in GUI mode). Ranges from 0 (average speed) to 1
520 (current/instantaneous speed) [default: 0.3].
521 * bar_format : str, optional
522 Specify a custom bar string formatting. May impact performance.
523 [default: '{l_bar}{bar}{r_bar}'], where
524 l_bar='{desc}: {percentage:3.0f}%|' and
525 r_bar='| {n_fmt}/{total_fmt} [{elapsed}<{remaining}, '
526 '{rate_fmt}{postfix}]'
527 Possible vars: l_bar, bar, r_bar, n, n_fmt, total, total_fmt,
528 percentage, elapsed, elapsed_s, ncols, nrows, desc, unit,
529 rate, rate_fmt, rate_noinv, rate_noinv_fmt,
530 rate_inv, rate_inv_fmt, postfix, unit_divisor,
531 remaining, remaining_s, eta.
532 Note that a trailing ": " is automatically removed after {desc}
533 if the latter is empty.
534 * initial : int or float, optional
535 The initial counter value. Useful when restarting a progress
536 bar [default: 0]. If using float, consider specifying ``{n:.3f}``
537 or similar in ``bar_format``, or specifying ``unit_scale``.
538 * position : int, optional
539 Specify the line offset to print this bar (starting from 0)
540 Automatic if unspecified.
541 Useful to manage multiple bars at once (eg, from threads).
542 * postfix : dict or ``*``, optional
543 Specify additional stats to display at the end of the bar.
544 Calls ``set_postfix(**postfix)`` if possible (dict).
545 * unit_divisor : float, optional
546 [default: 1000], ignored unless ``unit_scale`` is True.
547 * write_bytes : bool, optional
548 Whether to write bytes. If (default: False) will write unicode.
549 * lock_args : tuple, optional
550 Passed to ``refresh`` for intermediate output
551 (initialisation, iterating, and updating).
552 * nrows : int, optional
553 The screen height. If specified, hides nested bars outside this
554 bound. If unspecified, attempts to use environment height.
555 The fallback is 20.
556 * colour : str, optional
557 Bar colour (e.g. 'green', '#00ff00').
558 * delay : float, optional
559 Don't display until [default: 0] seconds have elapsed.
560
561 Extra CLI Options
562 ~~~~~~~~~~~~~~~~~
563
564 * delim : chr, optional
565 Delimiting character [default: '\n']. Use '\0' for null.
566 N.B.: on Windows systems, Python converts '\n' to '\r\n'.
567 * buf_size : int, optional
568 String buffer size in bytes [default: 256]
569 used when ``delim`` is specified.
570 * bytes : bool, optional
571 If true, will count bytes, ignore ``delim``, and default
572 ``unit_scale`` to True, ``unit_divisor`` to 1024, and ``unit`` to 'B'.
573 * tee : bool, optional
574 If true, passes ``stdin`` to both ``stderr`` and ``stdout``.
575 * update : bool, optional
576 If true, will treat input as newly elapsed iterations,
577 i.e. numbers to pass to ``update()``. Note that this is slow
578 (~2e5 it/s) since every input must be decoded as a number.
579 * update_to : bool, optional
580 If true, will treat input as total elapsed iterations,
581 i.e. numbers to assign to ``self.n``. Note that this is slow
582 (~2e5 it/s) since every input must be decoded as a number.
583 * null : bool, optional
584 If true, will discard input (no stdout).
585 * manpath : str, optional
586 Directory in which to install tqdm man pages.
587 * comppath : str, optional
588 Directory in which to place tqdm completion.
589 * log : str, optional
590 CRITICAL|FATAL|ERROR|WARN(ING)|[default: 'INFO']|DEBUG|NOTSET.
591
592 Returns
593 ~~~~~~~
594
595 * out : decorated iterator.
596
597 .. code:: python
598
599 class tqdm():
600 def update(self, n=1):
601 """
602 Manually update the progress bar, useful for streams
603 such as reading files.
604 E.g.:
605 >>> t = tqdm(total=filesize) # Initialise
606 >>> for current_buffer in stream:
607 ... ...
608 ... t.update(len(current_buffer))
609 >>> t.close()
610 The last line is highly recommended, but possibly not necessary if
611 ``t.update()`` will be called in such a way that ``filesize`` will be
612 exactly reached and printed.
613
614 Parameters
615 ----------
616 n : int or float, optional
617 Increment to add to the internal counter of iterations
618 [default: 1]. If using float, consider specifying ``{n:.3f}``
619 or similar in ``bar_format``, or specifying ``unit_scale``.
620
621 Returns
622 -------
623 out : bool or None
624 True if a ``display()`` was triggered.
625 """
626
627 def close(self):
628 """Cleanup and (if leave=False) close the progressbar."""
629
630 def clear(self, nomove=False):
631 """Clear current bar display."""
632
633 def refresh(self):
634 """
635 Force refresh the display of this bar.
636
637 Parameters
638 ----------
639 nolock : bool, optional
640 If ``True``, does not lock.
641 If [default: ``False``]: calls ``acquire()`` on internal lock.
642 lock_args : tuple, optional
643 Passed to internal lock's ``acquire()``.
644 If specified, will only ``display()`` if ``acquire()`` returns ``True``.
645 """
646
647 def unpause(self):
648 """Restart tqdm timer from last print time."""
649
650 def reset(self, total=None):
651 """
652 Resets to 0 iterations for repeated use.
653
654 Consider combining with ``leave=True``.
655
656 Parameters
657 ----------
658 total : int or float, optional. Total to use for the new bar.
659 """
660
661 def set_description(self, desc=None, refresh=True):
662 """
663 Set/modify description of the progress bar.
664
665 Parameters
666 ----------
667 desc : str, optional
668 refresh : bool, optional
669 Forces refresh [default: True].
670 """
671
672 def set_postfix(self, ordered_dict=None, refresh=True, **tqdm_kwargs):
673 """
674 Set/modify postfix (additional stats)
675 with automatic formatting based on datatype.
676
677 Parameters
678 ----------
679 ordered_dict : dict or OrderedDict, optional
680 refresh : bool, optional
681 Forces refresh [default: True].
682 kwargs : dict, optional
683 """
684
685 @classmethod
686 def write(cls, s, file=sys.stdout, end="\n"):
687 """Print a message via tqdm (without overlap with bars)."""
688
689 @property
690 def format_dict(self):
691 """Public API for read-only member access."""
692
693 def display(self, msg=None, pos=None):
694 """
695 Use ``self.sp`` to display ``msg`` in the specified ``pos``.
696
697 Consider overloading this function when inheriting to use e.g.:
698 ``self.some_frontend(**self.format_dict)`` instead of ``self.sp``.
699
700 Parameters
701 ----------
702 msg : str, optional. What to display (default: ``repr(self)``).
703 pos : int, optional. Position to ``moveto``
704 (default: ``abs(self.pos)``).
705 """
706
707 @classmethod
708 @contextmanager
709 def wrapattr(cls, stream, method, total=None, bytes=True, **tqdm_kwargs):
710 """
711 stream : file-like object.
712 method : str, "read" or "write". The result of ``read()`` and
713 the first argument of ``write()`` should have a ``len()``.
714
715 >>> with tqdm.wrapattr(file_obj, "read", total=file_obj.size) as fobj:
716 ... while True:
717 ... chunk = fobj.read(chunk_size)
718 ... if not chunk:
719 ... break
720 """
721
722 @classmethod
723 def pandas(cls, *targs, **tqdm_kwargs):
724 """Registers the current `tqdm` class with `pandas`."""
725
726 def trange(*args, **tqdm_kwargs):
727 """Shortcut for `tqdm(range(*args), **tqdm_kwargs)`."""
728
729 Convenience Functions
730 ~~~~~~~~~~~~~~~~~~~~~
731
732 .. code:: python
733
734 def tqdm.contrib.tenumerate(iterable, start=0, total=None,
735 tqdm_class=tqdm.auto.tqdm, **tqdm_kwargs):
736 """Equivalent of `numpy.ndenumerate` or builtin `enumerate`."""
737
738 def tqdm.contrib.tzip(iter1, *iter2plus, **tqdm_kwargs):
739 """Equivalent of builtin `zip`."""
740
741 def tqdm.contrib.tmap(function, *sequences, **tqdm_kwargs):
742 """Equivalent of builtin `map`."""
743
744 Submodules
745 ~~~~~~~~~~
746
747 .. code:: python
748
749 class tqdm.notebook.tqdm(tqdm.tqdm):
750 """IPython/Jupyter Notebook widget."""
751
752 class tqdm.auto.tqdm(tqdm.tqdm):
753 """Automatically chooses beween `tqdm.notebook` and `tqdm.tqdm`."""
754
755 class tqdm.asyncio.tqdm(tqdm.tqdm):
756 """Asynchronous version."""
757 @classmethod
758 def as_completed(cls, fs, *, loop=None, timeout=None, total=None,
759 **tqdm_kwargs):
760 """Wrapper for `asyncio.as_completed`."""
761
762 class tqdm.gui.tqdm(tqdm.tqdm):
763 """Matplotlib GUI version."""
764
765 class tqdm.tk.tqdm(tqdm.tqdm):
766 """Tkinter GUI version."""
767
768 class tqdm.rich.tqdm(tqdm.tqdm):
769 """`rich.progress` version."""
770
771 class tqdm.keras.TqdmCallback(keras.callbacks.Callback):
772 """Keras callback for epoch and batch progress."""
773
774 class tqdm.dask.TqdmCallback(dask.callbacks.Callback):
775 """Dask callback for task progress."""
776
777
778 ``contrib``
779 +++++++++++
780
781 The ``tqdm.contrib`` package also contains experimental modules:
782
783 - ``tqdm.contrib.itertools``: Thin wrappers around ``itertools``
784 - ``tqdm.contrib.concurrent``: Thin wrappers around ``concurrent.futures``
785 - ``tqdm.contrib.slack``: Posts to `Slack <https://slack.com>`__ bots
786 - ``tqdm.contrib.discord``: Posts to `Discord <https://discord.com>`__ bots
787 - ``tqdm.contrib.telegram``: Posts to `Telegram <https://telegram.org>`__ bots
788 - ``tqdm.contrib.bells``: Automagically enables all optional features
789
790 * ``auto``, ``pandas``, ``slack``, ``discord``, ``telegram``
791
792 Examples and Advanced Usage
793 ---------------------------
794
795 - See the `examples <https://github.com/tqdm/tqdm/tree/master/examples>`__
796 folder;
797 - import the module and run ``help()``;
798 - consult the `wiki <https://github.com/tqdm/tqdm/wiki>`__;
799
800 * this has an
801 `excellent article <https://github.com/tqdm/tqdm/wiki/How-to-make-a-great-Progress-Bar>`__
802 on how to make a **great** progressbar;
803
804 - check out the `slides from PyData London <https://tqdm.github.io/PyData2019/slides.html>`__, or
805 - run the |binder-demo|.
806
807 Description and additional stats
808 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
809
810 Custom information can be displayed and updated dynamically on ``tqdm`` bars
811 with the ``desc`` and ``postfix`` arguments:
812
813 .. code:: python
814
815 from tqdm import tqdm, trange
816 from random import random, randint
817 from time import sleep
818
819 with trange(10) as t:
820 for i in t:
821 # Description will be displayed on the left
822 t.set_description('GEN %i' % i)
823 # Postfix will be displayed on the right,
824 # formatted automatically based on argument's datatype
825 t.set_postfix(loss=random(), gen=randint(1,999), str='h',
826 lst=[1, 2])
827 sleep(0.1)
828
829 with tqdm(total=10, bar_format="{postfix[0]} {postfix[1][value]:>8.2g}",
830 postfix=["Batch", {"value": 0}]) as t:
831 for i in range(10):
832 sleep(0.1)
833 t.postfix[1]["value"] = i / 2
834 t.update()
835
836 Points to remember when using ``{postfix[...]}`` in the ``bar_format`` string:
837
838 - ``postfix`` also needs to be passed as an initial argument in a compatible
839 format, and
840 - ``postfix`` will be auto-converted to a string if it is a ``dict``-like
841 object. To prevent this behaviour, insert an extra item into the dictionary
842 where the key is not a string.
843
844 Additional ``bar_format`` parameters may also be defined by overriding
845 ``format_dict``, and the bar itself may be modified using ``ascii``:
846
847 .. code:: python
848
849 from tqdm import tqdm
850 class TqdmExtraFormat(tqdm):
851 """Provides a `total_time` format parameter"""
852 @property
853 def format_dict(self):
854 d = super().format_dict
855 total_time = d["elapsed"] * (d["total"] or 0) / max(d["n"], 1)
856 d.update(total_time=self.format_interval(total_time) + " in total")
857 return d
858
859 for i in TqdmExtraFormat(
860 range(9), ascii=" .oO0",
861 bar_format="{total_time}: {percentage:.0f}%|{bar}{r_bar}"):
862 if i == 4:
863 break
864
865 .. code::
866
867 00:00 in total: 44%|0000. | 4/9 [00:00<00:00, 962.93it/s]
868
869 Note that ``{bar}`` also supports a format specifier ``[width][type]``.
870
871 - ``width``
872
873 * unspecified (default): automatic to fill ``ncols``
874 * ``int >= 0``: fixed width overriding ``ncols`` logic
875 * ``int < 0``: subtract from the automatic default
876
877 - ``type``
878
879 * ``a``: ascii (``ascii=True`` override)
880 * ``u``: unicode (``ascii=False`` override)
881 * ``b``: blank (``ascii=" "`` override)
882
883 This means a fixed bar with right-justified text may be created by using:
884 ``bar_format="{l_bar}{bar:10}|{bar:-10b}right-justified"``
885
886 Nested progress bars
887 ~~~~~~~~~~~~~~~~~~~~
888
889 ``tqdm`` supports nested progress bars. Here's an example:
890
891 .. code:: python
892
893 from tqdm.auto import trange
894 from time import sleep
895
896 for i in trange(4, desc='1st loop'):
897 for j in trange(5, desc='2nd loop'):
898 for k in trange(50, desc='3rd loop', leave=False):
899 sleep(0.01)
900
901 For manual control over positioning (e.g. for multi-processing use),
902 you may specify ``position=n`` where ``n=0`` for the outermost bar,
903 ``n=1`` for the next, and so on.
904 However, it's best to check if ``tqdm`` can work without manual ``position``
905 first.
906
907 .. code:: python
908
909 from time import sleep
910 from tqdm import trange, tqdm
911 from multiprocessing import Pool, RLock, freeze_support
912
913 L = list(range(9))
914
915 def progresser(n):
916 interval = 0.001 / (n + 2)
917 total = 5000
918 text = f"#{n}, est. {interval * total:<04.2}s"
919 for _ in trange(total, desc=text, position=n):
920 sleep(interval)
921
922 if __name__ == '__main__':
923 freeze_support() # for Windows support
924 tqdm.set_lock(RLock()) # for managing output contention
925 p = Pool(initializer=tqdm.set_lock, initargs=(tqdm.get_lock(),))
926 p.map(progresser, L)
927
928 Note that in Python 3, ``tqdm.write`` is thread-safe:
929
930 .. code:: python
931
932 from time import sleep
933 from tqdm import tqdm, trange
934 from concurrent.futures import ThreadPoolExecutor
935
936 L = list(range(9))
937
938 def progresser(n):
939 interval = 0.001 / (n + 2)
940 total = 5000
941 text = f"#{n}, est. {interval * total:<04.2}s"
942 for _ in trange(total, desc=text):
943 sleep(interval)
944 if n == 6:
945 tqdm.write("n == 6 completed.")
946 tqdm.write("`tqdm.write()` is thread-safe in py3!")
947
948 if __name__ == '__main__':
949 with ThreadPoolExecutor() as p:
950 p.map(progresser, L)
951
952 Hooks and callbacks
953 ~~~~~~~~~~~~~~~~~~~
954
955 ``tqdm`` can easily support callbacks/hooks and manual updates.
956 Here's an example with ``urllib``:
957
958 **``urllib.urlretrieve`` documentation**
959
960 | [...]
961 | If present, the hook function will be called once
962 | on establishment of the network connection and once after each block read
963 | thereafter. The hook will be passed three arguments; a count of blocks
964 | transferred so far, a block size in bytes, and the total size of the file.
965 | [...]
966
967 .. code:: python
968
969 import urllib, os
970 from tqdm import tqdm
971 urllib = getattr(urllib, 'request', urllib)
972
973 class TqdmUpTo(tqdm):
974 """Provides `update_to(n)` which uses `tqdm.update(delta_n)`."""
975 def update_to(self, b=1, bsize=1, tsize=None):
976 """
977 b : int, optional
978 Number of blocks transferred so far [default: 1].
979 bsize : int, optional
980 Size of each block (in tqdm units) [default: 1].
981 tsize : int, optional
982 Total size (in tqdm units). If [default: None] remains unchanged.
983 """
984 if tsize is not None:
985 self.total = tsize
986 return self.update(b * bsize - self.n) # also sets self.n = b * bsize
987
988 eg_link = "https://caspersci.uk.to/matryoshka.zip"
989 with TqdmUpTo(unit='B', unit_scale=True, unit_divisor=1024, miniters=1,
990 desc=eg_link.split('/')[-1]) as t: # all optional kwargs
991 urllib.urlretrieve(eg_link, filename=os.devnull,
992 reporthook=t.update_to, data=None)
993 t.total = t.n
994
995 Inspired by `twine#242 <https://github.com/pypa/twine/pull/242>`__.
996 Functional alternative in
997 `examples/tqdm_wget.py <https://github.com/tqdm/tqdm/blob/master/examples/tqdm_wget.py>`__.
998
999 It is recommend to use ``miniters=1`` whenever there is potentially
1000 large differences in iteration speed (e.g. downloading a file over
1001 a patchy connection).
1002
1003 **Wrapping read/write methods**
1004
1005 To measure throughput through a file-like object's ``read`` or ``write``
1006 methods, use ``CallbackIOWrapper``:
1007
1008 .. code:: python
1009
1010 from tqdm.auto import tqdm
1011 from tqdm.utils import CallbackIOWrapper
1012
1013 with tqdm(total=file_obj.size,
1014 unit='B', unit_scale=True, unit_divisor=1024) as t:
1015 fobj = CallbackIOWrapper(t.update, file_obj, "read")
1016 while True:
1017 chunk = fobj.read(chunk_size)
1018 if not chunk:
1019 break
1020 t.reset()
1021 # ... continue to use `t` for something else
1022
1023 Alternatively, use the even simpler ``wrapattr`` convenience function,
1024 which would condense both the ``urllib`` and ``CallbackIOWrapper`` examples
1025 down to:
1026
1027 .. code:: python
1028
1029 import urllib, os
1030 from tqdm import tqdm
1031
1032 eg_link = "https://caspersci.uk.to/matryoshka.zip"
1033 response = getattr(urllib, 'request', urllib).urlopen(eg_link)
1034 with tqdm.wrapattr(open(os.devnull, "wb"), "write",
1035 miniters=1, desc=eg_link.split('/')[-1],
1036 total=getattr(response, 'length', None)) as fout:
1037 for chunk in response:
1038 fout.write(chunk)
1039
1040 The ``requests`` equivalent is nearly identical:
1041
1042 .. code:: python
1043
1044 import requests, os
1045 from tqdm import tqdm
1046
1047 eg_link = "https://caspersci.uk.to/matryoshka.zip"
1048 response = requests.get(eg_link, stream=True)
1049 with tqdm.wrapattr(open(os.devnull, "wb"), "write",
1050 miniters=1, desc=eg_link.split('/')[-1],
1051 total=int(response.headers.get('content-length', 0))) as fout:
1052 for chunk in response.iter_content(chunk_size=4096):
1053 fout.write(chunk)
1054
1055 **Custom callback**
1056
1057 ``tqdm`` is known for intelligently skipping unnecessary displays. To make a
1058 custom callback take advantage of this, simply use the return value of
1059 ``update()``. This is set to ``True`` if a ``display()`` was triggered.
1060
1061 .. code:: python
1062
1063 from tqdm.auto import tqdm as std_tqdm
1064
1065 def external_callback(*args, **kwargs):
1066 ...
1067
1068 class TqdmExt(std_tqdm):
1069 def update(self, n=1):
1070 displayed = super().update(n)
1071 if displayed:
1072 external_callback(**self.format_dict)
1073 return displayed
1074
1075 ``asyncio``
1076 ~~~~~~~~~~~
1077
1078 Note that ``break`` isn't currently caught by asynchronous iterators.
1079 This means that ``tqdm`` cannot clean up after itself in this case:
1080
1081 .. code:: python
1082
1083 from tqdm.asyncio import tqdm
1084
1085 async for i in tqdm(range(9)):
1086 if i == 2:
1087 break
1088
1089 Instead, either call ``pbar.close()`` manually or use the context manager syntax:
1090
1091 .. code:: python
1092
1093 from tqdm.asyncio import tqdm
1094
1095 with tqdm(range(9)) as pbar:
1096 async for i in pbar:
1097 if i == 2:
1098 break
1099
1100 Pandas Integration
1101 ~~~~~~~~~~~~~~~~~~
1102
1103 Due to popular demand we've added support for ``pandas`` -- here's an example
1104 for ``DataFrame.progress_apply`` and ``DataFrameGroupBy.progress_apply``:
1105
1106 .. code:: python
1107
1108 import pandas as pd
1109 import numpy as np
1110 from tqdm import tqdm
1111
1112 df = pd.DataFrame(np.random.randint(0, 100, (100000, 6)))
1113
1114 # Register `pandas.progress_apply` and `pandas.Series.map_apply` with `tqdm`
1115 # (can use `tqdm.gui.tqdm`, `tqdm.notebook.tqdm`, optional kwargs, etc.)
1116 tqdm.pandas(desc="my bar!")
1117
1118 # Now you can use `progress_apply` instead of `apply`
1119 # and `progress_map` instead of `map`
1120 df.progress_apply(lambda x: x**2)
1121 # can also groupby:
1122 # df.groupby(0).progress_apply(lambda x: x**2)
1123
1124 In case you're interested in how this works (and how to modify it for your
1125 own callbacks), see the
1126 `examples <https://github.com/tqdm/tqdm/tree/master/examples>`__
1127 folder or import the module and run ``help()``.
1128
1129 Keras Integration
1130 ~~~~~~~~~~~~~~~~~
1131
1132 A ``keras`` callback is also available:
1133
1134 .. code:: python
1135
1136 from tqdm.keras import TqdmCallback
1137
1138 ...
1139
1140 model.fit(..., verbose=0, callbacks=[TqdmCallback()])
1141
1142 Dask Integration
1143 ~~~~~~~~~~~~~~~~
1144
1145 A ``dask`` callback is also available:
1146
1147 .. code:: python
1148
1149 from tqdm.dask import TqdmCallback
1150
1151 with TqdmCallback(desc="compute"):
1152 ...
1153 arr.compute()
1154
1155 # or use callback globally
1156 cb = TqdmCallback(desc="global")
1157 cb.register()
1158 arr.compute()
1159
1160 IPython/Jupyter Integration
1161 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1162
1163 IPython/Jupyter is supported via the ``tqdm.notebook`` submodule:
1164
1165 .. code:: python
1166
1167 from tqdm.notebook import trange, tqdm
1168 from time import sleep
1169
1170 for i in trange(3, desc='1st loop'):
1171 for j in tqdm(range(100), desc='2nd loop'):
1172 sleep(0.01)
1173
1174 In addition to ``tqdm`` features, the submodule provides a native Jupyter
1175 widget (compatible with IPython v1-v4 and Jupyter), fully working nested bars
1176 and colour hints (blue: normal, green: completed, red: error/interrupt,
1177 light blue: no ETA); as demonstrated below.
1178
1179 |Screenshot-Jupyter1|
1180 |Screenshot-Jupyter2|
1181 |Screenshot-Jupyter3|
1182
1183 The ``notebook`` version supports percentage or pixels for overall width
1184 (e.g.: ``ncols='100%'`` or ``ncols='480px'``).
1185
1186 It is also possible to let ``tqdm`` automatically choose between
1187 console or notebook versions by using the ``autonotebook`` submodule:
1188
1189 .. code:: python
1190
1191 from tqdm.autonotebook import tqdm
1192 tqdm.pandas()
1193
1194 Note that this will issue a ``TqdmExperimentalWarning`` if run in a notebook
1195 since it is not meant to be possible to distinguish between ``jupyter notebook``
1196 and ``jupyter console``. Use ``auto`` instead of ``autonotebook`` to suppress
1197 this warning.
1198
1199 Note that notebooks will display the bar in the cell where it was created.
1200 This may be a different cell from the one where it is used.
1201 If this is not desired, either
1202
1203 - delay the creation of the bar to the cell where it must be displayed, or
1204 - create the bar with ``display=False``, and in a later cell call
1205 ``display(bar.container)``:
1206
1207 .. code:: python
1208
1209 from tqdm.notebook import tqdm
1210 pbar = tqdm(..., display=False)
1211
1212 .. code:: python
1213
1214 # different cell
1215 display(pbar.container)
1216
1217 The ``keras`` callback has a ``display()`` method which can be used likewise:
1218
1219 .. code:: python
1220
1221 from tqdm.keras import TqdmCallback
1222 cbk = TqdmCallback(display=False)
1223
1224 .. code:: python
1225
1226 # different cell
1227 cbk.display()
1228 model.fit(..., verbose=0, callbacks=[cbk])
1229
1230 Another possibility is to have a single bar (near the top of the notebook)
1231 which is constantly re-used (using ``reset()`` rather than ``close()``).
1232 For this reason, the notebook version (unlike the CLI version) does not
1233 automatically call ``close()`` upon ``Exception``.
1234
1235 .. code:: python
1236
1237 from tqdm.notebook import tqdm
1238 pbar = tqdm()
1239
1240 .. code:: python
1241
1242 # different cell
1243 iterable = range(100)
1244 pbar.reset(total=len(iterable)) # initialise with new `total`
1245 for i in iterable:
1246 pbar.update()
1247 pbar.refresh() # force print final status but don't `close()`
1248
1249 Custom Integration
1250 ~~~~~~~~~~~~~~~~~~
1251
1252 To change the default arguments (such as making ``dynamic_ncols=True``),
1253 simply use built-in Python magic:
1254
1255 .. code:: python
1256
1257 from functools import partial
1258 from tqdm import tqdm as std_tqdm
1259 tqdm = partial(std_tqdm, dynamic_ncols=True)
1260
1261 For further customisation,
1262 ``tqdm`` may be inherited from to create custom callbacks (as with the
1263 ``TqdmUpTo`` example `above <#hooks-and-callbacks>`__) or for custom frontends
1264 (e.g. GUIs such as notebook or plotting packages). In the latter case:
1265
1266 1. ``def __init__()`` to call ``super().__init__(..., gui=True)`` to disable
1267 terminal ``status_printer`` creation.
1268 2. Redefine: ``close()``, ``clear()``, ``display()``.
1269
1270 Consider overloading ``display()`` to use e.g.
1271 ``self.frontend(**self.format_dict)`` instead of ``self.sp(repr(self))``.
1272
1273 Some submodule examples of inheritance:
1274
1275 - `tqdm/notebook.py <https://github.com/tqdm/tqdm/blob/master/tqdm/notebook.py>`__
1276 - `tqdm/gui.py <https://github.com/tqdm/tqdm/blob/master/tqdm/gui.py>`__
1277 - `tqdm/tk.py <https://github.com/tqdm/tqdm/blob/master/tqdm/tk.py>`__
1278 - `tqdm/contrib/slack.py <https://github.com/tqdm/tqdm/blob/master/tqdm/contrib/slack.py>`__
1279 - `tqdm/contrib/discord.py <https://github.com/tqdm/tqdm/blob/master/tqdm/contrib/discord.py>`__
1280 - `tqdm/contrib/telegram.py <https://github.com/tqdm/tqdm/blob/master/tqdm/contrib/telegram.py>`__
1281
1282 Dynamic Monitor/Meter
1283 ~~~~~~~~~~~~~~~~~~~~~
1284
1285 You can use a ``tqdm`` as a meter which is not monotonically increasing.
1286 This could be because ``n`` decreases (e.g. a CPU usage monitor) or ``total``
1287 changes.
1288
1289 One example would be recursively searching for files. The ``total`` is the
1290 number of objects found so far, while ``n`` is the number of those objects which
1291 are files (rather than folders):
1292
1293 .. code:: python
1294
1295 from tqdm import tqdm
1296 import os.path
1297
1298 def find_files_recursively(path, show_progress=True):
1299 files = []
1300 # total=1 assumes `path` is a file
1301 t = tqdm(total=1, unit="file", disable=not show_progress)
1302 if not os.path.exists(path):
1303 raise IOError("Cannot find:" + path)
1304
1305 def append_found_file(f):
1306 files.append(f)
1307 t.update()
1308
1309 def list_found_dir(path):
1310 """returns os.listdir(path) assuming os.path.isdir(path)"""
1311 listing = os.listdir(path)
1312 # subtract 1 since a "file" we found was actually this directory
1313 t.total += len(listing) - 1
1314 # fancy way to give info without forcing a refresh
1315 t.set_postfix(dir=path[-10:], refresh=False)
1316 t.update(0) # may trigger a refresh
1317 return listing
1318
1319 def recursively_search(path):
1320 if os.path.isdir(path):
1321 for f in list_found_dir(path):
1322 recursively_search(os.path.join(path, f))
1323 else:
1324 append_found_file(path)
1325
1326 recursively_search(path)
1327 t.set_postfix(dir=path)
1328 t.close()
1329 return files
1330
1331 Using ``update(0)`` is a handy way to let ``tqdm`` decide when to trigger a
1332 display refresh to avoid console spamming.
1333
1334 Writing messages
1335 ~~~~~~~~~~~~~~~~
1336
1337 This is a work in progress (see
1338 `#737 <https://github.com/tqdm/tqdm/issues/737>`__).
1339
1340 Since ``tqdm`` uses a simple printing mechanism to display progress bars,
1341 you should not write any message in the terminal using ``print()`` while
1342 a progressbar is open.
1343
1344 To write messages in the terminal without any collision with ``tqdm`` bar
1345 display, a ``.write()`` method is provided:
1346
1347 .. code:: python
1348
1349 from tqdm.auto import tqdm, trange
1350 from time import sleep
1351
1352 bar = trange(10)
1353 for i in bar:
1354 # Print using tqdm class method .write()
1355 sleep(0.1)
1356 if not (i % 3):
1357 tqdm.write("Done task %i" % i)
1358 # Can also use bar.write()
1359
1360 By default, this will print to standard output ``sys.stdout``. but you can
1361 specify any file-like object using the ``file`` argument. For example, this
1362 can be used to redirect the messages writing to a log file or class.
1363
1364 Redirecting writing
1365 ~~~~~~~~~~~~~~~~~~~
1366
1367 If using a library that can print messages to the console, editing the library
1368 by replacing ``print()`` with ``tqdm.write()`` may not be desirable.
1369 In that case, redirecting ``sys.stdout`` to ``tqdm.write()`` is an option.
1370
1371 To redirect ``sys.stdout``, create a file-like class that will write
1372 any input string to ``tqdm.write()``, and supply the arguments
1373 ``file=sys.stdout, dynamic_ncols=True``.
1374
1375 A reusable canonical example is given below:
1376
1377 .. code:: python
1378
1379 from time import sleep
1380 import contextlib
1381 import sys
1382 from tqdm import tqdm
1383 from tqdm.contrib import DummyTqdmFile
1384
1385
1386 @contextlib.contextmanager
1387 def std_out_err_redirect_tqdm():
1388 orig_out_err = sys.stdout, sys.stderr
1389 try:
1390 sys.stdout, sys.stderr = map(DummyTqdmFile, orig_out_err)
1391 yield orig_out_err[0]
1392 # Relay exceptions
1393 except Exception as exc:
1394 raise exc
1395 # Always restore sys.stdout/err if necessary
1396 finally:
1397 sys.stdout, sys.stderr = orig_out_err
1398
1399 def some_fun(i):
1400 print("Fee, fi, fo,".split()[i])
1401
1402 # Redirect stdout to tqdm.write() (don't forget the `as save_stdout`)
1403 with std_out_err_redirect_tqdm() as orig_stdout:
1404 # tqdm needs the original stdout
1405 # and dynamic_ncols=True to autodetect console width
1406 for i in tqdm(range(3), file=orig_stdout, dynamic_ncols=True):
1407 sleep(.5)
1408 some_fun(i)
1409
1410 # After the `with`, printing is restored
1411 print("Done!")
1412
1413 Redirecting ``logging``
1414 ~~~~~~~~~~~~~~~~~~~~~~~
1415
1416 Similar to ``sys.stdout``/``sys.stderr`` as detailed above, console ``logging``
1417 may also be redirected to ``tqdm.write()``.
1418
1419 Warning: if also redirecting ``sys.stdout``/``sys.stderr``, make sure to
1420 redirect ``logging`` first if needed.
1421
1422 Helper methods are available in ``tqdm.contrib.logging``. For example:
1423
1424 .. code:: python
1425
1426 import logging
1427 from tqdm import trange
1428 from tqdm.contrib.logging import logging_redirect_tqdm
1429
1430 LOG = logging.getLogger(__name__)
1431
1432 if __name__ == '__main__':
1433 logging.basicConfig(level=logging.INFO)
1434 with logging_redirect_tqdm():
1435 for i in trange(9):
1436 if i == 4:
1437 LOG.info("console logging redirected to `tqdm.write()`")
1438 # logging restored
1439
1440 Monitoring thread, intervals and miniters
1441 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1442
1443 ``tqdm`` implements a few tricks to increase efficiency and reduce overhead.
1444
1445 - Avoid unnecessary frequent bar refreshing: ``mininterval`` defines how long
1446 to wait between each refresh. ``tqdm`` always gets updated in the background,
1447 but it will display only every ``mininterval``.
1448 - Reduce number of calls to check system clock/time.
1449 - ``mininterval`` is more intuitive to configure than ``miniters``.
1450 A clever adjustment system ``dynamic_miniters`` will automatically adjust
1451 ``miniters`` to the amount of iterations that fit into time ``mininterval``.
1452 Essentially, ``tqdm`` will check if it's time to print without actually
1453 checking time. This behaviour can be still be bypassed by manually setting
1454 ``miniters``.
1455
1456 However, consider a case with a combination of fast and slow iterations.
1457 After a few fast iterations, ``dynamic_miniters`` will set ``miniters`` to a
1458 large number. When iteration rate subsequently slows, ``miniters`` will
1459 remain large and thus reduce display update frequency. To address this:
1460
1461 - ``maxinterval`` defines the maximum time between display refreshes.
1462 A concurrent monitoring thread checks for overdue updates and forces one
1463 where necessary.
1464
1465 The monitoring thread should not have a noticeable overhead, and guarantees
1466 updates at least every 10 seconds by default.
1467 This value can be directly changed by setting the ``monitor_interval`` of
1468 any ``tqdm`` instance (i.e. ``t = tqdm.tqdm(...); t.monitor_interval = 2``).
1469 The monitor thread may be disabled application-wide by setting
1470 ``tqdm.tqdm.monitor_interval = 0`` before instantiation of any ``tqdm`` bar.
1471
1472
1473 Merch
1474 -----
1475
1476 You can buy `tqdm branded merch <https://tqdm.github.io/merch>`__ now!
1477
1478 Contributions
1479 -------------
1480
1481 |GitHub-Commits| |GitHub-Issues| |GitHub-PRs| |OpenHub-Status| |GitHub-Contributions| |CII Best Practices|
1482
1483 All source code is hosted on `GitHub <https://github.com/tqdm/tqdm>`__.
1484 Contributions are welcome.
1485
1486 See the
1487 `CONTRIBUTING <https://github.com/tqdm/tqdm/blob/master/CONTRIBUTING.md>`__
1488 file for more information.
1489
1490 Developers who have made significant contributions, ranked by *SLoC*
1491 (surviving lines of code,
1492 `git fame <https://github.com/casperdcl/git-fame>`__ ``-wMC --excl '\.(png|gif|jpg)$'``),
1493 are:
1494
1495 ==================== ======================================================== ==== ================================
1496 Name ID SLoC Notes
1497 ==================== ======================================================== ==== ================================
1498 Casper da Costa-Luis `casperdcl <https://github.com/casperdcl>`__ ~80% primary maintainer |Gift-Casper|
1499 Stephen Larroque `lrq3000 <https://github.com/lrq3000>`__ ~9% team member
1500 Martin Zugnoni `martinzugnoni <https://github.com/martinzugnoni>`__ ~3%
1501 Daniel Ecer `de-code <https://github.com/de-code>`__ ~2%
1502 Richard Sheridan `richardsheridan <https://github.com/richardsheridan>`__ ~1%
1503 Guangshuo Chen `chengs <https://github.com/chengs>`__ ~1%
1504 Helio Machado `0x2b3bfa0 <https://github.com/0x2b3bfa0>`__ ~1%
1505 Kyle Altendorf `altendky <https://github.com/altendky>`__ <1%
1506 Noam Yorav-Raphael `noamraph <https://github.com/noamraph>`__ <1% original author
1507 Matthew Stevens `mjstevens777 <https://github.com/mjstevens777>`__ <1%
1508 Hadrien Mary `hadim <https://github.com/hadim>`__ <1% team member
1509 Mikhail Korobov `kmike <https://github.com/kmike>`__ <1% team member
1510 ==================== ======================================================== ==== ================================
1511
1512 Ports to Other Languages
1513 ~~~~~~~~~~~~~~~~~~~~~~~~
1514
1515 A list is available on
1516 `this wiki page <https://github.com/tqdm/tqdm/wiki/tqdm-ports>`__.
1517
1518
1519 LICENCE
1520 -------
1521
1522 Open Source (OSI approved): |LICENCE|
1523
1524 Citation information: |DOI|
1525
1526 |README-Hits| (Since 19 May 2016)
1527
1528 .. |Logo| image:: https://tqdm.github.io/img/logo.gif
1529 .. |Screenshot| image:: https://tqdm.github.io/img/tqdm.gif
1530 .. |Video| image:: https://tqdm.github.io/img/video.jpg
1531 :target: https://tqdm.github.io/video
1532 .. |Slides| image:: https://tqdm.github.io/img/slides.jpg
1533 :target: https://tqdm.github.io/PyData2019/slides.html
1534 .. |Merch| image:: https://tqdm.github.io/img/merch.jpg
1535 :target: https://tqdm.github.io/merch
1536 .. |Build-Status| image:: https://img.shields.io/github/actions/workflow/status/tqdm/tqdm/test.yml?branch=master&label=tqdm&logo=GitHub
1537 :target: https://github.com/tqdm/tqdm/actions/workflows/test.yml
1538 .. |Coverage-Status| image:: https://img.shields.io/coveralls/github/tqdm/tqdm/master?logo=coveralls
1539 :target: https://coveralls.io/github/tqdm/tqdm
1540 .. |Branch-Coverage-Status| image:: https://codecov.io/gh/tqdm/tqdm/branch/master/graph/badge.svg
1541 :target: https://codecov.io/gh/tqdm/tqdm
1542 .. |Codacy-Grade| image:: https://app.codacy.com/project/badge/Grade/3f965571598f44549c7818f29cdcf177
1543 :target: https://www.codacy.com/gh/tqdm/tqdm/dashboard
1544 .. |CII Best Practices| image:: https://bestpractices.coreinfrastructure.org/projects/3264/badge
1545 :target: https://bestpractices.coreinfrastructure.org/projects/3264
1546 .. |GitHub-Status| image:: https://img.shields.io/github/tag/tqdm/tqdm.svg?maxAge=86400&logo=github&logoColor=white
1547 :target: https://github.com/tqdm/tqdm/releases
1548 .. |GitHub-Forks| image:: https://img.shields.io/github/forks/tqdm/tqdm.svg?logo=github&logoColor=white
1549 :target: https://github.com/tqdm/tqdm/network
1550 .. |GitHub-Stars| image:: https://img.shields.io/github/stars/tqdm/tqdm.svg?logo=github&logoColor=white
1551 :target: https://github.com/tqdm/tqdm/stargazers
1552 .. |GitHub-Commits| image:: https://img.shields.io/github/commit-activity/y/tqdm/tqdm.svg?logo=git&logoColor=white
1553 :target: https://github.com/tqdm/tqdm/graphs/commit-activity
1554 .. |GitHub-Issues| image:: https://img.shields.io/github/issues-closed/tqdm/tqdm.svg?logo=github&logoColor=white
1555 :target: https://github.com/tqdm/tqdm/issues?q=
1556 .. |GitHub-PRs| image:: https://img.shields.io/github/issues-pr-closed/tqdm/tqdm.svg?logo=github&logoColor=white
1557 :target: https://github.com/tqdm/tqdm/pulls
1558 .. |GitHub-Contributions| image:: https://img.shields.io/github/contributors/tqdm/tqdm.svg?logo=github&logoColor=white
1559 :target: https://github.com/tqdm/tqdm/graphs/contributors
1560 .. |GitHub-Updated| image:: https://img.shields.io/github/last-commit/tqdm/tqdm/master.svg?logo=github&logoColor=white&label=pushed
1561 :target: https://github.com/tqdm/tqdm/pulse
1562 .. |Gift-Casper| image:: https://img.shields.io/badge/dynamic/json.svg?color=ff69b4&label=gifts%20received&prefix=%C2%A3&query=%24..sum&url=https%3A%2F%2Fcaspersci.uk.to%2Fgifts.json
1563 :target: https://cdcl.ml/sponsor
1564 .. |Versions| image:: https://img.shields.io/pypi/v/tqdm.svg
1565 :target: https://tqdm.github.io/releases
1566 .. |PyPI-Downloads| image:: https://img.shields.io/pypi/dm/tqdm.svg?label=pypi%20downloads&logo=PyPI&logoColor=white
1567 :target: https://pepy.tech/project/tqdm
1568 .. |Py-Versions| image:: https://img.shields.io/pypi/pyversions/tqdm.svg?logo=python&logoColor=white
1569 :target: https://pypi.org/project/tqdm
1570 .. |Conda-Forge-Status| image:: https://img.shields.io/conda/v/conda-forge/tqdm.svg?label=conda-forge&logo=conda-forge
1571 :target: https://anaconda.org/conda-forge/tqdm
1572 .. |Snapcraft| image:: https://img.shields.io/badge/snap-install-82BEA0.svg?logo=snapcraft
1573 :target: https://snapcraft.io/tqdm
1574 .. |Docker| image:: https://img.shields.io/badge/docker-pull-blue.svg?logo=docker&logoColor=white
1575 :target: https://hub.docker.com/r/tqdm/tqdm
1576 .. |Libraries-Rank| image:: https://img.shields.io/librariesio/sourcerank/pypi/tqdm.svg?logo=koding&logoColor=white
1577 :target: https://libraries.io/pypi/tqdm
1578 .. |Libraries-Dependents| image:: https://img.shields.io/librariesio/dependent-repos/pypi/tqdm.svg?logo=koding&logoColor=white
1579 :target: https://github.com/tqdm/tqdm/network/dependents
1580 .. |OpenHub-Status| image:: https://www.openhub.net/p/tqdm/widgets/project_thin_badge?format=gif
1581 :target: https://www.openhub.net/p/tqdm?ref=Thin+badge
1582 .. |awesome-python| image:: https://awesome.re/mentioned-badge.svg
1583 :target: https://github.com/vinta/awesome-python
1584 .. |LICENCE| image:: https://img.shields.io/pypi/l/tqdm.svg
1585 :target: https://raw.githubusercontent.com/tqdm/tqdm/master/LICENCE
1586 .. |DOI| image:: https://img.shields.io/badge/DOI-10.5281/zenodo.595120-blue.svg
1587 :target: https://doi.org/10.5281/zenodo.595120
1588 .. |binder-demo| image:: https://mybinder.org/badge_logo.svg
1589 :target: https://mybinder.org/v2/gh/tqdm/tqdm/master?filepath=DEMO.ipynb
1590 .. |Screenshot-Jupyter1| image:: https://tqdm.github.io/img/jupyter-1.gif
1591 .. |Screenshot-Jupyter2| image:: https://tqdm.github.io/img/jupyter-2.gif
1592 .. |Screenshot-Jupyter3| image:: https://tqdm.github.io/img/jupyter-3.gif
1593 .. |README-Hits| image:: https://cgi.cdcl.ml/hits?q=tqdm&style=social&r=https://github.com/tqdm/tqdm&l=https://tqdm.github.io/img/favicon.png&f=https://tqdm.github.io/img/logo.gif
1594 :target: https://cgi.cdcl.ml/hits?q=tqdm&a=plot&r=https://github.com/tqdm/tqdm&l=https://tqdm.github.io/img/favicon.png&f=https://tqdm.github.io/img/logo.gif&style=social