ucon 0.3.2rc6__py3-none-any.whl

tests/ucon/test_dimension.py

@@ -0,0 +1,206 @@
+import unittest
+from ucon.dimension import Vector, Dimension
+
+
+class TestVector(unittest.TestCase):
+
+    def test_vector_iteration_and_length(self):
+        v = Vector(1, 0, 0, 0, 0, 0, 0)
+        self.assertEqual(tuple(v), (1, 0, 0, 0, 0, 0, 0))
+        self.assertEqual(len(v), 7)  # always 7 components
+
+    def test_vector_addition(self):
+        v1 = Vector(1, 0, 0, 0, 0, 0, 0)
+        v2 = Vector(0, 2, 0, 0, 0, 0, 0)
+        result = v1 + v2
+        self.assertEqual(result, Vector(1, 2, 0, 0, 0, 0, 0))
+
+    def test_vector_subtraction(self):
+        v1 = Vector(2, 1, 0, 0, 0, 0, 0)
+        v2 = Vector(1, 1, 0, 0, 0, 0, 0)
+        self.assertEqual(v1 - v2, Vector(1, 0, 0, 0, 0, 0, 0))
+
+    def test_vector_equality_and_hash(self):
+        v1 = Vector(1, 0, 0, 0, 0, 0, 0)
+        v2 = Vector(1, 0, 0, 0, 0, 0, 0)
+        v3 = Vector(0, 1, 0, 0, 0, 0, 0)
+        self.assertTrue(v1 == v2)
+        self.assertFalse(v1 == v3)
+        self.assertEqual(hash(v1), hash(v2))
+        self.assertNotEqual(hash(v1), hash(v3))
+
+
+class TestDimension(unittest.TestCase):
+
+    def test_basic_dimensions_are_unique(self):
+        seen = set()
+        for dim in Dimension:
+            self.assertNotIn(dim.value, seen, f'Duplicate vector found for {dim.name}')
+            seen.add(dim.value)
+
+    def test_multiplication_adds_exponents(self):
+        self.assertEqual(
+            Dimension.mass * Dimension.acceleration,
+            Dimension.force,
+        )
+        self.assertEqual(
+            Dimension.length * Dimension.length,
+            Dimension.area,
+        )
+        self.assertEqual(
+            Dimension.length * Dimension.length * Dimension.length,
+            Dimension.volume,
+        )
+
+    def test_division_subtracts_exponents(self):
+        self.assertEqual(
+            Dimension.length / Dimension.time,
+            Dimension.velocity,
+        )
+        self.assertEqual(
+            Dimension.force / Dimension.area,
+            Dimension.pressure,
+        )
+
+    def test_none_dimension_behaves_neutrally(self):
+        base = Dimension.mass
+        self.assertEqual(base * Dimension.none, base)
+        self.assertEqual(base / Dimension.none, base)
+        self.assertEqual(Dimension.none * base, base)
+        with self.assertRaises(ValueError) as exc:
+            Dimension.none / base
+        assert type(exc.exception) == ValueError
+        assert str(exc.exception).endswith('is not a valid Dimension')
+
+    def test_hash_and_equality_consistency(self):
+        d1 = Dimension.mass
+        d2 = Dimension.mass
+        d3 = Dimension.length
+        self.assertEqual(d1, d2)
+        self.assertNotEqual(d1, d3)
+        self.assertEqual(hash(d1), hash(d2))
+        self.assertNotEqual(hash(d1), hash(d3))
+
+    def test_composite_quantities_examples(self):
+        # Energy = Force * Length
+        self.assertEqual(
+            Dimension.force * Dimension.length,
+            Dimension.energy,
+        )
+        # Power = Energy / Time
+        self.assertEqual(
+            Dimension.energy / Dimension.time,
+            Dimension.power,
+        )
+        # Pressure = Force / Area
+        self.assertEqual(
+            Dimension.force / Dimension.area,
+            Dimension.pressure,
+        )
+        # Charge = Current * Time
+        self.assertEqual(
+            Dimension.current * Dimension.time,
+            Dimension.charge,
+        )
+
+    def test_vector_equality_reflects_dimension_equality(self):
+        self.assertEqual(Dimension.mass.value, Dimension.mass.value)
+        self.assertNotEqual(Dimension.mass.value, Dimension.time.value)
+        self.assertEqual(Dimension.mass, Dimension.mass)
+        self.assertNotEqual(Dimension.mass, Dimension.time)
+
+
+class TestVectorEdgeCases(unittest.TestCase):
+
+    def test_zero_vector_equality_and_additivity(self):
+        zero = Vector()
+        self.assertEqual(zero, Vector(0, 0, 0, 0, 0, 0, 0))
+        # Adding or subtracting zero should yield same vector
+        v = Vector(1, 2, 3, 4, 5, 6, 7)
+        self.assertEqual(v + zero, v)
+        self.assertEqual(v - zero, v)
+
+    def test_vector_with_negative_exponents(self):
+        v1 = Vector(1, -2, 3, 0, 0, 0, 0)
+        v2 = Vector(-1, 2, -3, 0, 0, 0, 0)
+        result = v1 + v2
+        self.assertEqual(result, Vector(0, 0, 0, 0, 0, 0, 0))
+        self.assertEqual(v1 - v1, Vector())  # perfect cancellation
+
+    def test_vector_equality_with_non_vector(self):
+        v = Vector()
+        with self.assertRaises(AssertionError):
+            v == "not a vector"
+        with self.assertRaises(AssertionError):
+            v == None
+
+    def test_hash_consistency_for_equal_vectors(self):
+        v1 = Vector(1, 0, 0, 0, 0, 0, 0)
+        v2 = Vector(1, 0, 0, 0, 0, 0, 0)
+        self.assertEqual(hash(v1), hash(v2))
+        self.assertEqual(len({v1, v2}), 1)
+
+    def test_iter_length_order_consistency(self):
+        v = Vector(1, 2, 3, 4, 5, 6, 7)
+        components = list(v)
+        self.assertEqual(len(components), len(v))
+        # Ensure order of iteration is fixed (T→L→M→I→Θ→J→N)
+        self.assertEqual(components, [1, 2, 3, 4, 5, 6, 7])
+
+    def test_vector_arithmetic_does_not_mutate_operands(self):
+        v1 = Vector(1, 0, 0, 0, 0, 0, 0)
+        v2 = Vector(0, 1, 0, 0, 0, 0, 0)
+        _ = v1 + v2
+        self.assertEqual(v1, Vector(1, 0, 0, 0, 0, 0, 0))
+        self.assertEqual(v2, Vector(0, 1, 0, 0, 0, 0, 0))
+
+    def test_invalid_addition_type_raises(self):
+        v = Vector(1, 0, 0, 0, 0, 0, 0)
+        with self.assertRaises(TypeError):
+            _ = v + "length"
+        with self.assertRaises(TypeError):
+            _ = v - 5
+
+
+class TestDimensionEdgeCases(unittest.TestCase):
+
+    def test_invalid_multiplication_type(self):
+        with self.assertRaises(TypeError):
+            Dimension.length * 5
+        with self.assertRaises(TypeError):
+            "mass" * Dimension.time
+
+    def test_invalid_division_type(self):
+        with self.assertRaises(TypeError):
+            Dimension.time / "length"
+        with self.assertRaises(TypeError):
+            5 / Dimension.mass
+
+    def test_equality_with_non_dimension(self):
+        with self.assertRaises(TypeError):
+            Dimension.mass ==  "mass"
+
+    def test_enum_uniqueness_and_hash(self):
+        # Hashes should be unique per distinct dimension
+        hashes = {hash(d) for d in Dimension}
+        self.assertEqual(len(hashes), len(Dimension))
+        # All Dimension.value entries must be distinct Vectors
+        values = [d.value for d in Dimension]
+        self.assertEqual(len(values), len(set(values)))
+
+    def test_combined_chained_operations(self):
+        # (mass * acceleration) / area = pressure
+        result = (Dimension.mass * Dimension.acceleration) / Dimension.area
+        self.assertEqual(result, Dimension.pressure)
+
+    def test_dimension_round_trip_equality(self):
+        # Multiplying and dividing by the same dimension returns self
+        d = Dimension.energy
+        self.assertEqual((d * Dimension.none) / Dimension.none, d)
+        self.assertEqual(d / Dimension.none, d)
+        self.assertEqual(Dimension.none * d, d)
+
+    def test_enum_is_hashable_and_iterable(self):
+        seen = {d for d in Dimension}
+        self.assertIn(Dimension.mass, seen)
+        self.assertEqual(len(seen), len(Dimension))

