ucon 0.3.4__py3-none-any.whl → 0.3.5__py3-none-any.whl

tests/ucon/__init__.py

@@ -0,0 +1,3 @@
+# © 2025 The Radiativity Company
+# Licensed under the Apache License, Version 2.0
+# See the LICENSE file for details.

tests/ucon/test_algebra.py

@@ -1,4 +1,6 @@
-
+# © 2025 The Radiativity Company
+# Licensed under the Apache License, Version 2.0
+# See the LICENSE file for details.
 
 import math
 from unittest import TestCase

tests/ucon/test_core.py

@@ -1,3 +1,7 @@
+# © 2025 The Radiativity Company
+# Licensed under the Apache License, Version 2.0
+# See the LICENSE file for details.
+
 import math
 import unittest
 
@@ -9,7 +13,7 @@ from ucon import Dimension
 from ucon import Unit
 from ucon import units
 from ucon.algebra import Vector
-from ucon.core import CompositeUnit, ScaleDescriptor
+from ucon.core import UnitFactor, UnitProduct, ScaleDescriptor
 
 
 class TestDimension(unittest.TestCase):
@@ -328,10 +332,11 @@ class TestScaleMultiplicationAdditional(unittest.TestCase):
         self.assertIsInstance(result, Scale)
         self.assertEqual(result.value.base, 10)
 
+    @unittest.skip("TODO: revamp: Unit.scale is deprecated.")
     def test_scale_multiplication_with_unit(self):
-        meter = Unit('m', name='meter', dimension=Dimension.length)
+        meter = UnitFactor('m', name='meter', dimension=Dimension.length)
         kilometer = Scale.kilo * meter
-        self.assertIsInstance(kilometer, Unit)
+        self.assertIsInstance(kilometer, UnitFactor)
         self.assertEqual(kilometer.scale, Scale.kilo)
         self.assertEqual(kilometer.dimension, Dimension.length)
         self.assertIn('meter', kilometer.name)
@@ -467,70 +472,63 @@ class TestUnit(unittest.TestCase):
         self.assertFalse(Unit("m", dimension=Dimension.length) == "meter")
 
 
-class TestCompositeUnit(unittest.TestCase):
+class TestUnitProduct(unittest.TestCase):
+
+    mf = UnitFactor(unit=units.meter, scale=Scale.one)
+    sf = UnitFactor(unit=units.second, scale=Scale.one)
+    nf = UnitFactor(unit=units.none, scale=Scale.one)
+    velocity = UnitProduct({mf: 1, sf: -1})
+    acceleration = UnitProduct({mf: 1, sf: -2})
+
     def test_composite_unit_collapses_to_unit(self):
-        u = Unit("m", name="meter", dimension=Dimension.length)
-        cu = CompositeUnit({u: 1})
+        cu = UnitProduct({self.mf: 1})
         # should anneal to Unit
-        self.assertIsInstance(cu, Unit)
-        self.assertEqual(cu.shorthand, u.shorthand)
+        self.assertIsInstance(cu, UnitProduct)
+        self.assertEqual(cu.shorthand, self.mf.shorthand)
 
     def test_merge_of_identical_units(self):
-        m = Unit("m", name="meter", dimension=Dimension.length)
         # Inner composite that already has m^1
-        inner = CompositeUnit({m: 1, units.second: -1})
+        inner = UnitProduct({self.mf: 1, self.sf: -1})
         # Outer composite sees both `m:1` and `inner:1`
-        cu = CompositeUnit({m: 1, inner: 1})
+        up = UnitProduct({self.mf: 1, inner: 1})
         # merge_unit should accumulate the exponents → m^(1 + 1) = m^2
-        self.assertIn(m, cu.components)
-        self.assertEqual(cu.components[m], 2)
+        self.assertIn(self.mf, up.factors)
+        self.assertEqual(up.factors[self.mf], 2)
 
     def test_merge_of_nested_composite_units(self):
-        m = Unit("m", dimension=Dimension.length)
-        s = Unit("s", dimension=Dimension.time)
-        velocity = CompositeUnit({m: 1, s: -1})
-        accel = CompositeUnit({velocity: 1, s: -1})
         # expect m*s^-2
