diff --git a/README.rst b/README.rst index 31488978..cdfb6b74 100644 --- a/README.rst +++ b/README.rst @@ -3,7 +3,7 @@ tqdm ==== -|PyPi-Status| |PyPi-Downloads| |PyPi-Versions| +|PyPi-Status| |PyPi-Versions| |Build-Status| |Coverage-Status| |Branch-Coverage-Status| @@ -69,7 +69,7 @@ Installation Latest pypi stable release ~~~~~~~~~~~~~~~~~~~~~~~~~~ -|PyPi-Status| |PyPi-Downloads| +|PyPi-Status| .. code:: sh @@ -127,7 +127,6 @@ Instantiation outside of the loop allows for manual control over ``tqdm()``: for char in pbar: pbar.set_description("Processing %s" % char) - Manual ~~~~~~ @@ -152,7 +151,6 @@ but in this case don't forget to ``del`` or ``close()`` at the end: pbar.update(10) pbar.close() - Module ~~~~~~ @@ -200,7 +198,7 @@ Backing up a large directory? Documentation ------------- -|PyPi-Versions| +|PyPi-Versions| |Readme-Hits| (Since 19 May 2016) .. code:: python @@ -298,7 +296,6 @@ Extra CLI Options String buffer size in bytes [default: 256] used when `delim` is specified. - Returns ~~~~~~~ @@ -380,6 +377,28 @@ Examples and Advanced Usage See the `examples `__ folder or import the module and run ``help()``. +Nested progress bars +~~~~~~~~~~~~~~~~~~~~ + +``tqdm`` supports nested progress bars. Here's an example: + +.. code:: python + + from tqdm import trange + from time import sleep + + for i in trange(10, desc='1st loop'): + for j in trange(5, desc='2nd loop', leave=False): + for k in trange(100, desc='3nd loop'): + sleep(0.01) + +On Windows `colorama `__ will be used if +available to produce a beautiful nested display. + +For manual control over positioning (e.g. for multi-threaded use), +you may specify `position=n` where `n=0` for the outermost bar, +`n=1` for the next, and so on. + Hooks and callbacks ~~~~~~~~~~~~~~~~~~~ @@ -473,28 +492,6 @@ own callbacks), see the `examples `__ folder or import the module and run ``help()``. -Nested progress bars -~~~~~~~~~~~~~~~~~~~~ - -``tqdm`` supports nested progress bars. Here's an example: - -.. code:: python - - from tqdm import trange - from time import sleep - - for i in trange(10, desc='1st loop'): - for j in trange(5, desc='2nd loop', leave=False): - for k in trange(100, desc='3nd loop'): - sleep(0.01) - -On Windows `colorama `__ will be used if -available to produce a beautiful nested display. - -For manual control over positioning (e.g. for multi-threaded use), -you may specify `position=n` where `n=0` for the outermost bar, -`n=1` for the next, and so on. - IPython/Jupyter Integration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -519,7 +516,8 @@ light blue: no ETA); as demonstrated below. |Screenshot-Jupyter3| Writing messages -~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~ + Since ``tqdm`` uses a simple printing mechanism to display progress bars, you should not write any message in the terminal using ``print()``. @@ -543,19 +541,18 @@ By default, this will print to standard output ``sys.stdout``. but you can specify any file-like object using the ``file`` argument. For example, this can be used to redirect the messages writing to a log file or class. -Redirecting all printing to tqdm.write() -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Redirecting writing +~~~~~~~~~~~~~~~~~~~ -If your application is using a library that can print messages to the console, -you may not be willing to edit the library to replace ``print()`` by -``tqdm.write()``. In that case, you may want to redirect ``sys.stdout`` to -``tqdm.write()``. +If using a library that can print messages to the console, editing the library +by replacing ``print()`` with ``tqdm.write()`` may not be desirable. +In that case, redirecting ``sys.stdout`` to ``tqdm.write()`` is an option. -To redirect ``sys.stdout``, you need to create a file-like class that will write -any input string to ``tqdm.write()``, and you need to supply the arguments -``file=sys.stdout, dynamic_ncols=True``, else you will get funky issues. +To redirect ``sys.stdout``, create a file-like class that will write +any input string to ``tqdm.write()``, and supply the arguments +``file=sys.stdout, dynamic_ncols=True``. -Here is a canonical example that you can reuse: +A reusable canonical example is given below: .. code:: python @@ -595,11 +592,11 @@ Here is a canonical example that you can reuse: # Redirect stdout to tqdm.write() (don't forget the `as save_stdout`) with stdout_redirect_to_tqdm() as save_stdout: - # tqdm call need to specify sys.stdout, not sys.stderr (default) - # and dynamic_ncols=True to autodetect console width - for _ in tqdm(range(3), file=save_stdout, dynamic_ncols=True): - blabla() - sleep(.5) + # tqdm call need to specify sys.stdout, not sys.stderr (default) + # and dynamic_ncols=True to autodetect console width + for _ in tqdm(range(3), file=save_stdout, dynamic_ncols=True): + blabla() + sleep(.5) # After the `with`, printing is restored print('Done!') @@ -768,6 +765,7 @@ Open Source (OSI approved): |Licence| Citation information: |DOI-URI| + Authors -------