From 1eb689c1fc0f00fa334a32476d31194551a3205c Mon Sep 17 00:00:00 2001 From: Casper da Costa-Luis Date: Sun, 11 Oct 2015 18:05:33 +0100 Subject: [PATCH] misc cleaning of docstrings --- CONTRIBUTE | 112 +++++++++++++++++++++++++------------------------- README.md | 27 ++++++++++-- setup.py | 2 +- tqdm/_tqdm.py | 17 +++++--- 4 files changed, 91 insertions(+), 67 deletions(-) diff --git a/CONTRIBUTE b/CONTRIBUTE index 591c2770..e795fafc 100644 --- a/CONTRIBUTE +++ b/CONTRIBUTE @@ -1,41 +1,40 @@ HOW TO CONTRIBUTE TO TQDM -=========================== +========================= -This file describes how to contribute changes to the project, and how to -upload to the pypi repository. +This file describes how to contribute changes to the project, and how to +upload to the pypi repository. -HOW TO COMMIT YOUR CONTRIBUTIONS ------------------------------------------------------------ +HOW TO COMMIT YOUR CONTRIBUTIONS +-------------------------------- -Contributions to the project is made using the `Fork & Pull` model. -Here's a quickstart on how to do that (your mileage may vary depending -on your git config): +Contributions to the project is made using the "Fork & Pull" model. Here's a +quickstart on how to do that (your mileage may vary depending on your git +config): -- first create an account on github. -- then go on the tqdm page `https://github.com/tqdm/tqdm` and fork it -(click on the fork button). -- now make a local clone of the project: -`git clone https://github.com/your_account/tqdm.git` -- do your changes on your local copy. +- create an account on [github](https://github.com) +- fork [tqdm](https://github.com/tqdm/tqdm) +- make a local clone: `git clone https://github.com/your_account/tqdm.git` +- make your changes on your local copy - commit your changes `git commit -m "my message"` -- TEST YOUR CHANGES (see below). -- push to your github account `git push origin` -- and now you can make a `Pull Request` from your github fork by -going to the webpage and clicking on `Pull Request`. You can then add a -message to describe your proposal. -- Your changes will then be reviewed and integrated into the project if OK. +- TEST YOUR CHANGES (see below) +- `push` to your github account: `git push origin` +- finally, 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.) TESTING -------------- +------- -Before submitting a Pull Request, you need to make sure that all the -unit tests pass. This will ensure that your changes did not introduce -any regression in the features that already working. +To test functionality on your machine (such as before submitting a Pull +Request), there are a number of unit tests. -To run the test, cd to the root of the tqdm folder (in the same folder -as this file), and then type the following (you need to install `tox`): +To run the tests, + +- install `tox` +- `cd` to the root of the `tqdm` directory (in the same folder as this file) +- run the following commands: ``` make test @@ -43,67 +42,68 @@ make coverage make flake8 ``` -Alternatively, if you can't use the Makefile, you can use the following to run -the tests (you need to install the `nosetest` python module before): +Alternatively (if you can't use `make`) + +- install `nosetest` +- run the following commands: ``` nosetests --with-coverage --cover-package=tqdm -v tqdm/ python -m flake8 tqdm/_tqdm.py ``` -If all the tests pass, then everything's good, you can submit a Pull Request. - SEMANTIC VERSIONING ----------------------------------- +------------------- -The tqdm repository managers should regularly bump the version number in -the VERSION file to follow the [Semantic Versioning](http://semver.org/) -convention. +The tqdm repository managers should regularly bump the version number in the +VERSION file to follow the [Semantic Versioning](http://semver.org/) +convention. -Tools can be used to automate this process, such as -[bumpversion](https://github.com/peritus/bumpversion) or -[python-semanticversion](https://github.com/rbarrois/python-semanticvers -ion/) to automate this task. +Tools can be used to automate this process, such as +[bumpversion](https://github.com/peritus/bumpversion) or +[python-semanticversion](https://github.com/rbarrois/python-semanticversion/) +to automate this task. -The managers should take care of this instead of users to avoid PR -conflicts solely due to the VERSION file bumping. +The managers should take care of this instead of users to avoid PR conflicts +solely due to the VERSION file bumping. BUILDING A RELEASE AND UPLOADING TO PYPI ---------------------------------------------------------------------- +---------------------------------------- -First, we need to check the setup.py and MANIFEST.in files, which define -the packaging process and the infos that will be uploaded to pypi. +First, check `setup.py` and `MANIFEST.in`, which define the packaging +process and info that will be uploaded to [pypi](pypi.python.org). -You can check the result easily by using the following commands: +Check the result by using the following commands: ``` python setup.py develop --uninstall python setup.py develop -``` +``` -Secondly, we need to build tqdm into a distributable python package: +Secondly, build tqdm into a distributable python package: ``` python setup.py sdist --formats=gztar,zip bdist_wininst --plat-name=win32 python setup.py sdist bdist_wheel --plat-name=win32 -``` +``` -This will generate several builds in the dist/ folder. +This will generate several builds in the `dist/` folder. -Finally, we can upload everything to pypi. Uploading to pypi can be done -easily using the [twine](https://github.com/pypa/twine) module: +Finally, we can upload everything to pypi. Uploading to pypi can be done +easily using the [twine](https://github.com/pypa/twine) module: ``` twine upload dist/* ``` -NOTE: you can also test on the pypi test servers `testpypi.python.org/pypi` -before the real deployment. Note also that in case of a mistake, you can delete -an uploaded release on pypi, but you cannot re-upload another with the same -version number! +NOTE: -Also, the new release can be added to the Github by creating a new release from -the web interface. +- you can also test on the pypi test servers `testpypi.python.org/pypi` +before the real deployment +- in case of a mistake, you can delete an uploaded release on pypi, but you +cannot re-upload another with the same version number! +Also, the new release can be added to the Github by creating a new release +from the web interface. diff --git a/README.md b/README.md index d3c04f0e..8d814a56 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,15 @@ tqdm (read taqadum, تقدّم) means "progress" in arabic. Instantly make your loops show a progress meter - just wrap any iterable with -"tqdm(iterable)", and you're done! Here's what the output looks like: +"tqdm(iterable)", and you're done! + +```python +from tqdm import tqdm +for i in tqdm(range(16)): + ... +``` + +Here's what the output looks like: 76%|████████████████████` ` ` ` ` ` | 7641/10000 [00:34<00:10, 222.22 it/s] @@ -22,15 +30,24 @@ competition [ProgressBar](https://code.google.com/p/python-progressbar/) has an 800ns/iter overhead. It's a matter of taste, but we also like to think our version is much more visually appealing. + ## Installation +### Latest pypi stable release + ```sh -# Latest stable release on pypi pip install tqdm -# Latest development release on github +``` + +### Latest development release on github + +Pull and install in the current directory: + +``` pip install -e git+https://github.com/tqdm/tqdm.git@master#egg=tqdm ``` + ## Documentation ```python @@ -176,6 +193,7 @@ It is recommend to use `miniters=1` whenever there is potentially large differences in iteration speed (e.g. downloading a file over a patchy connection). + ## Contributions To run the testing suite please make sure tox (http://tox.testrun.org/) @@ -190,7 +208,8 @@ $ make test $ make coverage ``` -See also the CONTRIBUTE file for more information. +See the [CONTRIBUTE](CONTRIBUTE) file for more information. + ## License diff --git a/setup.py b/setup.py index f3a8cb95..f389a9a8 100755 --- a/setup.py +++ b/setup.py @@ -6,7 +6,7 @@ from setuptools import setup setup( name='tqdm', version=__version__, - description='A Simple And Fast Python Progress Meter', + description='A Fast, Extensible Progress Meter', license='MIT License', author='Noam Yorav-Raphael', author_email='noamraph@gmail.com', diff --git a/tqdm/_tqdm.py b/tqdm/_tqdm.py index d284bf1e..7a913d58 100644 --- a/tqdm/_tqdm.py +++ b/tqdm/_tqdm.py @@ -470,10 +470,15 @@ class tqdm(object): n, self.total, elapsed, ncols, self.desc, ascii, unit, unit_scale)) + # If no `miniters` was specified, adjust automatically + # to the maximum iteration rate seen so far. if dynamic_miniters: miniters = max(miniters, delta_it) + + # Store old values for next call last_print_n = n last_print_t = cur_t + # Closing the progress bar. # Update some internal variables for close(). self.last_print_n = last_print_n @@ -573,15 +578,15 @@ class tqdm(object): self.n, self.total, elapsed, self.ncols, self.desc, self.ascii, self.unit, self.unit_scale)) - # If no miniters was specified, adjust automatically to the - # maximum iteration increase we have seen yet - # eg, if you do tqdm.update(5), then the subsequent - # calls to tqdm.update() won't update the progress bar - # until it reach 5 more iterations. + # If no `miniters` was specified, adjust automatically to the + # maximum iteration rate seen so far. + # e.g.: After running `tqdm.update(5)`, subsequent + # calls to `tqdm.update()` will only cause an update after + # at least 5 more iterations. if self.dynamic_miniters: self.miniters = max(self.miniters, delta_it) - # Update the memorization vars + # Store old values for next call self.last_print_n = self.n self.last_print_t = cur_t