bump version, merge branch 'devel'

.travis.yml

@@ -21,7 +21,7 @@ matrix:
     env: TOXENV=pypy3
   - python: 3.6
     env: TOXENV=flake8
-  - python: 2.7
+  - python: 3.6
     env: TOXENV=perf
 # use cache for big builds like pandas (to minimise build time).
 # If issues, clear cache

CONTRIBUTING.md

@@ -28,8 +28,8 @@ typical steps would be:
 3. make a local clone: `git clone https://github.com/your_account/tqdm.git`
 4. make changes on the local copy
 5. test (see below) and commit changes `git commit -a -m "my message"`
-6. `push` to your github account: `git push origin`
-7. create a Pull Request (PR) from your github fork
+6. `push` to your GitHub account: `git push origin`
+7. create a Pull Request (PR) from your GitHub fork
 (go to your fork's webpage and click on "Pull Request."
 You can then add a message to describe your proposal.)
 
@@ -103,15 +103,15 @@ Note: tools can be used to automate this process, such as
 
 ## Checking setup.py
 
-To check that the `setup.py` file is compliant with PyPi requirements (e.g.
-version number; reStructuredText in README.rst) use:
+To check that the `setup.py` file is compliant with PyPI requirements (e.g.
+version number; reStructuredText in `README.rst`) use:
 
 ```
 [python setup.py] make testsetup
 ```
 
 To upload just metadata (including overwriting mistakenly uploaded metadata)
-to PyPi, use:
+to PyPI, use:
 
 ```
 [python setup.py] make pypimeta
@@ -190,7 +190,7 @@ Formally publishing requires additional steps: testing and tagging.
 
 - ensure that all online CI tests have passed
 - check `setup.py` and `MANIFEST.in` - which define the packaging
-process and info that will be uploaded to [pypi](https://pypi.org) -
+process and info that will be uploaded to [PyPI](https://pypi.org) -
 using `[python setup.py] make installdev`
 
 ### Tag
@@ -219,34 +219,35 @@ Finally, upload everything to pypi. This can be done easily using the
 [python setup.py] make pypi
 ```
 
-Also, the new release can (should) be added to `github` by creating a new
+Also, the new release can (should) be added to GitHub by creating a new
 release from the web interface; uploading packages from the `dist/` folder
 created by `[python setup.py] make build`.
-The [wiki] can be automatically updated with github release notes by
+The [wiki] can be automatically updated with GitHub release notes by
 running `make` within the wiki repository.
 
 [wiki]: https://github.com/tqdm/tqdm/wiki
 
 ### Notes
 
-- you can also test on the pypi test servers `test.pypi.org`
+- you can also test on the PyPI test servers `test.pypi.org`
 before the real deployment
-- in case of a mistake, you can delete an uploaded release on pypi, but you
+- in case of a mistake, you can delete an uploaded release on PyPI, but you
 cannot re-upload another with the same version number
-- in case of a mistake in the metadata on pypi (e.g. bad README),
+- in case of a mistake in the metadata on PyPI (e.g. bad README),
 updating just the metadata is possible: `[python setup.py] make pypimeta`
 
 
 ## Updating Websites
 
-The most important file is `README.rst`, which sould always be kept up-to-date
+The most important file is `.readme.rst`, which should always be kept up-to-date
 and in sync with the in-line source documentation. This will affect all of the
 following:
 
+- `README.rst` (generated by `mkdocs.py` during `make build`)
 - The [main repository site](https://github.com/tqdm/tqdm) which automatically
-  serves the latest `README.rst` as well as links to all of github's features.
+  serves the latest `README.rst` as well as links to all of GitHub's features.
   This is the preferred online referral link for `tqdm`.
-- The [PyPi mirror](https://pypi.org/project/tqdm) which automatically
+- The [PyPI mirror](https://pypi.org/project/tqdm) which automatically
   serves the latest release built from `README.rst` as well as links to past
   releases.
 - Many external web crawlers.
@@ -277,7 +278,7 @@ For experienced devs, once happy with local master:
 9. upload to PyPI using one of the following:
     a) `[python setup.py] make pypi`
     b) `twine upload -s -i $(git config user.signingkey) dist/tqdm-*`
-10. create new release on https://github.com/tqdm/tqdm/releases
+10. create new release on <https://github.com/tqdm/tqdm/releases>
     a) add helpful release notes
     b) attach `dist/tqdm-*` binaries (usually only `*.whl*`)
 11. run `make` in the `wiki` submodule to update release notes

