Merge pull request #1 from clarkgwillison/update-log-units

Add feature documentation, merge recent Pint changes

.gitignore

@@ -11,6 +11,7 @@ dist/
 MANIFEST
 *pytest_cache*
 .eggs
+.mypy_cache
 
 # WebDAV file system cache files
 .DAV/

.travis.yml

@@ -17,7 +17,7 @@ env:
 
   - PKGS="python=3.7 flake8 black isort"  # Have linters fail first and quickly
   # Pinned packages to match readthedocs CI https://readthedocs.org/projects/pint/
-  - PKGS="python=3.7 ipython matplotlib nbsphinx numpy sphinx Pygments==2.3.1 docutils==0.14 alabaster commonmark==0.8.1 recommonmark==0.5.0"
+  - PKGS="python=3.7 ipython matplotlib nbsphinx numpy pandas jupyter_client ipykernel python-graphviz graphviz xarray sparse dask[complete] sphinx Pygments==2.3.1 docutils==0.14 alabaster commonmark==0.8.1 recommonmark==0.5.0"
   - PKGS="python=3.6"
   - PKGS="python=3.7"
   - PKGS="python=3.8"
@@ -31,7 +31,7 @@ env:
   - PKGS="python=3.6 numpy uncertainties"
   - PKGS="python=3.7 numpy uncertainties"
   - PKGS="python=3.8 numpy uncertainties"
-  - PKGS="python xarray netCDF4"
+  - PKGS="python=3.8 numpy uncertainties sparse xarray netCDF4"
 
   # TODO: pandas tests
   # - PKGS="python=3.7 numpy pandas uncertainties pandas"
@@ -61,6 +61,7 @@ install:
   - if [[ $PKGS =~ flake8 ]]; then LINT=1; else LINT=0; fi
   - if [[ $PKGS =~ sphinx ]]; then DOCS=1; else DOCS=0; fi
   - if [[ $PKGS =~ matplotlib && $DOCS == 0 ]]; then pip install pytest-mpl; export TEST_OPTS="$TEST_OPTS --mpl"; fi
+  - if [[ $DOCS == 1 ]]; then pip install pint-pandas; 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@bdb7a1603f1e0948ca0cab011987f616e7296167; python -c 'import pandas; print(pandas.__version__)'; fi
   - conda list
@@ -74,6 +75,7 @@ script:
   - if [[ $PANDAS == 0 && $LINT == 0 && $DOCS == 0 ]]; then python -bb -m pytest $TEST_OPTS; fi
   - if [[ $LINT == 1 ]]; then black -t py36 --check . && isort -rc -c . && flake8; fi
   - if [[ $DOCS == 1 ]]; then PYTHONPATH=$PWD sphinx-build -n -j auto -b html -d build/doctrees docs build/html; fi
+  - if [[ $DOCS == 1 ]]; then PYTHONPATH=$PWD sphinx-build -a -j auto -b doctest -d build/doctrees docs build/doctest; fi
   - if [[ $LINT == 0 && $DOCS == 0 ]]; then coverage report -m; fi
 
 after_success:

AUTHORS

@@ -43,6 +43,7 @@ Other contributors, listed alphabetically, are:
 * Sundar Raman <cybertoast@gmail.com>
 * Tiago Coutinho <coutinho@esrf.fr>
 * Thomas Kluyver <takowl@gmail.com>
+* Tom Nicholas <tomnicholas1@gmail.com>
 * Tom Ritchford <tom@swirly.com>
 * Virgil Dupras <virgil.dupras@savoirfairelinux.com>
 * Zebedee Nicholls <zebedee.nicholls@climate-energy-college.org>

CHANGES

@@ -1,13 +1,87 @@
 Pint Changelog
 ==============
 
-0.11 (unreleased)
+0.15 (unreleased)
 -----------------
 
