cooptools 1.76__tar.gz → 1.78__tar.gz

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

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

cooptools-1.78/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.78/cooptools/expertise/__init__.py

@@ -0,0 +1,6 @@
+from cooptools.expertise.expertiseArgs import *
+from cooptools.expertise.expertiseSchedules import *
+from cooptools.expertise.expertise_state import (
+    expertise_from_state,
+    expertise_to_state,
+)

cooptools-1.78/cooptools/expertise/expertise_state.py

@@ -0,0 +1,58 @@
+"""Expertise across the JSON boundary.
+
+Beside the calculator it serializes rather than in a persistence package, because
+what these two functions know about is *expertise* -- which accumulator holds the
+truth and which views are derived -- and only incidentally that the destination is
+JSON. Grouped by mechanism they would sit next to enum conversion, which they have
+nothing in common with; grouped by subject they sit next to the thing that breaks
+them when it changes.
+
+Functions over `ExpertiseCalculator` rather than methods on it, so that reading
+and writing its state is available without widening the calculator's own API.
+
+Deliberately asymmetric, and worth knowing why:
+
+- Reading has to reach `_expertise_args`, because the calculator exposes only
+  derived views (`PercExpert`, `CurrentTimeReductionPerc`) and neither can be
+  inverted back into the accumulator that produced it.
+- Writing does not, because `schedule` is public and the increments are public,
+  so a fresh calculator can be built and wound forward. That is also what makes
+  applying twice give the same answer as applying once -- incrementing an
+  existing calculator would accumulate instead of replace.
+
+The read is the half that would break if the calculator's internals moved, which
+is the argument for these eventually becoming methods on it.
+"""
+import logging
+from typing import Any, Dict
+
+from cooptools.expertise.expertiseSchedules import ExpertiseCalculator
+
+logger = logging.getLogger(__name__)
+
+
+def expertise_to_state(calculator: ExpertiseCalculator) -> Dict[str, Any]:
+    """The accumulators behind an expertise calculator.
+
+    The schedule is not written -- it is definition, rebuilt from tuning by
+    whatever constructs the calculator's owner.
+    """
+    args = calculator._expertise_args
+    return {'n_runs': args.n_runs,
+            'accumulated_s': args.accumulated_s,
+            'exp': args.exp}
+
+
+def expertise_from_state(state: Dict[str, Any],
+                         calculator: ExpertiseCalculator) -> ExpertiseCalculator:
+    """A calculator on `calculator`'s schedule, wound to the saved accumulators.
+
+    Returns a new instance rather than mutating: the caller reassigns, which is
+    what makes this replace rather than accumulate.
+    """
+    restored = ExpertiseCalculator(schedule=calculator.schedule)
+    saved = state or {}
+    restored.increment_n_runs(saved.get('n_runs', 0))
+    restored.increment_s_producting(saved.get('accumulated_s', 0))
+    restored.increment_exp(saved.get('exp', 0))
+    return restored

cooptools-1.78/cooptools/persistence/__init__.py

@@ -0,0 +1,36 @@
+"""Handing an object's state out and taking it back, without a base class.
+
+`Stateful` is a structural `typing.Protocol`, so a class conforms by having
+`to_state`/`apply_state` and importing nothing to do it. That is what lets a type
+in one package be persisted by another with no dependency edge pointing back --
+and it is why this belongs in a shared library rather than in whichever consumer
+happened to need it first.
+
+Alongside it is the conversion every state dict of any size ends up needing:
+enums as dict keys, because JSON keys must be strings.
+
+Conversions for a *particular* type live with that type instead --
+`cooptools.expertise.expertise_state` is the worked example. What those functions
+know is which of an expertise calculator's fields holds the truth and which are
+derived; that they happen to end up as JSON is incidental, and grouping them here
+would put them beside enum conversion, which they have nothing in common with.
+
+What is deliberately *not* here: anything about where state is written. A file
+format, a directory of saves, a version envelope around a whole document -- those
+are decisions about an application, not about an object handing over its state.
+"""
+from cooptools.persistence.stateful import (
+    StateDict,
+    StateError,
+    StateVersionError,
+    Stateful,
+    VERSION_KEY,
+    check_version,
+    version_of,
+)
+from cooptools.persistence.enum_state import (
+    enum_from_state,
+    enum_keyed_from_state,
+    enum_keyed_to_state,
+    enum_to_state,
+)

cooptools-1.78/cooptools/persistence/enum_state.py

