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

api/public.py

@@ -5,20 +5,40 @@ from api.si import (
     ampere,
     becquerel,
     candela,
+    centimetre,
     coulomb,
     degree_celcius,
     farad,
+    gram,
     gray,
     henry,
     hertz,
+    hour,
     joule,
     katal,
     kelvin,
     kilogram,
+    kiloampere,
+    kilometre,
+    kilovolt,
+    kilowatt,
     lumen,
     lux,
+    megawatt,
     metre,
+    microgram,
+    micrometre,
+    microsecond,
+    milliampere,
+    milligram,
+    millimetre,
+    millisecond,
+    millivolt,
+    milliwatt,
+    minute,
     mole,
+    nanometre,
+    nanosecond,
     newton,
     ohm,
     pascal,
@@ -28,6 +48,7 @@ from api.si import (
     sievert,
     steradian,
     tesla,
+    tonne,
     volt,
     watt,
     weber,
@@ -43,16 +64,21 @@ from core.quantity import (
     Quantity,
     complex_quantity,
     complex_unit,
+    convert,
     float_quantity,
     float_unit,
     int_quantity,
     int_unit,
     long_quantity,
     long_unit,
+    multiplier,
+    unit,
+    value,
 )
 from core.unit_definitions import BaseUnit, CustomUnitBase, DerivedUnit, SIUnit
 from models.dimension import Dimension, DimensionSystem
 
+
 Unit = Quantity
 
 __all__ = [
@@ -72,28 +98,50 @@ __all__ = [
     "ampere",
     "becquerel",
     "candela",
+    "centimetre",
     "complex_quantity",
     "complex_unit",
+    "convert",
     "coulomb",
     "degree_celcius",
     "farad",
     "float_quantity",
     "float_unit",
+    "gram",
     "gray",
     "henry",
     "hertz",
+    "hour",
     "int_quantity",
     "int_unit",
     "joule",
     "katal",
     "kelvin",
     "kilogram",
+    "kiloampere",
+    "kilometre",
+    "kilovolt",
+    "kilowatt",
     "long_quantity",
     "long_unit",
     "lumen",
     "lux",
+    "megawatt",
     "metre",
+    "microgram",
+    "micrometre",
+    "microsecond",
+    "milliampere",
+    "milligram",
+    "millimetre",
+    "millisecond",
+    "millivolt",
+    "milliwatt",
+    "minute",
+    "multiplier",
     "mole",
+    "nanometre",
+    "nanosecond",
     "newton",
     "ohm",
     "pascal",
@@ -103,6 +151,9 @@ __all__ = [
     "sievert",
     "steradian",
     "tesla",
+    "tonne",
+    "unit",
+    "value",
     "volt",
     "watt",
     "weber",

api/si.py

@@ -29,7 +29,11 @@ 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)
+degree_celcius = DerivedUnit.define(
+    "°C",
+    kelvin,
+    supports_multiplicative_conversion=False,
+)
 lumen = DerivedUnit.define("lm", candela * steradian)
 lux = DerivedUnit.define("lx", lumen / metre / metre)
 becquerel = DerivedUnit.define("Bq", SIUnit() / second)
@@ -37,6 +41,31 @@ gray = DerivedUnit.define("Gy", joule / kilogram)
 sievert = DerivedUnit.define("Sv", joule / kilogram)
 katal = DerivedUnit.define("kat", mole / second)
 
+kilometre = DerivedUnit.define("km", metre, conversion_factor=1000.0)
+centimetre = DerivedUnit.define("cm", metre, conversion_factor=0.01)
+millimetre = DerivedUnit.define("mm", metre, conversion_factor=0.001)
+micrometre = DerivedUnit.define("µm", metre, conversion_factor=0.000001)
+nanometre = DerivedUnit.define("nm", metre, conversion_factor=0.000000001)
+
+gram = DerivedUnit.define("g", kilogram, conversion_factor=0.001)
+milligram = DerivedUnit.define("mg", kilogram, conversion_factor=0.000001)
+microgram = DerivedUnit.define("µg", kilogram, conversion_factor=0.000000001)
+tonne = DerivedUnit.define("t", kilogram, conversion_factor=1000.0)
+
+minute = DerivedUnit.define("min", second, conversion_factor=60.0)
+hour = DerivedUnit.define("h", second, conversion_factor=3600.0)
+millisecond = DerivedUnit.define("ms", second, conversion_factor=0.001)
+microsecond = DerivedUnit.define("µs", second, conversion_factor=0.000001)
+nanosecond = DerivedUnit.define("ns", second, conversion_factor=0.000000001)
+
+milliampere = DerivedUnit.define("mA", ampere, conversion_factor=0.001)
+kiloampere = DerivedUnit.define("kA", ampere, conversion_factor=1000.0)
+millivolt = DerivedUnit.define("mV", volt, conversion_factor=0.001)
+kilovolt = DerivedUnit.define("kV", volt, conversion_factor=1000.0)
+milliwatt = DerivedUnit.define("mW", watt, conversion_factor=0.001)
+kilowatt = DerivedUnit.define("kW", watt, conversion_factor=1000.0)
+megawatt = DerivedUnit.define("MW", watt, conversion_factor=1000000.0)
+
 for unit in (
     newton,
     pascal,
@@ -59,20 +88,40 @@ __all__ = [
     "ampere",
     "becquerel",
     "candela",
+    "centimetre",
     "coulomb",
     "degree_celcius",
     "farad",
+    "gram",
     "gray",
     "henry",
     "hertz",
+    "hour",
     "joule",
     "katal",
     "kelvin",
     "kilogram",
+    "kiloampere",
+    "kilometre",
+    "kilovolt",
+    "kilowatt",
     "lumen",
     "lux",
+    "megawatt",
     "metre",
+    "microgram",
+    "micrometre",
+    "microsecond",
+    "milliampere",
+    "milligram",
+    "millimetre",
+    "millisecond",
+    "millivolt",
+    "milliwatt",
+    "minute",
     "mole",
+    "nanometre",
+    "nanosecond",
     "newton",
     "ohm",
     "pascal",
@@ -82,6 +131,7 @@ __all__ = [
     "sievert",
     "steradian",
     "tesla",
+    "tonne",
     "volt",
     "watt",
     "weber",

core/__init__.py

@@ -11,12 +11,16 @@ from .quantity import (
     Quantity,
     complex_quantity,
     complex_unit,
+    convert,
     float_quantity,
     float_unit,
     int_quantity,
     int_unit,
     long_quantity,
     long_unit,
+    multiplier,
+    unit,
+    value,
 )
 from .unit_definitions import BaseUnit, CustomUnitBase, DerivedUnit, SIUnit
 
@@ -33,10 +37,14 @@ __all__ = [
     "UnitsError",
     "complex_quantity",
     "complex_unit",
+    "convert",
     "float_quantity",
     "float_unit",
     "int_quantity",
     "int_unit",
     "long_quantity",
     "long_unit",
+    "multiplier",
+    "unit",
+    "value",
 ]

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,8 +3,15 @@
 
 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 core.unit_definitions import (
+    BaseUnit,
+    DerivedUnit,
+    SIUnit,
+    clone_unit,
+    require_unit_instance,
+)
 from models.dimension import SI_DIMENSION_SYSTEM
 from utils.numbers import Scalar, is_number, is_real_number, validate_numeric_value
 
@@ -17,6 +24,49 @@ def require_quantity_operand(operand: object, operation: str) -> None:
         )
 
 
+def normalize_scalar(value: Scalar) -> Scalar:
+    """Return ``int`` for exact integer floats, otherwise return ``value``."""
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    return value
+
+
+def normalize_product(value: Scalar, left: Scalar, right: Scalar) -> Scalar:
+    """Normalize exact integer products only when both inputs were integers."""
+    if isinstance(left, int) and isinstance(right, int):
+        return normalize_scalar(value)
+    return value
+
+
+def normalize_reverse_floor(value: Scalar, denominator: "Quantity") -> Scalar:
+    """Preserve legacy int display for unscaled integer reverse floor division."""
+    if (
+        denominator.unit.conversion_factor == 1.0
+        and isinstance(denominator.value, int)
+    ):
+        return normalize_scalar(value)
+    return value
+
+
+def normalize_result_unit(result_unit: BaseUnit) -> BaseUnit:
+    """Return a renderable result unit with no hidden anonymous scale."""
+    if isinstance(result_unit, DerivedUnit) or result_unit.conversion_factor == 1.0:
+        return result_unit
+    try:
+        return result_unit.__class__(
+            dimension=result_unit.dimension,
+            supports_multiplicative_conversion=(
+                result_unit.supports_multiplicative_conversion
+            ),
+        )
+    except TypeError:
+        unit = result_unit.__class__(dimension=result_unit.dimension)
+        unit._supports_multiplicative_conversion = (
+            result_unit.supports_multiplicative_conversion
+        )
+        return unit
+
+
 class Quantity:
     """A numeric value coupled to a unit definition."""
 
@@ -80,6 +130,44 @@ class Quantity:
                 "unsupported scalar for {}: {}".format(operation, type(value).__name__)
             )
 
+    def _base_value(self) -> Scalar:
+        return self.value * self.unit.conversion_factor
+
+    def to(self, target_unit: BaseUnit) -> "Quantity":
+        """
+        Convert this quantity to a compatible scale-only target unit.
+
+        Args:
+            target_unit: Unit definition with the same dimension.
+
+        Returns:
+            Quantity expressed in ``target_unit``.
+
+        Raises:
+            InvalidUnitError: If ``target_unit`` is not a unit definition.
+            UnitCompatibilityError: If dimensions differ or either unit cannot
+                be converted with a multiplicative scale factor.
+        """
+        require_unit_instance(target_unit)
+        if self.unit.dimension != target_unit.dimension:
+            raise UnitCompatibilityError(
+                "cannot convert {} to {}".format(self.unit, target_unit)
+            )
+        if (
+            not self.unit.supports_multiplicative_conversion
+            or not target_unit.supports_multiplicative_conversion
+        ):
+            raise UnitCompatibilityError(
+                "units require a non-multiplicative conversion: {} and {}".format(
+                    self.unit,
+                    target_unit,
+                )
+            )
+        return self.__class__(
+            normalize_scalar(self._base_value() / target_unit.conversion_factor),
+            target_unit,
+        )
+
     def __add__(self, quantity2: object) -> "Quantity":
         self._require_compatible_quantity(quantity2, "addition")
         return self.__class__(self.value + quantity2.value, self.unit)
@@ -97,9 +185,22 @@ class Quantity:
 
     def __mul__(self, quantity2: object) -> "Quantity":
         if isinstance(quantity2, Quantity):
-            return self.__class__(self.value * quantity2.value, self.unit * quantity2.unit)
+            result_unit = self.unit * quantity2.unit
+            result_value = self._base_value() * quantity2._base_value()
+            return self.__class__(
+                normalize_product(result_value, self.value, quantity2.value),
+                normalize_result_unit(result_unit),
+            )
         if isinstance(quantity2, BaseUnit):
-            return self.__class__(self.value, self.unit * quantity2)
+            result_unit = self.unit * quantity2
+            result_value = (
+                self._base_value()
+                * quantity2.conversion_factor
+            )
+            return self.__class__(
+                normalize_scalar(result_value),
+                normalize_result_unit(result_unit),
+            )
         self._require_numeric_scalar(quantity2, "multiplication")
         return self.__class__(self.value * quantity2, self.unit)
 
@@ -108,29 +209,55 @@ class Quantity:
 
     def __truediv__(self, quantity2: object) -> "Quantity":
         if isinstance(quantity2, Quantity):
-            return self.__class__(self.value / quantity2.value, self.unit / quantity2.unit)
+            result_unit = self.unit / quantity2.unit
+            result_value = self._base_value() / quantity2._base_value()
+            return self.__class__(result_value, normalize_result_unit(result_unit))
         if isinstance(quantity2, BaseUnit):
-            return self.__class__(self.value, self.unit / quantity2)
+            result_unit = self.unit / quantity2
+            result_value = (
+                self._base_value()
+                / quantity2.conversion_factor
+            )
+            return self.__class__(
+                normalize_scalar(result_value),
+                normalize_result_unit(result_unit),
+            )
         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)
+            result_unit = quantity2.unit / self.unit
+            result_value = quantity2._base_value() / self._base_value()
+            return self.__class__(result_value, normalize_result_unit(result_unit))
         self._require_numeric_scalar(quantity2, "division")
-        return self.__class__(quantity2 / self.value, self._dimensionless_unit() / self.unit)
+        result_unit = self._dimensionless_unit() / self.unit
+        result_value = quantity2 / self._base_value()
+        return self.__class__(result_value, normalize_result_unit(result_unit))
 
     def __floordiv__(self, quantity2: object) -> "Quantity":
         if isinstance(quantity2, Quantity):
-            return self.__class__(self.value // quantity2.value, self.unit / quantity2.unit)
+            result_unit = self.unit / quantity2.unit
+            result_value = self._base_value() // quantity2._base_value()
+            return self.__class__(result_value, normalize_result_unit(result_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)
+            result_unit = quantity2.unit / self.unit
+            result_value = quantity2._base_value() // self._base_value()
+            return self.__class__(
+                normalize_scalar(result_value),
+                normalize_result_unit(result_unit),
+            )
         self._require_real_scalar(quantity2, "floor division")
-        return self.__class__(quantity2 // self.value, self._dimensionless_unit() / self.unit)
+        result_unit = self._dimensionless_unit() / self.unit
+        result_value = quantity2 // self._base_value()
+        return self.__class__(
+            normalize_reverse_floor(result_value, self),
+            normalize_result_unit(result_unit),
+        )
 
     def __mod__(self, quantity2: object) -> "Quantity":
         if isinstance(quantity2, Quantity):
@@ -144,7 +271,12 @@ class 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)
+        result_unit = self._dimensionless_unit() / self.unit
+        result_value = quantity2 % self._base_value()
+        return self.__class__(
+            normalize_scalar(result_value),
+            normalize_result_unit(result_unit),
+        )
 
     def __divmod__(self, quantity2: object) -> tuple["Quantity", "Quantity"]:
         return self.__floordiv__(quantity2), self.__mod__(quantity2)
@@ -162,7 +294,12 @@ class Quantity:
             )
         if self.is_unitless:
             return self.__class__(self.value ** exponent, self.unit)
-        return self.__class__(self.value ** exponent, self.unit ** exponent)
+        result_unit = self.unit ** exponent
+        result_value = self._base_value() ** exponent
+        return self.__class__(
+            normalize_scalar(result_value),
+            normalize_result_unit(result_unit),
+        )
 
     def __neg__(self) -> "Quantity":
         return self.__class__(-self.value, self.unit)
@@ -200,8 +337,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 +351,119 @@ 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 convert(quantity: Quantity, target_unit: BaseUnit) -> Quantity:
+    """
+    Convert a quantity to a compatible scale-only target unit.
+
+    Args:
+        quantity: Quantity to convert.
+        target_unit: Unit definition with the same dimension.
+
+    Returns:
+        Quantity expressed in ``target_unit``.
+
+    Raises:
+        UnitOperandError: If ``quantity`` is not a Quantity.
+        InvalidUnitError: If ``target_unit`` is not a unit definition.
+        UnitCompatibilityError: If conversion is not scale-only compatible.
+    """
+    require_quantity_operand(quantity, "conversion")
+    return quantity.to(target_unit)
+
+
+def value(quantity: Quantity) -> Scalar:
+    """
+    Return the numeric value of a quantity without converting it.
+
+    Args:
+        quantity: Quantity to inspect.
+
+    Returns:
+        Numeric value stored on the quantity.
+
+    Raises:
+        UnitOperandError: If ``quantity`` is not a Quantity.
+    """
+    require_quantity_operand(quantity, "value extraction")
+    return quantity.value
+
+
+def unit(quantity: Quantity) -> BaseUnit:
+    """
+    Return the unit definition of a quantity.
+
+    Args:
+        quantity: Quantity to inspect.
+
+    Returns:
+        Unit definition stored on the quantity.
+
+    Raises:
+        UnitOperandError: If ``quantity`` is not a Quantity.
+    """
+    require_quantity_operand(quantity, "unit extraction")
+    return quantity.unit
+
+
+def multiplier(quantity_or_unit: Quantity | BaseUnit) -> float:
+    """
+    Return the multiplicative factor to the canonical base dimension.
+
+    Args:
+        quantity_or_unit: Quantity or unit definition to inspect.
+
+    Returns:
+        Multiplicative factor for the unit carried by the input.
+
+    Raises:
+        UnitOperandError: If the input is neither Quantity nor BaseUnit.
+    """
+    if isinstance(quantity_or_unit, Quantity):
+        return quantity_or_unit.unit.conversion_factor
+    if isinstance(quantity_or_unit, BaseUnit):
+        return quantity_or_unit.conversion_factor
+    raise UnitOperandError(
+        "unsupported operand for multiplier extraction: {}".format(
+            type(quantity_or_unit).__name__
+        )
+    )
+
+
+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),
+    )