ucon 0.3.1rc3__py3-none-any.whl → 0.3.2__py3-none-any.whl

tests/ucon/test_core.py

@@ -105,6 +105,7 @@ class TestScale(TestCase):
         self.assertEqual(Scale.deca, Scale.kilo / Scale.hecto)
         self.assertEqual(Scale._kibi, Scale.one / Scale.kibi)
         self.assertEqual(Scale.kibi, Scale.kibi / Scale.one)
+        self.assertEqual(Scale.one, Scale.one / Scale.one)
         self.assertEqual(Scale.one, Scale.kibi / Scale.kibi)
         self.assertEqual(Scale.one, Scale.kibi / Scale.kilo)
 
@@ -120,6 +121,92 @@ class TestScale(TestCase):
         self.assertIsInstance(Scale.all(), dict)
 
 
+class TestScaleDivisionAdditional(TestCase):
+
+    def test_division_same_base_large_gap(self):
+        # kilo / milli = mega
+        self.assertEqual(Scale.kilo / Scale.milli, Scale.mega)
+        # milli / kilo = micro
+        self.assertEqual(Scale.milli / Scale.kilo, Scale.micro)
+
+    def test_division_cross_base_scales(self):
+        # Decimal vs binary cross-base — should return nearest matching scale
+        result = Scale.kilo / Scale.kibi
+        self.assertIsInstance(result, Scale)
+        # They’re roughly equal, so nearest should be Scale.one
+        self.assertEqual(result, Scale.one)
+
+    def test_division_binary_inverse_scales(self):
+        self.assertEqual(Scale.kibi / Scale.kibi, Scale.one)
+        self.assertEqual(Scale.kibi / Scale.mebi, Scale._kibi)
+        self.assertEqual(Scale.mebi / Scale.kibi, Scale.kibi)
+
+    def test_division_unmatched_returns_nearest(self):
+        # giga / kibi is a weird combo → nearest mega or similar
+        result = Scale.giga / Scale.kibi
+        self.assertIsInstance(result, Scale)
+        self.assertIn(result, Scale)
+
+    def test_division_type_safety(self):
+        # Ensure non-Scale raises NotImplemented
+        with self.assertRaises(TypeError):
+            Scale.kilo / 42
+
+
+class TestScaleNearestAdditional(TestCase):
+
+    def test_nearest_handles_zero(self):
+        self.assertEqual(Scale.nearest(0), Scale.one)
+
+    def test_nearest_handles_negative_values(self):
+        # Only magnitude matters, not sign
+        self.assertEqual(Scale.nearest(-1000), Scale.kilo)
+        self.assertEqual(Scale.nearest(-0.001), Scale.milli)
+
+    def test_nearest_with_undershoot_bias_effect(self):
+        # Lower bias should make undershoot (ratios < 1) less penalized
+        # This test ensures the bias argument doesn’t break ordering
+        s_default = Scale.nearest(50_000, undershoot_bias=0.75)
+        s_stronger_bias = Scale.nearest(50_000, undershoot_bias=0.9)
+        # The result shouldn't flip to something wildly different
+        self.assertIn(s_default, [Scale.kilo, Scale.mega])
+        self.assertIn(s_stronger_bias, [Scale.kilo, Scale.mega])
+
+    def test_nearest_respects_binary_preference_flag(self):
+        # Confirm that enabling binary changes candidate set
+        decimal_result = Scale.nearest(2**10)
+        binary_result = Scale.nearest(2**10, include_binary=True)
+        self.assertNotEqual(decimal_result, binary_result)
+        self.assertEqual(binary_result, Scale.kibi)
+
+    def test_nearest_upper_and_lower_extremes(self):
+        self.assertEqual(Scale.nearest(10**9), Scale.giga)
+        self.assertEqual(Scale.nearest(10**-9), Scale.nano)
+
+
+class TestScaleInternals(TestCase):
+
+    def test_decimal_and_binary_sets_are_disjoint(self):
+        decimal_bases = {s.value.base for s in Scale._decimal_scales()}
+        binary_bases = {s.value.base for s in Scale._binary_scales()}
+        self.assertNotEqual(decimal_bases, binary_bases)
+        self.assertEqual(decimal_bases, {10})
+        self.assertEqual(binary_bases, {2})
+
+    def test_all_and_by_value_consistency(self):
+        mapping = Scale.all()
+        value_map = Scale.by_value()
+        # Each value’s evaluated form should appear in by_value keys
+        for (base, power), name in mapping.items():
+            val = Scale[name].value.evaluated
+            self.assertIn(round(val, 15), value_map)
+
+    def test_all_and_by_value_are_cached(self):
+        # Call multiple times and ensure they’re same object (cached)
+        self.assertIs(Scale.all(), Scale.all())
+        self.assertIs(Scale.by_value(), Scale.by_value())
+
+
 class TestNumber(TestCase):
 
     number = Number(unit=units.gram, quantity=1)
@@ -288,6 +375,21 @@ class TestExponentEdgeCases(TestCase):
 
 class TestScaleEdgeCases(TestCase):
 