@@ -0,0 +1,81 @@
+"""Enums across the JSON boundary.
+
+Most state blocks of any size carry at least one enum-keyed
+quantity map -- what a stockpile holds, what a villager carries, what a recipe
+costs -- and JSON has no enum and no non-string key. Left to each call site, that
+translation gets written seven ways: by `.value` in one place and `.name` in
+another, crashing on an unknown member here and silently dropping it there.
+
+**Names, not values.** A member's `name` is the thing the rest of the codebase
+already treats as its stable identity (log lines, config keys, file keys). Its
+`value` is frequently `auto()`, which renumbers the moment somebody inserts a
+member -- so a file written by value would read back as a *different* resource
+after an unrelated edit, with nothing to report it.
+"""
+import logging
+from enum import Enum
+from typing import Dict, Mapping, Optional, Type, TypeVar
+
+logger = logging.getLogger(__name__)
+
+E = TypeVar('E', bound=Enum)
+
+
+def enum_to_state(value: Optional[Enum]) -> Optional[str]:
+    """One enum member as its name, passing None through."""
+    return value.name if value is not None else None
+
+
+def enum_from_state(name: Optional[str], enum_cls: Type[E], *,
+                    owner: str = None) -> Optional[E]:
+    """One enum member back from its name.
+
+    An unknown name yields None with a warning rather than raising. A member
+    removed from the code between the write and the read is a real, expected event
+    during development, and it should cost the field rather than the file --
+    every caller already handles None for these (a region with no building, a
+    site with no target tier).
+    """
+    if name is None:
+        return None
+    try:
+        return enum_cls[name]
+    except KeyError:
+        logger.warning(f"{owner or enum_cls.__name__}: '{name}' is not a member of "
+                       f"{enum_cls.__name__} any more -- dropped")
+        return None
+
+
+def enum_keyed_to_state(quantities: Optional[Mapping[Enum, float]]) -> Dict[str, float]:
+    """An enum-keyed quantity map as a name-keyed one.
+
+    Written in the enum's own declaration order rather than the mapping's, so two
+    writes of the same state are byte-identical -- which is what lets a round-trip
+    test compare dicts, and lets two files diff usefully.
+    """
+    if not quantities:
+        return {}
+    members = sorted(quantities.keys(), key=lambda member: list(type(member)).index(member))
+    return {member.name: quantities[member] for member in members}
+
+
+def enum_keyed_from_state(quantities: Optional[Mapping[str, float]],
+                          enum_cls: Type[E], *,
+                          owner: str = None) -> Dict[E, float]:
+    """A name-keyed quantity map back to an enum-keyed one.
+
+    Unknown names are dropped with a warning, for the reason `enum_from_state`
+    gives -- but here the loss is quantified in the log, since goods vanishing
+    from a stockpile is the kind of thing that otherwise gets noticed as a
+    balance mystery three sessions later.
+    """
+    if not quantities:
+        return {}
+    result: Dict[E, float] = {}
+    for name, qty in quantities.items():
+        try:
+            result[enum_cls[name]] = qty
+        except KeyError:
+            logger.warning(f"{owner or enum_cls.__name__}: dropping {qty:g} of '{name}', "
+                           f"which is not a member of {enum_cls.__name__} any more")
+    return result

cooptools-1.78/cooptools/persistence/stateful.py