-        self.assertEqual(accel.components[m], 1)
-        self.assertEqual(accel.components[s], -2)
+        self.assertEqual(self.acceleration.factors[self.mf], 1)
+        self.assertEqual(self.acceleration.factors[self.sf], -2)
 
     def test_drop_dimensionless_component(self):
-        m = Unit("m", dimension=Dimension.length)
-        none = Unit("", dimension=Dimension.none)
-        cu = CompositeUnit({m: 2, none: 1})
-        self.assertIn(m, cu.components)
-        self.assertNotIn(none, cu.components)
-
-    def test_anneal_single_unit(self):
-        m = Unit("m", dimension=Dimension.length)
-        cu = CompositeUnit({m: 1})
-        self.assertIsInstance(cu, Unit)
-        self.assertEqual(cu.name, m.name)
+        up = UnitProduct({self.mf: 2, self.nf: 1})
+        self.assertIn(self.mf, up.factors)
+        self.assertNotIn(self.nf, up.factors)
+
+    def test_unitproduct_can_behave_like_single_unit(self):
+        """
+        A UnitProduct with only one factor should seem like that factor.
+        """
+        up = UnitProduct({self.mf: 1})
+        self.assertEqual(up.shorthand, self.mf.shorthand)
+        self.assertEqual(up.dimension, self.mf.dimension)
 
     def test_composite_mul_with_scale(self):
-        m = Unit("m", dimension=Dimension.length)
-        s = Unit("s", dimension=Dimension.time)
-        cu = CompositeUnit({m: 1, s: -1})
-        result = Scale.kilo * cu
+        up = UnitProduct({self.mf: 1, self.sf: -1})
+        result = Scale.kilo * up
         # equivalent to scale multiplication on RMUL path
         self.assertIsNotNone(result)
         self.assertIsNotNone(result.shorthand, "km/s")
 
     def test_composite_div_dimensionless(self):
-        m = Unit("m", dimension=Dimension.length)
-        none = Unit("", dimension=Dimension.none)
-        cu = CompositeUnit({m: 2})
-        out = cu / none
-        self.assertEqual(out.components[m], 2)
+        up = UnitProduct({self.mf: 2})
+        out = up / UnitProduct({})
+        self.assertEqual(out.factors[self.mf], 2)
 
     def test_truediv_composite_by_composite(self):
-        m = Unit("m", dimension=Dimension.length)
-        s = Unit("s", dimension=Dimension.time)
-        velocity = CompositeUnit({m: 1, s: -1})
-        accel = CompositeUnit({m: 1, s: -2})
-        jerk = accel / velocity
+        jerk = self.acceleration / self.velocity
         # jerk = m^1 s^-2  /  m^1 s^-1 = s^-1
-        self.assertEqual(list(jerk.components.values()), [-1])
+        self.assertEqual(list(jerk.factors.values()), [-1])
 
 
 class TestUnitEdgeCases(unittest.TestCase):
@@ -574,7 +572,7 @@ class TestUnitEdgeCases(unittest.TestCase):
         m = Unit('m', name='meter', dimension=Dimension.length)
         s = Unit('s', name='second', dimension=Dimension.time)
         v = m / s
-        self.assertIsInstance(v, Unit)
+        self.assertIsInstance(v, UnitProduct)
         self.assertEqual(v.dimension, Dimension.velocity)
         self.assertIn('/', repr(v))
 
@@ -602,8 +600,8 @@ class TestUnitEdgeCases(unittest.TestCase):
         m = Unit('m', name='meter', dimension=Dimension.length)
         c = Unit('C', name='coulomb', dimension=Dimension.charge)
         # The result of combination gives CompositeUnit
-        self.assertIsInstance(m / c, CompositeUnit)
-        self.assertIsInstance(m * c, CompositeUnit)
+        self.assertIsInstance(m / c, UnitProduct)
+        self.assertIsInstance(m * c, UnitProduct)
 
     # --- equality, hashing, immutability ----------------------------------
 
@@ -672,3 +670,159 @@ class TestScaleEdgeCases(unittest.TestCase):
         all_map = Scale.all()
         by_val = Scale.by_value()
         self.assertTrue(all((val in by_val.values()) for _, val in all_map.items()))
