From 3a64961373ef75ea549034d895827d3646569fa6 Mon Sep 17 00:00:00 2001 From: Casper da Costa-Luis Date: Fri, 18 Jan 2019 23:28:10 +0000 Subject: [PATCH] update demo notebook and unpin dependency - include more of README.rst in DEMO.ipynb - tidy, add badges, update examples closes #659, fixes #652 --- DEMO.ipynb | 1277 +++++++++++++++++----------------------------------- demo.yml | 2 +- 2 files changed, 408 insertions(+), 871 deletions(-) diff --git a/DEMO.ipynb b/DEMO.ipynb index e9d92e46..7d102ee6 100644 --- a/DEMO.ipynb +++ b/DEMO.ipynb @@ -4,28 +4,106 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "![](https://raw.githubusercontent.com/tqdm/tqdm/master/images/logo.gif)" + "

tqdm

\n", + "\n", + "\n", + "[![PyPI-Versions](https://img.shields.io/pypi/pyversions/tqdm.svg?logo=python&logoColor=white)](https://pypi.org/project/tqdm)|[![PyPI-Status](https://img.shields.io/pypi/v/tqdm.svg)](https://pypi.org/project/tqdm)|[![Conda-Forge-Status](https://img.shields.io/conda/v/conda-forge/tqdm.svg?label=conda-forge)](https://anaconda.org/conda-forge/tqdm)\n", + "-|-|-\n", + "\n", + "[![Build-Status](https://img.shields.io/travis/tqdm/tqdm/master.svg?logo=travis)](https://travis-ci.org/tqdm/tqdm)|[![Coverage-Status](https://coveralls.io/repos/tqdm/tqdm/badge.svg?branch=master)](https://coveralls.io/github/tqdm/tqdm)|[![Branch-Coverage-Status](https://codecov.io/gh/tqdm/tqdm/branch/master/graph/badge.svg)](https://codecov.io/gh/tqdm/tqdm)|[![Codacy-Grade](https://api.codacy.com/project/badge/Grade/3f965571598f44549c7818f29cdcf177)](https://www.codacy.com/app/tqdm/tqdm?utm_source=github.com&utm_medium=referral&utm_content=tqdm/tqdm&utm_campaign=Badge_Grade)|[![Libraries-Rank](https://img.shields.io/librariesio/sourcerank/pypi/tqdm.svg?logo=koding&logoColor=white)](https://libraries.io/pypi/tqdm)|[![PyPI-Downloads](https://img.shields.io/pypi/dm/tqdm.svg?label=pypi%20downloads&logo=python&logoColor=white)](https://pypi.org/project/tqdm)\n", + "-|-|-|-|-|-\n", + "\n", + "\n", + "[![DOI-URI](https://zenodo.org/badge/21637/tqdm/tqdm.svg)](https://zenodo.org/badge/latestdoi/21637/tqdm/tqdm)|[![LICENCE](https://img.shields.io/pypi/l/tqdm.svg)](https://raw.githubusercontent.com/tqdm/tqdm/master/LICENCE)|[![OpenHub-Status](https://www.openhub.net/p/tqdm/widgets/project_thin_badge?format=gif)](https://www.openhub.net/p/tqdm?ref=Thin+badge)|[![README-Hits](https://caspersci.uk.to/cgi-bin/hits.cgi?q=tqdm&style=social&r=https://github.com/tqdm/tqdm&l=https://caspersci.uk.to/images/tqdm.png&f=https://raw.githubusercontent.com/tqdm/tqdm/master/images/logo.gif)](https://caspersci.uk.to/cgi-bin/hits.cgi?q=tqdm&a=plot&r=https://github.com/tqdm/tqdm&l=https://caspersci.uk.to/images/tqdm.png&f=https://raw.githubusercontent.com/tqdm/tqdm/master/images/logo.gif&style=social)\n", + "-|-|-|-\n", + "\n", + "`tqdm` means \"progress\" in Arabic (taqadum, تقدّم) and is an\n", + "abbreviation for \"I love you so much\" in Spanish (te quiero demasiado).\n", + "\n", + "Instantly make your loops show a smart progress meter - just wrap any\n", + "iterable with `tqdm(iterable)`, and you're done!" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from tqdm import tqdm\n", + "for i in tqdm(range(10000)):\n", + " pass" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "# tqdm " + "`trange(N)` can be also used as a convenient shortcut for\n", + "`tqdm(xrange(N))`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from tqdm import trange\n", + "for i in trange(10000, unit_scale=True, desc=\"hello\", unit=\"epoch\"):\n", + " pass" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "`tqdm` means \"progress\" in Arabic (taqadum, تقدّم) and is an abbreviation for \"I love you so much\" in Spanish (te quiero demasiado)." + "![Screenshot](images/tqdm.gif)\n", + "\n", + "It can also be executed as a module with pipes:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "! seq 9999999 | tqdm --bytes | wc -l" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "![](https://raw.githubusercontent.com/tqdm/tqdm/master/images/tqdm.gif)" + "```sh\n", + "7z a -bd -r backup.7z docs/ | grep Compressing | \\\n", + " tqdm --total $(find docs/ -type f | wc -l) --unit files >> backup.log\n", + "100%|███████████████████████████████▉| 8014/8014 [01:37<00:00, 82.29files/s]\n", + "```" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Overhead is low -- about 60ns per iteration (80ns with `tqdm_gui`), and\n", + "is unit tested against performance regression. By comparison, the\n", + "well-established\n", + "[ProgressBar](https://github.com/niltonvolpato/python-progressbar) has\n", + "an 800ns/iter overhead.\n", + "\n", + "In addition to its low overhead, `tqdm` uses smart algorithms to predict\n", + "the remaining time and to skip unnecessary iteration displays, which\n", + "allows for a negligible overhead in most cases.\n", + "\n", + "`tqdm` works on any platform (Linux, Windows, Mac, FreeBSD, NetBSD,\n", + "Solaris/SunOS), in any console or in a GUI, and is also friendly with\n", + "IPython/Jupyter notebooks.\n", + "\n", + "`tqdm` does not require any dependencies (not even `curses`!), just\n", + "Python and an environment supporting `carriage return \\r` and\n", + "`line feed \\n` control characters." ] }, { @@ -41,7 +119,8 @@ "source": [ "## Usage\n", "\n", - "`tqdm` is very versatile and can be used in a number of ways. The three main ones are given below." + "`tqdm` is very versatile and can be used in a number of ways.\n", + "The three main ones are given below." ] }, { @@ -55,29 +134,20 @@ }, { "cell_type": "code", - "execution_count": 14, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ - "from tqdm import tqdm" + "from tqdm import tqdm\n", + "import time" ] }, { "cell_type": "code", - "execution_count": 15, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "100%|██████████| 4/4 [00:01<00:00, 3.93it/s]\n" - ] - } - ], + "outputs": [], "source": [ - "import time\n", - "\n", "text = \"\"\n", "for char in tqdm([\"a\", \"b\", \"c\", \"d\"]):\n", " time.sleep(0.25)\n", @@ -93,22 +163,14 @@ }, { "cell_type": "code", - "execution_count": 16, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "100%|██████████| 1000000/1000000 [00:00<00:00, 1849858.32it/s]\n" - ] - } - ], + "outputs": [], "source": [ "from tqdm import trange\n", "\n", - "for i in trange(1_000_000):\n", - " pass" + "for i in trange(100):\n", + " time.sleep(0.01)" ] }, { @@ -120,17 +182,9 @@ }, { "cell_type": "code", - "execution_count": 17, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "Processing d: 100%|██████████| 4/4 [00:01<00:00, 3.90it/s]\n" - ] - } - ], + "outputs": [], "source": [ "pbar = tqdm([\"a\", \"b\", \"c\", \"d\"])\n", "for char in pbar:\n", @@ -144,26 +198,18 @@ "source": [ "### Manual\n", "\n", - "Manual control on `tqdm()` updates by using a with statement:" + "Manual control on `tqdm()` updates by using a `with` statement:" ] }, { "cell_type": "code", - "execution_count": 18, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "100%|██████████| 100/100 [00:02<00:00, 39.11it/s]\n" - ] - } - ], + "outputs": [], "source": [ "with tqdm(total=100) as pbar:\n", " for i in range(10):\n", - " time.sleep(0.25)\n", + " time.sleep(0.1)\n", " pbar.update(10)" ] }, @@ -171,28 +217,22 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "If the optional variable total (or an iterable with `len()`) is provided, predictive stats are displayed.\n", + "If the optional variable `total` (or an iterable with `len()`) is\n", + "provided, predictive stats are displayed.\n", "\n", - "`with` is also optional (you can just assign `tqdm()` to a variable, but in this case don't forget to `del` or `close()` at the end:" + "`with` is also optional (you can just assign `tqdm()` to a variable,\n", + "but in this case don't forget to `del` or `close()` at the end:" ] }, { "cell_type": "code", - "execution_count": 19, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "100%|██████████| 100/100 [00:02<00:00, 39.24it/s]\n" - ] - } - ], + "outputs": [], "source": [ "pbar = tqdm(total=100)\n", "for i in range(10):\n", - " time.sleep(0.25)\n", + " time.sleep(0.1)\n", " pbar.update(10)\n", "pbar.close()" ] @@ -201,63 +241,131 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "It can also be executed as a module with pipes:" + "### Module" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Perhaps the most wonderful use of ``tqdm`` is in a script or on the command\n", + "line. Simply inserting ``tqdm`` (or ``python3 -m tqdm``) between pipes will pass\n", + "through all ``stdin`` to ``stdout`` while printing progress to ``stderr``.\n", + "\n", + "The example below demonstrated counting the number of lines in all Python files\n", + "in the current directory, with timing information included." ] }, { "cell_type": "code", - "execution_count": 20, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "1.00Mit [00:00, 1.17Mit/s]\n", - " 999999\n" - ] - } - ], + "outputs": [], "source": [ - "! seq 999999 | tqdm --unit_scale | wc -l" + "! time find . -name '*.py' -type f -exec cat \\{} \\; | wc -l" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "! time find . -name '*.py' -type f -exec cat \\{} \\; | tqdm | wc -l" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Advance usage" + "Note that the usual arguments for `tqdm` can also be specified." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "! find . -name '*.py' -type f -exec cat \\{} \\; | tqdm --unit loc --unit_scale --total 4104300 >> /dev/null" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ + "Backing up a large directory?\n", + "\n", + "```sh\n", + "$ 7z a -bd -r backup.7z docs/ | grep Compressing |\n", + " tqdm --total $(find docs/ -type f | wc -l) --unit files >> backup.log\n", + "100%|███████████████████████████████▉| 8014/8014 [01:37<00:00, 82.29files/s]\n", + "```" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Documentation" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "scrolled": true + }, + "outputs": [], + "source": [ + "print(tqdm.__init__.__doc__)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "scrolled": false + }, + "outputs": [], + "source": [ + "from tqdm._main import CLI_EXTRA_DOC\n", + "print(CLI_EXTRA_DOC)\n", + "#! tqdm --help" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Examples and Advance Usage\n", + "\n", + "- See the [examples](examples)\n", + " folder;\n", + "- import the module and run `help()`;\n", + "- consult the [wiki](https://github.com/tqdm/tqdm/wiki)\n", + " - this has an\n", + " [excellent article](https://github.com/tqdm/tqdm/wiki/How-to-make-a-great-Progress-Bar)\n", + " on how to make a **great** progressbar, or\n", + "- run this file!\n", + "\n", "### Description and additional stats\n", "\n", - "Custom information can be displayed and updated dynamically on `tqdm` bars with the `desc` and `postfix` arguments:" + "Custom information can be displayed and updated dynamically on `tqdm` bars\n", + "with the `desc` and `postfix` arguments:" ] }, { "cell_type": "code", - "execution_count": 21, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "GEN 99: 100%|██████████| 100/100 [00:11<00:00, 8.98it/s, gen=406, loss=0.256, lst=[1, 2], str=h]\n", - "Batch 4.5\n" - ] - } - ], + "outputs": [], "source": [ "from tqdm import trange\n", "from random import random, randint\n", "from time import sleep\n", "\n", - "with trange(100) as t:\n", + "with trange(10) as t:\n", " for i in t:\n", " # Description will be displayed on the left\n", " t.set_description('GEN %i' % i)\n", @@ -275,6 +383,19 @@ " t.update()" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Points to remember when using ``{postfix[...]}`` in the ``bar_format`` string:\n", + "\n", + "- ``postfix`` also needs to be passed as an initial argument in a compatible\n", + " format, and\n", + "- ``postfix`` will be auto-converted to a string if it is a ``dict``-like\n", + " object. To prevent this behaviour, insert an extra item into the dictionary\n", + " where the key is not a string." + ] + }, { "cell_type": "markdown", "metadata": {}, @@ -286,45 +407,120 @@ }, { "cell_type": "code", - "execution_count": 22, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "1st loop: 0%| | 0/3 [00:00 [...]\n", + "> If present, the hook function will be called once\n", + "> on establishment of the network connection and once after each block read\n", + "> thereafter. The hook will be passed three arguments; a count of blocks\n", + "> transferred so far, a block size in bytes, and the total size of the file.\n", + "> [...]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import urllib, os\n", + "from tqdm.auto import tqdm\n", + "\n", + "class TqdmUpTo(tqdm):\n", + " \"\"\"Provides `update_to(n)` which uses `tqdm.update(delta_n)`.\"\"\"\n", + " def update_to(self, b=1, bsize=1, tsize=None):\n", + " \"\"\"\n", + " b : int, optional\n", + " Number of blocks transferred so far [default: 1].\n", + " bsize : int, optional\n", + " Size of each block (in tqdm units) [default: 1].\n", + " tsize : int, optional\n", + " Total size (in tqdm units). If [default: None] remains unchanged.\n", + " \"\"\"\n", + " if tsize is not None:\n", + " self.total = tsize\n", + " self.update(b * bsize - self.n) # will also set self.n = b * bsize\n", + "\n", + "eg_link = \"https://caspersci.uk.to/matryoshka.zip\"\n", + "with TqdmUpTo(unit='B', unit_scale=True, miniters=1,\n", + " desc=eg_link.split('/')[-1]) as t: # all optional kwargs\n", + " urllib.urlretrieve(eg_link, filename=os.devnull,\n", + " reporthook=t.update_to, data=None)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Inspired by [twine#242](https://github.com/pypa/twine/pull/242).\n", + "Functional alternative in\n", + "[examples/tqdm_wget.py](../edit/examples/tqdm_wget.py).\n", + "\n", + "It is recommend to use `miniters=1` whenever there is potentially\n", + "large differences in iteration speed (e.g. downloading a file over\n", + "a patchy connection)." ] }, { @@ -333,683 +529,21 @@ "source": [ "### Pandas Integration\n", "\n", - "Due to popular demand we've added support for `pandas` -- here's an example for `DataFrame.progress_apply` and `DataFrameGroupBy.progress_apply`:" + "Due to popular demand we've added support for `pandas` -- here's an example\n", + "for `DataFrame.progress_apply` and `DataFrameGroupBy.progress_apply`:" ] }, { "cell_type": "code", - "execution_count": 24, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "my bar!: 100%|██████████| 6/6 [00:00<00:00, 411.54it/s]\n" - ] - }, - { - "data": { - "text/html": [ - "
\n", - "\n", - "\n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - " \n", - "
012345
096164176457764006889
16084144462552946244225
256259216608496181005476
377442304656173964008100
420253969111561681196
5313617641649921625
66889756972255041400361
7641446241168165613364
8476117649604883612962809
92601289484220910241849
10361636384438441521
11828129163721435695625
12841169688982819441
132568100529409627044761
1454768411024811849441
159980138441963600144
1698012809756967673967056
171296784396949005763721
18810091296705615219
19220970561089739616814489
2062525004356441254096
2125161849313688365476
222563721336416996044489
2340968196046255294489
2421164489115686495929900
25372117645476562538449216
261296441129632412964096
27400722577441681361441
2870567225400562537211369
29102440090028946244
.....................
99702893969729815295625
997147614008836902592163481
997228920258100792138441444
9973624184644951844414356
99741962116196161296144
997572251444260136119362025
997684143562116921694099801
99775776625841184946244096
9978676688916883653291
99793617056240153297396289
9980121169518416813649
9981369801841980136576
99823613136160082815776361
998332477446724108912962500
99842896241121422536529
9985435656257569624175695776
9986384417643481504110894900
998757762704656177441001369
998826014417744412967921
99896460843662546249216
9990499025902512254441
99918281291612157672259801
999288361600883610893844529
999314442116739636146242916
99944900121676921696043481
99955041640078464004001600
99961225490062419617845184
9997902552918281121900
9998363625640098019409
99997921362500368412809
\n", - "

10000 rows × 6 columns

\n", - "
" - ], - "text/plain": [ - " 0 1 2 3 4 5\n", - "0 961 64 1764 5776 400 6889\n", - "1 6084 1444 625 529 4624 4225\n", - "2 5625 9216 6084 961 8100 5476\n", - "3 7744 2304 6561 7396 400 8100\n", - "4 2025 3969 1 1156 1681 196\n", - "5 3136 1764 16 49 9216 25\n", - "6 6889 7569 7225 5041 400 361\n", - "7 64 144 6241 1681 6561 3364\n", - "8 4761 1764 9604 8836 1296 2809\n", - "9 2601 289 484 2209 1024 1849\n", - "10 36 16 36 3844 3844 1521\n", - "11 8281 2916 3721 4356 9 5625\n", - "12 841 169 6889 8281 9 441\n", - "13 256 8100 529 4096 2704 4761\n", - "14 5476 841 1024 81 1849 441\n", - "15 9 9801 3844 196 3600 144\n", - "16 9801 2809 7569 676 7396 7056\n", - "17 1296 784 3969 4900 576 3721\n", - "18 8100 9 1296 7056 1521 9\n", - "19 2209 7056 1089 7396 1681 4489\n", - "20 625 2500 4356 441 25 4096\n", - "21 25 16 1849 3136 8836 5476\n", - "22 256 3721 3364 169 9604 4489\n", - "23 4096 81 9604 625 529 4489\n", - "24 2116 4489 1156 8649 5929 900\n", - "25 3721 1764 5476 5625 3844 9216\n", - "26 1296 441 1296 324 1296 4096\n", - "27 400 7225 7744 1681 361 441\n", - "28 7056 7225 400 5625 3721 1369\n", - "29 1024 400 900 289 4624 4\n", - "... ... ... ... ... ... ...\n", - "9970 289 3969 729 81 529 5625\n", - "9971 4761 400 8836 9025 9216 3481\n", - "9972 289 2025 8100 7921 3844 1444\n", - "9973 6241 8464 49 5184 441 4356\n", - "9974 196 2116 196 16 1296 144\n", - "9975 7225 1444 2601 361 1936 2025\n", - "9976 841 4356 2116 9216 9409 9801\n", - "9977 5776 625 841 1849 4624 4096\n", - "9978 676 6889 16 8836 5329 1\n", - "9979 361 7056 2401 5329 7396 289\n", - "9980 121 169 5184 1681 36 49\n", - "9981 36 9801 841 9801 36 576\n", - "9982 361 3136 1600 8281 5776 361\n", - "9983 324 7744 6724 1089 1296 2500\n", - "9984 289 6241 121 4225 36 529\n", - "9985 4356 5625 7569 6241 7569 5776\n", - "9986 3844 1764 3481 5041 1089 4900\n", - "9987 5776 2704 6561 7744 100 1369\n", - "9988 2601 441 7744 4 1296 7921\n", - "9989 64 6084 36 625 4624 9216\n", - "9990 49 9025 9025 1225 4 441\n", - "9991 8281 2916 121 576 7225 9801\n", - "9992 8836 1600 8836 1089 3844 529\n", - "9993 1444 2116 7396 361 4624 2916\n", - "9994 4900 121 676 9216 9604 3481\n", - "9995 5041 6400 784 6400 400 1600\n", - "9996 1225 4900 6241 961 784 5184\n", - "9997 9025 529 1 8281 121 900\n", - "9998 36 36 256 400 9801 9409\n", - "9999 7921 36 2500 36 841 2809\n", - "\n", - "[10000 rows x 6 columns]" - ] - }, - "execution_count": 24, - "metadata": {}, - "output_type": "execute_result" - } - ], + "outputs": [], "source": [ "import pandas as pd\n", "import numpy as np\n", - "from tqdm import tqdm\n", + "from tqdm.auto import tqdm\n", "\n", - "df = pd.DataFrame(np.random.randint(0, 100, (100_00, 6)))\n", + "df = pd.DataFrame(np.random.randint(0, 100, (100000, 6)))\n", "\n", "# Register `pandas.progress_apply` and `pandas.Series.map_apply` with `tqdm`\n", "# (can use `tqdm_gui`, `tqdm_notebook`, optional kwargs, etc.)\n", @@ -1026,82 +560,81 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Writing messages\n", + "In case you're interested in how this works (and how to modify it for your\n", + "own callbacks), see the\n", + "[examples](examples)\n", + "folder or import the module and run `help()`.\n", "\n", - "Since `tqdm` uses a simple printing mechanism to display progress bars, you should not write any message in the terminal using `print()` while a progressbar is open.\n", + "### IPython/Jupyter Integration\n", "\n", - "To write messages in the terminal without any collision with `tqdm` bar display, a `.write()` method is provided:" + "IPython/Jupyter is supported via the `tqdm_notebook` submodule:" ] }, { "cell_type": "code", - "execution_count": 25, + "execution_count": null, "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - " 20%|██ | 2/10 [00:00<00:00, 9.40it/s]" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Done task 0\n" - ] - }, - { - "name": "stderr", - "output_type": "stream", - "text": [ - " 50%|█████ | 5/10 [00:00<00:00, 9.50it/s]" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Done task 3\n" - ] - }, - { - "name": "stderr", - "output_type": "stream", - "text": [ - " 80%|████████ | 8/10 [00:00<00:00, 9.49it/s]" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Done task 6\n" - ] - }, - { - "name": "stderr", - "output_type": "stream", - "text": [ - "100%|██████████| 10/10 [00:01<00:00, 9.42it/s]" - ] - }, - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Done task 9\n" - ] - }, - { - "name": "stderr", - "output_type": "stream", - "text": [ - "\n" - ] - } - ], + "outputs": [], + "source": [ + "from tqdm import tnrange, tqdm_notebook\n", + "from time import sleep\n", + "\n", + "for i in tnrange(3, desc='1st loop'):\n", + " for j in tqdm_notebook(range(100), desc='2nd loop'):\n", + " sleep(0.01)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In addition to `tqdm` features, the submodule provides a native Jupyter\n", + "widget (compatible with IPython v1-v4 and Jupyter), fully working nested bars\n", + "and colour hints (blue: normal, green: completed, red: error/interrupt,\n", + "light blue: no ETA); as demonstrated below.\n", + "\n", + "![Screenshot-Jupyter1](images/tqdm-jupyter-1.gif)\n", + "![Screenshot-Jupyter2](images/tqdm-jupyter-2.gif)\n", + "![Screenshot-Jupyter3](images/tqdm-jupyter-3.gif)\n", + "\n", + "It is also possible to let `tqdm` automatically choose between\n", + "console or notebook versions by using the `autonotebook` submodule:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from tqdm.autonotebook import tqdm\n", + "tqdm.pandas()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Note that this will issue a `TqdmExperimentalWarning` if run in a notebook\n", + "since it is not meant to be possible to distinguish between `jupyter notebook`\n", + "and `jupyter console`. Use `auto` instead of `autonotebook` to suppress\n", + "this warning.\n", + "\n", + "### Writing messages\n", + "\n", + "Since `tqdm` uses a simple printing mechanism to display progress bars,\n", + "you should not write any message in the terminal using `print()` while\n", + "a progressbar is open.\n", + "\n", + "To write messages in the terminal without any collision with `tqdm` bar\n", + "display, a `.write()` method is provided:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], "source": [ "from tqdm import tqdm, trange\n", "from time import sleep\n", @@ -1119,6 +652,10 @@ "cell_type": "markdown", "metadata": {}, "source": [ + "By default, this will print to standard output `sys.stdout`. but you can\n", + "specify any file-like object using the `file` argument. For example, this\n", + "can be used to redirect the messages writing to a log file or class.\n", + "\n", "---" ] }, @@ -1146,21 +683,21 @@ ], "metadata": { "kernelspec": { - "display_name": "Python 3", + "display_name": "Python 2", "language": "python", - "name": "python3" + "name": "python2" }, "language_info": { "codemirror_mode": { "name": "ipython", - "version": 3 + "version": 2 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.6.5" + "pygments_lexer": "ipython2", + "version": "2.7.15" } }, "nbformat": 4, diff --git a/demo.yml b/demo.yml index 4391337e..0b0f5f1c 100644 --- a/demo.yml +++ b/demo.yml @@ -1,2 +1,2 @@ requirements: - - tqdm==4.28.1 \ No newline at end of file + - tqdm