python-units 0.3.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,12 +64,16 @@ 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
@@ -73,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",
@@ -104,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/quantity.py

@@ -5,7 +5,13 @@ 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
 
@@ -18,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."""
 
@@ -81,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)
@@ -98,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)
 
@@ -109,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):
@@ -145,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)
@@ -163,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)
@@ -215,6 +351,84 @@ def complex_quantity(quantity: Quantity) -> Quantity:
     return Quantity(complex(quantity.value), quantity.unit)
 
 
+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(

core/unit_definitions.py

@@ -3,7 +3,7 @@
 
 from __future__ import annotations
 
-from numbers import Number
+from numbers import Number, Real
 from types import MappingProxyType
 from typing import Dict, Mapping
 
@@ -36,13 +36,50 @@ def require_unit_instance(unit: object) -> None:
         )
 
 
+def validate_conversion_factor(conversion_factor: object) -> float:
+    """Validate a multiplicative conversion factor and return it as float."""
+    if (
+        not isinstance(conversion_factor, Real)
+        or isinstance(conversion_factor, bool)
+        or conversion_factor <= 0
+    ):
+        raise InvalidValueError(
+            "conversion factor must be a positive real scalar, got {}".format(
+                type(conversion_factor).__name__
+            )
+        )
+    return float(conversion_factor)
+
+
+def validate_conversion_support(supports_conversion: object) -> bool:
+    """Validate a conversion support flag and return it."""
+    if not isinstance(supports_conversion, bool):
+        raise InvalidValueError(
+            "conversion support flag must be bool, got {}".format(
+                type(supports_conversion).__name__
+            )
+        )
+    return supports_conversion
+
+
 def clone_unit(unit: "BaseUnit | None") -> "BaseUnit":
     """Clone a unit definition while preserving its type."""
     if unit is None:
         return SIUnit()
     require_unit_instance(unit)
 
-    cloned_unit = unit.__class__(dimension=unit.dimension)
+    try:
+        cloned_unit = unit.__class__(
+            dimension=unit.dimension,
+            conversion_factor=unit.conversion_factor,
+            supports_multiplicative_conversion=unit.supports_multiplicative_conversion,
+        )
+    except TypeError:
+        cloned_unit = unit.__class__(dimension=unit.dimension)
+        cloned_unit._conversion_factor = unit.conversion_factor
+        cloned_unit._supports_multiplicative_conversion = (
+            unit.supports_multiplicative_conversion
+        )
     if isinstance(unit, DerivedUnit):
         cloned_unit.name = unit.name
     return cloned_unit
@@ -61,11 +98,20 @@ class BaseUnit:
 
     dimension_system = SI_DIMENSION_SYSTEM
 
-    def __init__(self, dimension: Dimension | None = None) -> None:
+    def __init__(
+        self,
+        dimension: Dimension | None = None,
+        conversion_factor: float = 1.0,
+        supports_multiplicative_conversion: bool = True,
+    ) -> None:
         self._dimension = dimension or Dimension(
             system=self.dimension_system,
             exponents=(0,) * len(self.dimension_system.symbols),
         )
+        self._conversion_factor = validate_conversion_factor(conversion_factor)
+        self._supports_multiplicative_conversion = validate_conversion_support(
+            supports_multiplicative_conversion
+        )
 
     @property
     def unit_dict(self) -> Dict[str, int]:
@@ -85,16 +131,32 @@ class BaseUnit:
     def dimension(self, dimension: Dimension) -> None:
         self._dimension = dimension
 
+    @property
+    def conversion_factor(self) -> float:
+        """Return the multiplicative factor to this dimension's base unit."""
+        return self._conversion_factor
+
+    @property
+    def supports_multiplicative_conversion(self) -> bool:
+        """Return whether this unit can use scale-only conversion."""
+        return self._supports_multiplicative_conversion
+
     def __eq__(self, unit2: object) -> bool:
         if not isinstance(unit2, BaseUnit):
             return False
         if self.dimension != unit2.dimension:
             return False