+
+    def test_descriptor_property(self):
+        self.assertIsInstance(Scale.kilo.descriptor, ScaleDescriptor)
+        self.assertEqual(Scale.kilo.descriptor, Scale.kilo.value)
+
+    def test_alias_property(self):
+        self.assertEqual(Scale.kilo.alias, "kilo")
+        self.assertEqual(Scale.one.alias, "")
+
+    def test_scale_descriptor_parts(self):
+        self.assertEqual(Scale.kilo.value.parts(), (10, 3))
+        self.assertEqual(Scale.kibi.value.parts(), (2, 10))
+
+    def test_scale_hash_used_in_sets(self):
+        s = {Scale.kilo, Scale.milli}
+        self.assertIn(Scale.kilo, s)
+        self.assertNotIn(Scale.one, s)
+
+    def test_scale_mul_nonmatching_falls_to_nearest(self):
+        # kilo * kibi → no exact match, falls through to Scale.nearest
+        result = Scale.kilo * Scale.kibi
+        self.assertIsInstance(result, Scale)
+
+    def test_scale_pow(self):
+        result = Scale.kilo ** 2
+        self.assertEqual(result, Scale.mega)
+
+    def test_scale_pow_binary(self):
+        result = Scale.kibi ** 2
+        self.assertEqual(result, Scale.mebi)
+
+    def test_scale_pow_nonmatching_falls_to_nearest(self):
+        result = Scale.kilo ** 0.5
+        self.assertIsInstance(result, Scale)
+
+
+class TestUnitAlgebra(unittest.TestCase):
+
+    def test_unit_mul_unitproduct(self):
+        m = units.meter
+        velocity = UnitProduct({m: 1, units.second: -1})
+        result = m * velocity
+        self.assertIsInstance(result, UnitProduct)
+        # m * (m/s) = m²/s
+        self.assertEqual(result.dimension, Dimension.area / Dimension.time)
+
+    def test_unit_mul_non_unit_returns_not_implemented(self):
+        result = units.meter.__mul__("not a unit")
+        self.assertIs(result, NotImplemented)
+
+    def test_unit_truediv_non_unit_returns_not_implemented(self):
+        result = units.meter.__truediv__("not a unit")
+        self.assertIs(result, NotImplemented)
+
+    def test_unit_pow(self):
+        m = units.meter
+        result = m ** 2
+        self.assertIsInstance(result, UnitProduct)
+        self.assertEqual(result.dimension, Dimension.area)
+
+    def test_unit_pow_3(self):
+        m = units.meter
+        result = m ** 3
+        self.assertEqual(result.dimension, Dimension.volume)
+
+
+class TestUnitFactorCoverage(unittest.TestCase):
+
+    def test_shorthand_name_fallback(self):
+        # UnitFactor where unit has no aliases but has a name
+        u = Unit(name='gram', dimension=Dimension.mass)
+        fu = UnitFactor(unit=u, scale=Scale.milli)
+        self.assertEqual(fu.shorthand, 'mgram')
+
+    def test_repr(self):
+        fu = UnitFactor(unit=units.meter, scale=Scale.kilo)
+        self.assertIn('UnitFactor', repr(fu))
+        self.assertIn('kilo', repr(fu))
+
+    def test_eq_non_unit_returns_not_implemented(self):
+        fu = UnitFactor(unit=units.meter, scale=Scale.one)
+        self.assertIs(fu.__eq__("string"), NotImplemented)
+
+
+class TestUnitProductAlgebra(unittest.TestCase):
+
+    def test_mul_unitproduct_by_unitproduct(self):
+        velocity = UnitProduct({units.meter: 1, units.second: -1})
+        time_sq = UnitProduct({units.second: 2})
+        result = velocity * time_sq
+        self.assertIsInstance(result, UnitProduct)
+        # (m/s) * s² = m·s
+        self.assertEqual(result.dimension, Dimension.length * Dimension.time)
+
+    def test_mul_unitproduct_by_scale_returns_not_implemented(self):
+        velocity = UnitProduct({units.meter: 1, units.second: -1})
+        result = velocity.__mul__(Scale.kilo)
+        self.assertIs(result, NotImplemented)
+
+    def test_mul_unitproduct_by_non_unit_returns_not_implemented(self):
+        velocity = UnitProduct({units.meter: 1, units.second: -1})
+        result = velocity.__mul__("string")
+        self.assertIs(result, NotImplemented)
+
+    def test_truediv_unitproduct_by_unitproduct(self):
+        acceleration = UnitProduct({units.meter: 1, units.second: -2})
+        velocity = UnitProduct({units.meter: 1, units.second: -1})
+        result = acceleration / velocity
+        self.assertIsInstance(result, UnitProduct)
+        # (m/s²) / (m/s) = 1/s
+        self.assertEqual(result.dimension, Dimension.frequency)
+
+    def test_rmul_unit_times_unitproduct(self):
+        velocity = UnitProduct({units.meter: 1, units.second: -1})
+        result = units.meter * velocity
+        self.assertIsInstance(result, UnitProduct)
+
+    def test_rmul_scale_on_empty_unitproduct(self):
+        empty = UnitProduct({})
+        result = Scale.kilo * empty
+        self.assertIs(result, empty)
+
+    def test_rmul_scale_applies_to_sink_unit(self):
+        velocity = UnitProduct({units.meter: 1, units.second: -1})
+        result = Scale.kilo * velocity
+        self.assertIsInstance(result, UnitProduct)
+        self.assertIn('km', result.shorthand)
+
+    def test_rmul_scale_combines_with_existing_scale(self):
+        km_per_s = Scale.kilo * UnitProduct({units.meter: 1, units.second: -1})
+        # Apply another scale on top → should combine scales
+        result = Scale.milli * km_per_s
+        self.assertIsInstance(result, UnitProduct)
+
+    def test_rmul_non_unit_returns_not_implemented(self):
+        velocity = UnitProduct({units.meter: 1, units.second: -1})
+        result = velocity.__rmul__("string")
+        self.assertIs(result, NotImplemented)
+
+    def test_append_dimensionless_skipped(self):
+        # UnitProduct with only dimensionless factor → empty shorthand
+        up = UnitProduct({})
+        self.assertEqual(up.shorthand, "")
+
+    def test_shorthand_with_negative_non_unit_exponent(self):
+        # e.g. m/s² should show superscript on denominator
+        accel = UnitProduct({units.meter: 1, units.second: -2})
+        sh = accel.shorthand
+        self.assertIn('m', sh)
+        self.assertIn('s', sh)
+
+    def test_shorthand_numerator_exponent(self):
+        area = UnitProduct({units.meter: 2})
+        self.assertIn('m', area.shorthand)
+        # Should contain superscript 2
+        self.assertIn('²', area.shorthand)

