unitx 0.6.1__tar.gz → 0.6.2__tar.gz

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

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.6.2] - 2026-10-18
+
+### Added
+
+- Support multiplication and division between Quantity and Factor or SymbolicConstant in both operand orders. Multiplication and right-hand division preserve the magnitude and its type, combining the exact factor with the unit's scale; left-hand division takes the reciprocal magnitude and scales the reciprocal unit. Ordinary numeric operands continue to operate on the magnitude.
+- Preserve generic magnitude types in the corresponding public type hints, with runtime and static regression coverage for exact scaling and reciprocal operations.
+
+### Changed
+
+- Combine the compact exact scale and formal units in ScaledUnit string output, grouping denominator factors into one product, such as `J⋅s/(2⋅π)`.
+- Display quantities with scaled units using the combined product and multiplication dots between adjacent numeric factors, such as `3⋅60⋅s`, without evaluating the exact scale. String output remains readable display rather than parser input; `repr()` retains reconstructible state.
+- Document exact-factor quantity arithmetic and the distinction between a symbolic expression such as `SI.h / (2 * PI)` and predefined `SI.hbar`, which continues to expose its numerical value in ordinary `J*s` units.
+
 ## [0.6.1] - 2026-10-17
 
 ### Changed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: unitx
-Version: 0.6.1
+Version: 0.6.2
 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
@@ -146,7 +146,7 @@ True
 2
 >>> double_metre = metre * Factor(2)
 >>> print(double_metre)
-2 m
+2⋅m
 >>> (3 * double_metre).to('m').value
 6
 >>> arcmin = si.deg / 60
@@ -161,6 +161,35 @@ Multiplying a `ScaledUnit` by an ordinary number also constructs a quantity,
 keeping the exact scale in its unit and preserving the supplied magnitude.
 Combining a Unit with a Quantity continues to return a Quantity.
 
+Quantities also accept `Factor` and `SymbolicConstant` operands on either side
+of multiplication or division. Multiplication and right-hand division preserve
+the magnitude and its type, combining the exact factor with the unit instead.
+Left-hand division takes the reciprocal magnitude and unit. Ordinary numeric
+operands continue to act on the magnitude: `q * 2` and `q * Factor(2)` represent
+equal physical quantities but can have different `.value` and `.unit` pairs.
+
+```pycon
+>>> from unitx.factor import PI
+>>> hbar = SI.h / (2 * PI)
+>>> print(hbar)
+6.62607015E-34 J⋅s/(2⋅π)
+>>> hbar.value == SI.h.value
+True
+>>> hbar * (2 * PI) == SI.h
+True
+>>> round(float(hbar.to('J*s').value) / 1e-34, 8)
+1.05457182
+
+```
+
+The local `hbar` above retains the exact scale, whereas predefined `SI.hbar`
+provides its numerical value in ordinary `J*s` units. `.value` is always the
+magnitude paired with `.unit`, including its exact scale. Use
+`.to('J*s').value` to evaluate the local expression in joule seconds;
+conversion involving an irrational factor evaluates it approximately.
+String output combines the scale and formal units into one product, with
+grouped denominator factors and multiplication dots between adjacent numbers.
+
 ## Conversion and arithmetic
 
 Use `.to()` to convert between units with the same physical dimensions.

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

@@ -124,7 +124,7 @@ True
 2
 >>> double_metre = metre * Factor(2)
 >>> print(double_metre)
-2 m
+2⋅m
 >>> (3 * double_metre).to('m').value
 6
 >>> arcmin = si.deg / 60
@@ -139,6 +139,35 @@ Multiplying a `ScaledUnit` by an ordinary number also constructs a quantity,
 keeping the exact scale in its unit and preserving the supplied magnitude.
 Combining a Unit with a Quantity continues to return a Quantity.
 