+    def test_nearest_prefers_decimal_by_default(self):
+        self.assertEqual(Scale.nearest(1024), Scale.kilo)
+        self.assertEqual(Scale.nearest(50_000), Scale.kilo)
+        self.assertEqual(Scale.nearest(1/1024), Scale.milli)
+
+    def test_nearest_includes_binary_when_opted_in(self):
+        self.assertEqual(Scale.nearest(1/1024, include_binary=True), Scale._kibi)
+        self.assertEqual(Scale.nearest(1024, include_binary=True), Scale.kibi)
+        self.assertEqual(Scale.nearest(50_000, include_binary=True), Scale.kibi)
+        self.assertEqual(Scale.nearest(2**20, include_binary=True), Scale.mebi)
+
+    def test_nearest_subunit_behavior(self):
+        self.assertEqual(Scale.nearest(0.0009), Scale.milli)
+        self.assertEqual(Scale.nearest(1e-7), Scale.micro)
+
     def test_division_same_base_scales(self):
         result = Scale.kilo / Scale.milli
         self.assertIsInstance(result, Scale)

ucon/core.py

@@ -16,10 +16,10 @@ Together, these classes allow full arithmetic, conversion, and introspection
 of physical quantities with explicit dimensional semantics.
 """
 from enum import Enum
-from functools import reduce, total_ordering
+from functools import lru_cache, reduce, total_ordering
 from math import log2
 from math import log10
-from typing import Tuple, Union
+from typing import Dict, Tuple, Union
 
 from ucon import units
 from ucon.unit import Unit
@@ -131,8 +131,10 @@ class Scale(Enum):
 
     Each entry stores its numeric scaling factor (e.g., `kilo = 10³`).
     """
+    gibi  = Exponent(2, 30)
     mebi  = Exponent(2, 20)
     kibi  = Exponent(2, 10)
+    giga  = Exponent(10, 9)
     mega  = Exponent(10, 6)
     kilo  = Exponent(10, 3)
     hecto = Exponent(10, 2)
@@ -142,43 +144,101 @@ class Scale(Enum):
     centi = Exponent(10,-2)
     milli = Exponent(10,-3)
     micro = Exponent(10,-6)
-    _kibi = Exponent(2,-10)
-    _mebi = Exponent(2,-20)
+    nano = Exponent(10,-9)
+    _kibi = Exponent(2,-10)   # "kibi" inverse
+    _mebi = Exponent(2,-20)   # "mebi" inverse
+    _gibi = Exponent(2,-30)   # "gibi" inverse
 
     @staticmethod
-    def all():
-        return dict(map(lambda x: ((x.value.base, x.value.power), x.name), Scale))
+    @lru_cache(maxsize=1)
+    def all() -> Dict[Tuple[int, int], str]:
+        """Return a map from (base, power) → Scale name."""
+        return {(s.value.base, s.value.power): s.name for s in Scale}
 
     @staticmethod
-    def by_value():
-        return dict(map(lambda x: (x.value.evaluated, x.name), Scale))
+    @lru_cache(maxsize=1)
+    def by_value() -> Dict[float, str]:
+        """
+        Return a map from evaluated numeric value → Scale name.
+        Cached after first access.
+        """
+        return {round(s.value.evaluated, 15): s.name for s in Scale}
+
+    @classmethod
+    @lru_cache(maxsize=1)
+    def _decimal_scales(cls):
+        """Return decimal (base-10) scales only."""
+        return list(s for s in cls if s.value.base == 10)
+
+    @classmethod
+    @lru_cache(maxsize=1)
+    def _binary_scales(cls):
+        """Return binary (base-2) scales only."""
+        return list(s for s in cls if s.value.base == 2)
+
+    @classmethod
+    def nearest(cls, value: float, include_binary: bool = False, undershoot_bias: float = 0.75) -> "Scale":
+        """
+        Return the Scale that best normalizes `value` toward 1 in log-space.
+        Optionally restricts to base-10 prefixes unless `include_binary=True`.
+        """
+        if value == 0:
+            return Scale.one
+
+        abs_val = abs(value)
+        candidates = cls._decimal_scales() if not include_binary else list(cls)
+
+        def distance(scale: "Scale") -> float:
+            ratio = abs_val / scale.value.evaluated
+            diff = log10(ratio)
+            # Bias overshoots slightly more than undershoots
+            if ratio < 1:
+                diff /= undershoot_bias
+            return abs(diff)
+
+        return min(candidates, key=distance)
 
