From 981c52e7b00458bc7c35e54c764b93c3e6a75422 Mon Sep 17 00:00:00 2001 From: Casper da Costa-Luis Date: Sun, 29 Mar 2020 20:17:51 +0100 Subject: [PATCH] document `reset()` and `refresh()` in notebooks - reason for no auto-`close()` upon `Exception` --- .meta/.readme.rst | 24 ++++++++++++++++++++++++ README.rst | 24 ++++++++++++++++++++++++ 2 files changed, 48 insertions(+) diff --git a/.meta/.readme.rst b/.meta/.readme.rst index 3e5587ff..c22799ec 100644 --- a/.meta/.readme.rst +++ b/.meta/.readme.rst @@ -726,6 +726,30 @@ since it is not meant to be possible to distinguish between ``jupyter notebook`` and ``jupyter console``. Use ``auto`` instead of ``autonotebook`` to suppress this warning. +Note that notebooks will display the bar in the cell where it was created. +This may be a different cell from the one where it is used. +If this is not desired, the creation of the bar must be delayed/moved to the +cell where it is desired to be displayed. + +Another possibility is to have a single bar (near the top of the notebook) +which is constantly re-used (using ``reset()`` rather than ``close()``). +For this reason, the notebook version (unlike the CLI version) does not +automatically call ``close()`` upon ``Exception``. + +.. code:: python + + from tqdm.notebook import tqdm + pbar = tqdm() + +.. code:: python + + # different cell + iterable = range(100) + pbar.reset(total=len(iterable)) # initialise with new `total` + for i in iterable: + pbar.update() + pbar.refresh() # force print final status but don't `close()` + Custom Integration ~~~~~~~~~~~~~~~~~~ diff --git a/README.rst b/README.rst index 1b1453bd..bf1b2686 100644 --- a/README.rst +++ b/README.rst @@ -912,6 +912,30 @@ since it is not meant to be possible to distinguish between ``jupyter notebook`` and ``jupyter console``. Use ``auto`` instead of ``autonotebook`` to suppress this warning. +Note that notebooks will display the bar in the cell where it was created. +This may be a different cell from the one where it is used. +If this is not desired, the creation of the bar must be delayed/moved to the +cell where it is desired to be displayed. + +Another possibility is to have a single bar (near the top of the notebook) +which is constantly re-used (using ``reset()`` rather than ``close()``). +For this reason, the notebook version (unlike the CLI version) does not +automatically call ``close()`` upon ``Exception``. + +.. code:: python + + from tqdm.notebook import tqdm + pbar = tqdm() + +.. code:: python + + # different cell + iterable = range(100) + pbar.reset(total=len(iterable)) # initialise with new `total` + for i in iterable: + pbar.update() + pbar.refresh() # force print final status but don't `close()` + Custom Integration ~~~~~~~~~~~~~~~~~~