Merge remote-tracking branch 'upstream/master' into bugfix/fix-386

.coveragerc

@@ -1,3 +1,19 @@
 [run]
 omit = pint/testsuite/*
 
+[report]
+# Regexes for lines to exclude from consideration
+exclude_lines =
+    # Have to re-enable the standard pragma
+    pragma: no cover
+
+    # Don't complain about missing debug-only code:
+    def __repr__
+
+    # Don't complain if tests don't hit defensive assertion code:
+    raise AssertionError
+    raise NotImplementedError
+    AbstractMethodError
+
+    # Don't complain if non-runnable code isn't run:
+    if TYPE_CHECKING:

.github/workflows/ci.yml

@@ -5,10 +5,11 @@ on: [push, pull_request]
 jobs:
   test-linux:
     strategy:
+      fail-fast: false
       matrix:
         python-version: [3.7, 3.8, 3.9]
         numpy: [null, "numpy>=1.17,<2.0.0"]
-        uncertainties: [null, "uncertainties==3.0.1", "uncertainties>=3.0.1,<4.0.0"]
+        uncertainties: [null, "uncertainties==3.1.4", "uncertainties>=3.1.4,<4.0.0"]
         extras: [null]
         include:
           - python-version: 3.7 # Minimal versions
@@ -17,7 +18,10 @@ jobs:
           - python-version: 3.8
             numpy: "numpy"
             uncertainties: "uncertainties"
-            extras: "sparse xarray pooch netCDF4 dask[complete] graphviz babel==2.8"
+            extras: "sparse xarray netCDF4 dask[complete] graphviz babel==2.8"
+          - python-version: "3.10"
+            numpy: null
+            extras: null
     runs-on: ubuntu-latest
 
     env:
@@ -95,9 +99,20 @@ jobs:
       with:
         python-version: 3.x
     - name: Coveralls Finished
+      continue-on-error: true
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         COVERALLS_SERVICE_NAME: github
       run: |
         pip install coveralls
         coveralls --finish
+
+  # Dummy task to summarize all. See https://github.com/bors-ng/bors-ng/issues/1300
+  ci-success:
+    name: ci
+    if: ${{ success() }}
+    needs: test-linux
+    runs-on: ubuntu-latest
+    steps:
+      - name: CI succeeded
+        run: exit 0

.pre-commit-config.yaml

@@ -1,10 +1,10 @@
 repos:
 -   repo: https://github.com/psf/black
-    rev: 21.5b1
+    rev: 21.9b0
     hooks:
     - id: black
 -   repo: https://github.com/pycqa/isort
-    rev: 5.8.0
+    rev: 5.9.3
     hooks:
     - id: isort
 -   repo: https://gitlab.com/pycqa/flake8

.readthedocs.yaml

@@ -5,8 +5,9 @@ sphinx:
   configuration: docs/conf.py
   fail_on_warning: false
 python:
-   version: 3.7
+   version: 3.8
    install:
      - requirements: requirements_docs.txt
      - method: pip
        path: .
+   system_packages: false

CHANGES

@@ -1,9 +1,19 @@
 Pint Changelog
 ==============
 
-0.18 (unreleased)
+0.19 (unreleased)
 -----------------
 
+- Upgrade min version of uncertainties to 3.1.4
+- Fix setting options of the application registry (Issue #1403).
+- Allow string parsing of offset units
+  (Issue #386)
+
+0.18 (2021-10-26)
+-----------------
+
+### Release Manager: jules-cheron
+
 - Implement use of Quantity in the Quantity constructor (convert to specified units).
   (Issue #1231)
 - Rename .readthedocs.yml to .readthedocs.yaml, update MANIFEST.in (Issue #1311)
@@ -14,13 +24,25 @@ Pint Changelog
 - Fix handling of positional max/min arguments in clip function.
   (Issue #1244)
 - Fix string formatting of numpy array scalars
-- Allow string parsing of offset units
-  (Issue #386)
+- Fix string formatting of numpy array scalars.
+- Fix default format for Measurement class (Issue #1300)
+- Fix parsing of pretty units with same exponents but different sign. (Issue #1360)
+- Convert the application registry to a wrapper object (Issue #1365)
+- Add documentation for the string format options.
+   (Issue #1357, #1375, thanks keewis)
+- Support custom units formats.
+  (Issue #1371, thanks keewis)
+- Autoupdate pre-commit hooks.
+- Improved the application registry.
+  (Issue #1366, thanks keewis)
+- Improved testing isolation using pytest fixtures.
 
 ### Breaking Changes
 
 - pint no longer supports Python 3.6
 - Minimum Numpy version supported is 1.17+
+- Add supports for type hints for Quantity class. Quantity is now a Generic (PEP560).
+- Add support for [PEP561](https://www.python.org/dev/peps/pep-0561/) (Package Type information)
 
 
 0.17 (2021-03-22)

README.rst

@@ -126,7 +126,7 @@ ufuncs are supported including automatic conversion of units. For example
 quantity will be radian.
 
 **Uncertainties integration**:  transparently handles calculations with
-quantities with uncertainties (like 3.14±0.01) meter via the `uncertainties
+quantities with uncertainties (like 3.14±0.01 meter) via the `uncertainties
 package`_.
 
 **Handle temperature**: conversion between units with different reference
@@ -138,12 +138,6 @@ like numpy and uncertainties if they are installed
 **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 `pint-pandas Jupyter notebook`_.
 
 
-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.
-
-
 Pint is maintained by a community of scientists, programmers and enthusiasts around the world.
 See AUTHORS_ for a complete list.
 

bors.toml

@@ -1,5 +1,5 @@
 status = [
-  "test-linux",
+  "ci",
   "docbuild",
   "lint"
 ]

docs/conf.py

@@ -42,6 +42,8 @@
     "sphinx.ext.mathjax",
     "matplotlib.sphinxext.plot_directive",
     "nbsphinx",
+    "IPython.sphinxext.ipython_directive",
+    "IPython.sphinxext.ipython_console_highlighting",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -109,6 +111,10 @@
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
 
+# -- Options for extensions ----------------------------------------------------
+# napoleon
+napoleon_preprocess_types = True
+
 
 # -- Options for HTML output ---------------------------------------------------
 
@@ -321,7 +327,13 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"http://docs.python.org/": None}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
+    "dask": ("https://docs.dask.org/en/latest", None),
+    "sparse": ("https://sparse.pydata.org/en/latest/", None),
+}
 
 # -- Doctest configuration -----------------------------------------------------
 

docs/faq.rst

@@ -13,23 +13,23 @@ Pint is a unit and sounds like Python in the first syllable. Most important, it
 You mention other similar Python libraries. Can you point me to those?
 ----------------------------------------------------------------------
 
-`natu <http://kdavies4.github.io/natu/>`_
+`natu <https://kdavies4.github.io/natu/>`_
 
-`Buckingham <https://code.google.com/p/buckingham/>`_
+`Buckingham <https://github.com/mdipierro/buckingham>`_
 
-`Magnitude <http://github.com/juanre/magnitude.git>`_
+`Magnitude <https://github.com/juanre/magnitude>`_
 
-`SciMath <https://github.com/enthought/scimath.git>`_
+`SciMath <https://github.com/enthought/scimath>`_
 
-`Python-quantities <https://github.com/python-quantities/python-quantities.git>`_
+`Python-quantities <https://github.com/python-quantities/python-quantities>`_
 
 `Unum <https://bitbucket.org/kiv/unum>`_
 
 `Units <https://bitbucket.org/adonohue/units/>`_
 
 `udunitspy <https://github.com/blazetopher/udunitspy>`_
 
-`SymPy <http://docs.sympy.org/dev/modules/physics/units.html>`_
+`SymPy <https://docs.sympy.org/latest/modules/physics/units/index.html>`_
 
 `cf units <https://github.com/SciTools/cf_units>`_
 

docs/formatting.rst

@@ -0,0 +1,111 @@
+.. _formatting:
+.. currentmodule:: pint
+
+
+.. ipython:: python
+   :suppress:
+
+   import pint
+
+
+String formatting
+=================
+The conversion of :py:class:`Unit` and :py:class:`Quantity` objects to strings (e.g.
+through the :py:class:`str` builtin or f-strings) can be customized using :ref:`format
+specifications <formatspec>`. The basic format is:
+
+.. code-block:: none
+
+   [magnitude format][modifier][unit format]
+
+where each part is optional and the order of these is arbitrary.
+
+In case any part (except the modifier) is omitted, the corresponding value in
+:py:attr:`Quantity.default_format` or :py:attr:`Unit.default_format` is filled in. If
+that is not set (it evaluates to ``False``), :py:attr:`UnitRegistry.default_format` is
+used.  If both are not set, the global default of ``"D"`` and the magnitude's default
+format are used instead.
+
+.. note::
+
+   Modifiers may be used without specifying any format: ``"~"`` is a valid format
+   specification.
+
+
+Unit Format Specifications
+--------------------------
+The :py:class:`Unit` class ignores the magnitude format part, and the unit format
+consists of just the format type.
+
+Let's look at some examples:
+
+.. ipython:: python
+
+   ureg = pint.UnitRegistry()
+   u = ureg.kg * ureg.m / ureg.s ** 2
+
+   f"{u:P}"  # using the pretty format
+   f"{u:~P}"  # short pretty
+   f"{u:P~}"  # also short pretty
+
+   # default format
+   u.default_format
+   ureg.default_format
+   str(u)  # default: default
+   f"{u:~}"  # default: short default
+   ureg.default_format = "C"  # registry default to compact
+   str(u)  # default: compact
+   f"{u}"  # default: compact
+   u.default_format = "P"
+   f"{u}"  # default: pretty
+   u.default_format = ""  # TODO: switch to None
+   ureg.default_format = ""  # TODO: switch to None
+   f"{u}"  # default: default
+
+Unit Format Types
+-----------------
+``pint`` comes with a variety of unit formats:
+
+======= =============== ======================================================================
+Spec    Name            Example
+======= =============== ======================================================================
+``D``   default         ``kilogram * meter / second ** 2``
+``P``   pretty          ``kilogram·meter/second²``
+``H``   HTML            ``kilogram meter/second<sup>2</sup>``
+``L``   latex           ``\frac{\mathrm{kilogram} \cdot \mathrm{meter}}{\mathrm{second}^{2}}``
+``Lx``  latex siunitx   ``\si[]{\kilo\gram\meter\per\second\squared}``
+``C``   compact         ``kilogram*meter/second**2``
+======= =============== ======================================================================
+
+Quantity Format Specifications
+------------------------------
+The magnitude format is forwarded to the magnitude (for a unit-spec of ``H`` the
+magnitude's ``_repr_html_`` is called).
+
+Let's look at some more examples:
+
+.. ipython:: python
+
+    q = 1e-6 * u
+
+    # modifiers
+    f"{q:~P}"  # short pretty
+    f"{q:~#P}"  # compact short pretty
+    f"{q:P#~}"  # also compact short pretty
+
+    # additional magnitude format
+    f"{q:.2f~#P}"  # short compact pretty with 2 float digits
+    f"{q:#~}"  # short compact default
+
+Quantity Format Types
+---------------------
+There are no special quantity formats yet.
+
+Modifiers
+---------
+======== =================================================== ================================
+Modifier Meaning                                             Example
+======== =================================================== ================================
+``~``    Use the unit's symbol instead of its canonical name ``kg·m/s²`` (``f"{u:~P}"``)
+``#``    Call :py:meth:`Quantity.to_compact` first           ``1.0 m·mg/s²`` (``f"{q:#~P}"``)
+======== =================================================== ================================

docs/index.rst

@@ -120,6 +120,7 @@ User Guide
     getting
     tutorial
     defining-quantities
+    formatting
     numpy
     nonmult
     log_units