ucon 0.3.2rc6__py3-none-any.whl → 0.3.3rc1__py3-none-any.whl

tests/ucon/test_core.py

@@ -109,6 +109,15 @@ class TestScale(TestCase):
         self.assertEqual(Scale.one, Scale.kibi / Scale.kibi)
         self.assertEqual(Scale.one, Scale.kibi / Scale.kilo)
 
+    def test___mul__(self):
+        self.assertEqual(Scale.kilo, Scale.kilo * Scale.one)
+        self.assertEqual(Scale.kilo, Scale.one * Scale.kilo)
+        self.assertEqual(Scale.one, Scale.kilo * Scale.milli)
+        self.assertEqual(Scale.deca, Scale.hecto * Scale.deci)
+        self.assertEqual(Scale.mega, Scale.kilo * Scale.kibi)
+        self.assertEqual(Scale.giga, Scale.mega * Scale.kilo)
+        self.assertEqual(Scale.one, Scale.one * Scale.one)
+
     def test___lt__(self):
         self.assertLess(Scale.one, Scale.kilo)
 
@@ -121,6 +130,43 @@ class TestScale(TestCase):
         self.assertIsInstance(Scale.all(), dict)
 
 
+class TestScaleMultiplicationAdditional(TestCase):
+
+    def test_decimal_combinations(self):
+        self.assertEqual(Scale.kilo * Scale.centi, Scale.deca)
+        self.assertEqual(Scale.kilo * Scale.milli, Scale.one)
+        self.assertEqual(Scale.hecto * Scale.deci, Scale.deca)
+
+    def test_binary_combinations(self):
+        # kibi (2^10) * mebi (2^20) = 2^30 (should round to nearest known)
+        result = Scale.kibi * Scale.mebi
+        self.assertEqual(result.value.base, 2)
+        self.assertTrue(isinstance(result, Scale))
+
+    def test_mixed_base_combination(self):
+        self.assertEqual(Scale.mega, Scale.kilo * Scale.kibi)
+
+    def test_result_has_no_exact_match_fallbacks_to_nearest(self):
+        # Suppose the exponent product is not in Scale.all()
+        # e.g. kilo (10^3) * deci (10^-1) = 10^2 = hecto
+        result = Scale.kilo * Scale.deci
+        self.assertEqual(result, Scale.hecto)
+
+    def test_order_independence(self):
+        # Associativity of multiplication
+        self.assertEqual(Scale.kilo * Scale.centi, Scale.centi * Scale.kilo)
+
+    def test_non_scale_operand_returns_not_implemented(self):
+        with self.assertRaises(TypeError):
+            Scale.kilo * 2
+
+    def test_large_exponent_clamping(self):
+        # simulate a very large multiplication, should still resolve
+        result = Scale.mega * Scale.mega  # 10^12, not defined -> nearest Scale
+        self.assertIsInstance(result, Scale)
+        self.assertEqual(result.value.base, 10)
+
+
 class TestScaleDivisionAdditional(TestCase):
 
     def test_division_same_base_large_gap(self):
@@ -255,7 +301,7 @@ class TestNumber(TestCase):
 
     def test___eq__(self):
         self.assertEqual(self.number, Ratio(self.number))  # 1 gram / 1
-        with self.assertRaises(ValueError):
+        with self.assertRaises(TypeError):
             self.number == 1
 
 
@@ -290,10 +336,12 @@ class TestRatio(TestCase):
         self.assertEqual(self.one_half * self.three_halves, self.three_fourths)
 
     def test___mul__(self):
-        bromine_density = Ratio(Number(units.gram, quantity=3.119), Number(units.liter, Scale.milli))
+        n1 = Number(unit=units.gram, quantity=3.119)
+        n2 = Number(unit=units.liter, scale=Scale.milli)
+        bromine_density = Ratio(n1, n2)
     
         # How many grams of bromine are in 2 milliliters?
-        two_milliliters_bromine = Number(units.liter, Scale.milli, 2)
+        two_milliliters_bromine = Number(unit=units.liter, scale=Scale.milli, quantity=2)
         ratio = two_milliliters_bromine.as_ratio() * bromine_density
         answer = ratio.evaluate()
         self.assertEqual(answer.unit.dimension, Dimension.mass)
