unitful 1.0.0__py3-none-any.whl

unitful/__init__.py

@@ -0,0 +1,167 @@
+"""Public API"""
+
+# Import numpy_support to install the ndarray patch (no-op if numpy absent)
+from . import numpy_support  # noqa: F401
+from .decorators import Dim, requires, returns
+from .dimension import Dimension, dimensionless
+from .exceptions import DimensionError
+from .numpy_support import QuantityArray
+from .quantity import Quantity
+from .registry import Unit, registry
+from .serialization import from_json, to_json
+
+# All built-in unit constants are imported from units.py
+from .units import (
+    GB,
+    KB,
+    MB,
+    MJ,
+    MN,
+    MW,
+    TB,
+    B,
+    GiB,
+    # Energy
+    J,
+    # Temperature
+    K,
+    KiB,
+    MiB,
+    MPa,
+    # Force
+    N_unit,
+    # Pressure
+    Pa,
+    # Power
+    W,
+    arcmin,
+    arcsec,
+    atm,
+    bar,
+    # Data
+    bit,
+    cal,
+    cm,
+    day,
+    deg,
+    degC,
+    degF,
+    eV,
+    ft,
+    g,
+    h,
+    hp,
+    inch,
+    kcal,
+    # Mass
+    kg,
+    kJ,
+    km,
+    kN,
+    knot,
+    kPa,
+    kW,
+    kWh,
+    lb,
+    lbf,
+    ly,
+    # Length
+    m,
+    mach,
+    mg,
+    mile,
+    min,
+    mm,
+    # Speed
+    mph,
+    ms,
+    nm,
+    nmi,
+    ns,
+    oz,
+    psi,
+    # Angle
+    rad,
+    # Time
+    s,
+    stone,
+    t,
+    ug,
+    um,
+    us,
+    week,
+    yd,
+    year,
+    μg,
+    μm,
+    μs,
+)
+
+# Newton exported as N (N_unit avoids clash with the Amount dimension symbol)
+N = N_unit
+
+
+def new_dimension(name: str, symbol: str = "") -> Dimension:
+    """Register and return a new base dimension
+
+    Example::
+
+        px = new_dimension("pixel", symbol="px")
+    """
+    return registry.new_dimension(name, symbol)
+
+
+def define_unit(name: str, quantity: Quantity, symbol: str = "") -> Quantity:
+    """Register a new unit derived from an existing Quantity
+
+    Example::
+
+        define_unit("furlong", 201.168 * m)
+        define_unit("fortnight", 14 * day)
+    """
+    unit = registry.define_unit(name, quantity, symbol)
+    return Quantity(1.0, unit)
+
+
+__all__ = [
+    # Core types
+    "Quantity",
+    "QuantityArray",
+    "Dimension",
+    "dimensionless",
+    "DimensionError",
+    "Unit",
+    # Registry helpers
+    "new_dimension",
+    "define_unit",
+    # Decorators
+    "requires",
+    "returns",
+    "Dim",
+    # Serialization
+    "to_json",
+    "from_json",
+    # Length
+    "m", "km", "cm", "mm", "μm", "um", "nm",
+    "inch", "ft", "yd", "mile", "nmi", "ly",
+    # Mass
+    "kg", "g", "mg", "μg", "ug", "t", "lb", "oz", "stone",
+    # Time
+    "s", "ms", "μs", "us", "ns", "min", "h", "day", "week", "year",
+    # Temperature
+    "K", "degC", "degF",
+    # Force
+    "N", "kN", "MN", "lbf",
+    # Energy
+    "J", "kJ", "MJ", "cal", "kcal", "eV", "kWh",
+    # Power
+    "W", "kW", "MW", "hp",
+    # Pressure
+    "Pa", "kPa", "MPa", "bar", "atm", "psi",
+    # Speed
+    "mph", "knot", "mach",
+    # Data
+    "bit", "B", "KB", "MB", "GB", "TB", "KiB", "MiB", "GiB",
+    # Angle
+    "rad", "deg", "arcmin", "arcsec",
+]

unitful/decorators.py