tests/ucon/test_unit.py

@@ -0,0 +1,143 @@
+
+
+from unittest import TestCase
+
+from ucon.dimension import Dimension
+from ucon.unit import Unit
+
+
+class TestUnit(TestCase):
+
+    unit_name = 'second'
+    unit_type = 'time'
+    unit_aliases = ('seconds', 'secs', 's', 'S')
+    unit = Unit(*unit_aliases, name=unit_name, dimension=Dimension.time)
+
+    def test___repr__(self):
+        self.assertEqual(f'<{self.unit_type} | {self.unit_name}>', str(self.unit))
+
+
+class TestUnitEdgeCases(TestCase):
+
+    # --- Initialization & representation -----------------------------------
+
+    def test_default_unit_is_dimensionless(self):
+        u = Unit()
+        self.assertEqual(u.dimension, Dimension.none)
+        self.assertEqual(u.name, '')
+        self.assertEqual(u.aliases, ())
+        self.assertEqual(u.shorthand, '')
+        self.assertEqual(repr(u), '<none>')
+
+    def test_unit_with_aliases_and_name(self):
+        u = Unit('m', 'M', name='meter', dimension=Dimension.length)
+        self.assertEqual(u.shorthand, 'm')
+        self.assertIn('m', u.aliases)
+        self.assertIn('M', u.aliases)
+        self.assertIn('length', repr(u))
+        self.assertIn('meter', repr(u))
+
+    def test_hash_and_equality_consistency(self):
+        u1 = Unit('m', name='meter', dimension=Dimension.length)
+        u2 = Unit('m', name='meter', dimension=Dimension.length)
+        u3 = Unit('s', name='second', dimension=Dimension.time)
+        self.assertEqual(u1, u2)
+        self.assertEqual(hash(u1), hash(u2))
+        self.assertNotEqual(u1, u3)
+        self.assertNotEqual(hash(u1), hash(u3))
+
+    def test_units_with_same_name_but_different_dimension_not_equal(self):
+        u1 = Unit(name='amp', dimension=Dimension.current)
+        u2 = Unit(name='amp', dimension=Dimension.time)
+        self.assertNotEqual(u1, u2)
+
+    # --- generate_name edge cases -----------------------------------------
+
+    def test_generate_name_both_have_shorthand(self):
+        u1 = Unit('m', name='meter', dimension=Dimension.length)
+        u2 = Unit('s', name='second', dimension=Dimension.time)
+        result = u1.generate_name(u2, '*')
+        self.assertEqual(result, '(m*s)')
+
+    def test_generate_name_missing_left_shorthand(self):
+        u1 = Unit(name='unitless', dimension=Dimension.none)
+        u2 = Unit('s', name='second', dimension=Dimension.time)
+        self.assertEqual(u1.generate_name(u2, '/'), 'second')
+
+    def test_generate_name_missing_right_shorthand(self):
+        u1 = Unit('m', name='meter', dimension=Dimension.length)
+        u2 = Unit(name='none', dimension=Dimension.none)
+        self.assertEqual(u1.generate_name(u2, '*'), 'meter')
+
+    def test_generate_name_no_aliases_on_either_side(self):
+        u1 = Unit(name='foo', dimension=Dimension.length)
+        u2 = Unit(name='bar', dimension=Dimension.time)
+        self.assertEqual(u1.generate_name(u2, '*'), '(foo*bar)')
+
+    # --- arithmetic behavior ----------------------------------------------
+
+    def test_multiplication_produces_composite_unit(self):
+        m = Unit('m', name='meter', dimension=Dimension.length)
+        s = Unit('s', name='second', dimension=Dimension.time)
+        v = m / s
+        self.assertIsInstance(v, Unit)
+        self.assertEqual(v.dimension, Dimension.velocity)
+        self.assertIn('/', v.name)
+
+    def test_division_with_dimensionless_denominator_returns_self(self):
+        m = Unit('m', name='meter', dimension=Dimension.length)
+        none = Unit(name='none', dimension=Dimension.none)
+        result = m / none
+        self.assertEqual(result, m)
+
+    def test_division_of_identical_units_returns_dimensionless(self):
+        m1 = Unit('m', name='meter', dimension=Dimension.length)
+        m2 = Unit('m', name='meter', dimension=Dimension.length)
+        result = m1 / m2
+        self.assertEqual(result.dimension, Dimension.none)
+        self.assertEqual(result.name, '')
+
+    def test_multiplying_with_dimensionless_returns_self(self):
+        m = Unit('m', name='meter', dimension=Dimension.length)
+        none = Unit(name='none', dimension=Dimension.none)
+        result = m * none
+        self.assertEqual(result.dimension, Dimension.length)
+        self.assertIn('m', result.name)
+
+    def test_invalid_dimension_combinations_raise_value_error(self):
+        m = Unit('m', name='meter', dimension=Dimension.length)
+        c = Unit('C', name='coulomb', dimension=Dimension.charge)
+        # The result of dividing these is undefined (no such Dimension)
+        with self.assertRaises(ValueError):
+            _ = m / c
+        with self.assertRaises(ValueError):
+            _ = c * m
+
+    # --- equality, hashing, immutability ----------------------------------
+
+    def test_equality_with_non_unit(self):
+        with self.assertRaises(TypeError):
+            Unit('m', name='meter', dimension=Dimension.length) == 'meter'
+
+    def test_hash_stability_in_collections(self):
+        m1 = Unit('m', name='meter', dimension=Dimension.length)
+        s = set([m1])
+        self.assertIn(Unit('m', name='meter', dimension=Dimension.length), s)
+
+    def test_operations_do_not_mutate_operands(self):
+        m = Unit('m', name='meter', dimension=Dimension.length)
+        s = Unit('s', name='second', dimension=Dimension.time)
+        _ = m / s
+        self.assertEqual(m.dimension, Dimension.length)
+        self.assertEqual(s.dimension, Dimension.time)
+
+    # --- operator edge cases ----------------------------------------------
+
+    def test_generate_name_handles_empty_names_and_aliases(self):
+        a = Unit()
+        b = Unit()
+        self.assertEqual(a.generate_name(b, '*'), '')
+
+    def test_repr_contains_dimension_name_even_without_name(self):
+        u = Unit(dimension=Dimension.force)
+        self.assertIn('force', repr(u))