+        if self.conversion_factor != unit2.conversion_factor:
+            return False
         if isinstance(self, DerivedUnit) or isinstance(unit2, DerivedUnit):
             return (
                 isinstance(self, DerivedUnit)
                 and isinstance(unit2, DerivedUnit)
                 and self.name == unit2.name
+                and (
+                    self.supports_multiplicative_conversion
+                    == unit2.supports_multiplicative_conversion
+                )
             )
         return True
 
@@ -109,15 +171,48 @@ class BaseUnit:
             )
         if operator_name == "mul":
             dimension = self.dimension * unit2.dimension
+            conversion_factor = self.conversion_factor * unit2.conversion_factor
         else:
             dimension = self.dimension / unit2.dimension
+            conversion_factor = self.conversion_factor / unit2.conversion_factor
+        supports_conversion = (
+            self.supports_multiplicative_conversion
+            and unit2.supports_multiplicative_conversion
+        )
         if dimension.system != SI_DIMENSION_SYSTEM:
-            return self.__class__(dimension=dimension)
-        return resolve_unit(dimension)
+            return self.__class__(
+                dimension=dimension,
+                conversion_factor=conversion_factor,
+                supports_multiplicative_conversion=supports_conversion,
+            )
+        if supports_conversion and conversion_factor == 1.0:
+            return resolve_unit(dimension)
+        return BaseUnit(
+            dimension=dimension,
+            conversion_factor=conversion_factor,
+            supports_multiplicative_conversion=supports_conversion,
+        )
 
     def _quantity_from_scalar(self, value: Number) -> object:
-        from core.quantity import Quantity
-
+        from core.quantity import Quantity, normalize_scalar
+
+        if not isinstance(self, DerivedUnit) and self.conversion_factor != 1.0:
+            try:
+                unit = self.__class__(
+                    dimension=self.dimension,
+                    supports_multiplicative_conversion=(
+                        self.supports_multiplicative_conversion
+                    ),
+                )
+            except TypeError:
+                unit = self.__class__(dimension=self.dimension)
+                unit._supports_multiplicative_conversion = (
+                    self.supports_multiplicative_conversion
+                )
+            result_value = value * self.conversion_factor
+            if self.conversion_factor.is_integer():
+                result_value = normalize_scalar(result_value)
+            return Quantity(result_value, unit)
         return Quantity(value, self)
 
     def __mul__(self, unit2: object) -> object:
@@ -152,13 +247,37 @@ class BaseUnit:
             system=self.dimension.system,
             exponents=tuple(value * exponent for value in self.dimension.exponents),
         )
-        if isinstance(self, DerivedUnit) and self.name and exponent != 1:
-            derived = DerivedUnit(dimension=dimension)
+        conversion_factor = self.conversion_factor**exponent
+        if (
+            isinstance(self, DerivedUnit)
+            and self.name
+            and exponent != 1
+            and self.conversion_factor == 1.0
+        ):
+            derived = DerivedUnit(
+                dimension=dimension,
+                conversion_factor=1.0,
+                supports_multiplicative_conversion=(
+                    self.supports_multiplicative_conversion
+                ),
+            )
             derived.name = "{}^{}".format(self.name, exponent)
             return derived
         if dimension.system != SI_DIMENSION_SYSTEM:
-            return self.__class__(dimension=dimension)
-        return resolve_unit(dimension)
+            return self.__class__(
+                dimension=dimension,
+                conversion_factor=conversion_factor,
+                supports_multiplicative_conversion=(
+                    self.supports_multiplicative_conversion
+                ),
+            )
+        if self.supports_multiplicative_conversion and conversion_factor == 1.0:
+            return resolve_unit(dimension)
+        return BaseUnit(
+            dimension=dimension,
+            conversion_factor=conversion_factor,
+            supports_multiplicative_conversion=self.supports_multiplicative_conversion,
+        )
 
     def __str__(self) -> str:
         return self.dimension.render()
