Converters

CHANGELOG.md

@@ -4,6 +4,15 @@
 
 ## Pinttrs 25.2.0 (*upcoming release*)
 
+* Move again {func}`ensure_units <.converters.ensure_units>` to the
+  {mod}`.converters` module.
+* Add a deferred version of {func}`.converters.ensure_units`.
+* Deprecate {func}`.to_units`.
+* Deprecate {func}`.util.ensure_units`
+* Add {func}`.to_quantity` converter.
+* Extend {func}`.to_quantity` to support xarray DataArray objects with
+  `units` attributes.
+
 ## Pinttrs 25.1.0 (2025-06-25)
 
 * Pinttrs is now available on

conftest.py

@@ -0,0 +1,33 @@
+"""Test configuration for pytest."""
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def add_doctest_imports(doctest_namespace):
+    """Add common imports to doctest namespace.
+
+    This allows doctests in docstrings to use these imports without
+    explicitly importing them, keeping examples clean and readable.
+    """
+    import attrs
+    import numpy
+    import pint
+    import xarray
+
+    import pinttrs
+    from pinttrs import field
+    from pinttrs.converters import ensure_units, to_quantity
+    from pinttrs.validators import has_compatible_units
+
+    # Add to namespace
+    doctest_namespace["attrs"] = attrs
+    doctest_namespace["pint"] = pint
+    doctest_namespace["ureg"] = pinttrs.get_unit_registry()
+    doctest_namespace["pinttrs"] = pinttrs
+    doctest_namespace["field"] = field
+    doctest_namespace["ensure_units"] = ensure_units
+    doctest_namespace["to_quantity"] = to_quantity
+    doctest_namespace["has_compatible_units"] = has_compatible_units
+    doctest_namespace["np"] = numpy
+    doctest_namespace["xr"] = xarray

docs/api.rst

@@ -45,6 +45,8 @@ Dictionary interpretation
 Converters [``pinttrs.converters``]
 -----------------------------------
 
+.. autofunction:: pinttrs.converters.ensure_units
+.. autofunction:: pinttrs.converters.to_quantity
 .. autofunction:: pinttrs.converters.to_units
 
 .. _api-validators:
@@ -60,7 +62,7 @@ Utilities [``pinttrs.util``]
 ----------------------------
 
 .. autofunction:: pinttrs.util.always_iterable
-.. autofunction:: pinttrs.converters.ensure_units
+.. autofunction:: pinttrs.util.ensure_units
 .. autofunction:: pinttrs.util.units_compatible
 
 .. _api-exceptions:

docs/api_classic.rst

@@ -51,6 +51,12 @@ Dictionary interpretation
 Converters [``pinttr.converters``]
 ----------------------------------
 
+.. autofunction:: pinttr.converters.ensure_units
+   :noindex:
+
+.. autofunction:: pinttr.converters.to_quantity
+   :noindex:
+
 .. autofunction:: pinttr.converters.to_units
    :noindex:
 
@@ -70,7 +76,7 @@ Utilities [``pinttr.util``]
 .. autofunction:: pinttr.util.always_iterable
    :noindex:
 
-.. autofunction:: pinttr.converters.ensure_units
+.. autofunction:: pinttr.util.ensure_units
    :noindex:
 
 .. autofunction:: pinttr.util.units_compatible

docs/usage.rst

@@ -135,7 +135,7 @@ Validators and converters
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Under the hood, Pinttrs's attribute conversion system leverages simple validators
-and converters which can be used manually to further customise the behaviour of
+and converters which can be used manually to further customize the behaviour of
 attributes. See relevant API sections for further information:
 :ref:`api-converters`, :ref:`api-validators`.
 
@@ -304,7 +304,7 @@ The returned unit generator can be used to attach units to an attribute:
    >>> MyClass(1.0)
    MyClass(field=1.0 m)
 
-When initialising a context or registering additional units to it, units can be
+When initializing a context or registering additional units to it, units can be
 directly passed and will be turned into generators automatically:
 
 .. doctest::
@@ -434,7 +434,7 @@ used to interpret units in a dictionary with string-valued keys:
    >>> pinttrs.interpret_units({"field": 1.0, "field_units": "m"}, ureg)
    {'field': <Quantity(1.0, 'meter')>}
 
-This is useful to *e.g.* initialise objects using simple JSON fragments.
+This is useful to *e.g.* initialize objects using simple JSON fragments.
 Example:
 
 .. doctest::

pyproject.toml

@@ -58,10 +58,10 @@ packages = ["src/pinttrs", "src/pinttr"]
 allow-direct-references = true
 
 [tool.pytest.ini_options]
-addopts = "--doctest-glob='*.rst'"
+addopts = "--doctest-glob='*.rst' --doctest-modules"
 norecursedirs = [".git", ".env", "dist", "build", "__pypackages__"]
 python_files = ["test_*.py", "*_test.py", "tests.py"]
-testpaths = ["tests", "docs"]
+testpaths = ["tests", "docs", "src"]
 
 [tool.ruff.lint]
 select = ["I", "E", "F"]
@@ -82,6 +82,8 @@ dev = [
   "xdoctest>=0.15.0",
   "setuptools>=69.1.1",
   "taskipy>=1.10",
+  "xarray>=2023.1.0",
+  "numpy>=1.24.4",
 ]
 
 [tool.taskipy.tasks]

src/pinttr/_make.py

@@ -6,7 +6,7 @@
 
 from ._generator import UnitGenerator
 from ._metadata import MetadataKey
-from .converters import to_units
+from .converters import ensure_units
 from .validators import has_compatible_units
 
 
@@ -44,7 +44,7 @@ def attrib(
 
     :param converter:
         If set to :class:`~attr.NOTHING` and ``units`` is not ``None``, defaults
-        to :func:`to_units(units) <pinttr.converters.to_units>`
+        to :func:`ensure_units(default_units=units) <pinttr.converters.ensure_units>`
         (possibly wrapped in :func:`attr.converters.optional` if ``default`` is
         ``None``). Otherwise retains original behaviour.
 
@@ -82,9 +82,11 @@ def attrib(
         # Set field converter
         if converter is NOTHING:
             if default is None:
-                converter = attr.converters.optional(to_units(unit_generator))
+                converter = attr.converters.optional(
+                    ensure_units(default_units=unit_generator)
+                )
             else:
-                converter = to_units(unit_generator)
+                converter = ensure_units(default_units=unit_generator)
 
         # Set field validator
         if validator is NOTHING: