TypedUnit 0.2.17__tar.gz → 0.3.0__tar.gz

{typedunit-0.2.17 → typedunit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TypedUnit
-Version: 0.2.17
+Version: 0.3.0
 Summary: A package wrapping pint for handling typed units in Python.
 Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
 License: MIT License
@@ -47,15 +47,17 @@ Requires-Dist: numpy
 Requires-Dist: matplotlib
 Requires-Dist: pint_pandas
 Provides-Extra: release
-Requires-Dist: martinpdes-maintenance==0.2.2; extra == "release"
+Requires-Dist: martinpdes-maintenance==0.2.3; extra == "release"
 Provides-Extra: testing
-Requires-Dist: pytest<10.0,>=7.4; extra == "testing"
-Requires-Dist: pytest-cov<7,>=2; extra == "testing"
+Requires-Dist: martinpdes-maintenance[testing]==0.2.3; extra == "testing"
 Requires-Dist: pytest-json-report~=1.5; extra == "testing"
-Requires-Dist: flake8==7.3.0; extra == "testing"
+Requires-Dist: pytest-cov<7; extra == "testing"
 Requires-Dist: coverage~=7.6; extra == "testing"
 Provides-Extra: documentation
 Requires-Dist: MartinPdeS-docs<0.5,>=0.4.0; extra == "documentation"
+Provides-Extra: dev
+Requires-Dist: martinpdes-maintenance[quality]==0.2.3; extra == "dev"
+Requires-Dist: flake8==7.3.0; extra == "dev"
 Dynamic: license-file
 
 TypedUnit

{typedunit-0.2.17 → typedunit-0.3.0}/TypedUnit/__init__.py

@@ -8,3 +8,4 @@ from TypedUnit.helper import validate_units as validate_units
 from TypedUnit.units import *  # noqa: F403 -- Re-export the unit module's public types.
 from TypedUnit.units import Quantity as Quantity
 from TypedUnit.units import ureg as ureg
+from TypedUnit.validation import validate_quantity  # noqa: F401 -- public API

{typedunit-0.2.17 → typedunit-0.3.0}/TypedUnit/_version.py

@@ -1,5 +1,5 @@
 """Release version maintained by martinpdes-maintenance."""
 
-__version__ = version = "0.2.17"
+__version__ = version = "0.3.0"
 __version_tuple__ = version_tuple = tuple(int(part) for part in version.split("."))
 __commit_id__ = commit_id = None

typedunit-0.3.0/TypedUnit/validation.py

@@ -0,0 +1,73 @@
+"""Direct validation of Pint quantities without modifying their values."""
+
+# ruff: noqa: I001
+from __future__ import annotations
+import numpy as np
+from pint import Quantity, UnitRegistry
+
+
+def validate_quantity(
+    *,
+    value: Quantity,
+    unit: str,
+    name: str,
+    registry: UnitRegistry | None = None,
+    shape: tuple[int, ...] | None = None,
+    positive: bool = False,
+    nonnegative: bool = False,
+) -> None:
+    """Validate a quantity's registry, dimensions, shape, and magnitudes.
+
+    Parameters
+    ----------
+    value : pint.Quantity
+        Quantity to validate; it is not changed or replaced.
+    unit : str
+        Unit compatible with the required dimensionality. Magnitudes are
+        checked after conversion to this unit.
+    name : str
+        Parameter name included in error messages.
+    registry : pint.UnitRegistry or None, optional
+        If supplied, require a quantity created by this exact registry. None
+        accepts quantities from any Pint registry. Default is None.
+    shape : tuple of int or None, optional
+        Required magnitude shape. An empty tuple requires a scalar; None leaves
+        the shape unrestricted. Default is None.
+    positive : bool, optional
+        Require every magnitude to be strictly positive. Default is False.
+    nonnegative : bool, optional
+        Require every magnitude to be nonnegative. Default is False.
+
+    Returns
+    -------
+    None
+        The supplied quantity is preserved and no converted value is returned.
+
+    Raises
+    ------
+    TypeError
+        If value is not a Pint quantity or belongs to a different registry.
+    pint.DimensionalityError
+        If the supplied units are incompatible with unit.
+    ValueError
+        If magnitudes are nonfinite or violate shape or sign requirements.
+    """
+    if not isinstance(value, Quantity):
+        raise TypeError(f"{name} must be a Pint quantity.")
+
+    if registry is not None and not isinstance(value, registry.Quantity):
+        raise TypeError(f"{name} must belong to the specified unit registry.")
+
+    magnitude = np.asarray(value.to(unit).magnitude, dtype=float)
+
+    if shape is not None and magnitude.shape != shape:
+        raise ValueError(f"{name} must have shape {shape}.")
+
+    if not np.all(np.isfinite(magnitude)):
+        raise ValueError(f"{name} must be finite.")
+
+    if positive and np.any(magnitude <= 0):
+        raise ValueError(f"{name} must be positive.")
+
+    if nonnegative and np.any(magnitude < 0):
+        raise ValueError(f"{name} must be nonnegative.")

{typedunit-0.2.17 → typedunit-0.3.0}/TypedUnit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TypedUnit
-Version: 0.2.17
+Version: 0.3.0
 Summary: A package wrapping pint for handling typed units in Python.
 Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
 License: MIT License
@@ -47,15 +47,17 @@ Requires-Dist: numpy
 Requires-Dist: matplotlib
 Requires-Dist: pint_pandas
 Provides-Extra: release
-Requires-Dist: martinpdes-maintenance==0.2.2; extra == "release"
+Requires-Dist: martinpdes-maintenance==0.2.3; extra == "release"
 Provides-Extra: testing
-Requires-Dist: pytest<10.0,>=7.4; extra == "testing"
-Requires-Dist: pytest-cov<7,>=2; extra == "testing"
+Requires-Dist: martinpdes-maintenance[testing]==0.2.3; extra == "testing"
 Requires-Dist: pytest-json-report~=1.5; extra == "testing"
-Requires-Dist: flake8==7.3.0; extra == "testing"
+Requires-Dist: pytest-cov<7; extra == "testing"
 Requires-Dist: coverage~=7.6; extra == "testing"
 Provides-Extra: documentation
 Requires-Dist: MartinPdeS-docs<0.5,>=0.4.0; extra == "documentation"
+Provides-Extra: dev
+Requires-Dist: martinpdes-maintenance[quality]==0.2.3; extra == "dev"
+Requires-Dist: flake8==7.3.0; extra == "dev"
 Dynamic: license-file
 
 TypedUnit

{typedunit-0.2.17 → typedunit-0.3.0}/TypedUnit.egg-info/SOURCES.txt

@@ -7,9 +7,11 @@ TypedUnit/directories.py
 TypedUnit/helper.py
 TypedUnit/units.py
 TypedUnit/utils.py
+TypedUnit/validation.py
 TypedUnit.egg-info/PKG-INFO
 TypedUnit.egg-info/SOURCES.txt
 TypedUnit.egg-info/dependency_links.txt
 TypedUnit.egg-info/requires.txt
 TypedUnit.egg-info/top_level.txt
-tests/test_0.py
+tests/test_0.py
+tests/test_validate_quantity.py

{typedunit-0.2.17 → typedunit-0.3.0}/TypedUnit.egg-info/requires.txt

@@ -3,15 +3,18 @@ numpy
 matplotlib
 pint_pandas
 
+[dev]
+martinpdes-maintenance[quality]==0.2.3
+flake8==7.3.0
+
 [documentation]
 MartinPdeS-docs<0.5,>=0.4.0
 
 [release]
-martinpdes-maintenance==0.2.2
+martinpdes-maintenance==0.2.3
 
 [testing]
-pytest<10.0,>=7.4
-pytest-cov<7,>=2
+martinpdes-maintenance[testing]==0.2.3
 pytest-json-report~=1.5
-flake8==7.3.0
+pytest-cov<7
 coverage~=7.6

{typedunit-0.2.17 → typedunit-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "TypedUnit"
-version = "0.2.17"
+version = "0.3.0"
 description = "A package wrapping pint for handling typed units in Python."
 license = {file = "LICENSE"}
 readme = "README.rst"
@@ -42,18 +42,13 @@ Documentation = "https://martinpdes.github.io/TypedUnit/"
 Repository = "https://github.com/MartinPdeS/TypedUnit.git"
 
 [project.optional-dependencies]
-release = ["martinpdes-maintenance==0.2.2"]
-testing = [
-    "pytest >=7.4,<10.0",
-    "pytest-cov >=2,<7",
-    "pytest-json-report ~=1.5",
-    "flake8 ==7.3.0",
-    "coverage ~=7.6"
-]
+release = ["martinpdes-maintenance==0.2.3"]
+testing = ["martinpdes-maintenance[testing]==0.2.3", "pytest-json-report ~=1.5", "pytest-cov<7", "coverage ~=7.6"]
 
 documentation = [
     "MartinPdeS-docs>=0.4.0,<0.5",
 ]
+dev = ["martinpdes-maintenance[quality]==0.2.3", "flake8 ==7.3.0"]
 
 [tool.ruff]
 target-version = "py310"

typedunit-0.3.0/tests/test_validate_quantity.py

@@ -0,0 +1,94 @@
+"""Direct quantity validation across registries and array shapes."""
+
+# ruff: noqa: I001
+import numpy as np
+import pint
+import pytest
+from TypedUnit import Length, validate_quantity, validate_units
+
+
+def test_valid_values_are_not_replaced_or_mutated() -> None:
+    """Compatible alternate units and array shapes preserve the input."""
+    registry = pint.UnitRegistry()
+    value = np.array([1.0, 2.0]) * registry.mm
+    assert (
+        validate_quantity(
+            value=value,
+            unit="m",
+            name="lengths",
+            registry=registry,
+            shape=(2,),
+            positive=True,
+        )
+        is None
+    )
+    np.testing.assert_array_equal(value.magnitude, [1.0, 2.0])
+    assert value.units == registry.mm
+    validate_quantity(value=2 * registry.cm, unit="m", name="length", shape=())
+
+
+def test_registry_is_optional_but_explicit_registry_is_enforced() -> None:
+    """Foreign registries are accepted by default and rejected when specified."""
+    first = pint.UnitRegistry()
+    second = pint.UnitRegistry()
+    validate_quantity(value=1 * first.mm, unit="m", name="length")
+    with pytest.raises(TypeError, match="specified unit registry"):
+        validate_quantity(
+            value=1 * first.mm,
+            unit="m",
+            name="length",
+            registry=second,
+        )
+    with pytest.raises(TypeError, match="length"):
+        validate_quantity(value=1, unit="m", name="length")
+
+
+def test_units_and_shape_are_checked() -> None:
+    """Wrong dimensions propagate Pint errors and scalar shape is explicit."""
+    registry = pint.UnitRegistry()
+    with pytest.raises(pint.DimensionalityError):
+        validate_quantity(value=1 * registry.second, unit="m", name="length")
+    with pytest.raises(ValueError, match="shape"):
+        validate_quantity(
+            value=np.array([1]) * registry.mm,
+            unit="m",
+            name="length",
+            shape=(),
+        )
+
+
+@pytest.mark.parametrize("value", [np.nan, np.inf, -np.inf])
+def test_nonfinite_values_rejected(value: float) -> None:
+    """Nonfinite values are rejected independently of sign requirements."""
+    registry = pint.UnitRegistry()
+    with pytest.raises(ValueError, match="finite"):
+        validate_quantity(value=value * registry.mm, unit="m", name="length")
+
+
+def test_sign_requirements_apply_to_every_element() -> None:
+    """Strict positivity rejects zero while nonnegativity permits it."""
+    registry = pint.UnitRegistry()
+    zero = np.array([0, 1]) * registry.mm
+    validate_quantity(value=zero, unit="m", name="length", nonnegative=True)
+    with pytest.raises(ValueError, match="positive"):
+        validate_quantity(value=zero, unit="m", name="length", positive=True)
+    with pytest.raises(ValueError, match="nonnegative"):
+        validate_quantity(
+            value=np.array([1, -1]) * registry.mm,
+            unit="m",
+            name="length",
+            nonnegative=True,
+        )
+
+
+def test_existing_validate_units_decorator_remains_available() -> None:
+    """The separate direct validator does not replace the decorator API."""
+    registry = pint.UnitRegistry()
+
+    @validate_units
+    def identity(length: Length) -> Length:
+        return length
+
+    assert identity(2 * registry.mm) == 2 * registry.mm
+    with pytest.raises(ValueError):
+        identity(2 * registry.second)