+Quantities also accept `Factor` and `SymbolicConstant` operands on either side
+of multiplication or division. Multiplication and right-hand division preserve
+the magnitude and its type, combining the exact factor with the unit instead.
+Left-hand division takes the reciprocal magnitude and unit. Ordinary numeric
+operands continue to act on the magnitude: `q * 2` and `q * Factor(2)` represent
+equal physical quantities but can have different `.value` and `.unit` pairs.
+
+```pycon
+>>> from unitx.factor import PI
+>>> hbar = SI.h / (2 * PI)
+>>> print(hbar)
+6.62607015E-34 J⋅s/(2⋅π)
+>>> hbar.value == SI.h.value
+True
+>>> hbar * (2 * PI) == SI.h
+True
+>>> round(float(hbar.to('J*s').value) / 1e-34, 8)
+1.05457182
+
+```
+
+The local `hbar` above retains the exact scale, whereas predefined `SI.hbar`
+provides its numerical value in ordinary `J*s` units. `.value` is always the
+magnitude paired with `.unit`, including its exact scale. Use
+`.to('J*s').value` to evaluate the local expression in joule seconds;
+conversion involving an irrational factor evaluates it approximately.
+String output combines the scale and formal units into one product, with
+grouped denominator factors and multiplication dots between adjacent numbers.
+
 ## Conversion and arithmetic
 
 Use `.to()` to convert between units with the same physical dimensions.

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

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

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