@@ -0,0 +1,142 @@
+"""@requires and @returns decorators for dimension-safe function signatures"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import Any
+
+from .dimension import Dimension
+from .exceptions import DimensionError
+from .quantity import Quantity
+from .registry import registry
+
+
+class Dim:
+    """Declare an expected dimension from a unit expression string
+
+    Usage::
+
+        @requires(speed=Dim("m/s"), time=Dim("s"))
+        def distance_traveled(speed, time):
+            ...
+
+    The string is parsed by dividing the named units from the registry
+    """
+
+    def __init__(self, expr: str) -> None:
+        self._expr = expr
+        self._dim = _parse_dim_expr(expr)
+
+    @property
+    def dimension(self) -> Dimension:
+        return self._dim
+
+    def __repr__(self) -> str:
+        return f"Dim({self._expr!r})"
+
+
+def _parse_dim_expr(expr: str) -> Dimension:
+    """Parse an expression like 'm/s', 'm/s^2', 'kg*m/s^2' into a Dimension"""
+    # Split on '/' once: numerator * denominator^-1
+    parts = expr.split("/", 1)
+    num_dim = _parse_product(parts[0])
+    if len(parts) == 2:
+        den_dim = _parse_product(parts[1])
+        return num_dim / den_dim
+    return num_dim
+
+
+def _parse_product(expr: str) -> Dimension:
+    """Parse 'kg*m' or 'kg' or 'm^2' into a Dimension"""
+    dim = Dimension()
+    for token in expr.split("*"):
+        token = token.strip()
+        if not token:
+            continue
+        if "^" in token:
+            base, exp_str = token.split("^", 1)
+            exp = float(exp_str)
+        else:
+            base, exp = token, 1.0
+        base = base.strip()
+        try:
+            unit = registry.get(base)
+        except KeyError:
+            raise ValueError(f"Unknown unit in dimension expression: {base!r}") from None
+        dim = dim * (unit.dimension ** exp)
+    return dim
+
+
+def requires(**expected_dims: Dim) -> Callable[..., Any]:
+    """Validate that keyword arguments have the expected physical dimensions
+
+    If an argument has compatible dimensions but a different unit, it is
+    automatically converted before being passed to the function
+    """
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            import inspect
+            sig = inspect.signature(func)
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+
+            for param_name, dim_spec in expected_dims.items():
+                if param_name not in bound.arguments:
+                    continue
+                val = bound.arguments[param_name]
+                expected = dim_spec.dimension
+
+                if not isinstance(val, Quantity):
+                    raise DimensionError.bare_value(
+                        func.__name__, param_name, expected.label(), val
+                    )
+
+                got_dim = val.dimension
+                if got_dim != expected:
+                    raise DimensionError.wrong_argument(
+                        func.__name__, param_name, expected.label(), val, got_dim.label()
+                    )
+
+                # Auto-convert to the canonical SI unit for that dimension so
+                # the function receives a consistent unit.  We keep the original
+                # unit if no mismatch was detected above.
+                # (Conversion already succeeded in the dimension check.)
+                bound.arguments[param_name] = val
+
+            return func(*bound.args, **bound.kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def returns(dim_spec: Dim) -> Callable[..., Any]:
+    """Validate that the return value has the expected physical dimensions"""
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            result = func(*args, **kwargs)
+            expected = dim_spec.dimension
+
+            if not isinstance(result, Quantity):
+                # Treat bare numbers as dimensionless.
+                from .dimension import dimensionless
+                if expected != dimensionless:
+                    raise DimensionError.wrong_return(
+                        func.__name__, expected.label(), result, "dimensionless"
+                    )
+                return result
+
+            if result.dimension != expected:
+                raise DimensionError.wrong_return(
+                    func.__name__, expected.label(), result, result.dimension.label()
+                )
+            return result
+
+        return wrapper
+
+    return decorator

unitful/dimension.py

@@ -0,0 +1,160 @@
+"""Immutable exponent vector over the 7 SI base quantities"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from fractions import Fraction
+
+# Ordered base dimension symbols used throughout the library
+BASE_DIMS = ("L", "M", "T", "I", "Theta", "N", "J")
+
+# Human-readable names for error messages
+_DIM_NAMES: dict[str, str] = {
+    "L": "Length",
+    "M": "Mass",
+    "T": "Time",
+    "I": "Current",
+    "Theta": "Temperature",
+    "N": "Amount",
+    "J": "Luminosity",
+}
+
+
+class Dimension:
+    """Immutable vector of rational exponents over the SI base dimensions
+
+    Each position corresponds to L, M, T, I, Theta, N, J in that order
+    Arithmetic on Dimension objects implements the algebra of physical dimensions
+    """
+
+    __slots__ = ("_exponents",)
+
+    def __init__(self, **exponents: int | float | Fraction) -> None:
+        """Create from keyword arguments, e.g. Dimension(L=1, T=-1)"""
+        exp: dict[str, Fraction] = {}
+        for dim in BASE_DIMS:
+            val = exponents.get(dim, 0)
+            exp[dim] = Fraction(val).limit_denominator(1000)
+        self._exponents: dict[str, Fraction] = exp
+
+    @classmethod
+    def _from_dict(cls, d: dict[str, Fraction]) -> Dimension:
+        obj = object.__new__(cls)
+        obj._exponents = dict(d)
+        return obj
+
+    # --- custom dimension support ---
+
+    @classmethod
+    def custom(cls, name: str) -> Dimension:
+        """Create a dimension with a single non-standard base dimension"""
+        obj = object.__new__(cls)
+        obj._exponents = {dim: Fraction(0) for dim in BASE_DIMS}
+        obj._exponents[name] = Fraction(1)
+        return obj
+
+    # --- arithmetic ---
+
+    def __mul__(self, other: Dimension) -> Dimension:
+        keys = set(self._exponents) | set(other._exponents)
+        result = {k: self._exponents.get(k, Fraction(0)) + other._exponents.get(k, Fraction(0)) for k in keys}
+        return Dimension._from_dict(result)
+
+    def __truediv__(self, other: Dimension) -> Dimension:
+        keys = set(self._exponents) | set(other._exponents)
+        result = {k: self._exponents.get(k, Fraction(0)) - other._exponents.get(k, Fraction(0)) for k in keys}
+        return Dimension._from_dict(result)
+
+    def __pow__(self, exp: int | float | Fraction) -> Dimension:
+        f = Fraction(exp).limit_denominator(1000)
+        result = {k: v * f for k, v in self._exponents.items()}
+        return Dimension._from_dict(result)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Dimension):
+            return NotImplemented
+        keys = set(self._exponents) | set(other._exponents)
+        return all(
+            self._exponents.get(k, Fraction(0)) == other._exponents.get(k, Fraction(0))
+            for k in keys
+        )
+
+    def __hash__(self) -> int:
+        return hash(tuple(sorted((k, v) for k, v in self._exponents.items() if v != 0)))
+
+    def is_dimensionless(self) -> bool:
+        return all(v == 0 for v in self._exponents.values())
+
+    def keys(self) -> Iterator[str]:
+        return iter(self._exponents)
+
+    def __getitem__(self, key: str) -> Fraction:
+        return self._exponents.get(key, Fraction(0))
+
+    # --- display ---
+
+    def __str__(self) -> str:
+        parts = []
+        for k, v in self._exponents.items():
+            if v == 0:
+                continue
+            if v == 1:
+                parts.append(k)
+            else:
+                # Use integer display when possible
+                exp_str = str(int(v)) if v.denominator == 1 else str(v)
+                parts.append(f"{k}^{exp_str}")
+        return "*".join(parts) if parts else "dimensionless"
+
+    def __repr__(self) -> str:
+        parts = {k: v for k, v in self._exponents.items() if v != 0}
+        return f"Dimension({parts!r})"
+
+    def label(self) -> str:
+        """Human-readable label for error messages, e.g. 'Length/Time'"""
+        pos = []
+        neg = []
+        for k, v in self._exponents.items():
+            if v == 0:
+                continue
+            name = _DIM_NAMES.get(k, k)
+            if v > 0:
+                if v == 1:
+                    pos.append(name)
+                else:
+                    exp_str = str(int(v)) if v.denominator == 1 else str(v)
+                    pos.append(f"{name}^{exp_str}")
+            else:
+                abs_v = -v
+                if abs_v == 1:
+                    neg.append(name)
+                else:
+                    exp_str = str(int(abs_v)) if abs_v.denominator == 1 else str(abs_v)
+                    neg.append(f"{name}^{exp_str}")
+        if not pos and not neg:
+            return "dimensionless"
+        result = "*".join(pos) if pos else "1"
+        if neg:
+            result += "/" + "*".join(neg)
+        return result
+
+    def si_str(self) -> str:
+        """Exponent notation used in error messages, e.g. 'L^1*T^-1'"""
+        parts = []
+        for k, v in self._exponents.items():
+            if v == 0:
+                continue
+            exp_str = str(int(v)) if v.denominator == 1 else str(v)
+            parts.append(f"{k}^{exp_str}")
+        return "*".join(parts) if parts else "1"
+
+
+# Convenience singletons for the 7 SI base dimensions.
+dimensionless = Dimension()
+Length = Dimension(L=1)
+Mass = Dimension(M=1)
+Time = Dimension(T=1)
+Current = Dimension(I=1)
+Temperature = Dimension(Theta=1)
+Amount = Dimension(N=1)
+Luminosity = Dimension(J=1)

