Merge #684

684: Add pandas support r=hgrecco a=znicholls

This pull request adds pandas support to pint (hence is related to #645, #401 and pandas-dev/pandas#10349).

An example can be seen in `example-notebooks/basic-example.ipynb`.

It's a little bit hacksih, feedback would be greatly appreciated by me and @andrewgsavage. One obvious example is that we have to run all the interface tests with `pytest` to fit with `pandas` test suite, which introduces a dependency for the CI and currently gives us this awkward testing setup (see the alterations we had to make to `testsuite`). This also means that our code coverage tests are fiddly too.

If you'd like us to squash the commits, that can be done.

If pint has a linter, it would be good to run that over this pull request too as we're a little bit all over the place re style.

Things to discuss:

- [x]  general feedback and changes
- [x] test setup, especially need for pytest for pandas tests and hackish way to get around automatic discovery
- [x] squashing/rebasing
- [x] linting/other code style (related to #664 and #628: we're happy with whatever, I've found using an automatic linter e.g. black and/or flake8 has made things much simpler in other projects)
- [x] including notebooks in the repo (if we want to, I'm happy to put them under CI so we can make sure they run)
- [x] setting up the docs correctly

Co-authored-by: Zebedee Nicholls <zebedee.nicholls@climate-energy-college.org>
Co-authored-by: andrewgsavage <andrewgsavage@gmail.com>

.gitignore

@@ -9,6 +9,7 @@ build/
 dist/
 MANIFEST
 .tox
+*pytest_cache*
 
 # WebDAV file system cache files
 .DAV/
@@ -18,3 +19,9 @@ tags
 
 test/
 .coverage*
+
+# notebook stuff
+*.ipynb_checkpoints*
+
+# test csv which should be user generated
+notebooks/pandas_test.csv

.travis.yml

@@ -7,19 +7,20 @@ branches:
   - trying.tmp
 
 env:
-  - UNCERTAINTIES="N" PYTHON="3.3" NUMPY_VERSION=1.9.2
-  - UNCERTAINTIES="N" PYTHON="3.4" NUMPY_VERSION=1.11.2
-  - UNCERTAINTIES="N" PYTHON="3.5" NUMPY_VERSION=1.11.2
-  - UNCERTAINTIES="Y" PYTHON="3.5" NUMPY_VERSION=1.11.2
-  - UNCERTAINTIES="N" PYTHON="3.6" NUMPY_VERSION=1.11.2
-  - UNCERTAINTIES="N" PYTHON="2.7" NUMPY_VERSION=0
-  - UNCERTAINTIES="N" PYTHON="3.5" NUMPY_VERSION=0
+  - UNCERTAINTIES="N" PYTHON="3.6" NUMPY_VERSION=1.14 PANDAS=1
+  - UNCERTAINTIES="N" PYTHON="3.3" NUMPY_VERSION=1.9.2 PANDAS=0
+  - UNCERTAINTIES="N" PYTHON="3.4" NUMPY_VERSION=1.11.2 PANDAS=0
+  - UNCERTAINTIES="N" PYTHON="3.5" NUMPY_VERSION=1.11.2 PANDAS=0
+  - UNCERTAINTIES="Y" PYTHON="3.5" NUMPY_VERSION=1.11.2 PANDAS=0
+  - UNCERTAINTIES="N" PYTHON="3.6" NUMPY_VERSION=1.11.2 PANDAS=0
+  - UNCERTAINTIES="N" PYTHON="2.7" NUMPY_VERSION=0 PANDAS=0
+  - UNCERTAINTIES="N" PYTHON="3.5" NUMPY_VERSION=0 PANDAS=0
   # Test with the latest numpy version
-  - UNCERTAINTIES="N" PYTHON="2.7" NUMPY_VERSION=1.14
-  - UNCERTAINTIES="N" PYTHON="3.4" NUMPY_VERSION=1.14
-  - UNCERTAINTIES="N" PYTHON="3.5" NUMPY_VERSION=1.14
-  - UNCERTAINTIES="Y" PYTHON="3.5" NUMPY_VERSION=1.14
-  - UNCERTAINTIES="N" PYTHON="3.6" NUMPY_VERSION=1.14
+  - UNCERTAINTIES="N" PYTHON="2.7" NUMPY_VERSION=1.14 PANDAS=0
+  - UNCERTAINTIES="N" PYTHON="3.4" NUMPY_VERSION=1.14 PANDAS=0
+  - UNCERTAINTIES="N" PYTHON="3.5" NUMPY_VERSION=1.14 PANDAS=0
+  - UNCERTAINTIES="Y" PYTHON="3.5" NUMPY_VERSION=1.14 PANDAS=0
+  - UNCERTAINTIES="N" PYTHON="3.6" NUMPY_VERSION=1.14 PANDAS=0
 
 before_install:
   - sudo apt-get update
@@ -48,10 +49,17 @@ install:
   - if [ $UNCERTAINTIES == 'Y' ]; then pip install 'uncertainties==2.4.7.1'; fi
   - if [ $NUMPY_VERSION != '0' ]; then conda install --yes numpy==$NUMPY_VERSION; fi
   - if [[ $TRAVIS_PYTHON_VERSION == '3.5' && $NUMPY_VERSION == 1.11.2 && $UNCERTAINTIES == "Y" ]]; then pip install babel serialize pyyaml; fi
+  # this is superslow but suck it up until updates to pandas are made
+  - if [[ $PANDAS == '1' ]]; then pip install numpy cython pytest pytest-cov nbval; pip install git+https://github.com/pandas-dev/pandas.git; fi
   - pip install coveralls
 
 script:
-  - python -bb -m coverage run -p --source=pint --omit="*test*","*compat*" setup.py test
+  # if we're doing the pandas tests and hence have pytest available, we can
+  # simply use it to run all the tests
+  - if [[ $PANDAS == '1' ]]; then python -bb -m coverage run -p --source=pint --omit="*test*","*compat*" -m py.test; fi
+  # test notebooks too if pandas available
+  - if [[ $PANDAS == '1' ]]; then pip install -e .; pytest --nbval notebooks/*; fi
+  - if [[ $PANDAS == '0' ]]; then python -bb -m coverage run -p --source=pint --omit="*test*","*compat*","*pandas*" setup.py test; fi
   - coverage combine
   - coverage report -m
 

docs/index.rst

@@ -102,6 +102,13 @@ points, like positions on a map or absolute temperature scales.
 **Python 2 and 3**: a single codebase that runs unchanged in Python 2.7+ and
 Python 3.3+.
 
+**Pandas integration**: Thanks to `Pandas Extension Types`_ it is now possible to use Pint with Pandas. Operations on DataFrames and between columns are units aware, providing even more convenience for users of Pandas DataFrames. For full details, see the `Pandas Support Documentation`_.
+
+
+When you choose to use a NumPy_ ndarray, its methods and
+ufuncs are supported including automatic conversion of units. For example
+`numpy.arccos(q)` will require a dimensionless `q` and the units of the output
+quantity will be radian.
 
 
 User Guide
@@ -152,3 +159,5 @@ One last thing
 .. _`NumPy`: http://www.numpy.org/
 .. _`PEP 3101`: https://www.python.org/dev/peps/pep-3101/
 .. _`Babel`: http://babel.pocoo.org/
+.. _`Pandas Extension Types`: https://pandas.pydata.org/pandas-docs/stable/extending.html#extension-types
+.. _`Pandas Support Documentation`: ./pandas.rst