@@ -168,7 +287,12 @@ class SIUnit(BaseUnit):
     """Template class for SI units."""
 
     @classmethod
-    def define(cls, key: str, value: int = 1) -> "SIUnit":
+    def define(
+        cls,
+        key: str,
+        value: int = 1,
+        conversion_factor: float = 1.0,
+    ) -> "SIUnit":
         """Define an SI unit or exponentiated SI dimension."""
         if key not in cls.dimension_system.symbols:
             raise InvalidUnitError("unknown SI unit key: {}".format(key))
@@ -176,7 +300,10 @@ class SIUnit(BaseUnit):
             raise InvalidValueError(
                 "unit exponent must be an integer, got {}".format(type(value).__name__)
             )
-        return cls(dimension=Dimension.from_mapping({key: value}, system=cls.dimension_system))
+        return cls(
+            dimension=Dimension.from_mapping({key: value}, system=cls.dimension_system),
+            conversion_factor=conversion_factor,
+        )
 
 
 class CustomUnitBase(BaseUnit):
@@ -185,7 +312,12 @@ class CustomUnitBase(BaseUnit):
     dimension_system = DimensionSystem("custom", ())
 
     @classmethod
-    def define(cls, key: str, value: int = 1) -> "CustomUnitBase":
+    def define(
+        cls,
+        key: str,
+        value: int = 1,
+        conversion_factor: float = 1.0,
+    ) -> "CustomUnitBase":
         """Define a custom base unit within the subclass dimension system."""
         if key not in cls.dimension_system.symbols:
             raise InvalidUnitError("unknown custom unit key: {}".format(key))
@@ -193,7 +325,10 @@ class CustomUnitBase(BaseUnit):
             raise InvalidValueError(
                 "unit exponent must be an integer, got {}".format(type(value).__name__)
             )
-        return cls(dimension=Dimension.from_mapping({key: value}, system=cls.dimension_system))
+        return cls(
+            dimension=Dimension.from_mapping({key: value}, system=cls.dimension_system),
+            conversion_factor=conversion_factor,
+        )
 
 
 class DerivedUnit(BaseUnit):
@@ -218,10 +353,28 @@ class DerivedUnit(BaseUnit):
         return super().__str__()
 
     @classmethod
-    def define(cls, name: str, unit: BaseUnit) -> "DerivedUnit":
+    def define(
+        cls,
+        name: str,
+        unit: BaseUnit,
+        conversion_factor: float | None = None,
+        supports_multiplicative_conversion: bool | None = None,
+    ) -> "DerivedUnit":
         """Define a named derived unit."""
         require_unit_instance(unit)
