Use the application registry as the default unit registry

CHANGELOG.md

@@ -5,6 +5,7 @@
 ## Pinttrs 24.1.0 (upcoming release)
 
 * Add Python 3.12 support ({ghpr}`7`).
+* The default registry is now the Pint application registry ({ghpr}`8`).
 
 ### Developer-side changes
 

docs/rst/usage.rst

@@ -9,8 +9,8 @@ Attaching units to attributes
 -----------------------------
 
 Pinttrs's main functionality is to provide support natural unit support to
-``attrs`` classes. Units must be specified explicitly, *i.e.* they cannot be
-specified using a string representation. Therefore, the first thing you need
+``attrs`` classes. Units must be specified explicitly, *i.e.* as :class:`~pint.Unit`
+instances created by a unit registry. Therefore, the first thing you need
 to do is to create a Pint unit registry:
 
 .. doctest::
@@ -26,6 +26,10 @@ to do is to create a Pint unit registry:
    the built-in unit registry is a potential source of trouble for users
    who would also manipulate units created with a different registry.
 
+   It should however be noted that with the application registry, Pint makes
+   using a shared registry much safer. We might support automatic string
+   interpretation using the default registry in a future release.
+
 Pinttrs defines a :func:`pinttrs.field` function similar to :func:`attrs.field`, which
 basically calls the latter after defining some metadata. The ``units`` argument
 is the main difference and allows for the attachment of units to a field:

docs/src/contributing.md

@@ -56,3 +56,10 @@ Incremental autobuild is also supported:
 ```bash
 make docs-serve
 ```
+
+## Roadmap
+
+**Not planned yet**
+
+* Allow automatic string interpretation using the built-in registry (this feature
+  should have a switch based on a user setting).

src/pinttr/_defaults.py

@@ -1,25 +1,37 @@
+from typing import Union
+
 import pint
 
-#: Default unit registry
-unit_registry = pint.UnitRegistry()
+#: Default unit registry (if not modified with :func:`.set_unit_registry`, it is the `application registry <https://pint.readthedocs.io/en/stable/getting/pint-in-your-projects.html#having-a-shared-registry>`_).
+unit_registry = pint.get_application_registry()
 
 
-def set_unit_registry(ureg: pint.UnitRegistry) -> None:
+def set_unit_registry(ureg: Union[pint.UnitRegistry, pint.ApplicationRegistry]) -> None:
     """
-    Set unit registry. By default, Pinttrs has its own registry.
+    Set unit registry. By default, Pinttrs uses the
+    `application registry <https://pint.readthedocs.io/en/stable/getting/pint-in-your-projects.html#having-a-shared-registry>`_).
 
     :param ureg: Unit registry.
     :raises: :class:`TypeError` if ``ureg`` is not a :class:`pint.UnitRegistry`.
+
+    .. versionchanged:: 24.1.0
+       The default registry is now the application registry.
     """
     global unit_registry
-    if not isinstance(ureg, pint.UnitRegistry):
-        raise TypeError("ureg must be a pint.UnitRegistry")
+    if not isinstance(ureg, (pint.UnitRegistry, pint.ApplicationRegistry)):
+        raise TypeError(
+            "ureg must be a pint.UnitRegistry or pint.ApplicationRegistry instance"
+        )
     unit_registry = ureg
 
 
-def get_unit_registry() -> pint.UnitRegistry:
+def get_unit_registry() -> Union[pint.UnitRegistry, pint.ApplicationRegistry]:
     """
-    Get default unit registry.
+    Get default unit registry. By default, Pinttrs uses the
+    `application registry <https://pint.readthedocs.io/en/stable/getting/pint-in-your-projects.html#having-a-shared-registry>`_).
+
+    .. versionchanged:: 24.1.0
+       The default registry is now the application registry.
     """
     global unit_registry
     return unit_registry

tests/test_defaults.py

@@ -7,8 +7,8 @@ def test_set_unit_registry():
     """
     Unit tests for :func:`pinttr._interpret.interpret_units`.
     """
-    # The default unit registry is a pint.UnitRegistry instance
-    assert isinstance(pinttr.get_unit_registry(), pint.UnitRegistry)
+    # The default unit registry is the application registry.
+    assert isinstance(pinttr.get_unit_registry(), pint.ApplicationRegistry)
     ureg = pint.UnitRegistry()
     assert ureg is not pinttr.get_unit_registry()