xpint 0.1.0b1__py3-none-any.whl

xpint/__init__.py

@@ -0,0 +1,32 @@
+"""xpint — extended semantic quantities for Pint."""
+
+from importlib.metadata import version
+
+from .registry import (
+    AffineRole,
+    DesignationSignature,
+    DesignationTerm,
+    KindDefinition,
+    SemanticQuantity,
+    SemanticRegistry,
+    SemanticUnit,
+    get_application_registry,
+    get_default_registry,
+    set_application_registry,
+)
+
+__version__ = version("xpint")
+
+__all__ = [
+    "AffineRole",
+    "DesignationSignature",
+    "DesignationTerm",
+    "KindDefinition",
+    "SemanticQuantity",
+    "SemanticRegistry",
+    "SemanticUnit",
+    "__version__",
+    "get_application_registry",
+    "get_default_registry",
+    "set_application_registry",
+]

xpint/_adapters.py

@@ -0,0 +1,155 @@
+"""Guard Pint's numerical adapters before they strip semantic objects."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import wraps
+from inspect import Parameter, signature
+from typing import Any
+
+from pint import registry_helpers
+from pint.compat import np  # type: ignore[attr-defined]
+from pint.util import UnitsContainer, pi_theorem
+
+
+def _require_plain(registry: Any, value: Any, operation: str) -> None:
+    registry._require_owned(value, name=f"{operation} input")
+    if isinstance(value, (registry.Quantity, registry.Unit)):
+        if registry.Quantity._operands_have_semantics(value):
+            raise TypeError(
+                f"{operation} cannot represent classified quantity metadata; "
+                "explicitly remove it or operate on magnitude first"
+            )
+    elif isinstance(value, dict):
+        for item in value.values():
+            _require_plain(registry, item, operation)
+    elif isinstance(value, (tuple, list)):
+        for item in value:
+            _require_plain(registry, item, operation)
+    elif np is not None and isinstance(value, np.ndarray) and value.dtype == np.dtype(object):
+        for item in value.flat:
+            _require_plain(registry, item, operation)
+
+
+def _require_plain_unit_spec(registry: Any, value: Any, operation: str) -> None:
+    if value is None:
+        return
+    if isinstance(value, str) and "=" not in value and "[" not in value:
+        value = registry.Unit(value)
+    _require_plain(registry, value, operation)
+
+
+def _require_plain_wraps_input(registry: Any, value: Any, strict: bool) -> None:
+    if strict and isinstance(value, str):
+        value = registry.parse_expression(value)
+    registry._require_owned(value, name="wraps input")
+    if isinstance(value, (registry.Quantity, registry.Unit)):
+        _require_plain(registry, value, "wraps")
+
+
+def _wraps_preserves_variadic_passthrough(registry: Any) -> bool:
+    """Check Pint's binding behavior without calling the user's function."""
+    probe = registry.Quantity(1, "")
+
+    def preserves_probe(*values: Any, scale: Any) -> bool:
+        return values[1] is probe
+
+    wrapped = registry_helpers.wraps(registry, None, (None, ""))(preserves_probe)
+    return bool(wrapped(None, probe, scale=probe))
+
+
+def _wraps(
+    registry: Any, ret: Any, args: Any, strict: bool
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    argument_specs = args if isinstance(args, (list, tuple)) else (args,)
+    return_specs = ret if isinstance(ret, (list, tuple)) else (ret,)
+    for spec in argument_specs:
+        _require_plain_unit_spec(registry, spec, "wraps")
+    for spec in return_specs:
+        registry._require_owned(spec, name="wraps return unit")
+        if isinstance(spec, registry.Unit) and spec.has_designation:
+            _require_plain(registry, spec, "wraps")
+    pint_decorator = registry_helpers.wraps(registry, ret, args, strict)
+
+    def decorate(function: Callable[..., Any]) -> Callable[..., Any]:
+        wrapped = pint_decorator(function)
+        sig = signature(function)
+        # Pint validates declaration counts; an omitted **kwargs specification
+        # means pass-through in converters that support omitting it.
+        declarations = tuple(zip(sig.parameters.values(), argument_specs, strict=False))
+        # Every value bound to a declared unit is a conversion candidate: a converter
+        # that binds by parameter name strips each *args element and each **kwargs
+        # value under that parameter's declaration, not just the first one.
+        declared = tuple(
+            (parameter.name, parameter.kind) for parameter, spec in declarations if spec is not None
+        )
+        # Pint 0.25.3 addresses declarations by positional slot instead, so a declared
+        # parameter after *args strips the variadic element occupying its index. Guard
+        # those slots unless the declaration covers them or Pint binds them correctly.
+        misbound_kinds = (Parameter.KEYWORD_ONLY, Parameter.VAR_KEYWORD)
+        misbound_slots = tuple(
+            index
+            for index, (parameter, spec) in enumerate(declarations)
+            if spec is not None and parameter.kind in misbound_kinds
+        )
+        if any(kind is Parameter.VAR_POSITIONAL for _name, kind in declared) or (
+            misbound_slots
+            and any(
+                parameter.kind is Parameter.VAR_POSITIONAL for parameter in sig.parameters.values()
+            )
+            and _wraps_preserves_variadic_passthrough(registry)
+        ):
+            misbound_slots = ()
+
+        @wraps(function)
+        def guarded(*values: Any, **kwargs: Any) -> Any:
+            bound = sig.bind(*values, **kwargs)
+            bound.apply_defaults()
+            for name, kind in declared:
+                value = bound.arguments[name]
+                if kind is Parameter.VAR_POSITIONAL:
+                    for item in value:
+                        _require_plain_wraps_input(registry, item, strict)
+                elif kind is Parameter.VAR_KEYWORD:
+                    for item in value.values():
+                        _require_plain_wraps_input(registry, item, strict)
+                else:
+                    _require_plain_wraps_input(registry, value, strict)
+            for index in misbound_slots:
+                if index < len(values):
+                    _require_plain_wraps_input(registry, values[index], strict)
+            return wrapped(*values, **kwargs)
+
+        return guarded
+
+    return decorate
+
+
+def _check(
+    registry: Any, dimensions: tuple[Any, ...]
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    for dimension in dimensions:
+        registry._require_owned(dimension, name="check dimension")
+    return registry_helpers.check(registry, *dimensions)
+
+
+def _pi_theorem(registry: Any, quantities: dict[str, Any]) -> Any:
+    for value in quantities.values():
+        if isinstance(value, (dict, UnitsContainer)):
+            value = registry.Unit(registry.UnitsContainer(value))
+        _require_plain_unit_spec(registry, value, "pi_theorem")
+    return pi_theorem(quantities, registry)
+
+
+def _setup_matplotlib(registry: Any, enable: bool) -> None:
+    try:
+        import matplotlib.units
+        from pint.matplotlib import setup_matplotlib_handlers
+
+        from ._matplotlib import _SemanticConverter
+    except ImportError as exc:
+        raise ImportError("setup_matplotlib requires matplotlib; install matplotlib first") from exc
+    setup_matplotlib_handlers(registry, enable)  # type: ignore[no-untyped-call]
+    if enable:
+        converters = matplotlib.units.registry
+        converters[registry.Quantity] = _SemanticConverter(registry)  # type: ignore[no-untyped-call]

xpint/_formatter.py

@@ -0,0 +1,38 @@
+"""Guard registry formatter delegates that cannot represent designations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, override
+
+from pint.delegates import Formatter
+
+
+def _require_undesignated(value: Any) -> None:
+    if getattr(value, "has_designation", False):
+        raise TypeError(
+            "Pint formatter APIs cannot represent designated objects; "
+            "use str() or format() on the xpint quantity or unit instead"
+        )
+
+
+@dataclass
+class _GuardedFormatter:
+    delegate: Any
+
+    def format_quantity(self, quantity: Any, *args: Any, **kwargs: Any) -> Any:
+        _require_undesignated(quantity)
+        return self.delegate.format_quantity(quantity, *args, **kwargs)
+
+    def format_unit(self, unit: Any, *args: Any, **kwargs: Any) -> Any:
+        _require_undesignated(unit)
+        return self.delegate.format_unit(unit, *args, **kwargs)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.delegate, name)
+
+
+class _SemanticFormatter(Formatter):
+    @override
+    def get_formatter(self, spec: str) -> Any:
+        return _GuardedFormatter(super().get_formatter(spec))