@@ -398,6 +398,10 @@ class Factor:
         """
         if not compact:
             return str(self._monomial)
+        return str(self._display_monomial())
+
+    def _display_monomial(self) -> Monomial[int | str]:
+        """Collect numeric bases for compact display, without changing exact state."""
         rational, irrational = self.decompose(rationalize_denominator=True)
         display_components: dict[int | str, Fraction] = {}
         if rational.numerator > 1:
@@ -417,7 +421,7 @@ class Factor:
             # Numeric roots use string keys to stay distinct from rational coefficients.
             # Symbol validation and Factor construction prevent collisions with symbols.
             display_components[str(base)] = exponent
-        return str(Monomial._from_dict(display_components))
+        return Monomial._from_dict(display_components)
 
     def __str__(self) -> str:
         return self.format()

{unitx-0.6.1 → unitx-0.6.2}/src/unitx/quantity.py

@@ -7,10 +7,11 @@ from fractions import Fraction
 from typing import Any, Generic, TypeVar, cast, overload
 
 from ._numerics import Fractionable, Magnitude, Number, Real, as_fraction, as_int_if_integral
+from ._unicode import DOT
 from .dimension import DIMENSIONLESS, Dimension
 from .exceptions import DimensionError
-from .factor import ONE, Factor
-from .unit import ScaledUnit, Unit
+from .factor import ONE, Factor, SymbolicConstant
+from .unit import Unit
 
 # Magnitudes are exposed read-only; operations construct new quantities.
 T = TypeVar('T', bound=Magnitude, covariant=True)
@@ -22,7 +23,9 @@ class Quantity(Generic[T]):
     Construction preserves the magnitude's type. Conversion uses Factor's
     scaling rules and can change that type. Arithmetic converts finite Decimal
     operands exactly to Fraction; other magnitudes use native arithmetic.
-    Multiplication or division by a Unit preserves the magnitude unchanged.
+    Multiplication or division by a Unit, Factor, or SymbolicConstant preserves
+    the magnitude unchanged. Exact factors are combined with the unit's scale,
+    while ordinary numeric operands participate in magnitude arithmetic.
 
     Magnitudes must be scalars whose equality returns a bool. NumPy scalars,
     arrays, and NumPy operations are not supported yet; NumPy integration is
@@ -33,9 +36,9 @@ class Quantity(Generic[T]):
     Scalar multiplication and division accept int, float, Fraction, and Decimal.
 
     Type hints preserve the magnitude type at construction and when combining
-    with a Unit. Numeric conversions and arithmetic use unions where the result
-    depends on runtime units or values. In particular, float annotations also
-    accept int inputs, which may produce Fraction after scaling. Custom
+    with a Unit or exact factor. Numeric conversions and arithmetic use unions
+    where the result depends on runtime units or values. In particular, float
+    annotations also accept int inputs, which may produce Fraction after scaling. Custom
     magnitudes retain their arithmetic protocol rather than an assumed Self.
 
     Equality and hashing retain the exact rational coefficient and the unit's
@@ -50,9 +53,9 @@ class Quantity(Generic[T]):
     Powers normalize the exponent once using as_fraction(), just as Unit does,
     and use that exponent for both the magnitude and the unit. Nonintegral
     magnitude powers use native numerical evaluation and can be approximate.
-    str() is readable display and groups units with an explicit scale in
-    parentheses without evaluating that scale. repr() uses a reconstructible
-    Unit expression.
+    str() displays the magnitude followed by the unit's exact product expression
+    without evaluating its scale. Adjacent numeric factors use a multiplication
+    dot. repr() uses a reconstructible Unit expression.
 
     >>> Quantity(1, 'm') + Quantity(50, 'cm')
     Quantity(Fraction(3, 2), Unit('m'))
@@ -106,11 +109,13 @@ class Quantity(Generic[T]):
         return f'{type(self).__name__}({self.value!r}, {self.unit!r})'
 
     def __str__(self) -> str:
-        if isinstance(self.unit, ScaledUnit) and self.unit.scale != ONE:
-            return f'{self.value} ({self.unit})'
-        if self.unit.symbol.startswith('1'):
-            return f'{self.value}{self.unit.symbol[1:]}'
-        return f'{self.value} {self.unit}'
+        unit = str(self.unit)
+        if unit == '1':
+            return str(self.value)
+        if unit.startswith('1/'):
+            return f'{self.value}{unit[1:]}'
+        separator = DOT if unit[0].isdecimal() else ' '
+        return f'{self.value}{separator}{unit}'
 
     def is_dimensionless(self) -> bool:
         return self.dimension is DIMENSIONLESS
@@ -263,7 +268,7 @@ class Quantity(Generic[T]):
         return NotImplemented
 
     @overload
-    def __mul__(self, other: Unit, /) -> Quantity[T]: ...
+    def __mul__(self, other: Unit | Factor | SymbolicConstant, /) -> Quantity[T]: ...
 
     @overload
     def __mul__(self: Quantity[int], other: Quantity[int] | int, /) -> Quantity[int]: ...
@@ -281,7 +286,7 @@ class Quantity(Generic[T]):
             quantity = cast(Quantity[Magnitude], other)
             value = cast(Magnitude, quantity._arithmetic_value)
             return Quantity(self._arithmetic_value * value, self.unit * quantity.unit)
-        if isinstance(other, Unit):
+        if isinstance(other, (Unit, Factor, SymbolicConstant)):
             return Quantity(self.value, self.unit * other)
         if isinstance(other, Fractionable):
             value = cast(Magnitude, Fraction(other) if isinstance(other, Decimal) else other)
@@ -291,7 +296,7 @@ class Quantity(Generic[T]):
     __rmul__ = __mul__
 
     @overload
-    def __truediv__(self, other: Unit, /) -> Quantity[T]: ...
+    def __truediv__(self, other: Unit | Factor | SymbolicConstant, /) -> Quantity[T]: ...
 
     @overload
     def __truediv__(self: Quantity[int], other: Quantity[int] | int, /) -> Quantity[float]: ...
@@ -309,7 +314,7 @@ class Quantity(Generic[T]):
             quantity = cast(Quantity[Magnitude], other)
             value = cast(Magnitude, quantity._arithmetic_value)
             return Quantity(self._arithmetic_value / value, self.unit / quantity.unit)
-        if isinstance(other, Unit):
+        if isinstance(other, (Unit, Factor, SymbolicConstant)):
             return Quantity(self.value, self.unit / other)
         if isinstance(other, Fractionable):
             value = cast(Magnitude, Fraction(other) if isinstance(other, Decimal) else other)
@@ -317,18 +322,22 @@ class Quantity(Generic[T]):
         return NotImplemented
 
     @overload
-    def __rtruediv__(self: Quantity[int], other: Unit | int, /) -> Quantity[float]: ...
+    def __rtruediv__(
+        self: Quantity[int], other: Unit | Factor | SymbolicConstant | int, /
+    ) -> Quantity[float]: ...
 
     @overload
     def __rtruediv__[N: Fractionable](
-        self: Quantity[N], other: Unit | Fractionable, /
+        self: Quantity[N], other: Unit | Factor | SymbolicConstant | Fractionable, /
     ) -> Quantity[Real]: ...
 
     @overload
-    def __rtruediv__(self, other: Unit | Fractionable, /) -> Quantity[Magnitude]: ...
+    def __rtruediv__(
+        self, other: Unit | Factor | SymbolicConstant | Fractionable, /
+    ) -> Quantity[Magnitude]: ...
 
     def __rtruediv__(self, other: object, /) -> Quantity[Magnitude]:
-        if isinstance(other, Unit):
+        if isinstance(other, (Unit, Factor, SymbolicConstant)):
             return Quantity(1 / self._arithmetic_value, other / self.unit)
         if isinstance(other, Fractionable):
             value = Fraction(other) if isinstance(other, Decimal) else other

{unitx-0.6.1 → unitx-0.6.2}/src/unitx/unit.py

@@ -306,7 +306,8 @@ class ScaledUnit(Unit):
     involving a ScaledUnit return ScaledUnit, even when the scale becomes one.
     Equality compares the formal product and explicit scale, so a scale of one
     compares equal to the unscaled Unit. `symbol` describes only the product;
-    str() also includes its scale, and repr() reconstructs both.
+    str() combines its compact exact scale and formal units into a single
+    product with a grouped denominator, and repr() reconstructs both.
 
     Copying and pickling preserve the formal units and exact scale. Restoring
     a unit requires its referenced unit definitions to be registered.
@@ -315,7 +316,7 @@ class ScaledUnit(Unit):
     >>> minute
     ScaledUnit('s', scale=Factor.from_dict({2: 2, 3: 1, 5: 1}))
     >>> str(minute)
-    '60 s'
+    '60⋅s'
     >>> minute == Unit('s')
     False
     """