-        obj = cls(dimension=unit.dimension)
+        obj = cls(
+            dimension=unit.dimension,
+            conversion_factor=(
+                unit.conversion_factor
+                if conversion_factor is None
+                else conversion_factor
+            ),
+            supports_multiplicative_conversion=(
+                unit.supports_multiplicative_conversion
+                if supports_multiplicative_conversion is None
+                else supports_multiplicative_conversion
+            ),
+        )
         obj.name = name
         return obj
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-units
-Version: 0.3.0
+Version: 0.4.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
@@ -30,7 +30,74 @@ Dynamic: license-file
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://pypi.org/project/python-units/)
 [![Coverage 92%](https://img.shields.io/badge/coverage-92%25-brightgreen.svg)](/Users/paulkorir/PycharmProjects/python-units/tests/unit/test_units.py)
 
-Python library to represent quantities with units.
+# The Price of Unitless Arithmetic
+
+On September 23, 1999, flight controllers expected NASA's Mars Climate Orbiter
+to pass behind Mars, fire its engine, and come back into radio contact after
+orbit insertion. It never came back. When engineers reviewed the final hours of
+flight data, the trajectory was not where the navigation system thought it was:
+the spacecraft had approached Mars far lower than planned. The investigation
+traced the loss to a unit boundary that software had failed to defend. One side
+of the system handled "small forces" data in English units; the navigation side
+expected metric units.
+
+That is the kind of bug this package is meant to stop. Without units, the
+mistake is just arithmetic:
+
+```python
+# A navigation routine expects impulse in newton-seconds.
+expected_impulse_ns = 120
+
+# A supplier routine accidentally sends a value in a different force unit.
+# The number is still just a number, so Python accepts it.
+reported_impulse_other_units = 120
+
+trajectory_impulse = expected_impulse_ns + reported_impulse_other_units
+print(trajectory_impulse)  # 240
+```
+
+There is nothing in `240` that tells you a spacecraft trajectory may now be
+wrong. With units attached, the mismatch stops at the boundary:
+
+```python
+from units import CustomUnitBase
+from units.dimension import DimensionSystem
+from units.si import newton, second
+
+class EnglishImpulseUnit(CustomUnitBase):
+    dimension_system = DimensionSystem("english-impulse", ("lbf_s",))
+
+pound_force_second = EnglishImpulseUnit.define("lbf_s")
+
+expected_impulse = 120 * newton * second
+reported_impulse = 120 * pound_force_second
+
+trajectory_impulse = expected_impulse + reported_impulse
+# UnitCompatibilityError: units mismatch: m·kg·s^-1 and lbf_s
+```
+
+That failure is the feature. A bug that would otherwise move through a program
+as an ordinary number is stopped before it contaminates mission-critical
+calculations.
+
+Background: NASA/JPL describe the Mars Climate Orbiter loss as a navigation
+error caused by a failure to translate English units to metric, sending the
+spacecraft too close to Mars.
+
+Source: https://en.wikipedia.org/wiki/Mars_Climate_Orbiter
+
+# About
+
+`python-units` is a Python package for unit-aware arithmetic. It provides:
+- a `Quantity` type that combines numeric values with unit information
+- a registry of SI base and derived units
+- algebraic unit manipulation and compatibility checks
+- explicit multiplicative conversions between compatible units
+- a public API that prioritizes scalar-by-unit construction and SI unit imports
+- a migration path from the legacy `Unit` constructor and compatibility helpers
+- a Python 3-only codebase with no Python 2 compatibility shims
+- a project structure that separates public API, core logic, data models, and utilities
+- comprehensive unit tests and documentation
 
 Supported Python versions: 3.10+
 
@@ -139,12 +206,18 @@ Stable top-level imports:
 
 * `Quantity`
 * `Unit` (compatibility alias for `Quantity`)
+* `convert`
+* `value`
+* `unit`
+* `multiplier`
 * `UnitsError`, `InvalidUnitError`, `InvalidValueError`,
   `UnitCompatibilityError`, `UnitOperandError`
 
 Canonical unit imports:
 
 * `from units.si import metre, second, newton`
+* prefixed and scaled units such as `kilometre`, `centimetre`, `gram`,
+  `minute`, `hour`, `kilowatt`, and `millivolt`
 
 Legacy compatibility helpers:
 
@@ -166,11 +239,119 @@ deprecated compatibility paths are scheduled for removal in `1.0.0`.
 
 * Addition and subtraction require identical units.
 * Multiplication and division combine units algebraically.
+* Explicit scale-only conversions are available through `quantity.to(unit)` and
+  `convert(quantity, unit)`.
 * Integer powers of units and unit-bearing quantities are supported.
 * Unitless quantities are supported explicitly.
+* Affine conversions, such as `degree_celcius <-> kelvin`, are intentionally not
+  implemented yet.
 * The core quantity model allows signed values. Domain-specific constraints such
   as non-negative lengths should be enforced by higher-level types or validators.
 
+# Conversion foundations
+
+`0.4.0` adds explicit multiplicative conversions. Conversion never happens
+silently during addition or subtraction; you choose the target unit.
+
+```python
+from units import convert, multiplier, unit, value
+from units.si import gram, hour, kilogram, kilometre, metre, minute, second
+
+distance = 1.5 * kilometre
+print(distance.to(metre))           # 1500 m
+print(convert(2500 * metre, kilometre))  # 2.5 km
+
+duration = 2 * hour
+print(duration.to(minute))          # 120 min
+print((1500 * gram).to(kilogram))   # 1.5 kg
+
+speed = (72 * kilometre) / (2 * hour)
+print(speed)                        # 10.0 m·s^-1
+
+print(value(distance))              # 1.5
+print(unit(distance))               # km
+print(multiplier(kilometre))        # 1000.0
+```
+
+The conversion model is scale-only in this release. Celsius is a named
+temperature unit, but converting between Celsius and kelvin requires an offset
+and is reserved for a later affine-conversion release.
+
+# Prefixed and scaled units
+
+Common SI prefixes and practical time units are available from `units.si`:
+
+```python
+from units.si import (
+    centimetre,
+    gram,
+    hour,
+    kiloampere,
+    kilometre,
+    kilovolt,
+    kilowatt,
+    megawatt,
+    micrometre,
+    microsecond,
+    milliampere,
+    milligram,
+    millimetre,
+    millisecond,
+    millivolt,
+    milliwatt,
+    minute,
+    nanometre,
+    nanosecond,
+    tonne,
+)
+```
+
+Scaled units participate correctly in multiplication, division, and powers:
+
+```python
+from units.si import hour, kilometre, metre
+
+area = (2 * kilometre) * (3 * metre)
+print(area)                         # 6000 m^2
+
+square = (2 * kilometre) ** 2
+print(square)                       # 4000000 m^2
+
+speed = (72 * kilometre) / (2 * hour)
+print(speed)                        # 10.0 m·s^-1
+```
+
+# Familiar composite units
+
+Composite unit expressions such as `kilometre / hour` are algebraic unit
+definitions. They carry the correct scale factor, but anonymous composite units
+render in canonical SI base form:
+
+```python
+from units.si import hour, kilometre
+
+speed = 30 * kilometre / hour
+print(speed)                        # 8.333333333333334 m·s^-1
+```
+
+When you want a semantically familiar display unit, give that composite unit an
+explicit name and convert to it:
+
+```python
+from units import DerivedUnit, convert
+from units.si import hour, kilometre
+
+kilometres_per_hour = DerivedUnit.define("km·hr^-1", kilometre / hour)
+
+speed = 30 * kilometre / hour
+print(convert(speed, kilometres_per_hour))  # 30 km·hr^-1
+print(30 * kilometres_per_hour)             # 30 km·hr^-1
+```
+
+This keeps the arithmetic deterministic while letting application code choose
+domain-specific display names such as `km·hr^-1`, `N·m`, or any other familiar
+derived unit form.
+
 # Real-world examples
 
 ## Electrical engineering: from resistance to power dissipation

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

@@ -1,25 +1,25 @@
 adapters/__init__.py,sha256=CSemt7d9mX9of0YQijrkQJ9FXwzXqN0TcnCeWGhXXC4,64
 api/__init__.py,sha256=EVoYM25GfHSWZnMigUDRsAnnyMnMUoeVZnlxlgQRfUI,72
-api/public.py,sha256=9iHQ3hy6S2NBAQYF9_vqLUrXlaVhSN_ibFVEZKmXjls,1759
-api/si.py,sha256=Qx-WMSia7wxd6hnuhadTtpB8jyeVH7eK-4s98rMnlyM,2242
-core/__init__.py,sha256=OjXKNa-EMmUZbVVyG4rLhoKfDl6ifZihCSmv27_XIMQ,811
+api/public.py,sha256=sNxV6ZQowrVsqYbMztx7tx_gtjfU6QG7ym9RZQVaAtE,2521
+api/si.py,sha256=kNRegHG1HI87reYFhA3C3zVzLjehVOD8yX2dBIUS7PM,4141
+core/__init__.py,sha256=f3NNOUAbLL9mECMoLLuYoEPbPYmPsP-aL3V1lzitZTA,919
 core/deprecations.py,sha256=SQf13eA5dJt78CvIKuXi3vI1bBknwEPHT3FkDWh0Xmc,1436
 core/errors.py,sha256=iwA73z53DPMPmdoGg-T_PYpyfETqbxwGpxcDYOrsxLY,609
-core/quantity.py,sha256=KbZowTitSwjudPDgx3cw-nnu4hnnLECxDG6T7vTjE9s,10058
-core/unit_definitions.py,sha256=c3vbjM5-bm-wRNG6z9qJY3b54W2U5JsQM-Vpt2QnaW4,10312
+core/quantity.py,sha256=aOJNjXfdV01MIg1KqyuJdVhyTt1sPED8kqxoLd3B4s0,17018
+core/unit_definitions.py,sha256=kdof8fIVrV6KGIsDPisEjsS7RHLKPBHXOENyvwQysJw,15887
 models/__init__.py,sha256=8-39jReNyDmbbih6K5IHeqwoWfagjXzjy7nIfJBpPMI,189
 models/dimension.py,sha256=UNlb234AaUim7iXWzc_2RZ5aZCUefZTvOGTNizoQiPc,3789
-python_units-0.3.0.dist-info/licenses/LICENSE,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+python_units-0.4.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
 units/errors.py,sha256=e24NaDCrked0wqWL4kLFLYS0Q1-VB-9QxfHzqrrkoRU,351
 units/quantity.py,sha256=hMYeiQo4EVLjg76Bx88jdNP8b_hXM6shSrXKUXBY3jA,513
 units/si.py,sha256=2wqvff8wxQP1w-fWPYolWuIeBGl942jyX8N6dQyGwDU,118
-units/unit.py,sha256=5g_azobEX4LPiO7W3n5RmpYCmZuVpZDX77Ipy9ydILk,450
+units/unit.py,sha256=r10068WecU2qrE_D8CL8CEK9_tbJvop11pL-7GBmyQU,845
 utils/__init__.py,sha256=zTkrwGlYAf6IRcS8e_9nRyACmwJO5Ni-Lwoy55K3qCw,191
 utils/numbers.py,sha256=_wzMOCoU2hOybqVcT-x__7eY6WkwHa97Ahhr9L5reQE,884
-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,,
+python_units-0.4.0.dist-info/METADATA,sha256=NE6ev6wLQzw_V0yyXeay7cNwfdOykovG0HhXpH7rZPc,13290
+python_units-0.4.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_units-0.4.0.dist-info/top_level.txt,sha256=xVEgUUcetmpTHsYk3A-xD9qAxU5S2yD0n8YW1r08tn0,46
+python_units-0.4.0.dist-info/RECORD,,

units/unit.py

@@ -1,6 +1,12 @@
 # -*- coding: utf-8 -*-
 """Compatibility exports for unit definitions."""
 
+from __future__ import annotations
+
+import sys
+from types import ModuleType
+
+from core.quantity import unit as _extract_unit
 from core.unit_definitions import (
     BaseUnit,
     CustomUnitBase,
@@ -22,3 +28,13 @@ __all__ = [
     "require_unit_instance",
     "resolve_unit",
 ]
+
+
+class _CallableUnitModule(ModuleType):
+    """Module wrapper that preserves the public ``units.unit(...)`` helper."""
+
+    def __call__(self, quantity: object) -> BaseUnit:
+        return _extract_unit(quantity)
+
+
+sys.modules[__name__].__class__ = _CallableUnitModule