tests/ucon/test_quantity.py

@@ -1,9 +1,11 @@
-
+# © 2025 The Radiativity Company
+# Licensed under the Apache License, Version 2.0
+# See the LICENSE file for details.
 
 import unittest
 
 from ucon import units
-from ucon.core import CompositeUnit, Dimension, Scale, Unit
+from ucon.core import UnitProduct, UnitFactor, Dimension, Scale, Unit
 from ucon.quantity import Number, Ratio
 
 
@@ -19,8 +21,8 @@ class TestNumber(unittest.TestCase):
 
     @unittest.skip("Requires ConversionGraph implementation")
     def test_simplify(self):
-        decagram = Unit(dimension=Dimension.mass, name='gram', scale=Scale.deca)
-        kibigram = Unit(dimension=Dimension.mass, name='gram', scale=Scale.kibi)
+        decagram = UnitFactor(dimension=Dimension.mass, name='gram', scale=Scale.deca)
+        kibigram = UnitFactor(dimension=Dimension.mass, name='gram', scale=Scale.kibi)
 
         ten_decagrams = Number(unit=decagram, quantity=10)
         point_one_decagrams = Number(unit=decagram, quantity=0.1)
@@ -32,9 +34,9 @@ class TestNumber(unittest.TestCase):
 
     @unittest.skip("Requires ConversionGraph implementation")
     def test_to(self):