xpint/_matplotlib.py

@@ -0,0 +1,27 @@
+"""Optional Pint plotting adapter that rejects semantic metadata loss."""
+
+from __future__ import annotations
+
+from typing import Any, override
+
+from pint.matplotlib import PintConverter
+
+from ._adapters import _require_plain, _require_plain_unit_spec
+
+
+class _SemanticConverter(PintConverter):
+    @override
+    def convert(self, value: Any, unit: Any, axis: Any) -> Any:  # type: ignore[override]
+        _require_plain(self._reg, value, "matplotlib")
+        _require_plain_unit_spec(self._reg, unit, "matplotlib")
+        return super().convert(value, unit, axis)  # type: ignore[no-untyped-call]
+
+    @override
+    def _convert_value(self, value: Any, unit: Any, axis: Any) -> Any:
+        _require_plain(self._reg, value, "matplotlib")
+        return super()._convert_value(value, unit, axis)  # type: ignore[no-untyped-call]
+
+    @override
+    def axisinfo(self, unit: Any, axis: Any) -> Any:  # type: ignore[override]
+        _require_plain_unit_spec(self._reg, unit, "matplotlib")
+        return super().axisinfo(unit, axis)  # type: ignore[no-untyped-call]

xpint/_measurement.py

@@ -0,0 +1,73 @@
+"""Keep Pint measurements within the unclassified quantity surface."""
+
+from __future__ import annotations
+
+from typing import Any, Self, override
+
+from pint.facets.measurement import Measurement
+from pint.facets.measurement.objects import MISSING
+from pint.util import UnitsContainer
+
+from ._adapters import _require_plain
+
+
+def _require_measurement_units(registry: Any, units: Any) -> None:
+    if isinstance(units, (str, UnitsContainer)):
+        units = registry.Unit(units)
+    _require_plain(registry, units, "Measurement")
+
+
+class _SemanticMeasurement(Measurement):
+    """Reject semantic inputs before Pint extracts magnitudes and physical units."""
+
+    __hash__ = Measurement.__hash__
+
+    def __new__(cls, value: Any, error: Any = MISSING, units: Any = MISSING) -> Self:
+        registry = cls._REGISTRY
+        _require_plain(registry, value, "Measurement")
+        _require_plain(registry, error, "Measurement")
+        # Pint accepts Measurement(ufloat, units) as well as (value, error, units).
+        if units is MISSING and hasattr(value, "nominal_value"):
+            _require_measurement_units(registry, error)
+        else:
+            _require_measurement_units(registry, units)
+        return super().__new__(cls, value, error, units)  # type: ignore[no-untyped-call,no-any-return]
+
+    @override
+    def _check(self, other: Any) -> bool:
+        _require_plain(self._REGISTRY, other, "Measurement arithmetic")
+        return super()._check(other)
+
+    @override
+    def __pow__(self, other: Any) -> Any:
+        _require_plain(self._REGISTRY, other, "Measurement exponent")
+        return super().__pow__(other)
+
+    @override
+    def __ipow__(self, other: Any) -> Any:
+        _require_plain(self._REGISTRY, other, "Measurement exponent")
+        return super().__ipow__(other)
+
+    @override
+    def to(self, other: Any = None, *contexts: Any, **ctx_kwargs: Any) -> Any:
+        _require_measurement_units(self._REGISTRY, other)
+        return super().to(other, *contexts, **ctx_kwargs)
+
+    @override
+    def ito(self, other: Any = None, *contexts: Any, **ctx_kwargs: Any) -> None:
+        _require_measurement_units(self._REGISTRY, other)
+        super().ito(other, *contexts, **ctx_kwargs)
+
+    @override
+    def compare(self, other: Any, op: Any) -> Any:
+        _require_plain(self._REGISTRY, other, "Measurement comparison")
+        return super().compare(other, op)
+
+    @override
+    def __eq__(self, other: Any) -> Any:
+        registry: Any = self._REGISTRY
+        if getattr(other, "_REGISTRY", registry) is not registry:
+            return False
+        if registry.Quantity._operands_have_semantics(other):
+            return False
+        return super().__eq__(other)

