cooptools 1.76__tar.gz → 1.77__tar.gz

{cooptools-1.76 → cooptools-1.77}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cooptools
-Version: 1.76
+Version: 1.77
 Summary: Generic Tooling
 Home-page: https://github.com/tylertjburns/cooptools
 Author: tburns

cooptools-1.77/cooptools/currency.py

@@ -0,0 +1,154 @@
+import dataclasses
+from dataclasses import dataclass, asdict
+from decimal import Decimal, ROUND_HALF_UP
+
+CENTS_PER_DOLLAR = 100
+_CENT = Decimal('0.01')
+
+@dataclass(frozen=True, slots=True)
+class USD:
+    dollars: int
+    cents: int
+
+    def __post_init__(self):
+        """ Canonicalizes to a single representation per amount so that equality and hashing agree
+        with value. Both fields carry the sign of the total, and cents always lands in (-100, 100)."""
+        total_cents = self.dollars * CENTS_PER_DOLLAR + self.cents
+        sign = -1 if total_cents < 0 else 1
+        dollars, cents = divmod(abs(total_cents), CENTS_PER_DOLLAR)
+        object.__setattr__(self, "dollars", sign * dollars)
+        object.__setattr__(self, "cents", sign * cents)
+
+    @classmethod
+    def zero(cls):
+        return USD(dollars=0, cents=0)
+
+    @classmethod
+    def from_val(cls, val: float | str | int | Decimal):
+        if isinstance(val, USD):
+            return val
+
+        # bool is a subclass of int, but a truth value is never an amount of money
+        if isinstance(val, bool):
+            raise TypeError(f'{val} [{type(val)}] not supported to be converted to CurrencySchema')
+
+        if isinstance(val, float):
+            # str() of a float is the shortest repr that round-trips, which recovers the decimal
+            # the caller actually meant rather than the binary approximation stored for it
+            dec = Decimal(str(val))
+        elif isinstance(val, (str, int, Decimal)):
+            dec = Decimal(val)
+        else:
+            raise TypeError(f'{val} [{type(val)}] not supported to be converted to CurrencySchema')
+
+        total_cents = int((dec * CENTS_PER_DOLLAR).to_integral_value(rounding=ROUND_HALF_UP))
+        return USD(dollars=0, cents=total_cents)
+
+    @property
+    def AmountAsDecimal(self) -> Decimal:
+        """ The exact value. This is what should cross a persistence or numeric boundary
+        (SQLAlchemy Numeric, pandas, arithmetic outside this class)."""
+        return (Decimal(self.dollars * CENTS_PER_DOLLAR + self.cents) / CENTS_PER_DOLLAR).quantize(_CENT)
+
+    @property
+    def AmountFloated(self) -> float:
+        return float(self.AmountAsDecimal)
+
+    @classmethod
+    def verify_val(cls, val):
+        if isinstance(val, (float, int, str, Decimal)) and not isinstance(val, bool):
+            val = USD.from_val(val)
+
+        if not isinstance(val, USD):
+            raise NotImplementedError(f"{val} is not of type [{USD}]")
+
+        return val
+
+    def __add__(self, other):
+        other = self.verify_val(other)
+        return USD(dollars=self.dollars + other.dollars,
+                   cents=self.cents + other.cents)
+
+    def __radd__(self, other):
+        return self.__add__(other)
+
+    def __sub__(self, other):
+        other = self.verify_val(other)
+        return USD(dollars=self.dollars - other.dollars,
+                   cents=self.cents - other.cents)
+
+    def __rsub__(self, other):
+        return self.verify_val(other).__sub__(self)
+
+    def __mul__(self, other):
+        if isinstance(other, bool) or not isinstance(other, (int, float, Decimal)):
+            raise NotImplementedError(f"type {type(other)} cannot be multipled with [{USD}]")
+
+        factor = Decimal(str(other)) if isinstance(other, float) else Decimal(other)
+        return USD.from_val(self.AmountAsDecimal * factor)
+
+    def __rmul__(self, other):
+        return self.__mul__(other)
+
+    def __truediv__(self, other):
+        # dividing two amounts yields a dimensionless ratio rather than money, and callers feed it
+        # into ordinary float math
+        if isinstance(other, USD):
+            return float(self.AmountAsDecimal / other.AmountAsDecimal)
+
+        if isinstance(other, bool) or not isinstance(other, (int, float, Decimal)):
+            raise NotImplementedError(f"cannot divide [{USD}] by type {type(other)} ")
+
+        divisor = Decimal(str(other)) if isinstance(other, float) else Decimal(other)
+        return USD.from_val(self.AmountAsDecimal / divisor)
+
+    def __gt__(self, other):
+        return self.AmountAsDecimal > self.verify_val(other).AmountAsDecimal
+
+    def __lt__(self, other):
+        return self.AmountAsDecimal < self.verify_val(other).AmountAsDecimal
+
+    def __ge__(self, other):
+        return not self.__lt__(other)
+
+    def __le__(self, other):
+        return not self.__gt__(other)
+
+    def __str__(self):
+        return "${:,.2f}".format(self.AmountAsDecimal)
+
+    def __format__(self, format_spec):
+        """ An empty spec gives the currency-decorated str(); any other spec formats the underlying
+        decimal, so "{:,.2f}".format(usd) behaves the way callers expect of a numeric type."""
+        if format_spec == "":
+            return str(self)
+        return format(self.AmountAsDecimal, format_spec)
+
+    def __neg__(self):
+        return USD(dollars=-self.dollars, cents=-self.cents)
+
+    def __abs__(self):
+        return USD(dollars=abs(self.dollars), cents=abs(self.cents))
+
+    def __bool__(self):
+        return self.dollars != 0 or self.cents != 0
+
+    def __float__(self):
+        return self.AmountFloated
+
+    def to_dict(self):
+        return asdict(self)
+
+
+if __name__ == "__main__":
+    a = USD.from_val(1.5)
+    b = USD.from_val(3.5)
+    d = USD(1, 250)
+    c = a + b
+    print(c)
+    print(d)
+    print(d.dollars, d.cents)
+    e = d + c
+    print(e, e.dollars, e.cents)
+    print(e.to_dict())
+    print(dataclasses.asdict(e))