-        kg = Unit(dimension=Dimension.mass, name='gram', scale=Scale.kilo)
-        mg = Unit(dimension=Dimension.mass, name='gram', scale=Scale.milli)
-        kibigram = Unit(dimension=Dimension.mass, name='gram', scale=Scale.kibi)
+        kg = UnitFactor(dimension=Dimension.mass, name='gram', scale=Scale.kilo)
+        mg = UnitFactor(dimension=Dimension.mass, name='gram', scale=Scale.milli)
+        kibigram = UnitFactor(dimension=Dimension.mass, name='gram', scale=Scale.kibi)
 
         thousandth_of_a_kilogram = Number(unit=kg, quantity=0.001)
         thousand_milligrams = Number(unit=mg, quantity=1000)
@@ -44,6 +46,7 @@ class TestNumber(unittest.TestCase):
         self.assertEqual(thousand_milligrams, self.number.to(Scale.milli))
         self.assertEqual(kibigram_fraction, self.number.to(Scale.kibi))
 
+    @unittest.skip("TODO: revamp: Unit.scale is deprecated.")
     def test___repr__(self):
         self.assertIn(str(self.number.quantity), str(self.number))
         self.assertIn(str(self.number.unit.scale.value.evaluated), str(self.number))
@@ -81,16 +84,17 @@ class TestNumberEdgeCases(unittest.TestCase):
         two_mL = Number(unit=mL, quantity=2)
 
         result = density.evaluate() * two_mL
-        self.assertIsInstance(result.unit, CompositeUnit)
-        self.assertDictEqual(result.unit.components, {units.gram: 1})
+        self.assertIsInstance(result.unit, UnitProduct)
+        self.assertDictEqual(result.unit.factors, {units.gram: 1})
         self.assertAlmostEqual(result.quantity, 6.238, places=12)
 
         mg = Scale.milli * units.gram
+        mg_factor = UnitFactor(unit=units.gram, scale=Scale.milli)
         mg_density = Ratio(Number(unit=mg, quantity=3119), Number(unit=mL, quantity=1))
 
         mg_result = mg_density.evaluate() * two_mL
-        self.assertIsInstance(mg_result.unit, CompositeUnit)
-        self.assertDictEqual(mg_result.unit.components, {mg: 1})
+        self.assertIsInstance(mg_result.unit, UnitProduct)
+        self.assertDictEqual(mg_result.unit.factors, {mg_factor: 1})
         self.assertAlmostEqual(mg_result.quantity, 6238, places=12)
 
     def test_number_mul_asymmetric_density_volume(self):
@@ -125,7 +129,7 @@ class TestNumberEdgeCases(unittest.TestCase):
         result = Number(unit=km, quantity=1) * Number(unit=m, quantity=1)
 
         # Should remain composite rather than collapsing to base m^2
-        assert isinstance(result.unit, CompositeUnit)
+        assert isinstance(result.unit, UnitProduct)
         assert "km" in result.unit.shorthand
         assert "m" in result.unit.shorthand
 
@@ -150,6 +154,7 @@ class TestNumberEdgeCases(unittest.TestCase):
         assert evaluated.unit == units.gram
         assert abs(evaluated.quantity - 6.238) < 1e-12
 
+    @unittest.skip("TODO: revamp: Unit.scale is deprecated.")
     def test_default_number_is_dimensionless_one(self):
         n = Number()
         self.assertEqual(n.unit, units.none)
@@ -160,15 +165,16 @@ class TestNumberEdgeCases(unittest.TestCase):
 
     @unittest.skip("Requires ConversionGraph implementation")
     def test_to_new_scale_changes_value(self):
-        thousand = Unit(dimension=Dimension.none, name='', scale=Scale.kilo)
+        thousand = UnitFactor(dimension=Dimension.none, name='', scale=Scale.kilo)
         n = Number(quantity=1000, unit=thousand)
         converted = n.to(Scale.one)
         self.assertNotEqual(n.value, converted.value)
         self.assertAlmostEqual(converted.value, 1000)
 
+    @unittest.skip("TODO: revamp: Unit.scale is deprecated.")
     @unittest.skip("Requires ConversionGraph implementation")
     def test_simplify_uses_value_as_quantity(self):
