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

adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapter-layer package reserved for external integrations."""

api/__init__.py

@@ -0,0 +1,3 @@
+"""Curated API exports for the units package."""
+
+from .public import *

api/public.py

@@ -0,0 +1,110 @@
+# -*- coding: utf-8 -*-
+"""Public export surface for the units package."""
+
+from api.si import (
+    ampere,
+    becquerel,
+    candela,
+    coulomb,
+    degree_celcius,
+    farad,
+    gray,
+    henry,
+    hertz,
+    joule,
+    katal,
+    kelvin,
+    kilogram,
+    lumen,
+    lux,
+    metre,
+    mole,
+    newton,
+    ohm,
+    pascal,
+    radian,
+    second,
+    siemens,
+    sievert,
+    steradian,
+    tesla,
+    volt,
+    watt,
+    weber,
+)
+from core.errors import (
+    InvalidUnitError,
+    InvalidValueError,
+    UnitCompatibilityError,
+    UnitOperandError,
+    UnitsError,
+)
+from core.quantity import (
+    Quantity,
+    complex_quantity,
+    complex_unit,
+    float_quantity,
+    float_unit,
+    int_quantity,
+    int_unit,
+    long_quantity,
+    long_unit,
+)
+from core.unit_definitions import BaseUnit, CustomUnitBase, DerivedUnit, SIUnit
+from models.dimension import Dimension, DimensionSystem
+
+
+Unit = Quantity
+
+__all__ = [
+    "Dimension",
+    "DimensionSystem",
+    "Quantity",
+    "Unit",
+    "UnitsError",
+    "InvalidUnitError",
+    "InvalidValueError",
+    "UnitCompatibilityError",
+    "UnitOperandError",
+    "BaseUnit",
+    "CustomUnitBase",
+    "DerivedUnit",
+    "SIUnit",
+    "ampere",
+    "becquerel",
+    "candela",
+    "complex_quantity",
+    "complex_unit",
+    "coulomb",
+    "degree_celcius",
+    "farad",
+    "float_quantity",
+    "float_unit",
+    "gray",
+    "henry",
+    "hertz",
+    "int_quantity",
+    "int_unit",
+    "joule",
+    "katal",
+    "kelvin",
+    "kilogram",
+    "long_quantity",
+    "long_unit",
+    "lumen",
+    "lux",
+    "metre",
+    "mole",
+    "newton",
+    "ohm",
+    "pascal",
+    "radian",
+    "second",
+    "siemens",
+    "sievert",
+    "steradian",
+    "tesla",
+    "volt",
+    "watt",
+    "weber",
+]

api/si.py

@@ -0,0 +1,88 @@
+# -*- coding: utf-8 -*-
+"""Predefined SI base units and common derived units."""
+
+from core.unit_definitions import DerivedUnit, SIUnit, register_canonical_unit
+
+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")
+
+for unit in (ampere, candela, kelvin, kilogram, metre, mole, second):
+    register_canonical_unit(unit)
+
+radian = DerivedUnit.define("rad", metre / metre)
+steradian = DerivedUnit.define("sr", metre * metre / metre / metre)
+hertz = DerivedUnit.define("Hz", SIUnit() / second)
+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)
+degree_celcius = DerivedUnit.define("°C", kelvin)
+lumen = DerivedUnit.define("lm", candela * steradian)
+lux = DerivedUnit.define("lx", lumen / metre / metre)
+becquerel = DerivedUnit.define("Bq", SIUnit() / second)
+gray = DerivedUnit.define("Gy", joule / kilogram)
+sievert = DerivedUnit.define("Sv", joule / kilogram)
+katal = DerivedUnit.define("kat", mole / second)
+
+for unit in (
+    newton,
+    pascal,
+    joule,
+    watt,
+    coulomb,
+    volt,
+    farad,
+    ohm,
+    siemens,
+    weber,
+    tesla,
+    henry,
+    lumen,
+    lux,
+):
+    register_canonical_unit(unit)
+
+__all__ = [
+    "ampere",
+    "becquerel",
+    "candela",
+    "coulomb",
+    "degree_celcius",
+    "farad",
+    "gray",
+    "henry",
+    "hertz",
+    "joule",
+    "katal",
+    "kelvin",
+    "kilogram",
+    "lumen",
+    "lux",
+    "metre",
+    "mole",
+    "newton",
+    "ohm",
+    "pascal",
+    "radian",
+    "second",
+    "siemens",
+    "sievert",
+    "steradian",
+    "tesla",
+    "volt",
+    "watt",
+    "weber",
+]

core/__init__.py

@@ -0,0 +1,42 @@
+"""Core unit and quantity logic."""
+
+from .errors import (
+    InvalidUnitError,
+    InvalidValueError,
+    UnitCompatibilityError,
+    UnitOperandError,
+    UnitsError,
+)
+from .quantity import (
+    Quantity,
+    complex_quantity,
+    complex_unit,
+    float_quantity,
+    float_unit,
+    int_quantity,
+    int_unit,
+    long_quantity,
+    long_unit,
+)
+from .unit_definitions import BaseUnit, CustomUnitBase, DerivedUnit, SIUnit
+
+__all__ = [
+    "BaseUnit",
+    "CustomUnitBase",
+    "DerivedUnit",
+    "InvalidUnitError",
+    "InvalidValueError",
+    "Quantity",
+    "SIUnit",
+    "UnitCompatibilityError",
+    "UnitOperandError",
+    "UnitsError",
+    "complex_quantity",
+    "complex_unit",
+    "float_quantity",
+    "float_unit",
+    "int_quantity",
+    "int_unit",
+    "long_quantity",
+    "long_unit",
+]

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/errors.py

@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+"""Domain exceptions for the units package."""
+
+
+class UnitsError(Exception):
+    """Base exception for unit-related failures."""
+
+
+class InvalidValueError(UnitsError):
+    """Raised when a numeric value is invalid for a quantity."""
+
+
+class InvalidUnitError(UnitsError):
+    """Raised when a provided unit object or unit definition is invalid."""
+
+
+class UnitCompatibilityError(UnitsError):
+    """Raised when an operation requires compatible units but they differ."""
+
+
+class UnitOperandError(UnitsError):
+    """Raised when an operation is attempted with an unsupported operand."""

core/quantity.py

@@ -0,0 +1,255 @@
+# -*- coding: utf-8 -*-
+"""Quantity type and quantity operations."""
+
+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
+from utils.numbers import Scalar, is_number, is_real_number, validate_numeric_value
+
+
+def require_quantity_operand(operand: object, operation: str) -> None:
+    """Raise when an operand is not a quantity."""
+    if not isinstance(operand, Quantity):
+        raise UnitOperandError(
+            "unsupported operand for {}: {}".format(operation, type(operand).__name__)
+        )
+
+
+class Quantity:
+    """A numeric value coupled to a unit definition."""
+
+    def __init__(self, value: Scalar, unit: BaseUnit | None = None) -> None:
+        validate_numeric_value(value)
+        self._value = value
+        self._unit = clone_unit(unit)
+
+    @property
+    def value(self) -> Scalar:
+        """Return the numeric value for the quantity."""
+        return self._value
+
+    @value.setter
+    def value(self, value: Scalar) -> None:
+        validate_numeric_value(value)
+        self._value = value
+
+    @property
+    def unit(self) -> BaseUnit:
+        """Return the unit definition for the quantity."""
+        return self._unit
+
+    @unit.setter
+    def unit(self, unit: BaseUnit | None) -> None:
+        self._unit = clone_unit(unit)
+
+    @property
+    def is_unitless(self) -> bool:
+        """Return ``True`` when the quantity is dimensionless."""
+        return all(exponent == 0 for exponent in self.unit.unit_dict.values())
+
+    @property
+    def full_units(self) -> str:
+        """Render derived units in their SI decomposition."""
+        if self.unit.dimension.system != SI_DIMENSION_SYSTEM:
+            return str(self)
+        if not self.is_unitless and not isinstance(self.unit, SIUnit):
+            return "{} {}".format(self.value, self.unit.full_units).strip()
+        return str(self)
+
+    def _dimensionless_unit(self) -> SIUnit:
+        return SIUnit()
+
+    def _require_compatible_quantity(self, quantity2: object, operation: str) -> None:
+        require_quantity_operand(quantity2, operation)
+        if self.unit != quantity2.unit:
+            raise UnitCompatibilityError(
+                "units mismatch: {} and {}".format(self.unit, quantity2.unit)
+            )
+
+    def _require_real_scalar(self, value: object, operation: str) -> None:
+        if not is_real_number(value):
+            raise UnitOperandError(
+                "unsupported scalar for {}: {}".format(operation, type(value).__name__)
+            )
+
+    def _require_numeric_scalar(self, value: object, operation: str) -> None:
+        if not is_number(value):
+            raise UnitOperandError(
+                "unsupported scalar for {}: {}".format(operation, type(value).__name__)
+            )
+
+    def __add__(self, quantity2: object) -> "Quantity":
+        self._require_compatible_quantity(quantity2, "addition")
+        return self.__class__(self.value + quantity2.value, self.unit)
+
+    def __radd__(self, quantity2: object) -> "Quantity":
+        return self.__add__(quantity2)
+
+    def __sub__(self, quantity2: object) -> "Quantity":
+        self._require_compatible_quantity(quantity2, "subtraction")
+        return self.__class__(self.value - quantity2.value, self.unit)
+
+    def __rsub__(self, quantity2: object) -> "Quantity":
+        self._require_compatible_quantity(quantity2, "subtraction")
+        return self.__class__(quantity2.value - self.value, self.unit)
+
+    def __mul__(self, quantity2: object) -> "Quantity":
+        if isinstance(quantity2, Quantity):
+            return self.__class__(self.value * quantity2.value, self.unit * quantity2.unit)
+        if isinstance(quantity2, BaseUnit):
+            return self.__class__(self.value, self.unit * quantity2)
+        self._require_numeric_scalar(quantity2, "multiplication")
+        return self.__class__(self.value * quantity2, self.unit)
+
+    def __rmul__(self, quantity2: object) -> "Quantity":
+        return self.__mul__(quantity2)
+
+    def __truediv__(self, quantity2: object) -> "Quantity":
+        if isinstance(quantity2, Quantity):
+            return self.__class__(self.value / quantity2.value, self.unit / quantity2.unit)
+        if isinstance(quantity2, BaseUnit):
+            return self.__class__(self.value, self.unit / quantity2)
+        self._require_numeric_scalar(quantity2, "division")
+        return self.__class__(self.value / quantity2, self.unit)
+
+    def __rtruediv__(self, quantity2: object) -> "Quantity":
+        if isinstance(quantity2, Quantity):
+            return self.__class__(quantity2.value / self.value, quantity2.unit / self.unit)
+        self._require_numeric_scalar(quantity2, "division")
+        return self.__class__(quantity2 / self.value, self._dimensionless_unit() / self.unit)
+
+    def __floordiv__(self, quantity2: object) -> "Quantity":
+        if isinstance(quantity2, Quantity):
+            return self.__class__(self.value // quantity2.value, self.unit / quantity2.unit)
+        self._require_real_scalar(quantity2, "floor division")
+        return self.__class__(self.value // quantity2, self.unit)
+
+    def __rfloordiv__(self, quantity2: object) -> "Quantity":
+        if isinstance(quantity2, Quantity):
+            return self.__class__(quantity2.value // self.value, quantity2.unit / self.unit)
+        self._require_real_scalar(quantity2, "floor division")
+        return self.__class__(quantity2 // self.value, self._dimensionless_unit() / self.unit)
+
+    def __mod__(self, quantity2: object) -> "Quantity":
+        if isinstance(quantity2, Quantity):
+            self._require_compatible_quantity(quantity2, "modulo")
+            return self.__class__(self.value % quantity2.value, self.unit)
+        self._require_real_scalar(quantity2, "modulo")
+        return self.__class__(self.value % quantity2, self.unit)
+
+    def __rmod__(self, quantity2: object) -> "Quantity":
+        if isinstance(quantity2, Quantity):
+            self._require_compatible_quantity(quantity2, "modulo")
+            return self.__class__(quantity2.value % self.value, self.unit)
+        self._require_real_scalar(quantity2, "modulo")
+        return self.__class__(quantity2 % self.value, self._dimensionless_unit() / self.unit)
+
+    def __divmod__(self, quantity2: object) -> tuple["Quantity", "Quantity"]:
+        return self.__floordiv__(quantity2), self.__mod__(quantity2)
+
+    def __rdivmod__(self, quantity2: object) -> tuple["Quantity", "Quantity"]:
+        return self.__rfloordiv__(quantity2), self.__rmod__(quantity2)
+
+    def __pow__(self, exponent: object) -> "Quantity":
+        self._require_numeric_scalar(exponent, "power")
+        if isinstance(exponent, complex):
+            raise UnitOperandError("unsupported scalar for power: complex")
+        if not self.is_unitless and (not isinstance(exponent, int) or isinstance(exponent, bool)):
+            raise UnitOperandError(
+                "unsupported scalar for power: {}".format(type(exponent).__name__)
+            )
+        if self.is_unitless:
+            return self.__class__(self.value ** exponent, self.unit)
+        return self.__class__(self.value ** exponent, self.unit ** exponent)
+
+    def __neg__(self) -> "Quantity":
+        return self.__class__(-self.value, self.unit)
+
+    def __pos__(self) -> "Quantity":
+        return self.__class__(+self.value, self.unit)
+
+    def __abs__(self) -> "Quantity":
+        return self.__class__(abs(self.value), self.unit)
+
+    def __complex__(self) -> complex:
+        raise TypeError("invalid conversion from Quantity object to complex")
+
+    def __int__(self) -> int:
+        raise TypeError("invalid conversion from Quantity object to int")
+
+    def __float__(self) -> float:
+        raise TypeError("invalid conversion from Quantity object to float")
+
+    def __str__(self) -> str:
+        return "{} {}".format(self.value, self.unit).strip()
+
+
+def int_quantity(quantity: Quantity) -> Quantity:
+    """Convert a quantity value to int while preserving its unit."""
+    require_quantity_operand(quantity, "int conversion")
+    return Quantity(int(quantity.value), quantity.unit)
+
+
+def float_quantity(quantity: Quantity) -> Quantity:
+    """Convert a quantity value to float while preserving its unit."""
+    require_quantity_operand(quantity, "float conversion")
+    return Quantity(float(quantity.value), quantity.unit)
+
+
+def long_quantity(quantity: Quantity) -> Quantity:
+    """Legacy compatibility helper equivalent to ``int_quantity``."""
+    return deprecated_call(
+        "long_quantity",
+        "int_quantity",
+        "1.0.0",
+        lambda: int_quantity(quantity),
+    )
+
+
+def complex_quantity(quantity: Quantity) -> Quantity:
+    """Convert a quantity value to complex while preserving its unit."""
+    require_quantity_operand(quantity, "complex conversion")
+    return Quantity(complex(quantity.value), quantity.unit)
+
+
+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),
+    )