tests/ucon/test_units.py

@@ -0,0 +1,21 @@
+
+
+from unittest import TestCase
+
+from ucon import units
+from ucon.dimension import Dimension
+from ucon.unit import Unit
+
+
+class TestUnits(TestCase):
+
+    def test_has_expected_basic_units(self):
+        expected_basic_units = {'none', 'volt', 'liter', 'gram', 'second', 'kelvin', 'mole', 'coulomb'}
+        missing = {name for name in expected_basic_units if not units.have(name)}
+        assert not missing, f"Missing expected units: {missing}"
+
+    def test___truediv__(self):
+        self.assertEqual(units.none, units.gram / units.gram)
+        self.assertEqual(units.gram, units.gram / units.none)
+
+        self.assertEqual(Unit(name='(g/L)', dimension=Dimension.density), units.gram / units.liter)

ucon/__init__.py

@@ -0,0 +1,49 @@
+"""
+ucon
+====
+
+*ucon* (Unit Conversion & Dimensional Analysis) is a lightweight,
+introspective library for reasoning about physical quantities.
+
+Unlike conventional unit libraries that focus purely on arithmetic convenience,
+*ucon* models the **semantics** of measurement-—exposing the algebra of
+dimensions and the structure of compound units.
+
+Overview
+--------
+*ucon* is organized into a small set of composable modules:
+
+- :mod:`ucon.dimension` — defines the algebra of physical dimensions using
+  exponent vectors. Provides the foundation for all dimensional reasoning.
+- :mod:`ucon.unit` — defines the :class:`Unit` abstraction, representing a
+  measurable quantity with an associated dimension, factor, and offset.
+- :mod:`ucon.core` — implements numeric handling via :class:`Number`,
+  :class:`Scale`, and :class:`Ratio`, along with unified conversion logic.
+- :mod:`ucon.units` — declares canonical SI base and derived units for immediate use.
+
+Design Philosophy
+-----------------
+*ucon* treats unit conversion not as a lookup problem but as an **algebra**:
+
+- **Dimensional Algebra** — all physical quantities are represented as
+  exponent vectors over the seven SI bases, ensuring strict composability.
+- **Explicit Semantics** — units, dimensions, and scales are first-class
+  objects, not strings or tokens.
+- **Unified Conversion Model** — all conversions are expressed through one
+  data-driven framework that is generalizable to arbitrary unit systems.
+"""
+from ucon import units
+from ucon.unit import Unit
+from ucon.core import Exponent, Number, Scale, Ratio
+from ucon.dimension import Dimension
+
+
+__all__ = [
+    'Exponent',
+    'Dimension',
+    'Number',
+    'Ratio',
+    'Scale',
+    'Unit',
+    'units',
+]