-        thousand = Unit(dimension=Dimension.none, name='', scale=Scale.kilo)
+        thousand = UnitFactor(dimension=Dimension.none, name='', scale=Scale.kilo)
         n = Number(quantity=2, unit=thousand)
         simplified = n.simplify()
         self.assertEqual(simplified.quantity, n.value)
@@ -182,16 +188,17 @@ class TestNumberEdgeCases(unittest.TestCase):
         self.assertEqual(result.quantity, 6)
         self.assertEqual(result.unit.dimension, Dimension.energy * Dimension.time)
 
+    @unittest.skip("TODO: revamp: Unit.scale is deprecated.")
     @unittest.skip("Requires ConversionGraph implementation")
     def test_division_combines_units_scales_and_quantities(self):
-        km = Unit('m', name='meter', dimension=Dimension.length, scale=Scale.kilo)
+        km = UnitFactor('m', name='meter', dimension=Dimension.length, scale=Scale.kilo)
         n1 = Number(unit=km, quantity=1000)
         n2 = Number(unit=units.second, quantity=2)
 
         result = n1 / n2     # should yield <500 km/s>
 
         cu = result.unit
-        self.assertIsInstance(cu, CompositeUnit)
+        self.assertIsInstance(cu, UnitProduct)
 
         # --- quantity check ---
         self.assertAlmostEqual(result.quantity, 500)
@@ -225,7 +232,7 @@ class TestNumberEdgeCases(unittest.TestCase):
         self.assertTrue(r == Number())
 
     def test_repr_includes_scale_and_unit(self):
-        kV = Unit('V', name='volt', dimension=Dimension.voltage, scale=Scale.kilo)
+        kV = Scale.kilo * Unit('V', name='volt', dimension=Dimension.voltage)
         n = Number(unit=kV, quantity=5)
         rep = repr(n)
         self.assertIn("kV", rep)
@@ -262,7 +269,7 @@ class TestRatio(unittest.TestCase):
         self.assertEqual(self.one_half * self.three_halves, self.three_fourths)
 
     def test___mul__(self):
-        mL = Unit('L', name='liter', dimension=Dimension.volume, scale=Scale.milli)
+        mL = Scale.milli * Unit('L', name='liter', dimension=Dimension.volume)
         n1 = Number(unit=units.gram, quantity=3.119)
         n2 = Number(unit=mL)
         bromine_density = Ratio(n1, n2)
@@ -282,7 +289,7 @@ class TestRatio(unittest.TestCase):
 
         # How many Wh from 20 kJ?
         twenty_kilojoules = Number(
-            unit=Unit('J', name='joule', dimension=Dimension.energy, scale=Scale.kilo),
+            unit=Scale.kilo * Unit('J', name='joule', dimension=Dimension.energy),
             quantity=20
         )
         ratio = twenty_kilojoules.as_ratio() / seconds_per_hour

tests/ucon/test_units.py

@@ -1,10 +1,12 @@
 
+# © 2025 The Radiativity Company
+# Licensed under the Apache License, Version 2.0
+# See the LICENSE file for details.
 
 from unittest import TestCase
 
 from ucon import units
 from ucon.core import Dimension
-from ucon.core import Unit
 
 
 class TestUnits(TestCase):

ucon/__init__.py

@@ -1,3 +1,7 @@
+# © 2025 The Radiativity Company
+# Licensed under the Apache License, Version 2.0
+# See the LICENSE file for details.
+
 """
 ucon
 ====
@@ -34,7 +38,7 @@ Design Philosophy
 """
 from ucon import units
 from ucon.algebra import Exponent
-from ucon.core import Dimension, Scale, Unit
+from ucon.core import Dimension, Scale, Unit, UnitFactor, UnitProduct
 from ucon.quantity import Number, Ratio
 
 
@@ -45,5 +49,7 @@ __all__ = [
     'Ratio',
     'Scale',
     'Unit',
+    'UnitFactor',
+    'UnitProduct',
     'units',
 ]

ucon/algebra.py

@@ -1,3 +1,7 @@
+# © 2025 The Radiativity Company
+# Licensed under the Apache License, Version 2.0
+# See the LICENSE file for details.
+
 """
 ucon.algebra
 ============