python-units 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

api/public.py

@@ -53,6 +53,7 @@ from core.quantity import (
 from core.unit_definitions import BaseUnit, CustomUnitBase, DerivedUnit, SIUnit
 from models.dimension import Dimension, DimensionSystem
 
+
 Unit = Quantity
 
 __all__ = [

core/deprecations.py

@@ -0,0 +1,62 @@
+# -*- coding: utf-8 -*-
+"""Deprecation helpers for compatibility APIs."""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Callable
+from typing import TypeVar
+
+
+_T = TypeVar("_T")
+
+
+def warn_legacy_api(name: str, replacement: str, removal_version: str) -> None:
+    """
+    Emit a deprecation warning for a legacy public API.
+
+    Args:
+        name: Deprecated API name.
+        replacement: Preferred API name or usage pattern.
+        removal_version: Planned removal release.
+
+    Returns:
+        None.
+
+    Raises:
+        None.
+    """
+    warnings.warn(
+        "{} is deprecated; use {} instead. It is scheduled for removal in {}.".format(
+            name,
+            replacement,
+            removal_version,
+        ),
+        DeprecationWarning,
+        stacklevel=4,
+    )
+
+
+def deprecated_call(
+    name: str,
+    replacement: str,
+    removal_version: str,
+    callback: Callable[[], _T],
+) -> _T:
+    """
+    Warn for a deprecated API call and return the callback result.
+
+    Args:
+        name: Deprecated API name.
+        replacement: Preferred API name or usage pattern.
+        removal_version: Planned removal release.
+        callback: Zero-argument callable that performs the actual work.
+
+    Returns:
+        The callback result.
+
+    Raises:
+        Any exception raised by ``callback``.
+    """
+    warn_legacy_api(name, replacement, removal_version)
+    return callback()

core/quantity.py

@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+from core.deprecations import deprecated_call
 from core.errors import InvalidValueError, UnitCompatibilityError, UnitOperandError
 from core.unit_definitions import BaseUnit, SIUnit, clone_unit
 from models.dimension import SI_DIMENSION_SYSTEM
@@ -200,8 +201,12 @@ def float_quantity(quantity: Quantity) -> Quantity:
 
 def long_quantity(quantity: Quantity) -> Quantity:
     """Legacy compatibility helper equivalent to ``int_quantity``."""
-    require_quantity_operand(quantity, "long conversion")
-    return Quantity(int(quantity.value), quantity.unit)
+    return deprecated_call(
+        "long_quantity",
+        "int_quantity",
+        "1.0.0",
+        lambda: int_quantity(quantity),
+    )
 
 
 def complex_quantity(quantity: Quantity) -> Quantity:
@@ -210,7 +215,41 @@ def complex_quantity(quantity: Quantity) -> Quantity:
     return Quantity(complex(quantity.value), quantity.unit)
 
 
-int_unit = int_quantity
-float_unit = float_quantity
-long_unit = long_quantity
-complex_unit = complex_quantity
+def int_unit(quantity: Quantity) -> Quantity:
+    """Legacy compatibility helper equivalent to ``int_quantity``."""
+    return deprecated_call(
+        "int_unit",
+        "int_quantity",
+        "1.0.0",
+        lambda: int_quantity(quantity),
+    )
+
+
+def float_unit(quantity: Quantity) -> Quantity:
+    """Legacy compatibility helper equivalent to ``float_quantity``."""
+    return deprecated_call(
+        "float_unit",
+        "float_quantity",
+        "1.0.0",
+        lambda: float_quantity(quantity),
+    )
+
+
+def long_unit(quantity: Quantity) -> Quantity:
+    """Legacy compatibility helper equivalent to ``int_quantity``."""
+    return deprecated_call(
+        "long_unit",
+        "int_quantity",
+        "1.0.0",
+        lambda: int_quantity(quantity),
+    )
+
+
+def complex_unit(quantity: Quantity) -> Quantity:
+    """Legacy compatibility helper equivalent to ``complex_quantity``."""
+    return deprecated_call(
+        "complex_unit",
+        "complex_quantity",
+        "1.0.0",
+        lambda: complex_quantity(quantity),
+    )

core/unit_definitions.py

@@ -4,7 +4,8 @@
 from __future__ import annotations
 
 from numbers import Number
-from typing import Dict
+from types import MappingProxyType
+from typing import Dict, Mapping
 
 from core.errors import (
     InvalidUnitError,
@@ -14,12 +15,17 @@ from core.errors import (
 )
 from models.dimension import Dimension, DimensionSystem, SI_DIMENSION_SYSTEM
 
-_CANONICAL_UNITS: dict[Dimension, "BaseUnit"] = {}
+_CANONICAL_UNITS: Mapping[Dimension, "BaseUnit"] = MappingProxyType({})
+_REGISTERED_CANONICAL_UNITS: tuple["BaseUnit", ...] = ()
 
 
 def register_canonical_unit(unit: "BaseUnit") -> None:
-    """Register a preferred unit for a canonical dimension."""
-    _CANONICAL_UNITS[unit.dimension] = unit
+    """Validate a preferred unit against the static canonical SI registry."""
+    require_unit_instance(unit)
+    if not any(registered_unit == unit for registered_unit in _REGISTERED_CANONICAL_UNITS):
+        raise InvalidUnitError(
+            "canonical units are statically defined and cannot be registered"
+        )
 
 
 def require_unit_instance(unit: object) -> None:
@@ -80,7 +86,17 @@ class BaseUnit:
         self._dimension = dimension
 
     def __eq__(self, unit2: object) -> bool:
-        return isinstance(unit2, BaseUnit) and self.dimension == unit2.dimension
+        if not isinstance(unit2, BaseUnit):
+            return False
+        if self.dimension != unit2.dimension:
+            return False
+        if isinstance(self, DerivedUnit) or isinstance(unit2, DerivedUnit):
+            return (
+                isinstance(self, DerivedUnit)
+                and isinstance(unit2, DerivedUnit)
+                and self.name == unit2.name
+            )
+        return True
 
     def _combine(self, unit2: "BaseUnit", operator_name: str) -> "BaseUnit":
         require_unit_instance(unit2)
@@ -213,3 +229,79 @@ class DerivedUnit(BaseUnit):
         if self.name:
             return self.name
         return self.full_units
+
+
+def _build_canonical_units() -> tuple[Mapping[Dimension, BaseUnit], tuple[BaseUnit, ...]]:
+    ampere = SIUnit.define("A")
+    candela = SIUnit.define("cd")
+    kelvin = SIUnit.define("K")
+    kilogram = SIUnit.define("kg")
+    metre = SIUnit.define("m")
+    mole = SIUnit.define("mol")
+    second = SIUnit.define("s")
+
+    newton = DerivedUnit.define("N", kilogram * metre / second / second)
+    pascal = DerivedUnit.define("Pa", newton / metre / metre)
+    joule = DerivedUnit.define("J", newton * metre)
+    watt = DerivedUnit.define("W", joule / second)
+    coulomb = DerivedUnit.define("C", second * ampere)
+    volt = DerivedUnit.define("V", watt / ampere)
+    farad = DerivedUnit.define("F", coulomb / volt)
+    ohm = DerivedUnit.define("Ω", volt / ampere)
+    siemens = DerivedUnit.define("S", ampere / volt)
+    weber = DerivedUnit.define("Wb", volt * second)
+    tesla = DerivedUnit.define("T", weber / metre / metre)
+    henry = DerivedUnit.define("H", weber / ampere)
+    steradian = DerivedUnit.define("sr", metre * metre / metre / metre)
+    lumen = DerivedUnit.define("lm", candela * steradian)
+    lux = DerivedUnit.define("lx", lumen / metre / metre)
+
+    registered_units = (
+        ampere,
+        candela,
+        kelvin,
+        kilogram,
+        metre,
+        mole,
+        second,
+        newton,
+        pascal,
+        joule,
+        watt,
+        coulomb,
+        volt,
+        farad,
+        ohm,
+        siemens,
+        weber,
+        tesla,
+        henry,
+        lumen,
+        lux,
+    )
+    preferred_units = (
+        ampere,
+        kelvin,
+        kilogram,
+        metre,
+        mole,
+        second,
+        newton,
+        pascal,
+        joule,
+        watt,
+        coulomb,
+        volt,
+        farad,
+        ohm,
+        siemens,
+        weber,
+        tesla,
+        henry,
+        lumen,
+        lux,
+    )
+    return MappingProxyType({unit.dimension: unit for unit in preferred_units}), registered_units
+
+
+_CANONICAL_UNITS, _REGISTERED_CANONICAL_UNITS = _build_canonical_units()

models/dimension.py

@@ -31,6 +31,13 @@ class Dimension:
             raise ValueError(
                 "dimension must define {} exponents".format(len(self.system.symbols))
             )
+        for exponent in self.exponents:
+            if not isinstance(exponent, int) or isinstance(exponent, bool):
+                raise ValueError(
+                    "dimension exponents must be integers, got {}".format(
+                        type(exponent).__name__
+                    )
+                )
 
     @classmethod
     def from_mapping(
@@ -40,11 +47,30 @@ class Dimension:
     ) -> "Dimension":
         """Construct a dimension from a base-symbol mapping."""
         dimension_system = system or cls.default_system
+        unknown_symbols = set(mapping) - set(dimension_system.symbols)
+        if unknown_symbols:
+            raise ValueError(
+                "unknown dimension symbols: {}".format(", ".join(sorted(unknown_symbols)))
+            )
         return cls(
             system=dimension_system,
-            exponents=tuple(int(mapping.get(symbol, 0)) for symbol in dimension_system.symbols),
+            exponents=tuple(
+                cls._validate_exponent(mapping.get(symbol, 0))
+                for symbol in dimension_system.symbols
+            ),
         )
 
+    @staticmethod
+    def _validate_exponent(exponent: object) -> int:
+        """Return a valid exponent or raise for invalid exponent input."""
+        if not isinstance(exponent, int) or isinstance(exponent, bool):
+            raise ValueError(
+                "dimension exponents must be integers, got {}".format(
+                    type(exponent).__name__
+                )
+            )
+        return exponent
+
     def to_mapping(self) -> dict[str, int]:
         """Return a base-symbol mapping for compatibility with public APIs."""
         return dict(zip(self.system.symbols, self.exponents))

{python_units-0.2.0.dist-info → python_units-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-units
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python library to represent numbers with units
 Author-email: "Paul K. Korir, PhD" <paul.korir@gmail.com>
 License-Expression: GPL-3.0-or-later
@@ -92,8 +92,10 @@ print(u.Unit(1, u.metre))
 ```
 
 The legacy `Unit` constructor remains available as a compatibility alias for
-`Quantity` during the migration period, but new code should prefer
-`from units import Quantity` and `from units.si import ...`.
+`Quantity` during the migration period. It is deprecated and scheduled for
+removal in `1.0.0`, but it remains a true alias until then so existing type
+checks keep working. New code should prefer `from units import Quantity` and
+`from units.si import ...`.
 
 The package is Python 3-only. Python 2 compatibility behavior is not part of the
 supported interface.
@@ -146,11 +148,19 @@ Canonical unit imports:
 
 Legacy compatibility helpers:
 
+* `Unit`
 * `long_quantity`
+* `int_unit`
+* `float_unit`
 * `long_unit`
-
-These names remain available as compatibility aliases for integer conversion in
-Python 3, but new code should prefer `int_quantity`.
+* `complex_unit`
+
+These names remain available during the migration period and emit
+`DeprecationWarning` when called. `Unit` remains a true alias for `Quantity` and
+does not emit a call-time warning, because preserving `Unit is Quantity` is part
+of the pre-`1.0.0` compatibility contract. New code should prefer `Quantity`,
+scalar-by-unit construction, and the `*_quantity` conversion helpers. The
+deprecated compatibility paths are scheduled for removal in `1.0.0`.
 
 # Notes on semantics
 

{python_units-0.2.0.dist-info → python_units-0.3.0.dist-info}/RECORD

@@ -1,14 +1,15 @@
 adapters/__init__.py,sha256=CSemt7d9mX9of0YQijrkQJ9FXwzXqN0TcnCeWGhXXC4,64
 api/__init__.py,sha256=EVoYM25GfHSWZnMigUDRsAnnyMnMUoeVZnlxlgQRfUI,72
-api/public.py,sha256=fFQgVFfBlrvavn2XXdh4z1Co1lGgj46JiEvqV4b-_LY,1758
+api/public.py,sha256=9iHQ3hy6S2NBAQYF9_vqLUrXlaVhSN_ibFVEZKmXjls,1759
 api/si.py,sha256=Qx-WMSia7wxd6hnuhadTtpB8jyeVH7eK-4s98rMnlyM,2242
 core/__init__.py,sha256=OjXKNa-EMmUZbVVyG4rLhoKfDl6ifZihCSmv27_XIMQ,811
+core/deprecations.py,sha256=SQf13eA5dJt78CvIKuXi3vI1bBknwEPHT3FkDWh0Xmc,1436
 core/errors.py,sha256=iwA73z53DPMPmdoGg-T_PYpyfETqbxwGpxcDYOrsxLY,609
-core/quantity.py,sha256=5A8o3qDiWp2Hq8z5hRTVjS6j9woCSdu5XfzgXY_LIdM,9054
-core/unit_definitions.py,sha256=a0-2Ntz9RSLfww7GmCuR0D4fCl5adf4lNFwL48WnpfA,7611
+core/quantity.py,sha256=KbZowTitSwjudPDgx3cw-nnu4hnnLECxDG6T7vTjE9s,10058
+core/unit_definitions.py,sha256=c3vbjM5-bm-wRNG6z9qJY3b54W2U5JsQM-Vpt2QnaW4,10312
 models/__init__.py,sha256=8-39jReNyDmbbih6K5IHeqwoWfagjXzjy7nIfJBpPMI,189
-models/dimension.py,sha256=iGIZCT5_AZySAhcH8RYHh3tYUmdmseJ70KlbbsctzZY,2757
-python_units-0.2.0.dist-info/licenses/LICENSE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+models/dimension.py,sha256=UNlb234AaUim7iXWzc_2RZ5aZCUefZTvOGTNizoQiPc,3789
+python_units-0.3.0.dist-info/licenses/LICENSE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 services/__init__.py,sha256=tSot9S3F7fHezy3Lj4DNRMQK1ATptRaN0efKRJSgrKs,65
 units/__init__.py,sha256=Tyj9-XgWDco8J7s_wx2jaEP3fylc2Tc6VZIbsZ1ron4,251
 units/dimension.py,sha256=v-aiG3bDV7tJUV_xuxZSAw8UHQe0GnbybI2UkiEwuQM,221
@@ -18,7 +19,7 @@ units/si.py,sha256=2wqvff8wxQP1w-fWPYolWuIeBGl942jyX8N6dQyGwDU,118
 units/unit.py,sha256=5g_azobEX4LPiO7W3n5RmpYCmZuVpZDX77Ipy9ydILk,450
 utils/__init__.py,sha256=zTkrwGlYAf6IRcS8e_9nRyACmwJO5Ni-Lwoy55K3qCw,191
 utils/numbers.py,sha256=_wzMOCoU2hOybqVcT-x__7eY6WkwHa97Ahhr9L5reQE,884
-python_units-0.2.0.dist-info/METADATA,sha256=u0daWTTz-YbT8Ox1KB6iUpTn3HjndViAV-2hx47K-r4,6879
-python_units-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-python_units-0.2.0.dist-info/top_level.txt,sha256=xVEgUUcetmpTHsYk3A-xD9qAxU5S2yD0n8YW1r08tn0,46
-python_units-0.2.0.dist-info/RECORD,,
+python_units-0.3.0.dist-info/METADATA,sha256=2brF79U2LZZXfM_7o-YhOdH7i8RQmqNA4LGMHpBHEJM,7377
+python_units-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_units-0.3.0.dist-info/top_level.txt,sha256=xVEgUUcetmpTHsYk3A-xD9qAxU5S2yD0n8YW1r08tn0,46
+python_units-0.3.0.dist-info/RECORD,,