bump version, merge branch 'devel'

WhiteRobe · Sep 17, 2019 · 89b73bd · 89b73bd
2 parents f856c57 + 1bd486c
commit 89b73bd
Show file tree

Hide file tree

Showing 27 changed files with 2,740 additions and 2,616 deletions.
diff --git a/.meta/.readme.rst b/.meta/.readme.rst
@@ -40,7 +40,7 @@ It can also be executed as a module with pipes:
         tqdm --total $(find docs/ -type f | wc -l) --unit files >> backup.log
     100%|███████████████████████████████▉| 8014/8014 [01:37<00:00, 82.29files/s]
 
-Overhead is low -- about 60ns per iteration (80ns with ``tqdm_gui``), and is
+Overhead is low -- about 60ns per iteration (80ns with ``tqdm.gui``), and is
 unit tested against performance regression.
 By comparison, the well-established
 `ProgressBar <https://github.com/niltonvolpato/python-progressbar>`__ has
@@ -303,7 +303,7 @@ Parameters
 Extra CLI Options
 ~~~~~~~~~~~~~~~~~
 
-{DOC_tqdm._main.CLI_EXTRA_DOC}
+{DOC_tqdm.cli.CLI_EXTRA_DOC}
 Returns
 ~~~~~~~
 
@@ -352,16 +352,16 @@ Returns
         On Python3+ range is used instead of xrange.
         """
 
-    class tqdm_gui(tqdm):
+    class tqdm.gui.tqdm(tqdm.tqdm):
         """Experimental GUI version"""
 
-    def tgrange(*args, **kwargs):
+    def tqdm.gui.trange(*args, **kwargs):
         """Experimental GUI version of trange"""
 
-    class tqdm_notebook(tqdm):
+    class tqdm.notebook.tqdm(tqdm.tqdm):
         """Experimental IPython/Jupyter Notebook widget"""
 
-    def tnrange(*args, **kwargs):
+    def tqdm.notebook.trange(*args, **kwargs):
         """Experimental IPython/Jupyter Notebook widget version of trange"""
 
 
@@ -373,9 +373,9 @@ Examples and Advanced Usage
 - import the module and run ``help()``;
 - consult the `wiki <https://github.com/tqdm/tqdm/wiki>`__;
 
-    * this has an
-      `excellent article <https://github.com/tqdm/tqdm/wiki/How-to-make-a-great-Progress-Bar>`__
-      on how to make a **great** progressbar;
+  * this has an
+    `excellent article <https://github.com/tqdm/tqdm/wiki/How-to-make-a-great-Progress-Bar>`__
+    on how to make a **great** progressbar;
 
 - run the |notebook-demo| or |binder-demo|, or
 - check out the `slides from PyData London <https://tqdm.github.io/PyData2019/slides.html>`__.
@@ -476,32 +476,54 @@ Nested progress bars
 On Windows `colorama <https://github.com/tartley/colorama>`__ will be used if
 available to keep nested bars on their respective lines.
 
-For manual control over positioning (e.g. for multi-threaded use),
+For manual control over positioning (e.g. for multi-processing use),
 you may specify ``position=n`` where ``n=0`` for the outermost bar,
 ``n=1`` for the next, and so on:
 
 .. code:: python
 
     from time import sleep
     from tqdm import trange, tqdm
-    from multiprocessing import Pool, freeze_support, RLock
+    from multiprocessing import Pool, freeze_support
 
     L = list(range(9))
 
     def progresser(n):
         interval = 0.001 / (n + 2)
         total = 5000
         text = "#{}, est. {:<04.2}s".format(n, interval * total)
-        for i in trange(total, desc=text, position=n):
+        for _ in trange(total, desc=text, position=n):
             sleep(interval)
 
     if __name__ == '__main__':
         freeze_support()  # for Windows support
-        p = Pool(len(L),
-                 # again, for Windows support
-                 initializer=tqdm.set_lock, initargs=(RLock(),))
+        p = Pool(len(L), initializer=tqdm.set_lock, initargs=(tqdm.get_lock(),))
         p.map(progresser, L)
-        print("\n" * (len(L) - 2))
+
+Note that in python 3, threads do not require manual positioning,
+and ``tqdm.write`` is safe to use:
+
+.. code:: python
+
+    from time import sleep
+    from tqdm import tqdm, trange
+    from concurrent.futures import ThreadPoolExecutor
+
+    L = list(range(9))
+
+    def progresser(n):
+        interval = 0.001 / (n + 2)
+        total = 5000
+        text = "#{}, est. {:<04.2}s".format(n, interval * total)
+        for _ in trange(total, desc=text):
+            sleep(interval)
+        if n == 6:
+            tqdm.write("n == 6 completed.")
+            tqdm.write("`tqdm.write()` is thread-safe in py3!")
+
+    if __name__ == '__main__':
+        with ThreadPoolExecutor() as p:
+            p.map(progresser, L)
 
 Hooks and callbacks
 ~~~~~~~~~~~~~~~~~~~
@@ -567,7 +589,7 @@ for ``DataFrame.progress_apply`` and ``DataFrameGroupBy.progress_apply``:
     df = pd.DataFrame(np.random.randint(0, 100, (100000, 6)))
 
     # Register `pandas.progress_apply` and `pandas.Series.map_apply` with `tqdm`
-    # (can use `tqdm_gui`, `tqdm_notebook`, optional kwargs, etc.)
+    # (can use `tqdm.gui.tqdm`, `tqdm.notebook.tqdm`, optional kwargs, etc.)
     tqdm.pandas(desc="my bar!")
 
     # Now you can use `progress_apply` instead of `apply`
@@ -584,15 +606,15 @@ folder or import the module and run ``help()``.
 IPython/Jupyter Integration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-IPython/Jupyter is supported via the ``tqdm_notebook`` submodule:
+IPython/Jupyter is supported via the ``tqdm.notebook`` submodule:
 
 .. code:: python
 
-    from tqdm import tnrange, tqdm_notebook
+    from tqdm.notebook import trange, tqdm
     from time import sleep
 
-    for i in tnrange(3, desc='1st loop'):
-        for j in tqdm_notebook(range(100), desc='2nd loop'):
+    for i in trange(3, desc='1st loop'):
+        for j in tqdm(range(100), desc='2nd loop'):
             sleep(0.01)
 
 In addition to ``tqdm`` features, the submodule provides a native Jupyter
@@ -631,6 +653,11 @@ Custom Integration
 Consider overloading ``display()`` to use e.g.
 ``self.frontend(**self.format_dict)`` instead of ``self.sp(repr(self))``.
 
+`tqdm/notebook.py <https://github.com/tqdm/tqdm/blob/master/tqdm/notebook.py>`__
+and `tqdm/gui.py <https://github.com/tqdm/tqdm/blob/master/tqdm/gui.py>`__
+submodules are examples of inheritance which don't (yet) strictly conform to the
+above recommendation.
+
 Dynamic Monitor/Meter
 ~~~~~~~~~~~~~~~~~~~~~
 

diff --git a/.meta/mkdocs.py b/.meta/mkdocs.py
@@ -1,5 +1,6 @@
 from __future__ import print_function
 import tqdm
+import tqdm.cli
 from textwrap import dedent
 from io import open as io_open
 from os import path
@@ -47,7 +48,7 @@ def doc2rst(doc, arglist=True, raw=False):
     .replace('\n      ', '\n    ')
 DOC_tqdm_init_args, _, DOC_tqdm_init_rets = DOC_tqdm_init_args\
     .partition(doc2rst(HEAD_RETS))
-DOC_cli = doc2rst(tqdm._main.CLI_EXTRA_DOC).partition(doc2rst(HEAD_CLI))[-1]
+DOC_cli = doc2rst(tqdm.cli.CLI_EXTRA_DOC).partition(doc2rst(HEAD_CLI))[-1]
 DOC_tqdm_tqdm = {}
 for i in dir(tqdm.tqdm):
     doc = getattr(tqdm.tqdm, i).__doc__
@@ -60,7 +61,7 @@ def doc2rst(doc, arglist=True, raw=False):
 
 README_rst = README_rst.replace('{DOC_tqdm}', DOC_tqdm)\
     .replace('{DOC_tqdm.tqdm.__init__.Parameters}', DOC_tqdm_init_args)\
-    .replace('{DOC_tqdm._main.CLI_EXTRA_DOC}', DOC_cli)\
+    .replace('{DOC_tqdm.cli.CLI_EXTRA_DOC}', DOC_cli)\
     .replace('{DOC_tqdm.tqdm.__init__.Returns}', DOC_tqdm_init_rets)
 for k, v in DOC_tqdm_tqdm.items():
     README_rst = README_rst.replace('{DOC_tqdm.tqdm.%s}' % k, v)

diff --git a/.zenodo.json b/.zenodo.json
@@ -4,8 +4,10 @@
     "progressbar", "progressmeter", "progress-bar", "meter", "rate", "eta",
     "console", "terminal", "time", "progress", "bar", "gui", "python",
     "parallel", "cli", "utilities", "shell", "batch"],
+  "related_identifiers": [
+    {"identifier": "10.21105/joss.01277", "relation": "cites"}],
   "creators": [
     {"name": "da Costa-Luis, Casper O.", "orcid": "0000-0002-7211-1557"}],
   "contributors": [
-    {"name": "tqdm developers", "type": "other", "affiliation": "tqdm"}]
+    {"name": "tqdm developers", "type": "Other", "affiliation": "tqdm"}]
 }
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -34,8 +34,36 @@ typical steps would be:
 You can then add a message to describe your proposal.)
 
 
+## WHAT CODE LAYOUT SHOULD I FOLLOW?
+
+Don't worry too much - maintainers can help reorganise contributions.
+However it would be helpful to bear in mind:
+
+- The standard core of `tqdm`, i.e. [`tqdm.std.tqdm`](tqdm/std.py)
+    + must have no dependencies apart from pure python built-in standard libraries
+    + must have negligible impact on performance
+    + should have 100% coverage by unit tests
+    + should be appropriately commented
+    + will not break backward compatibility unless there is a very good reason
+        * e.g. breaking py26 compatibility purely in favour of readability (such as converting `dict(a=1)` to `{'a': 1}`) is not a good enough reason
+    + API changes should be discussed carefully
+    + remember, with millions of downloads per month, `tqdm` must be extremely fast and reliable
+- Any other kind of change may be included in a (possibly new) submodule
+    + submodules are likely single python files under the main [tqdm/](tqdm/) directory
+        * large submodules requiring a sub-folder should be included in [`MANIFEST.in`](MANIFEST.in)
+    + submodules extending `tqdm.std.tqdm` or any other module (e.g. [`tqdm.notebook.tqdm`](tqdm/notebook.py), [`tqdm.gui.tqdm`](tqdm/gui.py))
+    + can implement anything from experimental new features to support for third-party libraries such as `pandas`, `numpy`, etc.
+    + submodule maturity
+        * alpha: experimental; missing unit tests, comments, and/or feedback; raises `tqdm.TqdmExperimentalWarning`
+        * beta: well-used; commented, perhaps still missing tests
+        * stable: >10 users; commented, 80% coverage
+
+
 ## TESTING
 
+Once again, don't worry too much - tests are automated online, and maintainers
+can also help.
+
 To test functionality (such as before submitting a Pull
 Request), there are a number of unit tests.
 

diff --git a/MANIFEST.in b/MANIFEST.in
@@ -11,10 +11,6 @@ include tox.ini
 recursive-include tqdm/tests *.py
 include requirements-dev.txt
 
-# Sub-packages
-recursive-include tqdm/autonotebook *.py
-recursive-include tqdm/auto *.py
-
 # Examples/Documentation
 recursive-include examples *.py
 include README.rst

diff --git a/Makefile b/Makefile
@@ -46,7 +46,8 @@ flake8:
 	@+flake8 -j 8 --count --statistics --exit-zero .
 
 test:
-	tox --skip-missing-interpreters
+	TOX_SKIP_ENV=perf tox --skip-missing-interpreters -p all
+	tox -e perf
 
 testnose:
 	nosetests tqdm -d -v