-    def __truediv__(self, another_scale):
-        power_diff = self.value.power - another_scale.value.power
-        if self.value == another_scale.value:
+    def __truediv__(self, other: 'Scale'):
+        """
+        Divide one Scale by another.
+
+        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 == other:
             return Scale.one
-        if self.value.base == another_scale.value.base:
-            return Scale[Scale.all()[Exponent(self.value.base, power_diff).parts()]]
 
-        base_quotient = self.value.base / another_scale.value.base
-        exp_quotient = round((base_quotient ** another_scale.value.power) * (self.value.base ** power_diff), 15)
+        if other is Scale.one:
+            return self
+
+        should_consider_binary = (self.value.base == 2) or (other.value.base == 2)
+
+        if self is Scale.one:
+            result = Exponent(other.value.base, -other.value.power)
+            name = Scale.all().get((result.base, result.power))
+            if name:
+                return Scale[name]
+            return Scale.nearest(float(result), include_binary=should_consider_binary)
 
-        if Scale.one in [self, another_scale]:
-            power = Exponent.bases[2](exp_quotient)
-            return Scale[Scale.all()[Exponent(2, int(power)).parts()]]
+        result: Union[Exponent, float] = self.value / other.value
+        if isinstance(result, Exponent):
+            match = Scale.all().get(result.parts())
+            if match:
+                return Scale[match]
         else:
-            scale_exp_values = [Scale[Scale.all()[pair]].value.evaluated for pair in Scale.all().keys()]
-            closest_val = min(scale_exp_values, key=lambda val: abs(val - exp_quotient))
-            return Scale[Scale.by_value()[closest_val]]
+            return Scale.nearest(float(result), include_binary=should_consider_binary)
 
-    def __lt__(self, another_scale):
-        return self.value < another_scale.value
+    def __lt__(self, other: 'Scale'):
+        return self.value < other.value
 
-    def __gt__(self, another_scale):
-        return self.value > another_scale.value
+    def __gt__(self, other: 'Scale'):
+        return self.value > other.value
 
-    def __eq__(self, another_scale):
-        return self.value == another_scale.value
+    def __eq__(self, other: 'Scale'):
+        return self.value == other.value
 
 
 # TODO -- consider using a dataclass

{ucon-0.3.1rc3.dist-info → ucon-0.3.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.3.1rc3
+Version: 0.3.2
 Summary: a tool for dimensional analysis: a "Unit CONverter"
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi
@@ -82,7 +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:
 
-![Alt text](https://private-user-images.githubusercontent.com/7152453/505356617-0de63681-8c46-41d5-a0bf-a859ca9ab81b.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NjEzMjAzMjksIm5iZiI6MTc2MTMyMDAyOSwicGF0aCI6Ii83MTUyNDUzLzUwNTM1NjYxNy0wZGU2MzY4MS04YzQ2LTQxZDUtYTBiZi1hODU5Y2E5YWI4MWIucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI1MTAyNCUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNTEwMjRUMTUzMzQ5WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9MzdhYjNiYjlmYTRlNDBiNzdkY2YxNzJiODU1ZGEwNGM2ZThlZGQ4MTc2OTgyY2Y1NWMxNjZhYzViMDg2MmY4NiZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QifQ.aQz0gq_44Yygw4wTMe3bER2xR6NiVM7Yb_rFIimD2hM "Data Model Diagram")
+<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.1rc3.dist-info → ucon-0.3.2.dist-info}/RECORD

@@ -1,15 +1,15 @@
 tests/ucon/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-tests/ucon/test_core.py,sha256=fD4c6K35RxCyaR5pHqBSr8DEHTqmMvYX9ZuVS6JdSwo,16408
+tests/ucon/test_core.py,sha256=rpKCH5olc9EI0tPXuiGXRlEfMFnsFGJ-Ntrn-ZV34fY,20854
 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=DRymayBlXfVZMSHIt_Hi-xe8GPs9WYHOCCJ1QDaKn7Q,10643
+ucon/core.py,sha256=is6cgQ7iwYo6_41S1b9VOydMFlN_kDtfbyH224Vjjcw,12463
 ucon/dimension.py,sha256=uUP05bPE8r15oFeD36DrclNIfBsugV7uFhvtJRYy4qI,6598
 ucon/unit.py,sha256=KxOBcQNxciljGskhZCfktLhRF5u-rWgrTg565Flo3eI,3213
 ucon/units.py,sha256=e1j7skYMghlMZi7l94EAgxq4_lNRDC7FcSooJoE_U50,3689
-ucon-0.3.1rc3.dist-info/licenses/LICENSE,sha256=-Djjiq2wM8Cc6fzTsdMbr_T2_uaX6Yorxcemr3GGkqc,1072
-ucon-0.3.1rc3.dist-info/METADATA,sha256=2RSmsE3LJM-isu7H89QzDGupZG04123OMN_FMsoPWvQ,11214
-ucon-0.3.1rc3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ucon-0.3.1rc3.dist-info/top_level.txt,sha256=zZYRJiQrVUtN32ziJD2YEq7ClSvDmVYHYy5ArRAZGxI,11
-ucon-0.3.1rc3.dist-info/RECORD,,
+ucon-0.3.2.dist-info/licenses/LICENSE,sha256=-Djjiq2wM8Cc6fzTsdMbr_T2_uaX6Yorxcemr3GGkqc,1072
+ucon-0.3.2.dist-info/METADATA,sha256=2fLCgE7B-OlfN1fIOWI_B4JUxJBJAE9HDYph6JDyeFQ,10603
+ucon-0.3.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ucon-0.3.2.dist-info/top_level.txt,sha256=zZYRJiQrVUtN32ziJD2YEq7ClSvDmVYHYy5ArRAZGxI,11
+ucon-0.3.2.dist-info/RECORD,,