diff --git a/CHANGELOG.md b/CHANGELOG.md index a021e1d..5642594 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/docs/rst/usage.rst b/docs/rst/usage.rst index cc4ade9..030e683 100644 --- a/docs/rst/usage.rst +++ b/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: diff --git a/docs/src/contributing.md b/docs/src/contributing.md index a37776b..319b38c 100644 --- a/docs/src/contributing.md +++ b/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). diff --git a/src/pinttr/_defaults.py b/src/pinttr/_defaults.py index 31c5f9d..ff229d3 100644 --- a/src/pinttr/_defaults.py +++ b/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 `_). +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 `_). :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 `_). + + .. versionchanged:: 24.1.0 + The default registry is now the application registry. """ global unit_registry return unit_registry diff --git a/tests/test_defaults.py b/tests/test_defaults.py index 42434e9..3064b8a 100644 --- a/tests/test_defaults.py +++ b/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()