@@ -358,9 +359,11 @@ class ScaledUnit(Unit):
     def __str__(self) -> str:
         if self.scale == ONE:
             return self.symbol
-        if self.symbol.startswith('1'):
-            return f'{self.scale}{self.symbol[1:]}'
-        return f'{self.scale} {self.symbol}'
+        components: dict[SingleUnit | int | str, Fraction] = dict(
+            self.scale._display_monomial().components()
+        )
+        components.update(self._monomial.components())
+        return str(Monomial(components))
 
     def __hash__(self) -> int:
         if self.scale == ONE:

{unitx-0.6.1 → unitx-0.6.2}/tests/test_quantity.py

@@ -38,9 +38,14 @@ def test_quantity_str(unit: str, expected: str) -> None:
 @pytest.mark.parametrize(
     ('unit', 'expected'),
     [
-        (Factor(2) * Unit(), '3 (2)'),
-        (Factor(2) / Unit('s'), '3 (2/s)'),
-        (Factor(60) * Unit('s'), '3 (60 s)'),
+        (Factor(2) * Unit(), '3⋅2'),
+        (Factor(2) / Unit('s'), '3⋅2/s'),
+        (Factor(60) * Unit('s'), '3⋅60⋅s'),
+        (Unit('J*s') / (2 * PI), '3 J⋅s/(2⋅π)'),
+        (Unit('1/s') / (2 * PI), '3/(2⋅π⋅s)'),
+        (Unit() / PI, '3/π'),
+        (PI * Unit('s'), '3 π⋅s'),
+        (Factor(12) * Unit('s'), '3⋅12⋅s'),
         (ScaledUnit(Unit(), ONE), '3'),
         (ScaledUnit(Unit('1/s'), ONE), '3/s'),
     ],
@@ -52,6 +57,54 @@ def test_quantity_scaled_str(unit: ScaledUnit, expected: str) -> None:
     assert (quantity.value, quantity.unit, quantity.unit.factor) == before
 
 
+@pytest.mark.parametrize('value', [0, -2, 2**60 + 1, 0.1, Fraction(3, 7), Decimal('1.2345'), 2j])
+@pytest.mark.parametrize('unit', [Unit('cm'), ScaledUnit('cm', PI), Unit('km/m')])
+@pytest.mark.parametrize('factor', [ONE, Factor(2), PI, 1 / (2 * PI), Factor(2) ** Fraction(1, 2)])
+def test_quantity_factor_operations(value, unit: Unit, factor) -> None:
+    quantity = Quantity(value, unit)
+    before = (repr(quantity), hash(quantity))
+    with localcontext() as context:
+        context.prec = 2
+        products = (quantity * factor, factor * quantity)
+        quotient = quantity / factor
+    for result in products:
+        assert result.value is value
+        assert result.unit == unit * factor
+        assert (result / factor).unit == unit
+        assert result == value * (unit * factor)
+    assert quotient.value is value
+    assert quotient.unit == unit / factor
+    assert (quotient * factor) == quantity
+    assert hash(quotient * factor) == hash(quantity)
+    assert {quantity: 'found'}[quotient * factor] == 'found'
+    assert (repr(quantity), hash(quantity)) == before
+
+
+@pytest.mark.parametrize('value', [2, Fraction(3, 7), Decimal('1.2345'), 2j])
+@pytest.mark.parametrize('factor', [Factor(2), PI])
+def test_quantity_factor_reciprocal(value, factor) -> None:
+    quantity = Quantity(value, ScaledUnit('cm', PI))
+    result = factor / quantity
+    reciprocal = 1 / quantity
+    assert result.value == reciprocal.value
+    assert type(result.value) is type(reciprocal.value)
+    assert result.unit == factor / quantity.unit
+    assert result == reciprocal * factor
+
+
+def test_quantity_factor_scaling() -> None:
+    quantity = Quantity(3, 'cm')
+    numeric = quantity * 2
+    exact = quantity * Factor(2)
+    assert numeric.value == 6
+    assert numeric.unit == quantity.unit
+    assert exact.value == 3
+    assert exact.unit == ScaledUnit('cm', Factor(2))
+    assert exact == numeric
+    assert hash(exact) == hash(numeric)
+    assert (exact.to('m').to(exact.unit)).value == exact.value
+
+
 def test_quantity_scaled_operations() -> None:
     minute = Factor(60) * Unit('s')
     quantity = Quantity(1, minute)

{unitx-0.6.1 → unitx-0.6.2}/tests/test_si.py

@@ -132,6 +132,11 @@ def test_si_defining_constants(attribute: str, target: str, value: str) -> None:
     assert result.value == Decimal(value)
 
 
+def test_si_hbar_value() -> None:
+    assert SI.hbar.unit == SI.h.unit
+    assert SI.hbar.value == pytest.approx(1.0545718176461565e-34, rel=1e-15, abs=0)
+
+
 @pytest.mark.parametrize(
     ('attribute', 'target'),
     [('Phi0', si.Wb), ('G0', si.S), ('RK', si.ohm), ('a0', si.m), ('lambdaC', si.m), ('Eh', si.J)],

{unitx-0.6.1 → unitx-0.6.2}/tests/test_unit.py

@@ -575,11 +575,16 @@ def test_scaled_unit_exact_power() -> None:
 @pytest.mark.parametrize(
     ('base', 'scale', 'expected'),
     [
-        ('s', Factor(60), '60 s'),
+        ('s', Factor(60), '60⋅s'),
         ('', Factor(2), '2'),
         ('1/s', Factor(2), '2/s'),
         ('1/(m*s)', Factor(2), '2/(m⋅s)'),
         ('cm', ONE, 'cm'),
+        ('J*s', 1 / (2 * PI), 'J⋅s/(2⋅π)'),
+        ('m/s', PI / 180, 'π⋅m/(180⋅s)'),
+        ('1/(m*s)', 1 / (2 * PI), '1/(2⋅π⋅m⋅s)'),
+        ('s', Factor(5040) ** Fraction(1, 2), '12⋅35¹ᐟ²⋅s'),
+        ('m^(1/2)/s', PI ** Fraction(1, 2), 'π¹ᐟ²⋅m¹ᐟ²/s'),
     ],
 )
 def test_scaled_unit_str(base: str, scale: Factor, expected: str) -> None:

{unitx-0.6.1 → unitx-0.6.2}/tests/typing/check_quantity.py

@@ -143,6 +143,19 @@ def test_quantity_unit_operations[T: Magnitude](value: T) -> Quantity[T]:
     return quantity
 
 
+def test_quantity_factor_operations[T: Magnitude](value: T) -> Quantity[T]:
+    quantity = Quantity(value, 'm')
+    for factor in (Factor(2), PI):
+        assert_type(quantity * factor, Quantity[T])
+        assert_type(factor * quantity, Quantity[T])
+        assert_type(quantity / factor, Quantity[T])
+        assert_type(factor / quantity, Quantity[Magnitude])
+        assert_type(Factor(2) / Quantity(2, 's'), Quantity[float])
+        assert_type(PI / Quantity(Decimal(2), 's'), Quantity[Real])
+    assert_type(Quantity(Decimal(2), 's') / (2 * PI), Quantity[Decimal])
+    return quantity
+
+
 def test_quantity_numeric_operations() -> None:
     integer = Quantity(1, 'm')
     rational = Quantity(Fraction(1), 'm')

{unitx-0.6.1 → unitx-0.6.2}/tests/typing/check_si.py

@@ -20,5 +20,6 @@ def test_si_unit_types() -> None:
 def test_si_constant_types() -> None:
     assert_type(SI.c, Quantity[int])
     assert_type(SI.h, Quantity[Decimal])
+    assert_type(SI.hbar, Quantity[Real])
     assert_type(SI.e, Quantity[Decimal])
     assert_type(SI.h.to(si.J * si.s), Quantity[Real])