xpint/_policies.py

@@ -0,0 +1,160 @@
+"""Immutable semantic dispatch tables and built-in registry catalogs."""
+
+from types import MappingProxyType
+
+_NUMPY_METHOD_PRESERVING = frozenset(
+    {
+        "astype",
+        "compress",
+        "conj",
+        "conjugate",
+        "copy",
+        "diagonal",
+        "flatten",
+        "item",
+        "max",
+        "mean",
+        "min",
+        "ravel",
+        "repeat",
+        "reshape",
+        "round",
+        "squeeze",
+        "swapaxes",
+        "take",
+        "transpose",
+    }
+)
+_NUMPY_METHOD_ADDITIVE = frozenset({"sum", "cumsum"})
+# These methods share argument names with the corresponding NumPy functions.
+_NUMPY_METHOD_REDUCTIONS = frozenset({"sum", "max", "min", "mean", "std", "var", "cumsum"})
+_NUMPY_METHOD_SUPPORTED = (
+    _NUMPY_METHOD_PRESERVING | _NUMPY_METHOD_ADDITIVE | frozenset({"std", "var"})
+)
+
+_NUMPY_UFUNC_BINARY_METHODS = MappingProxyType(
+    {
+        "add": ("__add__", "__radd__"),
+        "subtract": ("__sub__", "__rsub__"),
+        "multiply": ("__mul__", "__rmul__"),
+        "divide": ("__truediv__", "__rtruediv__"),
+        "true_divide": ("__truediv__", "__rtruediv__"),
+        "power": ("__pow__", "__rpow__"),
+        "equal": ("__eq__", "__eq__"),
+        "not_equal": ("__ne__", "__ne__"),
+        "less": ("__lt__", "__gt__"),
+        "less_equal": ("__le__", "__ge__"),
+        "greater": ("__gt__", "__lt__"),
+        "greater_equal": ("__ge__", "__le__"),
+    }
+)
+_NUMPY_UFUNC_MAGNITUDE_PREDICATES = frozenset({"isfinite", "isinf", "isnan", "signbit"})
+
+# Trigonometry consumes or produces an angle, so an input kind never describes the
+# output. Pint converts the argument to radian and rejects a non-angle; xpint only has
+# to prevent its own metadata from crossing the boundary silently.
+_ANGLE_UFUNCS = frozenset(
+    {
+        "sin",
+        "cos",
+        "tan",
+        "arcsin",
+        "arccos",
+        "arctan",
+        "arctan2",
+        "degrees",
+        "radians",
+        "deg2rad",
+        "rad2deg",
+    }
+)
+
+_NUMPY_FUNCTION_PRESERVING = frozenset({"mean", "nanmean", "max", "min", "amax", "amin"})
+_NUMPY_FUNCTION_ADDITIVE = frozenset({"sum", "nansum", "cumsum", "nancumsum"})
+_NUMPY_STATISTICS = frozenset({"std", "nanstd", "var", "nanvar"})
+_NUMPY_VARIANCES = frozenset({"var", "nanvar"})
+_NUMPY_MAGNITUDE_INDICES = frozenset({"argmax", "argmin", "argsort", "nonzero"})
+_NUMPY_UFUNC_POWERS = MappingProxyType({"sqrt": 0.5, "square": 2, "cbrt": 1 / 3, "reciprocal": -1})
+_NUMPY_FUNCTION_REDUCTIONS = (
+    _NUMPY_FUNCTION_PRESERVING | _NUMPY_FUNCTION_ADDITIVE | _NUMPY_STATISTICS
+)
+_NUMPY_FUNCTION_LIKE_CONSTRUCTORS = frozenset({"zeros_like"})
+_NUMPY_FUNCTION_COMPOSITION = frozenset({"concatenate", "stack", "where"})
+
+# Canonical unit per angular dimension, used to tell a caller what a rejected value
+# actually carries and which factor clears it.
+_ANGULAR_UNITS = MappingProxyType({"[angle]": "radian"})
+
+# Pint declares [luminous_flux] and [illuminance] independently of the units carrying
+# them, so redefining steradian alone leaves those named dimensions inconsistent.
+_ANGLE_DEFINITIONS = (
+    "radian = [angle] = rad",
+    # A small patch on a sphere is a rectangle whose sides are arcs, so its solid angle
+    # is a product of two plane angles with the radius and every constant cancelling.
+    # Leonard (Metrologia 58 052001, 2021) and Kalinin (Metrologia 56 065009, 2019) both
+    # reach the same place: the steradian is a coherent derived unit, sr = rad**2.
+    "steradian = radian ** 2 = sr",
+    "[luminous_flux] = [luminosity] * [angle] ** 2",
+    "[illuminance] = [luminous_flux] / [length] ** 2",
+)
+
+# Conjugate forms. Generalized force is energy per coordinate and conjugate momentum is
+# action per coordinate, so once angle is a coordinate the dimension appears on its own;
+# newton * meter carries no angle and would leave torque indistinguishable from energy.
+_ANGLE_KIND_OVERRIDES = MappingProxyType(
+    {
+        "Dimensionless": "dimensionless",
+        "Torque": "joule / radian",
+        "AngularMomentum": "joule * second / radian",
+        "MomentOfInertia": "kilogram * meter ** 2 / radian ** 2",
+    }
+)
+
+_DEFAULT_KINDS = MappingProxyType(
+    {
+        "Dimensionless": "radian",
+        "Energy": "joule",
+        "Torque": "newton * meter",
+        "PlaneAngle": "radian",
+        "SolidAngle": "steradian",
+        "Frequency": "hertz",
+        "AngularVelocity": "radian / second",
+        "Action": "joule * second",
+        "AngularMomentum": "kilogram * meter ** 2 / second",
+        "Temperature": "kelvin",
+        "TemperatureDifference": "kelvin",
+        "Length": "meter",
+        "Time": "second",
+        "Mass": "kilogram",
+        "ElectricCurrent": "ampere",
+        "AmountOfSubstance": "mole",
+        "LuminousIntensity": "candela",
+        "Force": "newton",
+        "Pressure": "pascal",
+        "EnergyDensity": "joule / meter ** 3",
+        "Power": "watt",
+        "ElectricCharge": "coulomb",
+        "ElectricPotential": "volt",
+        "Capacitance": "farad",
+        "Resistance": "ohm",
+        "Conductance": "siemens",
+        "MagneticFlux": "weber",
+        "MagneticFluxDensity": "tesla",
+        "Inductance": "henry",
+        "LuminousFlux": "lumen",
+        "Illuminance": "lux",
+        "Radioactivity": "becquerel",
+        "AbsorbedDose": "gray",
+        "EquivalentDose": "sievert",
+        "CatalyticActivity": "katal",
+        "Velocity": "meter / second",
+        "Acceleration": "meter / second ** 2",
+        "Area": "meter ** 2",
+        "Volume": "meter ** 3",
+        "Density": "kilogram / meter ** 3",
+        "Entropy": "joule / kelvin",
+        "HeatCapacity": "joule / kelvin",
+        "KinematicViscosity": "meter ** 2 / second",
+        "Diffusivity": "meter ** 2 / second",
+    }
+)