@@ -319,7 +367,7 @@ class TestRatio(TestCase):
 
     def test___repr__(self):
         self.assertEqual(str(self.one_ratio), '<1.0 >')
-        self.assertEqual(str(self.two_ratio), '<2 > / <1 >')
+        self.assertEqual(str(self.two_ratio), '<2 > / <1.0 >')
         self.assertEqual(str(self.two_ratio.evaluate()), '<2.0 >')
 
 
@@ -458,8 +506,8 @@ class TestNumberEdgeCases(TestCase):
 
     def test_equality_with_non_number_raises_value_error(self):
         n = Number()
-        with self.assertRaises(ValueError):
-            _ = (n == "5")
+        with self.assertRaises(TypeError):
+            n == '5'
 
     def test_equality_between_numbers_and_ratios(self):
         n1 = Number(quantity=10)

ucon/core.py

@@ -15,6 +15,7 @@ Classes
 Together, these classes allow full arithmetic, conversion, and introspection
 of physical quantities with explicit dimensional semantics.
 """
+from dataclasses import dataclass, field
 from enum import Enum
 from functools import lru_cache, reduce, total_ordering
 from math import log2
@@ -33,6 +34,8 @@ class Exponent:
 
     Provides comparison and division semantics used internally to represent
     magnitude prefixes (e.g., kilo, mega, micro).
+
+    TODO (wittwemms): embrace fractional exponents for closure on multiplication/division.
     """
     bases = {2: log2, 10: log10}
 
@@ -198,6 +201,31 @@ class Scale(Enum):
 
         return min(candidates, key=distance)
 
+    def __mul__(self, other: 'Scale'):
+        """
+        Multiply two Scales together.
+
+        Always returns a `Scale`, representing the resulting order of magnitude.
+        If no exact prefix match exists, returns the nearest known Scale.
+        """
+        if not isinstance(other, Scale):
+            return NotImplemented
+
+        if self is Scale.one:
+            return other
+        if other is Scale.one:
+            return self
+
+        result = self.value * other.value  # delegates to Exponent.__mul__
+        include_binary = 2 in {self.value.base, other.value.base}
+
+        if isinstance(result, Exponent):
+            match = Scale.all().get(result.parts())
+            if match:
+                return Scale[match]
+
+        return Scale.nearest(float(result), include_binary=include_binary)
+
     def __truediv__(self, other: 'Scale'):
         """
         Divide one Scale by another.
@@ -210,7 +238,6 @@ class Scale(Enum):
 
         if self == other:
             return Scale.one
-
         if other is Scale.one:
             return self
 
@@ -241,7 +268,9 @@ class Scale(Enum):
         return self.value == other.value
 
 
-# TODO -- consider using a dataclass
+Quantifiable = Union['Number', 'Ratio']
+
+@dataclass
 class Number:
     """
     Represents a **numeric quantity** with an associated :class:`Unit` and :class:`Scale`.