{cooptools-1.76 → cooptools-1.77}/cooptools.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cooptools
-Version: 1.76
+Version: 1.77
 Summary: Generic Tooling
 Home-page: https://github.com/tylertjburns/cooptools
 Author: tburns

{cooptools-1.76 → cooptools-1.77}/setup.py

@@ -7,7 +7,7 @@ with open('requirements.txt') as f:
     requirements = f.read().splitlines()
 
 setuptools.setup(name='cooptools',
-      version='1.76',
+      version='1.77',
       description='Generic Tooling',
       url='https://github.com/tylertjburns/cooptools',
       author='tburns',

cooptools-1.77/tests/test_currency.py

@@ -0,0 +1,116 @@
+import unittest
+from decimal import Decimal
+from cooptools.currency import USD
+class TestUSD(unittest.TestCase):
+    def test_usd_initialization(self):
+        usd = USD(5, 150)
+        self.assertEqual(usd.dollars, 6)
+        self.assertEqual(usd.cents, 50)
+
+    def test_usd_from_val(self):
+        self.assertEqual(USD.from_val(5.75), USD(5, 75))
+        self.assertEqual(USD.from_val("3.20"), USD(3, 20))
+        self.assertEqual(USD.from_val(2), USD(2, 0))
+
+    def test_usd_addition(self):
+        self.assertEqual(USD(3, 50) + USD(2, 75), USD(6, 25))
+        self.assertEqual(USD(1, 90) + 0.15, USD(2, 5))
+
+    def test_usd_subtraction(self):
+        self.assertEqual(USD(5, 50) - USD(2, 25), USD(3, 25))
+        self.assertEqual(USD(2, 10) - 1.05, USD(1, 5))
+
+    def test_usd_multiplication(self):
+        self.assertEqual(USD(3, 50) * 2, USD(7, 0))
+        self.assertEqual(USD(2, 25) * 3, USD(6, 75))
+
+    def test_usd_division(self):
+        self.assertEqual(USD(5, 0) / 2, USD(2, 50))
+        self.assertAlmostEqual(USD(10, 0) / USD(2, 0), 5.0)
+
+    def test_usd_division__by_usd_yields_a_float_ratio(self):
+        ratio = USD(10, 0) / USD(4, 0)
+        self.assertIsInstance(ratio, float)
+        self.assertEqual(ratio * 2.0, 5.0)
+
+    def test_usd_from_val__every_cent_round_trips(self):
+        """ Values whose binary float lands just under the cent boundary (0.29 -> 28.999...)
+        must not truncate down a cent."""
+        mismatches = [total_cents / 100
+                      for total_cents in range(-100000, 100001)
+                      if USD.from_val(total_cents / 100).AmountAsDecimal != Decimal(total_cents) / 100]
+        self.assertEqual(mismatches[:10], [], f"{len(mismatches)} values did not round-trip")
+
+    def test_usd_from_val__known_truncation_cases(self):
+        for val, expected in [(0.29, USD(0, 29)),
+                              (0.57, USD(0, 57)),
+                              (1.13, USD(1, 13)),
+                              (2.01, USD(2, 1)),
+                              (48.15, USD(48, 15))]:
+            with self.subTest(val=val):
+                self.assertEqual(USD.from_val(val), expected)
+
+    def test_usd_from_val__negative(self):
+        self.assertEqual(USD.from_val(-0.29), USD(0, -29))
+        self.assertEqual(USD.from_val(-48.15), USD(-48, -15))
+        self.assertEqual(USD.from_val(-48.15).AmountAsDecimal, Decimal("-48.15"))
+
+    def test_usd_from_val__decimal_and_usd_passthrough(self):
+        self.assertEqual(USD.from_val(Decimal("12.34")), USD(12, 34))
+        self.assertEqual(USD.from_val(USD(12, 34)), USD(12, 34))
+
+    def test_usd_from_val__rejects_bool(self):
+        self.assertRaises(TypeError, lambda: USD.from_val(True))
+
+    def test_usd_normalization__equality_and_hash_agree_with_value(self):
+        self.assertEqual(USD(0, 100), USD(1, 0))
+        self.assertEqual(hash(USD(0, 100)), hash(USD(1, 0)))
+        self.assertEqual(USD(1, -150), USD(0, -50))
+        self.assertEqual(hash(USD(1, -150)), hash(USD(0, -50)))
+
+    def test_usd_normalization__sign_is_consistent_across_both_fields(self):
+        neg = USD(0, -150)
+        self.assertEqual(neg.dollars, -1)
+        self.assertEqual(neg.cents, -50)
+
+    def test_usd_subtraction__crossing_below_negative_one_dollar(self):
+        self.assertEqual(USD(1, 0) - USD(2, 50), USD(-1, -50))
+        self.assertEqual((USD(1, 0) - USD(2, 50)).AmountAsDecimal, Decimal("-1.50"))
+
+    def test_usd_amount_as_decimal__is_exact_and_two_places(self):
+        self.assertEqual(USD(48, 15).AmountAsDecimal, Decimal("48.15"))
+        self.assertEqual(str(USD(1, 0).AmountAsDecimal), "1.00")
+
+    def test_usd_accumulation_is_exact(self):
+        """ The float-accumulation drift that motivated this type: bare float += lands on
+        107.60999999999999, so a request to move 107.61 reads as more than the balance."""
+        total = USD.zero()
+        for v in [15.04, 33.11, 22.83, 36.63]:
+            total = total + v
+        self.assertEqual(total, USD.from_val(107.61))
+        self.assertFalse(USD.from_val(107.61) > total)
+
+    def test_usd_format(self):
+        self.assertEqual("{:,.2f}".format(USD(1234, 56)), "1,234.56")
+        self.assertEqual("{}".format(USD(1234, 56)), "$1,234.56")
+        self.assertEqual(f"{USD(1234, 56)}", "$1,234.56")
+
+    def test_usd_bool(self):
+        self.assertFalse(USD.zero())
+        self.assertTrue(USD(0, 1))
+
+    def test_usd_comparisons(self):
+        self.assertTrue(USD(1, 0) > USD(0, 99))
+        self.assertTrue(USD(0, 99) < USD(1, 0))
+        self.assertTrue(USD(1, 0) >= USD(1, 0))
+        self.assertTrue(USD(1, 0) <= USD(1, 0))
+        self.assertTrue(USD(0, -50) < USD.zero())
+
+    def test_usd_rsub(self):
+        self.assertEqual(5.00 - USD(2, 25), USD(2, 75))
+
+    def test_usd_abs(self):
+        self.assertEqual(abs(USD(-1, -50)), USD(1, 50))
+
+if __name__ == "__main__":
+    unittest.main()

cooptools-1.76/cooptools/currency.py

@@ -1,134 +0,0 @@
-import dataclasses
-import math
-from dataclasses import dataclass, asdict
-
-@dataclass(frozen=True, slots=True)
-class USD:
-    dollars: int
-    cents: int
-
-    def __post_init__(self):
-        if self.cents > 100:
-            object.__setattr__(self, "dollars", self.dollars + self.cents // 100)
-            object.__setattr__(self, 'cents', self.cents % 100)
-
-    @classmethod
-    def zero(cls):
-        return USD(dollars=0, cents=0)
-
-    @classmethod
-    def from_val(cls, val: float|str|int):
-        if isinstance(val, str):
-            val = float(val)
-
-        if not isinstance(val, (float, int)):
-            raise TypeError(f'{val} [{type(val)}] not supported to be converted to CurrencySchema')
-
-        dollars = int(val)
-        cents = int(val * 100 - dollars * 100) # Weird multiplcation to avoid float issues
-
-        return USD(dollars=dollars, cents=cents)
-
-    @property
-    def AmountFloated(self) -> float:
-        return self.dollars + round(self.cents / 100, 2)
-
-    @classmethod
-    def verify_val(cls, val):
-        if type(val) in [float, int, str]:
-            val = USD.from_val(val)
-
-        if type(val) != USD:
-            raise NotImplementedError(f"{val} is not of type [{USD}]")
-
-        return val
-
-    def __add__(self, other):
-        other = self.verify_val(other)
-
-        dollars = self.dollars + other.dollars
-        cents = self.cents + other.cents
-
-        if cents >= 100:
-            cent_dols = math.floor(cents / 100)
-            cents = cents % 100
-            dollars += cent_dols
-
-        if cents < 0:
-            factor = math.ceil(- cents / 100)
-            dollars -= 1 * factor
-            cents += 100 * factor
-
-        return USD(dollars=dollars, cents=cents)
-
-    def __radd__(self, other):
-        return self.__add__(other)
-
-    def __sub__(self, other):
-        other = self.verify_val(other)
-
-        dollars = self.dollars - other.dollars
-        cents = self.cents - other.cents
-
-        if cents > -100:
-            cent_dols = math.floor(cents / 100)
-            cents = cents % 100
-            dollars += cent_dols
-        return USD(dollars=dollars, cents=cents)
-
-    def __mul__(self, other):
-        if type(other) not in [int, float]:
-            raise NotImplementedError(f"type {type(other)} cannot be multipled with [{USD}]")
-
-        return USD.from_val(float(self) * other)
-
-    def __rmul__(self, other):
-        return self.__mul__(other)
-
-    def __truediv__(self, other):
-        if type(other) in [int, float]:
-            return USD.from_val(float(self) / float(other))
-        if isinstance(other, USD):
-            return float(self) / float(other)
-
-        raise NotImplementedError(f"cannot divide [{USD}] by type {type(other)} ")
-
-
-
-    def __gt__(self, other):
-        return (self - other).AmountFloated > 0
-
-    def __lt__(self, other):
-        return (other - self).AmountFloated > 0
-
-    def __ge__(self, other):
-        return not self.__lt__(other)
-
-    def __le__(self, other):
-        return not self.__gt__(other)
-
-    def __str__(self):
-        return "${:,.2f}".format(self.AmountFloated)
-
-    def __neg__(self):
-        return USD(dollars=-self.dollars, cents=-self.cents)
-
-    def __float__(self):
-        return self.AmountFloated
-
-    def to_dict(self):
-        return asdict(self)
-
-
-if __name__ == "__main__":
-    a = USD.from_val(1.5)
-    b = USD.from_val(3.5)
-    d = USD(1, 250)
-    c = a + b
-    print(c)
-    print(d)
-    print(d.dollars, d.cents)
-    e = d + c
-    print(e, e.dollars, e.cents)
-    print(e.to_dict())
-    print(dataclasses.asdict(e))

cooptools-1.76/tests/test_currency.py

@@ -1,31 +0,0 @@
-import unittest
-from cooptools.currency import USD
-class TestUSD(unittest.TestCase):
-    def test_usd_initialization(self):
-        usd = USD(5, 150)
-        self.assertEqual(usd.dollars, 6)
-        self.assertEqual(usd.cents, 50)
-
-    def test_usd_from_val(self):
-        self.assertEqual(USD.from_val(5.75), USD(5, 75))
-        self.assertEqual(USD.from_val("3.20"), USD(3, 20))
-        self.assertEqual(USD.from_val(2), USD(2, 0))
-
-    def test_usd_addition(self):
-        self.assertEqual(USD(3, 50) + USD(2, 75), USD(6, 25))
-        self.assertEqual(USD(1, 90) + 0.15, USD(2, 5))
-
-    def test_usd_subtraction(self):
-        self.assertEqual(USD(5, 50) - USD(2, 25), USD(3, 25))
-        self.assertEqual(USD(2, 10) - 1.05, USD(1, 5))
-
-    def test_usd_multiplication(self):
-        self.assertEqual(USD(3, 50) * 2, USD(7, 0))
-        self.assertEqual(USD(2, 25) * 3, USD(6, 75))
-
-    def test_usd_division(self):
-        self.assertEqual(USD(5, 0) / 2, USD(2, 50))
-        self.assertAlmostEqual(USD(10, 0) / USD(2, 0), 5.0)
-
-if __name__ == "__main__":
-    unittest.main()