bump version, merge branch 'devel'

.coveragerc

@@ -2,5 +2,6 @@
 branch = True
 omit =
     tqdm/tests/*
+    tqdm/contrib/telegram.py
 [report]
 show_missing = True

.meta/.readme.rst

@@ -111,6 +111,9 @@ There are 3 channels to choose from:
     snap install tqdm  --candidate  # master branch
     snap install tqdm  --edge  # devel branch
 
+Note than ``snap`` binaries are purely for CLI use (not ``import``-able), and
+automatically set up ``bash`` tab-completion.
+
 Latest Docker release
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -419,10 +422,14 @@ Returns
     def tqdm.contrib.tmap(function, *sequences, **tqdm_kwargs):
         """Equivalent of builtin `map`."""
 
+``contrib``
+-----------
+
 The ``tqdm.contrib`` package also contains experimental modules:
 
 - ``tqdm.contrib.itertools``: Thin wrappers around ``itertools``
 - ``tqdm.contrib.concurrent``: Thin wrappers around ``concurrent.futures``
+- ``tqdm.contrib.telegram``: Posts to `Telegram <https://telegram.org/>`__ bots
 
 Examples and Advanced Usage
 ---------------------------
@@ -621,7 +628,7 @@ Here's an example with ``urllib``:
             self.update(b * bsize - self.n)  # will also set self.n = b * bsize
 
     eg_link = "https://caspersci.uk.to/matryoshka.zip"
-    with TqdmUpTo(unit='B', unit_scale=True, miniters=1,
+    with TqdmUpTo(unit='B', unit_scale=True, unit_divisor=1024, miniters=1,
                   desc=eg_link.split('/')[-1]) as t:  # all optional kwargs
         urllib.urlretrieve(eg_link, filename=os.devnull,
                            reporthook=t.update_to, data=None)
@@ -670,6 +677,21 @@ down to:
         for chunk in urllib.urlopen(eg_link):
             fout.write(chunk)
 
+The ``requests`` equivalent is nearly identical, albeit with a ``total``:
+
+.. code:: python
+
+    import requests, os
+    from tqdm import tqdm
+
+    eg_link = "https://caspersci.uk.to/matryoshka.zip"
+    response = requests.get(eg_link, stream=True)
+    with tqdm.wrapattr(open(os.devnull, "wb"), "write",
+                       miniters=1, desc=eg_link.split('/')[-1],
+                       total=response.headers.get('content-length')) as fout:
+        for chunk in response.iter_content(chunk_size=4096):
+            fout.write(chunk)
+
 Pandas Integration
 ~~~~~~~~~~~~~~~~~~
 

.meta/.snapcraft.yml

@@ -44,6 +44,10 @@ parts:
     source: {source}
     source-commit: '{commit}'
     parse-info: [setup.py]
+    override-build: |
+        snapcraftctl build
+        cp $SNAPCRAFT_PART_BUILD/tqdm/completion.sh $SNAPCRAFT_PART_INSTALL/
 apps:
   tqdm:
     command: bin/tqdm
+    completer: completion.sh

.meta/mkcompletion.py

@@ -0,0 +1,68 @@
+"""
+Auto-generate tqdm/completion.sh from docstrings.
+"""
+from __future__ import print_function
+from io import open as io_open
+from os import path
+import re
+import sys
+
+sys.path.insert(0, path.dirname(path.dirname(__file__)))  # NOQA
+import tqdm
+import tqdm.cli
+
+RE_OPT = re.compile(r'(\w+)  :', flags=re.M)
+RE_OPT_INPUT = re.compile(
+    r'(\w+)  : (?:str|int|float|chr|dict|tuple)', flags=re.M)
+
+
+def doc2opt(doc, user_input=True):
+    """
+    doc  : str, document to parse
+    user_input  : bool, optional.
+      [default: True] for only options requiring user input
+    """
+    RE = RE_OPT_INPUT if user_input else RE_OPT
+    return ('--' + i for i in RE.findall(doc))
+
+
+# CLI options
+options = {'-h', '--help', '-v', '--version'}
+options_input = set()
+for doc in (tqdm.tqdm.__init__.__doc__, tqdm.cli.CLI_EXTRA_DOC):
+    options.update(doc2opt(doc, user_input=False))
+    options_input.update(doc2opt(doc, user_input=True))
+options.difference_update(
+    '--' + i for i in ('name',) + tqdm.cli.UNSUPPORTED_OPTS)
+options_input &= options
+options_input -= {"--log"}  # manually dealt with
+src_dir = path.abspath(path.dirname(__file__))
+completion = u"""\
+#!/usr/bin/env bash
+_tqdm(){{
+  local cur prv
+  cur="${{COMP_WORDS[COMP_CWORD]}}"
+  prv="${{COMP_WORDS[COMP_CWORD - 1]}}"
+
+  case ${{prv}} in
+  {opts_manual})
+    # await user input
+    ;;
+  "--log")
+    COMPREPLY=($(compgen -W \
+      'CRITICAL FATAL ERROR WARN WARNING INFO DEBUG NOTSET' -- ${{cur}}))
+    ;;
+  *)
+    COMPREPLY=($(compgen -W '{opts}' -- ${{cur}}))
+    ;;
+  esac
+}}
+complete -F _tqdm tqdm
+""".format(
+    opts=' '.join(sorted(options)),
+    opts_manual='|'.join(sorted(options_input)))
+
+if __name__ == "__main__":
+    fncompletion = path.join(path.dirname(src_dir), 'tqdm', 'completion.sh')
+    with io_open(fncompletion, mode='w', encoding='utf-8') as fd:
+        fd.write(completion)

.meta/mkdocs.py

@@ -1,12 +1,16 @@
+"""
+Auto-generate README.rst from .meta/.readme.rst and docstrings.
+"""
 from __future__ import print_function
+from io import open as io_open
 from os import path
 import sys
-sys.path = [path.dirname(path.dirname(__file__))] + sys.path  # NOQA
+from textwrap import dedent
+
+sys.path.insert(0, path.dirname(path.dirname(__file__)))  # NOQA
 import tqdm
 import tqdm.cli
-from textwrap import dedent
-from io import open as io_open
-from os import path
+
 
 HEAD_ARGS = """
 Parameters

CONTRIBUTING.md

@@ -46,7 +46,7 @@ However it would be helpful to bear in mind:
     + should be appropriately commented
     + should have well-formatted docstrings for functions
         * under 76 chars (incl. initial spaces) to avoid linebreaks in terminal pagers
-        * use two spaces between variable name and colon
+        * use two spaces between variable name and colon, specify a type, and most likely state that it's optional: `VAR<space><space>:<space>TYPE[, optional]`
         * use [default: ...] for default values of keyword arguments
     + 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
@@ -56,11 +56,15 @@ However it would be helpful to bear in mind:
     + 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))
+    + CLI wrapper `tqdm.cli`
+        * if a newly added `tqdm.std.tqdm` option is not supported by the CLI, append to `tqdm.cli.UNSUPPORTED_OPTS`
     + 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
+- `.meta/`
+    + A "hidden" folder containing helper utilities not strictly part of `tqdm` distribution itself
 
 
 ## TESTING
@@ -118,6 +122,12 @@ Also consider `pip install`ing development utilities:
 `-r requirements-dev.txt` or `tqdm[dev]`.
 
 
+## Pre-commit Hook
+
+It's probably a good idea to add `[python setup.py] make pre-commit` to
+`.git/hooks/pre-commit` for convenient local sanity-checking.
+
+
 ## Semantic Versioning
 
 The tqdm repository managers should:

DEMO.ipynb

@@ -431,8 +431,6 @@
       "\n",
       "        Extra CLI Options\n",
       "        -----------------\n",
-      "        name  : type, optional\n",
-      "             TODO: find out why this is needed.\n",
       "        delim  : chr, optional\n",
       "            Delimiting character [default: '\\n']. Use '\\0' for null.\n",
       "            N.B.: on Windows systems, Python converts '\\n' to '\\r\\n'.\n",
@@ -444,6 +442,8 @@
       "            `unit_scale` to True, `unit_divisor` to 1024, and `unit` to 'B'.\n",
       "        manpath  : str, optional\n",
       "            Directory in which to install tqdm man pages.\n",
+      "        comppath  : str, optional\n",
+      "            Directory in which to place tqdm completion.\n",
       "        log  : str, optional\n",
       "            CRITICAL|FATAL|ERROR|WARN(ING)|[default: 'INFO']|DEBUG|NOTSET.\n",
       "\n"
@@ -706,7 +706,7 @@
     "        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",
+    "with TqdmUpTo(unit='B', unit_scale=True, unit_divisor=1024, 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)\n",
@@ -774,6 +774,39 @@
     "        fout.write(chunk)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The `requests` equivalent is nearly identical, albeit with a `total`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "matryoshka.zip: 254kB [00:00, 460kB/s] \n"
+     ]
+    }
+   ],
+   "source": [
+    "import requests, os\n",
+    "from tqdm import tqdm\n",
+    "\n",
+    "eg_link = \"https://caspersci.uk.to/matryoshka.zip\"\n",
+    "response = requests.get(eg_link, stream=True)\n",
+    "with tqdm.wrapattr(open(os.devnull, \"wb\"), \"write\",\n",
+    "                   miniters=1, desc=eg_link.split('/')[-1],\n",
+    "                   total=response.headers.get('content-length')) as fout:\n",
+    "    for chunk in response.iter_content(chunk_size=4096):\n",
+    "        fout.write(chunk)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

MANIFEST.in

@@ -18,4 +18,5 @@ include requirements-dev.txt
 recursive-include examples *.py
 include README.rst
 include tqdm/tqdm.1
+include tqdm/completion.sh
 include DEMO.ipynb

Makefile

@@ -56,6 +56,7 @@ testnose:
 testsetup:
 	@make README.rst
 	@make tqdm/tqdm.1
+	@make tqdm/completion.sh
 	python setup.py check --metadata --restructuredtext --strict
 	python setup.py make none
 
@@ -94,6 +95,9 @@ tqdm/tqdm.1: .meta/.tqdm.1.md tqdm/cli.py tqdm/std.py
     cat "$<" - |\
     pandoc -o "$@" -s -t man
 
+tqdm/completion.sh: .meta/mkcompletion.py tqdm/std.py tqdm/cli.py
+	@python .meta/mkcompletion.py
+
 README.rst: .meta/.readme.rst tqdm/std.py tqdm/cli.py
 	@python .meta/mkdocs.py
 

README.rst

@@ -111,6 +111,9 @@ There are 3 channels to choose from:
     snap install tqdm  --candidate  # master branch
     snap install tqdm  --edge  # devel branch
 
+Note than ``snap`` binaries are purely for CLI use (not ``import``-able), and
+automatically set up ``bash`` tab-completion.
+
 Latest Docker release
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -461,6 +464,8 @@ Extra CLI Options
     ``unit_scale`` to True, ``unit_divisor`` to 1024, and ``unit`` to 'B'.
 * manpath  : str, optional  
     Directory in which to install tqdm man pages.
+* comppath  : str, optional  
+    Directory in which to place tqdm completion.
 * log  : str, optional  
     CRITICAL|FATAL|ERROR|WARN(ING)|[default: 'INFO']|DEBUG|NOTSET.
 
@@ -605,10 +610,14 @@ Returns
     def tqdm.contrib.tmap(function, *sequences, **tqdm_kwargs):
         """Equivalent of builtin `map`."""
 
+``contrib``
+-----------
+
 The ``tqdm.contrib`` package also contains experimental modules:
 
 - ``tqdm.contrib.itertools``: Thin wrappers around ``itertools``
 - ``tqdm.contrib.concurrent``: Thin wrappers around ``concurrent.futures``
+- ``tqdm.contrib.telegram``: Posts to `Telegram <https://telegram.org/>`__ bots
 
 Examples and Advanced Usage
 ---------------------------
@@ -807,7 +816,7 @@ Here's an example with ``urllib``:
             self.update(b * bsize - self.n)  # will also set self.n = b * bsize
 
     eg_link = "https://caspersci.uk.to/matryoshka.zip"
-    with TqdmUpTo(unit='B', unit_scale=True, miniters=1,
+    with TqdmUpTo(unit='B', unit_scale=True, unit_divisor=1024, miniters=1,
                   desc=eg_link.split('/')[-1]) as t:  # all optional kwargs
         urllib.urlretrieve(eg_link, filename=os.devnull,
                            reporthook=t.update_to, data=None)
@@ -856,6 +865,21 @@ down to:
         for chunk in urllib.urlopen(eg_link):
             fout.write(chunk)
 
+The ``requests`` equivalent is nearly identical, albeit with a ``total``:
+
+.. code:: python
+
+    import requests, os
+    from tqdm import tqdm
+
+    eg_link = "https://caspersci.uk.to/matryoshka.zip"
+    response = requests.get(eg_link, stream=True)
+    with tqdm.wrapattr(open(os.devnull, "wb"), "write",
+                       miniters=1, desc=eg_link.split('/')[-1],
+                       total=response.headers.get('content-length')) as fout:
+        for chunk in response.iter_content(chunk_size=4096):
+            fout.write(chunk)
+
 Pandas Integration
 ~~~~~~~~~~~~~~~~~~