Makefile

@@ -50,6 +50,7 @@ testnose:
 	nosetests tqdm -d -v
 
 testsetup:
+	@make README.rst
 	python setup.py check --restructuredtext --strict
 	python setup.py make none
 
@@ -80,13 +81,17 @@ viewasv:
 	asv preview
 
 tqdm/tqdm.1: .tqdm.1.md
+	# TODO: add to mkdocs.py
 	python -m tqdm --help | tail -n+5 |\
     sed -r -e 's/\\/\\\\/g' \
       -e 's/^  (--.*)=<(.*)>  : (.*)$$/\n\\\1=*\2*\n: \3./' \
       -e 's/  (-.*, )(--.*)  /\n\1\\\2\n: /' |\
     cat "$<" - |\
     pandoc -o "$@" -s -t man
 
+README.rst: .readme.rst tqdm/_tqdm.py tqdm/_main.py
+	@python mkdocs.py
+
 distclean:
 	@+make coverclean
 	@+make prebuildclean
@@ -122,14 +127,14 @@ install:
 
 build:
 	@make prebuildclean
+	@make testsetup
 	python setup.py sdist bdist_wheel
 	# python setup.py bdist_wininst
 
 pypi:
 	twine upload dist/*
 
 buildupload:
-	@make testsetup
 	@make build
 	@make pypi
 

README.rst

@@ -301,7 +301,7 @@ Parameters
 * file  : ``io.TextIOWrapper`` or ``io.StringIO``, optional  
     Specifies where to output the progress messages
     (default: sys.stderr). Uses ``file.write(str)`` and ``file.flush()``
-    methods.
+    methods.  For encoding, see ``write_bytes``.
 * ncols  : int, optional  
     The width of the entire output message. If specified,
     dynamically resizes the progressbar to stay within this bound.
@@ -323,9 +323,9 @@ Parameters
     Tweak this and ``mininterval`` to get very efficient loops.
     If your progress is erratic with both fast and slow iterations
     (network, skipping items, etc) you should set miniters=1.
-* ascii  : bool, optional  
+* ascii  : bool or str, optional  
     If unspecified or False, use unicode (smooth blocks) to fill
-    the meter. The fallback is to use ASCII characters ``1-9 #``.
+    the meter. The fallback is to use ASCII characters " 123456789#".
 * disable  : bool, optional  
     Whether to disable the entire progressbar wrapper
     [default: False]. If set to None, disable on non-TTY.
@@ -337,8 +337,8 @@ Parameters
     automatically and a metric prefix following the
     International System of Units standard will be added
     (kilo, mega, etc.) [default: False]. If any other non-zero
+    number, will scale ``total`` and ``n``.
 * dynamic_ncols  : bool, optional  
-    number, will scale ```total`` and ``n``.
     If set, constantly alters ``ncols`` to the environment (allowing
     for window resizes) [default: False].
 * smoothing  : float, optional  
@@ -353,7 +353,8 @@ Parameters
     '{rate_fmt}{postfix}]'
     Possible vars: l_bar, bar, r_bar, n, n_fmt, total, total_fmt,
     percentage, rate, rate_fmt, rate_noinv, rate_noinv_fmt,
-    rate_inv, rate_inv_fmt, elapsed, remaining, desc, postfix.
+    rate_inv, rate_inv_fmt, elapsed, elapsed_s, remaining,
+    remaining_s, desc, postfix, unit.
     Note that a trailing ": " is automatically removed after {desc}
     if the latter is empty.
 * initial  : int, optional  
@@ -368,6 +369,10 @@ Parameters
     Calls ``set_postfix(**postfix)`` if possible (dict).
 * unit_divisor  : float, optional  
     [default: 1000], ignored unless ``unit_scale`` is True.
+* write_bytes  : bool, optional  
+    If (default: None) and ``file`` is unspecified,
+    bytes will be written in Python 2. If ``True`` will also write
+    bytes. In all other cases will default to unicode.
 
 Extra CLI Options
 ~~~~~~~~~~~~~~~~~
@@ -379,7 +384,8 @@ Extra CLI Options
     String buffer size in bytes [default: 256]
     used when ``delim`` is specified.
 * bytes  : bool, optional  
-    If true, will count bytes and ignore ``delim``.
+    If true, will count bytes, ignore ``delim``, and default
+    ``unit_scale`` to True, ``unit_divisor`` to 1024, and ``unit`` to 'B'.
 * manpath  : str, optional  
     Directory in which to install tqdm man pages.
 * log  : str, optional  
@@ -537,7 +543,7 @@ Points to remember when using ``{postfix[...]}`` in the ``bar_format`` string:
   where the key is not a string.
 
 Additional ``bar_format`` parameters may also be defined by overriding
-``format_dict``:
+``format_dict``, and the bar itself may be modified using ``ascii``:
 
 .. code:: python
 
@@ -552,10 +558,14 @@ Additional ``bar_format`` parameters may also be defined by overriding
             return d
 
     for i in TqdmExtraFormat(
-          range(10),
+          range(10), ascii=" .oO0",
           bar_format="{total_time}: {percentage:.0f}%|{bar}{r_bar}"):
         pass
 
+.. code::
+
+    00:01 in total: 40%|000o     | 4/10 [00:00<00:00,  9.96it/s]
+
 Nested progress bars
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -715,6 +725,20 @@ 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.
 
+Custom Integration
+~~~~~~~~~~~~~~~~~~
+
+``tqdm`` may be inherited from to create custom callbacks (as with the
+``TqdmUpTo`` example `above <#hooks-and-callbacks>`__) or for custom frontends
+(e.g. GUIs such as notebook or plotting packages). In the latter case:
+
+1. ``def __init__()`` to call ``super().__init__(..., gui=True)`` to disable
+   terminal ``status_printer`` creation.
+2. Redefine: ``close()``, ``clear()``, ``display()``.
+
+Consider overloading ``display()`` to use e.g.
+``self.frontend(**self.format_dict)`` instead of ``self.sp(repr(self))``.
+
 Writing messages
 ~~~~~~~~~~~~~~~~
 

mkdocs.py

@@ -0,0 +1,58 @@
+from __future__ import print_function
+import tqdm
+from textwrap import dedent
+from io import open as io_open
+from os import path
+
+HEAD_ARGS = """
+Parameters
+----------
+"""
+HEAD_RETS = """
+Returns
+-------
+"""
+HEAD_CLI = """
+Extra CLI Options
+-----------------
+name  : type, optional
+    TODO: find out why this is needed.
+"""
+
+
+def doc2rst(doc, arglist=True):
+    """
+    arglist  : bool, whether to create argument lists
+    """
+    doc = dedent(doc).replace('`', '``')
+    if arglist:
+        doc = '\n'.join([i if not i or i[0] == ' ' else '* ' + i + '  '
+                         for i in doc.split('\n')])
+    return doc
+
+
+src_dir = path.abspath(path.dirname(__file__))
+README_rst = path.join(src_dir, '.readme.rst')
+with io_open(README_rst, mode='r', encoding='utf-8') as fd:
+    README_rst = fd.read()
+DOC_tqdm = doc2rst(tqdm.tqdm.__doc__, False).replace('\n', '\n      ')
+DOC_tqdm_init = doc2rst(tqdm.tqdm.__init__.__doc__)
+DOC_tqdm_init_args = DOC_tqdm_init.partition(doc2rst(HEAD_ARGS))[-1]\
+    .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]
+
+# special cases
+DOC_tqdm_init_args = DOC_tqdm_init_args.replace(' *,', ' ``*``,')
+DOC_tqdm_init_args = DOC_tqdm_init_args.partition('* gui  : bool, optional')[0]
+
+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.tqdm.__init__.Returns}', DOC_tqdm_init_rets)
+
+if __name__ == "__main__":
+    fndoc = path.join(src_dir, 'README.rst')
+    with io_open(fndoc, mode='w', encoding='utf-8') as fd:
+        fd.write(README_rst)

setup.py

@@ -46,8 +46,6 @@ def find_packages(where='.'):
     description='Fast, Extensible Progress Meter',
     long_description=README_rst,
     license='MPLv2.0, MIT Licences',
-    author='Noam Yorav-Raphael',
-    author_email='noamraph@gmail.com',
     url='https://github.com/tqdm/tqdm',
     maintainer='tqdm developers',
     maintainer_email='python.tqdm@gmail.com',

tqdm/_main.py

@@ -99,7 +99,7 @@ def posix_pipe(fin, fout, delim='\n', buf_size=256,
         Extra CLI Options
         -----------------
         name  : type, optional
-             TODO: find out why this is needed.
+            TODO: find out why this is needed.
         delim  : chr, optional
             Delimiting character [default: '\n']. Use '\0' for null.
             N.B.: on Windows systems, Python converts '\n' to '\r\n'.