unitx 0.6.2__tar.gz → 0.6.3__tar.gz

{unitx-0.6.2 → unitx-0.6.3}/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [0.6.3] - 2026-10-18
+
+### Added
+
+- Add `Quantity.value_in(unit)` to return the same magnitude and concrete type as `.to(unit).value` without constructing a temporary quantity. The target unit is required and accepts a string or Unit, including ScaledUnit.
+- Add `Quantity.isclose()` for symmetric real scalar comparisons with relative and absolute tolerances in coherent SI units. Nonzero absolute tolerances for dimensional quantities must carry matching units. Rational coefficients remain exact; residual irrational factors are approximated. Zero tolerances use exact equality.
+- Make quantity truth values follow their magnitudes, so zero quantities are false regardless of unit.
+
+### Changed
+
+- Apply native magnitude operators in operand order for arithmetic, unary operations, and numerical powers, preserving numerical promotion, Decimal contexts, signals, and exceptions. Support the scalar operand types accepted by the magnitude, including complex values and custom scalars.
+- Keep Decimal conversions and arithmetic in Decimal. Rational conversions combine the magnitude and scale exactly before rounding once in the active context; identity conversions preserve the original magnitude. Addition and subtraction align integer operands in the Decimal domain when paired with Decimal magnitudes. Derived SI constants use Decimal arithmetic and `Decimal(str(math.pi))` where an approximate pi is required, with evaluation in the context active at import.
+- Interpret float formal exponents by their shortest decimal text, without a denominator limit, consistently across Monomial, Dimension, Factor, SymbolicConstant, Unit, and Quantity. For example, `0.1` represents `1/10` and `1e-10` remains nonzero. Numeric scale inputs to Factor retain their existing denominator-limit and warning rules.
+- Cache rationalized Factor decompositions lazily, independently of numerical value evaluation, while preserving equality, hashing, copying, and serialization.
+- Update public type hints, examples, and regression coverage for conversion, native arithmetic, comparisons, and formal exponents.
+
+### Fixed
+
+- Preserve native comparisons, including independent `!=`, Decimal signals, and complex ordering errors, when unit factors agree. Across different factors, compare builtin real values and complex components using exact coefficients, retaining consistent hashes for equal quantities and native unhashability for custom magnitudes.
+
+### Migration
+
+- Decimal arithmetic no longer converts operands to Fraction automatically. Mixing Decimal with float or Fraction in arithmetic now raises the native TypeError; explicitly choose a common numerical type when needed. Decimal conversion and derived SI constants can therefore have different result types and rounding from earlier releases.
+- Quantity numerical powers use the original exponent object; for example, an integer magnitude raised to `2.0` produces a float. Use `Fraction(1, 3)` for an exactly one-third formal exponent: the float `1 / 3` now represents the decimal `0.3333333333333333` and does not simplify as exactly one third.
+
 ## [0.6.2] - 2026-10-18
 
 ### Added