unitful/exceptions.py

@@ -0,0 +1,106 @@
+"""Exceptions raised by unitful"""
+
+from __future__ import annotations
+
+
+class DimensionError(TypeError):
+    """Raised when a dimensional operation is invalid
+
+    Provides a human-readable message describing the mismatch, including the
+    values involved and their dimensions
+    """
+
+    @classmethod
+    def incompatible(
+        cls,
+        op: str,
+        left: object,
+        right: object,
+        left_dim: str,
+        right_dim: str,
+    ) -> DimensionError:
+        """Mismatch between two operands (e.g. add/subtract)"""
+        msg = (
+            f"Cannot {op} [{left_dim}] and [{right_dim}]\n"
+            f"  left:  {left!r} -> dimensions: {left_dim}\n"
+            f"  right: {right!r} -> dimensions: {right_dim}"
+        )
+        return cls(msg)
+
+    @classmethod
+    def wrong_unit(
+        cls,
+        expected_dim: str,
+        got_dim: str,
+        got: object,
+    ) -> DimensionError:
+        """Conversion to an incompatible unit"""
+        msg = (
+            f"Cannot convert [{got_dim}] to [{expected_dim}]\n"
+            f"  value:    {got!r} -> dimensions: {got_dim}\n"
+            f"  expected: dimensions: {expected_dim}"
+        )
+        return cls(msg)
+
+    @classmethod
+    def wrong_argument(
+        cls,
+        func_name: str,
+        param: str,
+        expected_dim: str,
+        got: object,
+        got_dim: str,
+    ) -> DimensionError:
+        """Argument passed to a @requires-decorated function has wrong dimensions"""
+        msg = (
+            f"Expected [{expected_dim}], got [{got_dim}]\n"
+            f"  function:  {func_name}({param}, ...)\n"
+            f"  parameter: {param}\n"
+            f"  got:       {got!r} -> dimensions: {got_dim}\n"
+            f"  expected:  dimensions: {expected_dim}"
+        )
+        return cls(msg)
+
+    @classmethod
+    def bare_value(
+        cls,
+        func_name: str,
+        param: str,
+        expected_dim: str,
+        got: object,
+    ) -> DimensionError:
+        """A bare number was passed where a Quantity is required"""
+        msg = (
+            f"Expected [{expected_dim}], got a bare number\n"
+            f"  function:  {func_name}({param}, ...)\n"
+            f"  parameter: {param}\n"
+            f"  got:       {got!r} (no unit)\n"
+            f"  expected:  dimensions: {expected_dim}"
+        )
+        return cls(msg)
+
+    @classmethod
+    def wrong_return(
+        cls,
+        func_name: str,
+        expected_dim: str,
+        got: object,
+        got_dim: str,
+    ) -> DimensionError:
+        """Return value of a @returns-decorated function has wrong dimensions"""
+        msg = (
+            f"Return value has wrong dimensions: expected [{expected_dim}], got [{got_dim}]\n"
+            f"  function: {func_name}\n"
+            f"  got:      {got!r} -> dimensions: {got_dim}\n"
+            f"  expected: dimensions: {expected_dim}"
+        )
+        return cls(msg)
+
+    @classmethod
+    def temperature_arithmetic(cls, op: str) -> DimensionError:
+        """Arithmetic on offset temperature units is ambiguous"""
+        msg = (
+            f"Cannot {op} offset temperature quantities (degC / degF) directly.\n"
+            "  Convert to Kelvin first: q.to(K)"
+        )
+        return cls(msg)