@@ -0,0 +1,148 @@
+"""The contract every persistable thing implements: hand out your state, and
+take it back.
+
+Deliberately a `typing.Protocol` rather than a base class, because conformance is
+*structural*: a class satisfies this by having the two methods, without importing
+anything from here. That is what lets a class in one package be persisted by
+another with no dependency edge pointing back -- which is the whole reason this
+is a library type rather than one belonging to whoever is doing the persisting.
+
+## State is not definition
+
+The split this protocol exists to enforce: **state is what use changed;
+definition is what built the object.** A production station is built from its
+recipe -- inputs, outputs, a timer callback, a schedule -- and *holds* the
+contents of its stores and how far its current run has got. Only the second half
+belongs in a state dict. The first half is reconstructed by whatever built the
+object the first time, from the same source it used then.
+
+Getting this line wrong in either direction is expensive. Persisting definition
+means a restored object silently pins yesterday's configuration and stops
+tracking the file it should be reading. Persisting too little means the object
+comes back subtly wrong, usually in a way nothing notices for a while.
+
+## Why `apply_state` mutates instead of `from_state` constructing
+
+Almost nothing worth persisting can be rebuilt from a dict alone. The objects
+that carry interesting state are usually constructed with injected collaborators
+-- providers, callbacks, the graph they read -- none of which survive a round trip
+through JSON. A `from_state` classmethod would force every one of them to grow a
+second construction path whose only caller is the loader.
+
+`apply_state` matches how a restore actually goes instead: the object graph is
+rebuilt the ordinary way, so everything exists with its collaborators already
+wired, and the saved state is then poured into objects that are otherwise ready to
+run.
+
+A leaf that genuinely owns nothing may additionally offer a `from_state`
+classmethod as a convenience. The protocol does not ask for one.
+
+## Versioning
+
+Each block carries its own `STATE_VERSION`, stamped under `VERSION_KEY`, and each
+`apply_state` is responsible for reading older shapes of its own block. Versioning
+per class rather than once for the whole file is what stops a new field on one
+class invalidating every file in existence -- and it keeps a migration next to the
+invariant it is migrating, which is the same reason the state lives on the object
+rather than in a central writer.
+"""
+import logging
+from typing import Any, ClassVar, Dict, Protocol, runtime_checkable
+
+logger = logging.getLogger(__name__)
+
+# A JSON-safe mapping: dicts, lists, strings, numbers, bools and None, and
+# nothing else. Enum keys are written as `.name` (see enum_state.py), and any
+# identity-bearing type -- a uuid, a graph Node -- is written as whatever stable
+# name addresses it, never as the object.
+StateDict = Dict[str, Any]
+
+# Where a block's own version lives. Short because it appears once per block, and
+# a file of any size holds a great many blocks.
+VERSION_KEY = "v"
+
+
+class StateError(ValueError):
+    """A state dict could not be read."""
+
+
+class StateVersionError(StateError):
+    """A state dict is a version this build does not understand."""
+
+
+@runtime_checkable
+class Stateful(Protocol):
+    """Hands out its own state, and takes it back.
+
+    Two things to know about checking conformance against this at runtime:
+
+    - **`isinstance` works and covers all three members**, `STATE_VERSION`
+      included, so a class that has the methods but never declared a version is
+      correctly refused.
+    - **`issubclass` raises `TypeError`** on every Python version, because this
+      protocol has a non-method member. Check an instance, never a class.
+
+    And what `isinstance` does *not* buy: `runtime_checkable` compares member
+    presence, never signatures. It catches a conformer that dropped or renamed a
+    member -- the realistic failure for a class in another package that never
+    imports this -- and says nothing about one that changed an argument.
+    """
+
+    STATE_VERSION: ClassVar[int]
+
+    def to_state(self) -> StateDict:
+        """This object's play-state, as JSON-safe primitives.
+
+        Must include `VERSION_KEY`. Must not include anything reconstructed by
+        whatever builds this object -- see the module docstring on state vs.
+        definition.
+        """
+        ...
+
+    def apply_state(self, state: StateDict) -> None:
+        """Adopts `state`, replacing whatever this object currently holds.
+
+        Called on an object that is fully constructed and wired to its
+        collaborators. Implementations replace rather than merge: applying a state
+        twice must leave the same result as applying it once, and a field absent
+        from `state` takes its documented default rather than whatever happened to
+        be there.
+        """
+        ...
+
+
+def version_of(state: StateDict) -> int:
+    """The version stamped on a state block.
+
+    Raises rather than defaulting: an unstamped block is either corrupt or predates
+    versioning, and both are cases where guessing a version reads the rest of the
+    block under rules it was not written to.
+    """
+    if VERSION_KEY not in state:
+        raise StateVersionError(
+            f"State block carries no '{VERSION_KEY}' -- it is corrupt, or was written "
+            f"before this block was versioned")
+    version = state[VERSION_KEY]
+    if not isinstance(version, int) or isinstance(version, bool):
+        raise StateVersionError(
+            f"State block's '{VERSION_KEY}' is {version!r}, which is not a version number")
+    return version
+
+
+def check_version(state: StateDict, *, owner: str, supported: int) -> int:
+    """Returns the block's version, refusing one this build cannot read.
+
+    `owner` names the class in the error, because a load failure often reaches a
+    user as a single line, and "which part of this file is too new" is the whole of
+    what they can act on.
+
+    A version *below* `supported` is returned rather than refused -- that is the
+    case `apply_state` migrates, and this function has no way to know whether it
+    can.
+    """
+    version = version_of(state)
+    if version > supported:
+        raise StateVersionError(
+            f"{owner} state is version {version}, but this build understands up to "
+            f"{supported} -- it was written by a newer build")
+    return version

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

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

{cooptools-1.76 → cooptools-1.78}/cooptools.egg-info/SOURCES.txt

@@ -61,6 +61,7 @@ cooptools/dataStore/inMemoryDataStore.py
 cooptools/expertise/__init__.py
 cooptools/expertise/expertiseArgs.py
 cooptools/expertise/expertiseSchedules.py
+cooptools/expertise/expertise_state.py
 cooptools/finance/__init__.py
 cooptools/finance/dicounted_cashflow_analysis.py
 cooptools/finance/fund_projection.py
@@ -114,6 +115,9 @@ cooptools/pathing/waypoint.py
 cooptools/pathing/waypointFollower.py
 cooptools/pathing/demo/__init__.py
 cooptools/pathing/demo/server.py
+cooptools/persistence/__init__.py
+cooptools/persistence/enum_state.py
+cooptools/persistence/stateful.py
 cooptools/physics/__init__.py
 cooptools/physics/kinematic.py
 cooptools/physics/kinematic_utils.py
@@ -160,6 +164,7 @@ tests/test_coopEnum.py
 tests/test_currency.py
 tests/test_curves.py
 tests/test_date_utils.py
+tests/test_expertise_state.py
 tests/test_flow_field.py
 tests/test_flow_field_perf.py
 tests/test_fund_projection.py
@@ -169,6 +174,7 @@ tests/test_kinematic_utils.py
 tests/test_os_manip.py
 tests/test_pandas.py
 tests/test_path_utils.py
+tests/test_persistence.py
 tests/test_printing.py
 tests/test_qualifiers.py
 tests/test_sectors.py

{cooptools-1.76 → cooptools-1.78}/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.78',
       description='Generic Tooling',
       url='https://github.com/tylertjburns/cooptools',
       author='tburns',

cooptools-1.78/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()