+- Implement Dask collection interface to support Pint Quantity wrapped Dask arrays.
+- Started automatically testing examples in the documentation
+- Implements Logarithmic Units like dBm, dB or decade
+  (Issue #71, Thanks Dima Pustakhod, Giorgio Signorello, Jonathan Wheeler)
+
+
+0.14 (2020-07-01)
+-----------------
+
+- Changes required to support Pint-Pandas 0.1.
+
+
+0.13 (2020-06-17)
+-----------------
+- Reinstated support for pickle protocol 0 and 1, which is required by pytables
+  (Issue #1036, Thanks Guido Imperiale)
+- Fixed bug with multiplication of Quantity by dict (Issue #1032)
+- Bare zeros and NaNs (not wrapped by Quantity) are now gracefully accepted by all numpy
+  operations; e.g. np.stack([Quantity([1, 2], "m"), [0, np.nan]) is now valid, whereas
+  np.stack([Quantity([1, 2], "m"), [3, 4]) will continue raising DimensionalityError.
+  (Issue #1050, Thanks Guido Imperiale)
+- NaN is now treated the same as zero in addition, subtraction, equality, and
+  disequality (Issue #1051, Thanks Guido Imperiale)
+- Fixed issue where quantities with a very large magnitude would throw an IndexError
+  when using to_compact()
+- Fixed crash when a Unit with prefix is declared for the first time while a Context
+  containing unit redefinitions is active
+  (Issues #1062 and #1097, Thanks Guido Imperiale)
+- New implementation of 'Lx' String Format Type Option
+  The old implementation treated 'Lx' as 'S' as produced by 'uncertainties'
+  package, but that is not fully compatible with SIunitx. The new code protects
+  SIunitx by fixing what unceratinties produces.
+  (Issue #814)
+- Added link to budding `pint-xarray` interface library to the docs, next to
+  the link to pint-pandas. (Thanks Tom Nicholas.)
+- Removed outdated `_dir` attribute of `UnitsRegistry`, and added `__iter__`
+  method so that now `list(ureg)` returns a list of all units in registry.
+  (Issue #1072, Thanks Tom Nicholas)
+- Replace pkg_resources.version to importlib.metadata.version. (Issue #1083)
+- Fix typo in docs for wraps example with optional arguments. (Issue #1088)
+- Add momentum as a dimension
+- Fixed a bug where unit exponents were only partially superscripted in HTML format
+- Multiple contexts containing the same redefinition can now be stacked
+  (Issue #1108, Thanks Guido Imperiale)
+- Fixed crash when some specific combinations of contexts were enabled
+  (Issue #1112, Thanks Guido Imperiale)
+- Added support for checking prefixed units using `in` keyword (Issue #1086)
+- Updated many examples in the documentation to reflect Pint's current behavior
+
+
+0.12 (2020-05-29)
+-----------------
+
+- Add full support for Decimal and Fraction at the registry level.
+  **BREAKING CHANGE**:
+  `use_decimal` is deprecated. Use `non_int_type=Decimal` when instantiating
+  the registry.
+- Fixed bug where numpy.pad didn't work without specifying constant_values or
+  end_values (Issue #1026)
+
+
+0.11 (2020-02-19)
+-----------------
+
+- Added pint-convert script.
+- Remove `default_en_0.6.txt`.
+- Make `__str__` and `__format__` locale configurable.
+  (Issue #984)
+- Quantities wrapping NumPy arrays will no longer warning for the changed
+  array function behavior introduced in 0.10.
+  (Issue #1029, Thanks Jon Thielen)
+- **BREAKING CHANGE**:
+  The array protocol fallback deprecated in version 0.10 has been removed.
+  (Issue #1029, Thanks Jon Thielen)
 - Now we use `pyproject.toml` for providing `setuptools_scm` settings
 - Remove `default_en_0.6.txt`
 - Reorganize long_description.
-- Moved Pi to defintions files.
+- Moved Pi to definitions files.
 - Use ints (not floats) a defaults at many points in the codebase as in Python 3
   the true division is the default one.
 - **BREAKING CHANGE**:
@@ -19,8 +93,7 @@ Pint Changelog
 - Allow constants in units by using a leading underscore (Issue #989, Thanks
   Juan Nunez-Iglesias)
 - Fixed bug where to_compact handled prefix units incorrectly (Issue #960)
-- Implements Logarithmic Units like dBm, dB or decade
-  (Issue #71, Thanks Dima Pustakhod, Giorgio Signorello, Jonathan Wheeler)
+
 
 0.10.1 (2020-01-07)
 -------------------
@@ -32,6 +105,7 @@ Pint Changelog
   (Issue #881, Thanks Guido Imperiale)
 - Fixed __array__ signature to match numpy docs (Issue #974, Thanks Ryan May)
 
+
 0.10 (2020-01-05)
 -----------------
 
@@ -237,7 +311,7 @@ Pint Changelog
 - Added several new units and Systems
   (Issues #749, #737, )
 - Started experimental pandas support
-  (Issue #746 and others. Thanks andrewgsavage, znicholls and others)  
+  (Issue #746 and others. Thanks andrewgsavage, znicholls and others)
 - wraps and checks now supports kwargs and defaults.
   (Issue #660, thanks jondoesntgit)
 
@@ -309,6 +383,7 @@ Pint Changelog
 - Allow changing shape for Quantities with numpy arrays.
   (Issue #344, thanks tecki)
 
+
 0.7.2 (2016-03-02)
 ------------------
 - Fixed backward incompatibility problem when parsing dimensionless units.

MANIFEST.in

@@ -1,4 +1,4 @@
-include AUTHORS CHANGES LICENSE README.rst BADGES.rst version.txt readthedocs.yml
+include AUTHORS CHANGES LICENSE README.rst BADGES.rst version.txt readthedocs.yml .coveragerc
 recursive-include pint *
 recursive-include docs *
 recursive-include bench *

README.rst

@@ -87,12 +87,20 @@ Documentation
 
 Full documentation is available at http://pint.readthedocs.org/
 
+
 GUI Website 
 -----------
 
 This Website_ wraps Pint's "dimensional analysis" methods to provide a GUI.
 
 
+Command-line converter
+----------------------
+
+A command-line script `pint-convert` provides a quick way to convert between
+units or get conversion factors.
+
+
 Design principles
 -----------------
 
@@ -158,4 +166,4 @@ see CHANGES_
 .. _`Pandas Extension Types`: https://pandas.pydata.org/pandas-docs/stable/extending.html#extension-types
 .. _`pint-pandas Jupyter notebook`: https://github.com/hgrecco/pint-pandas/blob/master/notebooks/pandas_support.ipynb
 .. _`AUTHORS`: https://github.com/hgrecco/pint/blob/master/AUTHORS
-.. _`CHANGES`: https://github.com/hgrecco/pint/blob/master/CHANGES
+.. _`CHANGES`: https://github.com/hgrecco/pint/blob/master/CHANGES

docs/conf.py

@@ -13,7 +13,11 @@
 
 import datetime
 
-import pkg_resources
+try:
+    from importlib.metadata import version
+except ImportError:
+    # Backport for Python < 3.8
+    from importlib_metadata import version
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -29,6 +33,7 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosectionlabel",
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx.ext.coverage",
@@ -60,7 +65,7 @@
 # built documents.
 
 try:  # pragma: no cover
-    version = pkg_resources.get_distribution(project).version
+    version = version(project)
 except Exception:  # pragma: no cover
     # we seem to have a local copy not installed without setuptools
     # so the reported version will be unknown
@@ -317,3 +322,20 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {"http://docs.python.org/": None}
+
+# -- Doctest configuration -----------------------------------------------------
+
+# fill a dictionary with package names that may be missing
+# this is checked by :skipif: clauses in certain doctests that rely
+# on optional dependencies
+doctest_global_setup = """
+from importlib.util import find_spec
+
+not_installed = {
+    pkg_name: find_spec(pkg_name) is None
+    for pkg_name in [
+        'uncertainties',
+        'serialize',
+    ]
+}
+"""

docs/contexts.rst

@@ -1,4 +1,3 @@
-.. _contexts:
 
 Contexts
 ========
@@ -55,11 +54,15 @@ Contexts can be also enabled for blocks of code using the `with` statement:
     <Quantity(5.99584916e+14, 'hertz')>
 
 If you need a particular context in all your code, you can enable it for all
-operations with the registry::
+operations with the registry
+
+.. doctest::
 
     >>> ureg.enable_contexts('sp')
 
-To disable the context, just call::
+To disable the context, just call
+
+.. doctest::
 
     >>> ureg.disable_contexts()
 
@@ -69,17 +72,23 @@ Enabling multiple contexts
 
 You can enable multiple contexts:
 
+.. doctest::
+
     >>> q.to('Hz', 'sp', 'boltzmann')
     <Quantity(5.99584916e+14, 'hertz')>
 
 This works also using the `with` statement:
 
+.. doctest::
+
     >>> with ureg.context('sp', 'boltzmann'):
     ...     q.to('Hz')
     <Quantity(5.99584916e+14, 'hertz')>
 
 or in the registry:
 
+.. doctest::
+
     >>> ureg.enable_contexts('sp', 'boltzmann')
     >>> q.to('Hz')
     <Quantity(5.99584916e+14, 'hertz')>
@@ -88,6 +97,8 @@ If a conversion rule between two dimensions appears in more than one context,
 the one in the last context has precedence. This is easy to remember if you
 think that the previous syntax is equivalent to nest contexts:
 
+.. doctest::
+
     >>> with ureg.context('sp'):
     ...     with ureg.context('boltzmann') :
     ...         q.to('Hz')
@@ -106,7 +117,7 @@ calculate, for example, the wavelength in water of a laser which on air is 530 n
     >>> wl = 530. * ureg.nm
     >>> f = wl.to('Hz', 'sp')
     >>> f.to('nm', 'sp', n=1.33)
-    <Quantity(398.496240602, 'nanometer')>
+    <Quantity(398.4962..., 'nanometer')>
 
 Contexts can also accept Pint Quantity objects as parameters. For example, the
 'chemistry' context accepts the molecular weight of a substance (as a Quantity
@@ -135,7 +146,7 @@ context and the parameters that you wish to set.
     ... def f(wl):
     ...     return wl.to('Hz').magnitude
     >>> f(wl)
-    398.496240602
+    425297855014895.6
 
 
 This decorator can be combined with **wraps** or **check** decorators described in
@@ -194,14 +205,16 @@ functions. For example:
     ...                      lambda ureg, x: x * ureg.speed_of_light)
     >>> ureg.add_context(c)
     >>> ureg("1 s").to("km", "ab")
-    299792.458 kilometer
+    <Quantity(299792.458, 'kilometer')>
 
 It is also possible to create anonymous contexts without invoking add_context:
 
+.. doctest::
+
    >>> c = pint.Context()
-   ...
+   >>> c.add_transformation('[time]', '[length]', lambda ureg, x: x * ureg.speed_of_light)
    >>> ureg("1 s").to("km", c)
-   299792.458 kilometer
+   <Quantity(299792.458, 'kilometer')>
 
 Using contexts for unit redefinition
 ------------------------------------

docs/contributing.rst

@@ -32,6 +32,38 @@ Pint uses `bors-ng` as a merge bot and therefore every PR is tested before mergi
 In any case, feel free to use the `issue tracker`_ to discuss ideas for new features or improvements.
 
 
+Setting up your environment
+---------------------------
+
+If you're contributing to this project for the fist time, you can set up your
+environment on Linux or OSX with the following commands::
+
+    $ git clone git@github.com:hgrecco/pint.git
+    $ cd pint
+    $ python -m virtualenv venv
+    $ source venv/bin/activate
+    $ pip install -e .
+    $ pip install -r requirements_docs.txt
+
+Running tests and building documentation
+----------------------------------------
+
+To run the test suite, invoke pytest from the ``pint`` directory::
+
+    $ cd pint
+    $ pytest
+
+To run the doctests, invoke Sphinx's doctest module from the ``docs`` directory::
+
+    $ cd docs
+    $ make doctest
+
+To build the documentation, invoke Sphinx from the ``docs`` directory::
+
+    $ cd docs
+    $ make html
+
+
 .. _github: http://github.com/hgrecco/pint
 .. _`issue tracker`: https://github.com/hgrecco/pint/issues
 .. _`bors-ng`: https://github.com/bors-ng/bors-ng