@@ -256,11 +285,14 @@ class Number:
         >>> speed
         <2.5 (m/s)>
     """
-    def __init__(self, unit: Unit = units.none, scale: Scale = Scale.one, quantity = 1):
-        self.unit = unit
-        self.scale = scale
-        self.quantity = quantity
-        self.value = round(self.quantity * self.scale.value.evaluated, 15)
+    quantity: Union[float, int] = 1.0
+    unit: Unit = units.none
+    scale: Scale = field(default_factory=lambda: Scale.one)
+
+    @property
+    def value(self) -> float:
+        """Return numeric magnitude as quantity × scale factor."""
+        return round(self.quantity * self.scale.value.evaluated, 15)
 
     def simplify(self):
         return Number(unit=self.unit, quantity=self.value)
@@ -272,28 +304,44 @@ class Number:
     def as_ratio(self):
         return Ratio(self)
 
-    def __mul__(self, another_number: 'Number') -> 'Number':
+    def __mul__(self, other: Quantifiable) -> 'Number':
+        if not isinstance(other, (Number, Ratio)):
+            return NotImplemented
+
+        if isinstance(other, Ratio):
+            other = other.evaluate()
+
         return Number(
-            unit=self.unit * another_number.unit,
-            scale=self.scale,
-            quantity=self.quantity * another_number.quantity,
+            quantity=self.quantity * other.quantity,
+            unit=self.unit * other.unit,
+            scale=self.scale * other.scale,
         )
 
-    def __truediv__(self, another_number: 'Number') -> 'Number':
-        unit = self.unit / another_number.unit
-        scale = self.scale / another_number.scale
-        quantity = self.quantity / another_number.quantity
-        return Number(unit, scale, quantity)
-
-    def __eq__(self, another_number):
-        if isinstance(another_number, Number):
-            return (self.unit == another_number.unit) and \
-                   (self.quantity == another_number.quantity) and \
-                   (self.value == another_number.value)
-        elif isinstance(another_number, Ratio):
-            return self == another_number.evaluate()
-        else:
-            raise ValueError(f'"{another_number}" is not a Number or Ratio. Comparison not possible.')
+    def __truediv__(self, other: Quantifiable) -> 'Number':
+        if not isinstance(other, (Number, Ratio)):
+            return NotImplemented
+
+        if isinstance(other, Ratio):
+            other = other.evaluate()
+
+        return Number(
+            quantity=self.quantity / other.quantity,
+            unit=self.unit / other.unit,
+            scale=self.scale / other.scale,
+        )
+
+    def __eq__(self, other: Quantifiable) -> bool:
+        if not isinstance(other, (Number, Ratio)):
+            raise TypeError(f'Cannot compare Number to non-Number/Ratio type: {type(other)}')
+
+        elif isinstance(other, Ratio):
+            other = other.evaluate()
+
+        # Compare on evaluated numeric magnitude and exact unit
+        return (
+            self.unit == other.unit and
+            abs(self.value - other.value) < 1e-12
+        )
 
     def __repr__(self):
         return f'<{self.quantity} {"" if self.scale.name == "one" else self.scale.name}{self.unit.name}>'

{ucon-0.3.2rc6.dist-info → ucon-0.3.3rc1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.3.2rc6
+Version: 0.3.3rc1
 Summary: a tool for dimensional analysis: a "Unit CONverter"
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi
@@ -34,17 +34,18 @@ Dynamic: maintainer
 Dynamic: maintainer-email
 Dynamic: summary
 
-<img src="https://gist.githubusercontent.com/withtwoemms/0cb9e6bc8df08f326771a89eeb790f8e/raw/dde6c7d3b8a7d79eb1006ace03fb834e044cdebc/ucon-logo.png" align="left" width="420" />
+<img src="https://gist.githubusercontent.com/withtwoemms/0cb9e6bc8df08f326771a89eeb790f8e/raw/dde6c7d3b8a7d79eb1006ace03fb834e044cdebc/ucon-logo.png" align="left" width="200" />
 
 # ucon
 
 > Pronounced: _yoo · cahn_
-> A lightweight, **unit-aware computation library** for Python — built on first-principles.
 
 [![tests](https://github.com/withtwoemms/ucon/workflows/tests/badge.svg)](https://github.com/withtwoemms/ucon/actions?query=workflow%3Atests)
 [![codecov](https://codecov.io/gh/withtwoemms/ucon/graph/badge.svg?token=BNONQTRJWG)](https://codecov.io/gh/withtwoemms/ucon)
 [![publish](https://github.com/withtwoemms/ucon/workflows/publish/badge.svg)](https://github.com/withtwoemms/ucon/actions?query=workflow%3Apublish)
 
+> A lightweight, **unit-aware computation library** for Python — built on first-principles.
+
 ---
 
 ## Overview
@@ -81,35 +82,7 @@ To best answer this question, we turn to an age-old technique ([dimensional anal
 
 `ucon` models unit math through a hierarchy where each layer builds on the last:
 
-```mermaid
----
-config:
-  layout: elk
-  elk:
-    mergeEdges: true  # Combines parallel edges
-    nodePlacementStrategy: SIMPLE # Other options: SIMPLE, NETWORK_SIMPLEX, BRANDES_KOEPF (default)
----
-flowchart LR
-%% --- Algebraic substrate ---
-subgraph "Algebraic Substrate"
-  A[Exponent] --> B[Scale]
-end
-%% --- Physical ontology ---
-subgraph "Physical Ontology"
-  D[Dimension] --> E[Unit]
-end
-%% --- Value layer ---
-subgraph "Value Layer"
-  F[Number]
-  G[Ratio]
-end
-%% --- Cross-layer relationships ---
-E --> F
-B --> F
-%% Ratio composes Numbers and also evaluates to a Number
-F --> G
-G --> F
-```
+<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/f3518d37445301950026fc9ffd1bd062768005fe/ucon.data-model.png align="center" alt="ucon Data Model" width=600/>
 
 ## Why `ucon`?
 

{ucon-0.3.2rc6.dist-info → ucon-0.3.3rc1.dist-info}/RECORD

@@ -1,15 +1,15 @@
 tests/ucon/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-tests/ucon/test_core.py,sha256=rpKCH5olc9EI0tPXuiGXRlEfMFnsFGJ-Ntrn-ZV34fY,20854
+tests/ucon/test_core.py,sha256=a48nfTqg-WJ_jzjVT6KtsBb6E8oPUZaqCmscKDzlG_g,22871
 tests/ucon/test_dimension.py,sha256=JyA9ySFvohs2l6oK77ehCQ7QvvFVqB_9t0iC7CUErjw,7296
 tests/ucon/test_unit.py,sha256=vEPOeSxFBqcRBAUczCN9KPo_dTmLk4LQExPSt6UGVa4,5712
 tests/ucon/test_units.py,sha256=248JZbo8RVvG_q3T0IhKG43vxM4F_2Xgf4_RjGZNsFM,704
 ucon/__init__.py,sha256=ZWWLodIiG17OgCfoAm532wpwmJzdRXlUGX3w6OBxFeQ,1743
-ucon/core.py,sha256=is6cgQ7iwYo6_41S1b9VOydMFlN_kDtfbyH224Vjjcw,12463
+ucon/core.py,sha256=QI0aayUm0rgggdD7_zvdrmV26dbEARCJ6Yj5gn5PitI,13729
 ucon/dimension.py,sha256=uUP05bPE8r15oFeD36DrclNIfBsugV7uFhvtJRYy4qI,6598
 ucon/unit.py,sha256=KxOBcQNxciljGskhZCfktLhRF5u-rWgrTg565Flo3eI,3213
 ucon/units.py,sha256=e1j7skYMghlMZi7l94EAgxq4_lNRDC7FcSooJoE_U50,3689
-ucon-0.3.2rc6.dist-info/licenses/LICENSE,sha256=-Djjiq2wM8Cc6fzTsdMbr_T2_uaX6Yorxcemr3GGkqc,1072
-ucon-0.3.2rc6.dist-info/METADATA,sha256=Zax97Y5GOFBLD7OFIMNSpWYcz_TPEJ5tM7eLARPDrT8,10996
-ucon-0.3.2rc6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ucon-0.3.2rc6.dist-info/top_level.txt,sha256=zZYRJiQrVUtN32ziJD2YEq7ClSvDmVYHYy5ArRAZGxI,11
-ucon-0.3.2rc6.dist-info/RECORD,,
+ucon-0.3.3rc1.dist-info/licenses/LICENSE,sha256=-Djjiq2wM8Cc6fzTsdMbr_T2_uaX6Yorxcemr3GGkqc,1072
+ucon-0.3.3rc1.dist-info/METADATA,sha256=j9qlRr2LbkyV4WbRFcMjfMSI_hOEujAHb5iBGHO-g0Y,10606
+ucon-0.3.3rc1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ucon-0.3.3rc1.dist-info/top_level.txt,sha256=zZYRJiQrVUtN32ziJD2YEq7ClSvDmVYHYy5ArRAZGxI,11
+ucon-0.3.3rc1.dist-info/RECORD,,