{unitx-0.6.2 → unitx-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: unitx
-Version: 0.6.2
+Version: 0.6.3
 Summary: A modern, intuitive Python library for units, quantities, and dimensional analysis.
 Project-URL: Homepage, https://github.com/DaitTHU/unitx
 Project-URL: Issues, https://github.com/DaitTHU/unitx/issues
@@ -107,8 +107,9 @@ text spellings without adding an attribute to `si`.
 
 SI defining constants retain their exact decimal values. Measured constants
 are stored nominal values; measurement uncertainties are not propagated.
-Derived constants involving numerical approximations, such as `math.pi`, are
-evaluated numerically.
+Derived Decimal constants are evaluated in the Decimal context active at
+import. Formulas involving pi use `Decimal(str(math.pi))` as an approximation;
+additional Decimal precision does not add precision to pi.
 
 ## Constructing units and quantities
 
@@ -192,16 +193,23 @@ grouped denominator factors and multiplication dots between adjacent numbers.
 
 ## Conversion and arithmetic
 
-Use `.to()` to convert between units with the same physical dimensions.
+Use `.to()` to obtain a new quantity in a unit with the same physical dimensions,
+or `.value_in(unit)` to obtain only its numerical value. The target unit is
+required and accepts a string or `Unit`, including `ScaledUnit`.
+`.value_in(unit)` returns the same value and concrete type as `.to(unit).value`,
+without constructing a temporary quantity. Both follow the conversion rules
+below. A conversion with scale one preserves the original magnitude; Decimal
+magnitudes stay Decimal and other conversions can change the numerical type.
+`.value` reads the original stored magnitude.
 Addition and subtraction convert the right operand to the left operand's unit:
 
 ```pycon
 >>> length = Quantity(1, 'm')
 >>> print(length + Quantity(50, 'cm'))
 3/2 m
->>> length.to('cm').value
+>>> length.value_in('cm')
 100
->>> Quantity(1, 'cm').to('m').value
+>>> Quantity(1, 'cm').value_in('m')
 Fraction(1, 100)
 
 ```
@@ -368,29 +376,90 @@ Fraction(1001, 1)
 
 Exact unit algebra and numerical magnitude evaluation have different rules:
 
-- Rational unit scales and exponents remain exact. Prefer `Fraction` or
-  `Decimal` for exact exponents; float exponents may be approximated with an
-  `InexactFloatWarning`.
-- Conversion and arithmetic can change the magnitude's type. Finite `Decimal`
-  operands are converted exactly to `Fraction`, without Decimal context
-  rounding.
-- Other magnitudes use native numerical arithmetic. In particular, integer
-  division produces a float, and nonintegral magnitude powers can round or
-  produce complex values.
+- Formal exponents use one rule in Monomial, Dimension, Factor, Unit, and
+  Quantity: int/Fraction/Decimal values stay exact; floats use their shortest
+  decimal text without a denominator limit. Thus `0.1` means `1/10` and
+  `1e-10` remains nonzero. Use `Fraction(1, 3)` for exactly one third:
+  the float `1 / 3` means the decimal `0.3333333333333333` in formal exponents.
+  Factor's numeric scale inputs retain their separate denominator-limit rules.
+- Quantity handles units; the magnitudes determine numerical arithmetic.
+  Operators use the magnitudes in operand order and preserve native promotion,
+  rounding, signals, and exceptions. Decimal arithmetic returns Decimal and
+  follows its active context. Mixing Decimal with float or Fraction raises
+  `TypeError`, as it does for the bare numbers; choose a common numerical type
+  explicitly when needed.
+- Conversion with a rational scale keeps int/Fraction values exact. Decimal
+  conversion combines the value and scale exactly internally, then rounds once
+  to Decimal in the active context. Irrational unit scales are approximated as
+  floats, using their shortest decimal representations for Decimal conversion.
+  A scale of one preserves the magnitude without arithmetic or rounding.
+  Direct `Factor(value)` retains its separate exact Fraction evaluation rules.
+- Addition and subtraction align the right operand with the left quantity's
+  unit before numerical arithmetic. Integers being aligned with a Decimal
+  magnitude are scaled in the Decimal domain, so `Decimal('1') * si.m + 50 *
+  si.cm` returns a Decimal magnitude of `1.5`. Explicit Fraction/float operands
+  keep their own numerical domains. Finite-precision conversion and arithmetic
+  can round; changing the result unit can therefore change rounding errors.
+- Unary `+` and `-` apply the magnitude's native operators and preserve the unit.
+  Decimal results remain Decimal and follow its context precision, rounding,
+  signals, and exceptions; unary `+` can therefore change the numerical value.
+- Integer division produces a float; Fraction arithmetic remains rational.
+  Use Fraction magnitudes explicitly for exact rational results. Powers pass
+  the original exponent to the magnitude: `2 ** 2.0` returns float and
+  `2 ** Decimal('0.5')` returns Decimal. Decimal magnitudes require int or
+  Decimal exponents, as in Python. The unit follows the common formal exponent
+  rule above; numerical evaluation still uses the original exponent object.
+  Exponents must be finite real scalars other than bool. Numerical powers can
+  round or produce complex values, following the magnitude's rules.
+- Truth values follow the magnitude, so zero quantities are false regardless
+  of unit. Comparisons with equal unit factors use native magnitude operators,
+  including independent `!=`, Decimal signals/exceptions and complex ordering
+  errors. For different unit factors, builtin real values and complex
+  components are aligned exactly to avoid rounding-dependent equality or
+  hashes. Ordinary numeric subclasses use the same alignment as their base
+  types. Decimal/float signals apply to native comparisons with equal factors;
+  cross-factor alignment compares exact rational coefficients and does not
+  perform an additional comparison merely to reproduce signals. Decimal/Fraction
+  comparisons are supported natively.
 - Equality is exact, without a tolerance. Finite floats are compared as their
   stored binary rational values. Floating-point conversions and irrational
-  powers may round; compare their values approximately in a common unit when
-  appropriate.
+  powers may round; use `isclose()` for approximate real scalar comparisons.
+  It uses the symmetric condition
+  `abs(a - b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)` in coherent SI
+  units, with defaults `rel_tol=1e-9` and `abs_tol=0`. Swapping quantities
+  preserves the result. Nonzero absolute tolerances for dimensional quantities
+  must carry matching units; plain operands and plain absolute tolerances
+  represent unscaled dimensionless values. Tolerances must be finite and
+  nonnegative. Different dimensions raise `DimensionError`. NaNs are never
+  close, and infinities are close only to infinities of the same sign.
+  Finite rational coefficients stay exact; residual irrational unit factors
+  are approximated. With both tolerances zero, `isclose()` uses exact equality.
 
 ```pycon
->>> from decimal import Decimal
+>>> from decimal import Decimal, localcontext
 >>> from fractions import Fraction
+>>> with localcontext() as context:
+...     context.prec = 2
+...     q = Quantity(Decimal('1.2345'), 'm')
+...     print((+q).value, (-q).value, (q * 2).value)
+1.2 -1.2 2.5
 >>> Quantity(Decimal('0.1'), 'm').to('cm').value
-10
+Decimal('10')
 >>> (Quantity(Fraction(1), 'm') / Quantity(3, 's')).value
 Fraction(1, 3)
+>>> (Quantity(2, 'm') ** 2.0).value
+4.0
+>>> bool(Quantity(0, 'm'))
+False
 >>> Quantity(0.1, '') == Quantity(Fraction(1, 10), '')
 False
+>>> Quantity(0.1 + 0.2, 'm').isclose(Quantity(0.3, 'm'))
+True
+>>> a, b = Quantity(1, 'm'), Quantity(100.05, 'cm')
+>>> a.isclose(b, rel_tol=0, abs_tol=Quantity(1, 'mm'))
+True
+>>> b.isclose(a, rel_tol=0, abs_tol=Quantity(1, 'mm'))
+True
 
 ```
 
@@ -410,9 +479,10 @@ python -m pip install sympy
 - Custom magnitudes must support scalar arithmetic, return a Python `bool`
   from equality, and defer raw operations with `Unit` operands to its reflected
   operators.
-- Scalar multiplication and division of quantities currently accept `int`,
-  `float`, `Fraction`, and `Decimal`. Complex magnitudes are supported, including
-  results of fractional powers; ordering follows the magnitude's native rules.
+- Scalar operations use the magnitude's supported operand types, including
+  complex numbers and custom scalar magnitudes. Custom magnitudes must also
+  defer operations with Quantity operands so that Quantity can handle units.
+  Ordering follows the magnitude's native rules.
 - Unit conversion is multiplicative. Offset temperature scales such as Celsius
   and Fahrenheit are not supported.
 

{unitx-0.6.2 → unitx-0.6.3}/README.md

@@ -85,8 +85,9 @@ text spellings without adding an attribute to `si`.
 
 SI defining constants retain their exact decimal values. Measured constants
 are stored nominal values; measurement uncertainties are not propagated.
-Derived constants involving numerical approximations, such as `math.pi`, are
-evaluated numerically.
+Derived Decimal constants are evaluated in the Decimal context active at
+import. Formulas involving pi use `Decimal(str(math.pi))` as an approximation;
+additional Decimal precision does not add precision to pi.
 
 ## Constructing units and quantities
 
@@ -170,16 +171,23 @@ grouped denominator factors and multiplication dots between adjacent numbers.
 
 ## Conversion and arithmetic
 
-Use `.to()` to convert between units with the same physical dimensions.
+Use `.to()` to obtain a new quantity in a unit with the same physical dimensions,
+or `.value_in(unit)` to obtain only its numerical value. The target unit is
+required and accepts a string or `Unit`, including `ScaledUnit`.
+`.value_in(unit)` returns the same value and concrete type as `.to(unit).value`,
+without constructing a temporary quantity. Both follow the conversion rules
+below. A conversion with scale one preserves the original magnitude; Decimal
+magnitudes stay Decimal and other conversions can change the numerical type.
+`.value` reads the original stored magnitude.
 Addition and subtraction convert the right operand to the left operand's unit:
 
 ```pycon
 >>> length = Quantity(1, 'm')
 >>> print(length + Quantity(50, 'cm'))
 3/2 m
->>> length.to('cm').value
+>>> length.value_in('cm')
 100
->>> Quantity(1, 'cm').to('m').value
+>>> Quantity(1, 'cm').value_in('m')
 Fraction(1, 100)
 
 ```
@@ -346,29 +354,90 @@ Fraction(1001, 1)
 
 Exact unit algebra and numerical magnitude evaluation have different rules:
 
-- Rational unit scales and exponents remain exact. Prefer `Fraction` or
-  `Decimal` for exact exponents; float exponents may be approximated with an
-  `InexactFloatWarning`.
-- Conversion and arithmetic can change the magnitude's type. Finite `Decimal`
-  operands are converted exactly to `Fraction`, without Decimal context
-  rounding.
-- Other magnitudes use native numerical arithmetic. In particular, integer
-  division produces a float, and nonintegral magnitude powers can round or
-  produce complex values.
+- Formal exponents use one rule in Monomial, Dimension, Factor, Unit, and
+  Quantity: int/Fraction/Decimal values stay exact; floats use their shortest
+  decimal text without a denominator limit. Thus `0.1` means `1/10` and
+  `1e-10` remains nonzero. Use `Fraction(1, 3)` for exactly one third:
+  the float `1 / 3` means the decimal `0.3333333333333333` in formal exponents.
+  Factor's numeric scale inputs retain their separate denominator-limit rules.
+- Quantity handles units; the magnitudes determine numerical arithmetic.
+  Operators use the magnitudes in operand order and preserve native promotion,
+  rounding, signals, and exceptions. Decimal arithmetic returns Decimal and
+  follows its active context. Mixing Decimal with float or Fraction raises
+  `TypeError`, as it does for the bare numbers; choose a common numerical type
+  explicitly when needed.
+- Conversion with a rational scale keeps int/Fraction values exact. Decimal
+  conversion combines the value and scale exactly internally, then rounds once
+  to Decimal in the active context. Irrational unit scales are approximated as
+  floats, using their shortest decimal representations for Decimal conversion.
+  A scale of one preserves the magnitude without arithmetic or rounding.
+  Direct `Factor(value)` retains its separate exact Fraction evaluation rules.
+- Addition and subtraction align the right operand with the left quantity's
+  unit before numerical arithmetic. Integers being aligned with a Decimal
+  magnitude are scaled in the Decimal domain, so `Decimal('1') * si.m + 50 *
+  si.cm` returns a Decimal magnitude of `1.5`. Explicit Fraction/float operands
+  keep their own numerical domains. Finite-precision conversion and arithmetic
+  can round; changing the result unit can therefore change rounding errors.
+- Unary `+` and `-` apply the magnitude's native operators and preserve the unit.
+  Decimal results remain Decimal and follow its context precision, rounding,
+  signals, and exceptions; unary `+` can therefore change the numerical value.
+- Integer division produces a float; Fraction arithmetic remains rational.
+  Use Fraction magnitudes explicitly for exact rational results. Powers pass
+  the original exponent to the magnitude: `2 ** 2.0` returns float and
+  `2 ** Decimal('0.5')` returns Decimal. Decimal magnitudes require int or
+  Decimal exponents, as in Python. The unit follows the common formal exponent
+  rule above; numerical evaluation still uses the original exponent object.
+  Exponents must be finite real scalars other than bool. Numerical powers can
+  round or produce complex values, following the magnitude's rules.
+- Truth values follow the magnitude, so zero quantities are false regardless
+  of unit. Comparisons with equal unit factors use native magnitude operators,
+  including independent `!=`, Decimal signals/exceptions and complex ordering
+  errors. For different unit factors, builtin real values and complex
+  components are aligned exactly to avoid rounding-dependent equality or
+  hashes. Ordinary numeric subclasses use the same alignment as their base
+  types. Decimal/float signals apply to native comparisons with equal factors;
+  cross-factor alignment compares exact rational coefficients and does not
+  perform an additional comparison merely to reproduce signals. Decimal/Fraction
+  comparisons are supported natively.
 - Equality is exact, without a tolerance. Finite floats are compared as their
   stored binary rational values. Floating-point conversions and irrational
-  powers may round; compare their values approximately in a common unit when
-  appropriate.
+  powers may round; use `isclose()` for approximate real scalar comparisons.
+  It uses the symmetric condition
+  `abs(a - b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)` in coherent SI
+  units, with defaults `rel_tol=1e-9` and `abs_tol=0`. Swapping quantities
+  preserves the result. Nonzero absolute tolerances for dimensional quantities
+  must carry matching units; plain operands and plain absolute tolerances
+  represent unscaled dimensionless values. Tolerances must be finite and
+  nonnegative. Different dimensions raise `DimensionError`. NaNs are never
+  close, and infinities are close only to infinities of the same sign.
+  Finite rational coefficients stay exact; residual irrational unit factors
+  are approximated. With both tolerances zero, `isclose()` uses exact equality.
 
 ```pycon
->>> from decimal import Decimal
+>>> from decimal import Decimal, localcontext
 >>> from fractions import Fraction
+>>> with localcontext() as context:
+...     context.prec = 2
+...     q = Quantity(Decimal('1.2345'), 'm')
+...     print((+q).value, (-q).value, (q * 2).value)
+1.2 -1.2 2.5
 >>> Quantity(Decimal('0.1'), 'm').to('cm').value
-10
+Decimal('10')
 >>> (Quantity(Fraction(1), 'm') / Quantity(3, 's')).value
 Fraction(1, 3)
+>>> (Quantity(2, 'm') ** 2.0).value
+4.0
+>>> bool(Quantity(0, 'm'))
+False
 >>> Quantity(0.1, '') == Quantity(Fraction(1, 10), '')
 False
+>>> Quantity(0.1 + 0.2, 'm').isclose(Quantity(0.3, 'm'))
+True
+>>> a, b = Quantity(1, 'm'), Quantity(100.05, 'cm')
+>>> a.isclose(b, rel_tol=0, abs_tol=Quantity(1, 'mm'))
+True
+>>> b.isclose(a, rel_tol=0, abs_tol=Quantity(1, 'mm'))
+True
 
 ```
 
@@ -388,9 +457,10 @@ python -m pip install sympy
 - Custom magnitudes must support scalar arithmetic, return a Python `bool`
   from equality, and defer raw operations with `Unit` operands to its reflected
   operators.
-- Scalar multiplication and division of quantities currently accept `int`,
-  `float`, `Fraction`, and `Decimal`. Complex magnitudes are supported, including
-  results of fractional powers; ordering follows the magnitude's native rules.
+- Scalar operations use the magnitude's supported operand types, including
+  complex numbers and custom scalar magnitudes. Custom magnitudes must also
+  defer operations with Quantity operands so that Quantity can handle units.
+  Ordering follows the magnitude's native rules.
 - Unit conversion is multiplicative. Offset temperature scales such as Celsius
   and Fahrenheit are not supported.
 

{unitx-0.6.2 → unitx-0.6.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = 'hatchling.build'
 
 [project]
 name = 'unitx'
-version = '0.6.2'
+version = '0.6.3'
 description = 'A modern, intuitive Python library for units, quantities, and dimensional analysis.'
 readme = 'README.md'
 requires-python = '>=3.12'

{unitx-0.6.2 → unitx-0.6.3}/src/unitx/_numerics.py

@@ -39,17 +39,18 @@ class Magnitude(Protocol):
     can produce complex values. NumPy scalars, arrays, and operation dispatch
     are not supported yet; NumPy integration is planned.
 
-    Forward multiplication and division have an unspecified operand domain at
+    Forward binary arithmetic has an unspecified operand domain at
     this protocol boundary. `Never` lets concrete numeric methods satisfy the
     protocol without claiming that they accept every operand. In particular,
-    raw magnitudes must defer Unit operands to Unit's reflected operators,
-    which construct quantities and preserve the magnitude's type.
+    raw magnitudes must defer Unit operands to Unit's reflected multiplication
+    and division, which construct quantities and preserve the magnitude's type.
+    They must also defer Quantity operands so that Quantity can handle units.
     """
 
     def __pos__(self, /) -> Magnitude: ...
     def __neg__(self, /) -> Magnitude: ...
-    def __add__(self, other: Any, /) -> Magnitude: ...
-    def __sub__(self, other: Any, /) -> Magnitude: ...
+    def __add__(self, other: Never, /) -> Magnitude: ...
+    def __sub__(self, other: Never, /) -> Magnitude: ...
     def __mul__(self, other: Never, /) -> Magnitude: ...
     def __truediv__(self, other: Never, /) -> Magnitude: ...
     def __pow__(self, other: Any, /) -> Magnitude: ...
@@ -120,6 +121,16 @@ def as_int_if_integral(value: Fraction, /) -> int | Fraction:
     return value.numerator if value.denominator == 1 else value
 
 
+def as_exponent(value: Fractionable, /) -> Fraction:
+    """Normalize formal exponents; floats use their shortest decimal text."""
+    if not isinstance(value, Fractionable) or isinstance(value, bool):
+        raise TypeError(f'Cannot convert {type(value).__name__} to Fraction.')
+    # Nonfinite floats still use Fraction's standard ValueError/OverflowError.
+    return Fraction(
+        str(float(value)) if isinstance(value, float) and math.isfinite(value) else value
+    )
+
+
 # Number theory functions: prime factorization and primality testing.
 # These are implemented here to avoid a dependency on `sympy`.
 # However, the implementation is limited and may not be as efficient or

{unitx-0.6.2 → unitx-0.6.3}/src/unitx/dimension.py

@@ -4,7 +4,7 @@ from collections.abc import Iterable
 from fractions import Fraction
 from typing import Literal
 
-from ._numerics import Fractionable, as_fraction, as_int_if_integral
+from ._numerics import Fractionable, as_exponent, as_int_if_integral
 from ._unicode import superscript
 
 __all__ = ['DIMENSIONLESS', 'Dimension']
@@ -26,7 +26,8 @@ class Dimension:
     - `J`: luminous
 
     Zero exponents represent the `DIMENSIONLESS` singleton. Use Fraction or
-    Decimal for exact exponents; floats may be approximated with a warning.
+    Decimal for exact exponents; floats use their shortest decimal text,
+    without a denominator limit, consistently with Monomial, Factor, and Unit.
 
     >>> dim_velocity = Dimension(L=1, T=-1)
     >>> dim_force = Dimension(M=1, L=1, T=-2)
@@ -58,7 +59,7 @@ class Dimension:
         N: Fractionable = 0,
         J: Fractionable = 0,
     ) -> Dimension:
-        exponents = tuple(as_fraction(exp) for exp in (T, L, M, I, Theta, N, J))
+        exponents = tuple(as_exponent(exp) for exp in (T, L, M, I, Theta, N, J))
         if not any(exponents):
             return DIMENSIONLESS
         obj = object.__new__(cls)
@@ -125,7 +126,7 @@ class Dimension:
         return self._from_iter(a - b for a, b in zip(self._exponents, other._exponents))
 
     def __pow__(self, power: Fractionable) -> Dimension:
-        power_as_fraction = as_fraction(power)
+        power_as_fraction = as_exponent(power)
         return self._from_iter(exp * power_as_fraction for exp in self._exponents)
 
     def __rtruediv__(self, other: Literal[1]) -> Dimension:

{unitx-0.6.2 → unitx-0.6.3}/src/unitx/factor.py

@@ -9,7 +9,14 @@ from decimal import MAX_EMAX, MIN_EMIN, Context, Decimal, Overflow, localcontext
 from fractions import Fraction
 from typing import Any, overload
 
-from ._numerics import Fractionable, Magnitude, UnfactoredInteger, as_fraction, as_int_if_integral
+from ._numerics import (
+    Fractionable,
+    Magnitude,
+    UnfactoredInteger,
+    as_exponent,
+    as_fraction,
+    as_int_if_integral,
+)
 from .exceptions import _WARNING_SKIP_PREFIXES, IncompleteFactorWarning
 from .monomial import Monomial
 
@@ -162,7 +169,7 @@ class SymbolicConstant:
     def __pow__(self, other: Fractionable) -> Factor:
         if not isinstance(other, Fractionable):
             return NotImplemented
-        return Factor._from_monomial(Monomial({self: as_fraction(other)}))
+        return Factor._from_monomial(Monomial({self: as_exponent(other)}))
 
     @property
     def symbol(self) -> str:
@@ -198,11 +205,13 @@ class Factor:
     and classification may be incomplete, and equivalent expressions may compare
     unequal. Install SymPy for more complete support.
 
-    Construction and arithmetic convert float inputs and exponents to Fractions
-    with denominators at most 1,000,000. Inexact conversions emit
-    InexactFloatWarning. Small positive floats can round to zero and fail the
-    positivity check: Factor(1e-10) warns and raises ValueError. Use Decimal or
-    Fraction for exact inputs and exponents.
+    Construction and ordinary multiplication/division convert float scales to
+    Fractions with denominators at most 1,000,000. Inexact conversions emit
+    InexactFloatWarning. Small positive float scales can round to zero and fail
+    the positivity check: Factor(1e-10) warns and raises ValueError. Use Decimal
+    or Fraction for exact scales. Exponents, including from_dict(), instead use
+    a float's shortest decimal text without a denominator limit, consistently
+    with Monomial, Dimension, and Unit. Use Fraction(1, 3) for exactly one third.
 
     Factor equality compares stored bases and exponents. Numeric operands are
     compared as exact rational values, including the stored value of floats.
@@ -226,11 +235,13 @@ class Factor:
     Fraction(127, 50)
     """
 
-    __slots__ = ('_monomial', '_value_cache')
+    __slots__ = ('_monomial', '_value_cache', '_decompose_cache')
     _monomial: Monomial[int | SymbolicConstant]
     _value_cache: int | Fraction | float | None
+    _decompose_cache: tuple[Fraction, Factor] | None
 
     def __init__(self, value: Fractionable | SymbolicConstant, /) -> None:
+        self._decompose_cache = None
         if isinstance(value, SymbolicConstant):
             self._monomial = Monomial({value: 1})
             self._value_cache = float(value)
@@ -264,6 +275,7 @@ class Factor:
         obj = object.__new__(cls)
         obj._monomial = monomial
         obj._value_cache = None
+        obj._decompose_cache = None
         return obj
 
     @classmethod
@@ -279,7 +291,7 @@ class Factor:
             raise TypeError(error_message)
         normalized: dict[int | SymbolicConstant, Fraction] = {}
         for base, exponent in components.items():
-            normalized[base] = as_fraction(exponent)
+            normalized[base] = as_exponent(exponent)
         monomial = Monomial(normalized)
         if not all(isinstance(base, (int, SymbolicConstant)) for base in monomial.bases()):
             raise TypeError('All bases must be int or SymbolicConstant.')
@@ -317,6 +329,8 @@ class Factor:
         The rational part is a Fraction, and the irrational part is a Factor
         containing only SymbolicConstant bases and integer bases with *proper*
         fraction exponents. The product of the two parts equals the original factor.
+        Rationalized decompositions are cached lazily on this factor; default
+        decompositions are computed on each call, independently of the value cache.
 
         Parameters
         ----------
@@ -337,6 +351,8 @@ class Factor:
         >>> (Factor(2) ** Fraction(-3, 2)).decompose(rationalize_denominator=True)
         (Fraction(1, 4), Factor.from_dict({2: Fraction(1, 2)}))
         """
+        if rationalize_denominator and self._decompose_cache is not None:
+            return self._decompose_cache
         rational = Fraction(1)
         irrational: dict[int | SymbolicConstant, Fraction] = {}
         for base, exponent in self._monomial.components():
@@ -348,7 +364,10 @@ class Factor:
                 integer_part = math.floor(exponent) if rationalize_denominator else int(exponent)
                 rational *= Fraction(base) ** integer_part
                 irrational[base] = exponent - integer_part
-        return rational, Factor._from_monomial(Monomial._from_dict(irrational))
+        result = rational, Factor._from_monomial(Monomial._from_dict(irrational))
+        if rationalize_denominator:
+            self._decompose_cache = result
+        return result
 
     @property
     def value(self) -> int | Fraction | float:
@@ -490,7 +509,7 @@ class Factor:
         return NotImplemented
 
     def __pow__(self, other: Fractionable) -> Factor:
-        return Factor._from_monomial(self._monomial ** as_fraction(other))
+        return Factor._from_monomial(self._monomial ** as_exponent(other))
 
     @overload
     def __call__(self, magnitude: Fraction) -> Fraction | float: ...

{unitx-0.6.2 → unitx-0.6.3}/src/unitx/monomial.py

@@ -5,7 +5,7 @@ from fractions import Fraction
 from types import MappingProxyType
 from typing import Generic, Literal, TypeVar
 
-from ._numerics import Fractionable, as_fraction
+from ._numerics import Fractionable, as_exponent
 from ._unicode import DOT, superscript
 
 __all__ = ['Monomial']
@@ -31,8 +31,8 @@ class Monomial(Generic[BaseT]):
     components : Mapping[BaseT, Fractionable], optional
         Bases and exponents. The mapping is copied and zero exponents are
         removed. Defaults to an empty monomial. Use int, Fraction, or Decimal
-        for exact exponents. Float exponents may be approximated with an
-        `InexactFloatWarning`.
+        for exact exponents. Float exponents use their shortest decimal text,
+        so 0.1 means Fraction(1, 10); no denominator limit is applied.
 
     Notes
     -----
@@ -76,7 +76,7 @@ class Monomial(Generic[BaseT]):
             raise TypeError(error_message)
         normalized: dict[BaseT, Fraction] = {}
         for base, exp in components.items():
-            if exponent := as_fraction(exp):
+            if exponent := as_exponent(exp):
                 normalized[base] = exponent
         obj = super().__new__(cls)
         object.__setattr__(obj, '_components', MappingProxyType(normalized))
@@ -193,7 +193,7 @@ class Monomial(Generic[BaseT]):
     def __pow__(self, other: Fractionable) -> Monomial[BaseT]:
         if not isinstance(other, Fractionable):
             return NotImplemented
-        other_as_fraction = as_fraction(other)
+        other_as_fraction = as_exponent(other)
         if other_as_fraction == 0:
             return self._from_dict({})
         return self._from_dict({base: exp * other_as_fraction for base, exp in self.components()})