unitful/formatting.py

@@ -0,0 +1,114 @@
+"""Formatting helpers for Quantity.__format__"""
+
+from __future__ import annotations
+
+import re
+from re import Match
+
+
+def _split_spec(format_spec: str) -> tuple[str, str]:
+    """Split '0.2f~P' into ('0.2f', 'P').  Returns ('', '') for empty spec"""
+    match = re.match(r"^([^~]*)(?:~([A-Za-z]+))?$", format_spec)
+    if not match:
+        return format_spec, ""
+    num_spec, mode = match.group(1) or "", match.group(2) or ""
+    return num_spec, mode.upper()
+
+
+def _format_number(value: float, num_spec: str) -> str:
+    """Format a bare float with a numeric format spec"""
+    if num_spec:
+        return format(value, num_spec)
+    return str(value)
+
+
+# Unicode superscript digits/signs
+_SUPERSCRIPTS = str.maketrans("0123456789+-", "\u2070\u00b9\u00b2\u00b3\u2074\u2075\u2076\u2077\u2078\u2079\u207a\u207b")
+
+
+def _to_superscript(s: str) -> str:
+    return s.translate(_SUPERSCRIPTS)
+
+
+def _unit_to_unicode(unit_str: str) -> str:
+    """Convert 'm/s^2' style unit string to Unicode superscript form"""
+    # Replace ^ followed by digits/sign with superscript chars
+    def replace_exp(m: Match[str]) -> str:
+        return _to_superscript(m.group(1))
+
+    result = re.sub(r"\^([-+]?\d+(?:/\d+)?)", replace_exp, unit_str)
+    # Replace * with middle dot (Unicode U+00B7)
+    result = result.replace("*", "\u00b7")
+    return result
+
+
+def _unit_to_latex(unit_str: str) -> str:
+    """Convert unit string to LaTeX \\mathrm notation"""
+    # Split numerator / denominator on '/'
+    if "/" in unit_str:
+        parts = unit_str.split("/", 1)
+        num = _part_to_latex(parts[0])
+        den = _part_to_latex(parts[1])
+        return rf"\frac{{{num}}}{{{den}}}"
+    return _part_to_latex(unit_str)
+
+
+def _part_to_latex(s: str) -> str:
+    tokens = s.split("*")
+    result = []
+    for tok in tokens:
+        if "^" in tok:
+            base, exp = tok.split("^", 1)
+            result.append(rf"\mathrm{{{base}}}^{{{exp}}}")
+        else:
+            result.append(rf"\mathrm{{{tok}}}")
+    return r"\," .join(result)
+
+
+def _sci_to_unicode(value: float, num_spec: str) -> str:
+    """Format value with possible scientific notation in Unicode style"""
+    formatted = _format_number(value, num_spec)
+    # Check for e-notation
+    if "e" in formatted or "E" in formatted:
+        mantissa, exp_part = re.split(r"[eE]", formatted, maxsplit=1)
+        exp_int = int(exp_part)
+        return f"{mantissa} \u00d7 10{_to_superscript(str(exp_int))}"
+    return formatted
+
+
+def format_plain(value: float, unit_str: str, num_spec: str) -> str:
+    return f"{_format_number(value, num_spec)} {unit_str}"
+
+
+def format_unicode(value: float, unit_str: str, num_spec: str) -> str:
+    num_part = _sci_to_unicode(value, num_spec)
+    unit_part = _unit_to_unicode(unit_str)
+    return f"{num_part} {unit_part}"
+
+
+def format_latex(value: float, unit_str: str, num_spec: str) -> str:
+    formatted = _format_number(value, num_spec)
+    if "e" in formatted or "E" in formatted:
+        mantissa, exp_part = re.split(r"[eE]", formatted, maxsplit=1)
+        exp_int = int(exp_part)
+        num_part = rf"{mantissa} \times 10^{{{exp_int}}}"
+    else:
+        num_part = formatted
+    unit_part = _unit_to_latex(unit_str)
+    return rf"{num_part}\,{unit_part}"
+
+
+def format_html(value: float, unit_str: str, num_spec: str) -> str:
+    inner = format_unicode(value, unit_str, num_spec)
+    return f"<span>{inner}</span>"
+
+
+def apply_format(value: float, unit_str: str, format_spec: str) -> str:
+    num_spec, mode = _split_spec(format_spec)
+    if mode == "P":
+        return format_unicode(value, unit_str, num_spec)
+    if mode == "L":
+        return format_latex(value, unit_str, num_spec)
+    if mode == "H":
+        return format_html(value, unit_str, num_spec)
+    return format_plain(value, unit_str, num_spec)