DEV Community

polycratia
polycratia

Posted on Originally published at polycratia.com

Why a money type should refuse the division operator

A rounding mode is an input to a calculation, and Python's binary operators have nowhere to put it. a / b calls type(a).__truediv__(a, b): two operands, one result, no keyword arguments. So a money type that lets division succeed has already picked a rounding mode for every call site in the codebase, and recorded it nowhere the reader of that line can see it. The alternative is narrower operators plus a mandatory argument, and that trade is what this post is about.

The operator has two slots and the operation needs three

Take a 0.15% fee on a BTC balance. The result almost never lands on a satoshi boundary, so something has to decide what happens to the fraction. There are eight reasonable answers (decimal ships exactly eight rounding modes, from ROUND_05UP to ROUND_UP), and the choice is not a detail. Rounding a fee down is a gift to the payer, rounding it up is a gift to the house, and over enough rows that difference becomes a reconciliation ticket.

Python does offer one place to keep the decision: the arithmetic context. decimal.localcontext() carries a precision and a rounding mode, and the operators read it. That works, and I think it is the wrong mechanism for money, because it makes the mode ambient. The line fee = amount * Decimal("0.0015") looks identical whether the enclosing context rounds half-even or up, and identical whether some caller three frames above changed it. I have spent more time than I would like chasing reconciliation drift in payment systems, and the pattern repeats: the bug sits not in the branch that compares two numbers but in a half-unit decided somewhere nobody wrote down.

So cryptomoney (https://github.com/polycratia/cryptomoney) takes the other route. Operators are allowed to do only the arithmetic that cannot leave the asset's grid. Everything else is a method, and the method's rounding argument is keyword-only with no default.

The grid

An Asset is a symbol and the number of decimal places it is divisible into (BTC has 8, ETH has 18), and a Money is bound to exactly one of them. An amount is therefore an integer multiple of the asset's smallest unit, and the useful property here is closure: add or subtract two multiples of 10^-8 and you get a multiple of 10^-8. Multiply by a whole number and it still is. No decision is needed, because no result can fall between two base units.

from decimal import Decimal

from cryptomoney import BTC, ETH, Money, from_satoshi

balance = Money(Decimal("0.5"), BTC)
fee = Money("0.000125", BTC)

balance - fee             # 0.49987500 BTC
3 * fee                   # 0.00037500 BTC
from_satoshi(12_500_000)  # 0.12500000 BTC
Enter fullscreen mode Exit fullscreen mode

Those are plain operators because they are exact. __add__ and __sub__ return NotImplemented when the other operand is not a Money, so Python produces its ordinary unsupported-operand message. When both are Money but the assets differ, _require_same_asset raises CurrencyMismatch. The four ordering operators run through the same gate, which matters more than the sum does, because balance >= amount is the line that releases a payout:

Money("1", BTC) + Money("1", ETH)     # CurrencyMismatch
Money("1", BTC) >= Money("1", ETH)    # CurrencyMismatch
Enter fullscreen mode Exit fullscreen mode

CurrencyMismatch subclasses TypeError, because that is what it is: the operands have no common type, whatever the annotations claim.

Multiplication is two operations sharing one symbol

* is where the line has to be drawn carefully, because fee * 3 and fee * Decimal("0.0015") look alike and behave nothing alike. The first is three fees, exactly. The second is a rate, and it falls between base units for almost every input you give it.

So __mul__ accepts an int and nothing else. A float is refused by _refuse_float. A Decimal or a str raises a TypeError that names the replacement instead of guessing, and __rmul__ delegates so the natural reading order still works:

from decimal import ROUND_HALF_UP, Decimal

fee * 3                     # 0.00037500 BTC
3 * fee                     # the same, via __rmul__
fee * 0.0015                # TypeError: float is refused
fee * Decimal("0.0015")     # TypeError: use .multiply(factor, rounding=...)

Money("1", BTC).multiply("0.015", rounding=ROUND_HALF_UP)   # 0.01500000 BTC
Enter fullscreen mode Exit fullscreen mode

Accepting a str factor in multiply is deliberate. Rates arrive from config files and admin forms as text, so _operand parses them rather than making every caller round-trip through Decimal, refusing floats, bools, unparseable text and non-finite values on the way through.

Division is refused outright, and the error names the way out

__truediv__ does not return NotImplemented. It raises TypeError unconditionally. The distinction is for whoever reads the traceback: NotImplemented produces "unsupported operand type(s) for /", which reads like an oversight somebody will helpfully fix by adding the method. A raise can say what to use instead, and the message names divide, split and allocate, because a remainder has three different questions sitting behind it.

from decimal import ROUND_DOWN, ROUND_UP

Money("0.5", BTC) / 3                            # TypeError: / is refused

Money("1", BTC).divide(3, rounding=ROUND_DOWN)   # 33_333_333 satoshi
Money("1", BTC).divide(3, rounding=ROUND_UP)     # 33_333_334 satoshi

Money.from_base_units(-10, BTC).split(3)         # -4, -3, -3 satoshi
Money("0.00000010", BTC).allocate([3, 1, 1])     # 6, 2, 2 satoshi
Enter fullscreen mode Exit fullscreen mode

divide needs a mode because a unit genuinely has to end up outside the result. split and allocate do not take one, and that asymmetry is the whole design. They return shares that sum back to the original, handing the remainder to the earliest shares, so nothing is lost and there is nothing to decide. split(3) on -10 satoshi gives you -4, -3, -3, still -10 in total, where integer floor division gives -4, -4, -4 and pays out twelve.

Rounding is mandatory exactly where a unit can disappear and absent exactly where it cannot. That is a rule a reviewer can apply to a diff without reading the implementation.

The argument is validated before any arithmetic happens

A mandatory argument that accepts anything is a worse lie than a default. _check_rounding runs first, before the operand is even examined: a non-str is a TypeError, and a string outside _ROUNDING_MODES is a ValueError listing the eight accepted modes. A near-miss like a misspelled constant fails loudly rather than falling back to something plausible.

Then there is one rounding point, and only one. The product or quotient is computed inside a localcontext whose precision _working_precision sets to the longer operand's digit count (counting a positive exponent) plus the asset's decimals plus ten guard digits, with the context's rounding set to the mode you passed. _quantize then rounds the result once, to the asset's places, with that same mode. A zero divisor is a ZeroDivisionError, not a quantized nothing.

The guard digits are what stops the intermediate from being the thing that rounds. An 18-decimal asset near the top of its range still divides the way arithmetic says it should:

money = Money.from_base_units(10**38, ETH)
money.divide(3, rounding=ROUND_DOWN).to_base_units() == 10**38 // 3   # True
Enter fullscreen mode Exit fullscreen mode

Parsing follows the same rule instead of inventing its own. parse_amount refuses text carrying more decimals than the asset has, with a ParseError, unless you pass a rounding mode to accept the loss. Reading "0.000000001 BTC" off an API is a lossy operation too, and it gets the same treatment as a quotient.

What I would change

The cost is real. A fee calculation runs three lines where it used to be one, and your first week with the type feels like fighting it. At the operator level I do not see a way around that, but I would reconsider where the mode comes from. Writing rounding=ROUND_DOWN at forty call sites invites copy-paste, and copy-paste is how one of them ends up rounding the wrong way for its direction of money flow. What I would want is for a service to decide its modes once at its own boundary (fees one way, payouts the other) and pass them inward explicitly, so the per-call argument stays in the signature and stays visible in the diff, while the policy gets reviewed in one file. What I would not do is put that in a module-level default, because that is the ambient context again wearing a nicer name.

The other honest cost is that str factors make it easy to park a rate in a config file and never type-check it. The parse is strict, so a bad value fails at the first calculation rather than silently, but it fails at runtime, not at startup, and that is a boundary I would tighten in the service rather than in the money type.

Close

An operator is a fixed-arity function with no room for policy. Money arithmetic needs policy for exactly those operations that can fall between two base units. Keeping the two sets disjoint, operators for the closed arithmetic and methods with a mandatory mode for everything else, costs you fluency and buys the property that actually matters: no balance was ever shortened by a decision nobody made.


Originally published on polycratia.com — where I write about payment systems, crypto rails and marketplace backends.

Top comments (71)

Collapse
 
oddeggs profile image
Odd Eggs Studio •

Same lesson from our budgeting app: the only division that really matters is free money ÷ days left, and we put the floor to whole thousands of đồng in the function's name so nobody has to guess. The leftover isn't lost either, it stays in the month and turns up in tomorrow's line when it's recomputed.

Collapse
 
polycratia profile image
polycratia •

That’s a great example of why the rounding policy should be explicit. I especially like that the remainder isn’t discarded but carried forward into the next calculation.

One subtle distinction is that rounding down a daily budget and allocating money across recipients are different operations. In your case, recalculating from the remaining balance each day preserves the leftover naturally. For payments or payouts, though, explicitly allocating the remainder can be important to ensure the individual shares always add up to the original amount.

Thanks for sharing a real-world example!

Collapse
 
oddeggs profile image
Odd Eggs Studio •

Good distinction. Recomputing from what's left means the rounding never piles up for us, but with a split you're right: someone has to own the leftover đồng or the shares won't add back to the total.

Thread Thread
 
polycratia profile image
polycratia •

The owner is positional in allocate: the remainder goes out one base unit at a time to the earliest shares with a nonzero weight, and a zero weight stays at zero. split(parts) is just allocate([1] * parts), so the first entries in the list soak it up. That makes the leftover deterministic instead of fair. Pass recipients in the same order every period and the same share keeps picking up the extra unit, and rotating that is on the caller, since a Money holds no state between calls. I think that asymmetry belongs in the docstring rather than in a strategy parameter, and writing it down goes on the list.

One detail that matters for payouts specifically: allocate sizes the shares from the magnitude and puts the sign back at the end, so a negative total splits as -4, -3, -3 instead of the -4, -4, -4 that floor division gives you. A refund is the same operation as a payout as far as the type cares, which is what you want when a reversal has to clear exactly as much as went out and not a unit more.

Your recompute model is the closed case: the leftover never leaves the balance you read again the next day, so there is nothing to assign. divide is the open one, where a unit really does end up outside the result. That is the whole reason divide takes a mandatory rounding while split and allocate refuse one at all.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

The sign handling is the part I hadn't thought through: -4, -4, -4 clears 12 on a 10 refund, and that's exactly the kind of bug nobody notices until reconciliation. Agree on the docstring over a strategy parameter, "earliest shares soak up the remainder" is easy to work around once it's written down.

Thread Thread
 
polycratia profile image
polycratia •

The sign asymmetry doesn't stop at allocate. It changes what a rounding mode means, and that's the part that took me longest to internalize. decimal's modes are defined relative to zero, not relative to minus infinity: ROUND_DOWN truncates toward zero, ROUND_UP moves away from it, so on a negative total divide(3, rounding=ROUND_DOWN) of -10 satoshi gives you -3 per share and ROUND_UP gives -4. The names read like smaller and larger. They mean less magnitude and more magnitude.

So allocate agrees with six of the eight modes: both are symmetric about zero, so negating the input negates the result element by element. ROUND_FLOOR and ROUND_CEILING are the two that aren't, and they're the ones that reproduce integer floor division on a refund. That bears on the boundary I argued for at the end of the post. A service that fixes one mode per direction of flow, fees one way and payouts the other, has fixed it while looking at a positive amount, and the same constant handed to a reversal rounds the other way in value unless the mode happens to be a symmetric one.

I wouldn't have the type refuse ROUND_FLOOR. It's the right mode when you want a bound rather than a share. But the docstring note I owe you now has a second half: allocate sizes the shares from the magnitude and puts the sign back, divide rounds relative to zero, and those two directional modes are where a negative amount stops mirroring a positive one. A case in tests/test_precision_edges.py pinning divide on a negative total across both of them goes on the list with it.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

Reading ROUND_DOWN as "less magnitude" instead of "smaller" untangles it for me. A mode picked while staring at a positive fee and then handed a reversal is exactly the kind of bug that sits quietly for months, so pinning FLOOR and CEILING on a negative total sounds like the right test.

Thread Thread
 
polycratia profile image
polycratia •

The test is missing more than I made it sound. test_division_rounds_at_the_last_unit only divides Money("1", BTC), so every assertion in it sits on a positive amount, and what negative coverage exists lives in test_rounding_modes_at_half_of_the_smallest_unit, which goes through parse_amount instead of divide. The path that quantizes a quotient has no negative case at all.

The other half of the problem: the negative cases elsewhere are written with symmetric modes. test_convert_quotes_both_directions asserts that negative.convert(USDT, rate, rounding=ROUND_HALF_UP) equals -usdt, and ROUND_HALF_UP is one of the six modes that negate cleanly, so that line holds whether the sign handling is right or wrong. It records the symmetry it happens to be using rather than testing it.

What goes on the list is an invariant over the base-unit fixtures, which already carry negatives: for the six symmetric modes, (-money).divide(n, rounding=mode) equals -money.divide(n, rounding=mode), with split and allocate checked share by share, and then ROUND_FLOOR and ROUND_CEILING written out as the explicit pair, -10 satoshi over three giving -4 under floor and -3 under ceiling. test_shortened_text_truncates_towards_zero already phrases its claim the way I want it, as abs(shortened) <= abs(units). Nothing about divide is stated in magnitude terms yet...

One more hole worth closing in the same pass: the half-unit table covers seven modes and leaves out ROUND_05UP, probably the one whose behavior nobody predicts correctly from the name.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

Stating it as an invariant over the fixtures that already carry negatives is a much better shape than adding cases one by one, and -10 satoshi over three giving -4 under floor and -3 under ceiling is the pair I'd want spelled out too. Good call on ROUND_05UP, I'd have guessed it wrong from the name.

Thread Thread
 
polycratia profile image
polycratia •

ROUND_05UP is the one I'd want written into the invariant, for that reason. It's symmetric about zero, so it negates cleanly like the other five, but by value it's almost always ROUND_DOWN: it truncates unless the last retained digit of the truncated result is 0 or 5, and only then does it move away from zero. One BTC over three ends in 3, so that fixture can't tell the two modes apart. The symmetry assertion still holds, since it compares a negative input against the negated positive one and not against a literal.

In the test I'll write the symmetric set as _ROUNDING_MODES - {ROUND_FLOOR, ROUND_CEILING} rather than a literal list of six. A mode added to _ROUNDING_MODES later then picks up the symmetry assertion by default, and you have to exclude it deliberately.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

Subtracting from _ROUNDING_MODES is the better default, since a new mode then has to be excluded on purpose instead of quietly skipping the check. For a fixture that actually splits 05UP from DOWN, 16 satoshi over 3 works: 5.33 truncates to 5, so DOWN gives 5 sat and 05UP gives 6 (and -6 for the negative).

Thread Thread
 
polycratia profile image
polycratia •

That fixture works, and you need something like it: the symmetry assertion compares a negative against the negated positive, so it can't separate two modes that both negate cleanly. 16 satoshi over 3 truncates to 5, the last retained digit is 5, so ROUND_05UP moves away from zero and gives 6, and -6 on the negative. It agrees with ROUND_UP there, though. To pin 05UP as itself I'll sit 10 satoshi over 3 next to it: the truncated result ends in 3, so 05UP stays at 3 where ROUND_UP gives 4. The pair then says UP at a 0 or 5 boundary, DOWN everywhere else.

Both go in as literals beside the ROUND_FLOOR/ROUND_CEILING case in test_division_rounds_at_the_last_unit, which right now divides nothing but Money("1", BTC).

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

Good catch, I only checked 16 against DOWN and never against UP. Putting 10 next to it is a nice pair, and it's good the BTC test will finally divide something other than 1.

Thread Thread
 
polycratia profile image
polycratia •

The same gap sits one method over. multiply reaches _quantize with the mode you pass, exactly like divide does, and its coverage is one test: test_whole_factors_stay_exact, which multiplies 123,456,789 base units by 1000. A whole factor can't land between base units, so that test never touches the rounding at all, and the str-factor path that can round has no negative case and no asymmetric mode anywhere.

So multiply with a fractional str rate goes into the same symmetry invariant over the base-unit fixtures, with the ROUND_FLOOR / ROUND_CEILING pair written out beside it. convert rides in the same loop, since it quantizes at the target asset's precision through the same function.

A rate that truncates one way on a fee and the other way on its reversal is the bug I've been talking about, arriving through a different signature.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

That's a sneaky one: a whole factor can't land between base units, so test_whole_factors_stay_exact passes whatever mode you hand it. Putting multiply and convert in the same symmetry loop means one invariant covers every road into _quantize, which beats three tests that each only look like coverage.

Thread Thread
 
polycratia profile image
polycratia •

Three of the roads, not every one. parse_amount calls _quantize directly when the text carries more decimals than the asset has, and format does its own rounding when decimals sits below the asset's. Neither one fits a loop over the base-unit fixtures: one takes text in, the other hands text back.

Both are where divide was. The only negative case in parse_amount asserts rounding=ROUND_HALF_UP on half a satoshi, and that negates cleanly, while format's rounding case is positive under ROUND_DOWN alone.

So the explicit ROUND_FLOOR / ROUND_CEILING pair gets written out twice more. Once on parse_amount, with a negative string a half satoshi fine, floor giving -1 satoshi and ceiling 0, and once on format, with decimals below the asset's on a negative amount, in test_shortening_and_padding_the_fraction.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

Fair, text in and text out don't belong in a base-unit loop, and a half-satoshi HALF_UP case negates cleanly so it can't catch an asymmetric mode anyway. For format I'd pick a negative amount where DOWN and FLOOR land on different digits, so the test breaks if someone ever swaps one for the other.

Thread Thread
 
polycratia profile image
polycratia •

Yeah, a positive amount can't split them. ROUND_DOWN and ROUND_FLOOR only diverge below zero, so the case as you have it would pass with either one wired in. The fixture I'll use is Money.from_base_units(-15, BTC) formatted at decimals=7: the dropped tail is 5, so ROUND_DOWN truncates toward zero to -0.0000001, ROUND_FLOOR goes to -0.0000002, and ROUND_CEILING lands back on the DOWN digit. Three assertions sitting side by side, and a swap moves exactly one of them.

So ROUND_DOWN gets written in next to the ROUND_FLOOR / ROUND_CEILING pair in test_shortening_and_padding_the_fraction instead of replacing it, with trim left off so the digit under assertion is the last retained one and not something the trimming already took away.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

One gap left in that trio: on a negative amount DOWN and CEILING land on the same digit, so CEILING wired in where DOWN belongs still passes. A +15 twin under ROUND_DOWN closes it, since there DOWN and FLOOR agree and CEILING goes up to 0.0000002.

Thread Thread
 
polycratia profile image
polycratia •

Right, and that's my gap, not the fixture's: at decimals=7, ROUND_CEILING on -0.00000015 truncates toward zero exactly like ROUND_DOWN, so the negative trio only pins FLOOR. The +15 twin closes it: 0.00000015 under DOWN and FLOOR both land on 0.0000001 while CEILING goes to 0.0000002. So four assertions land in test_shortening_and_padding_the_fraction: -15 under DOWN, FLOOR and CEILING, plus +15 under DOWN, with trim left off on all of them.

One pair still slips past that fixture. The dropped tail is exactly 5, so ROUND_HALF_DOWN reads the same as DOWN on both signs, and ROUND_05UP does too, since the last retained digit is 1. Splitting those probably needs a tail that isn't a half, which is a different amount than the one this test is built around...

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

A tail past the half splits the first pair: -16 at decimals=7 gives -0.0000002 under HALF_DOWN and -0.0000001 under DOWN. For 05UP the last kept digit has to be 0 or 5, so -55 lands on -0.0000006 under 05UP while DOWN and HALF_DOWN both stay on -0.0000005.

Thread Thread
 
polycratia profile image
polycratia •

At decimals=7 the tail you drop on -16 is 6, past the half, so ROUND_HALF_DOWN rounds away from zero to -0.0000002 while ROUND_DOWN holds at -0.0000001. -55 is different: its last retained digit is 5, the one condition ROUND_05UP reads, so it lands on -0.0000006 where DOWN and HALF_DOWN both stay at -0.0000005. Neither amount fits test_shortening_and_padding_the_fraction, since that fixture exists to carry a tail of exactly 5, so the two go into a second format case beside it, trim off: -16 under ROUND_DOWN and ROUND_HALF_DOWN, -55 under ROUND_DOWN, ROUND_HALF_DOWN and ROUND_05UP.

That leaves ROUND_HALF_EVEN as the only mode format has no case for, and it does fit the original fixture: on -15 the tie rounds the retained 1 up to 2, giving -0.0000002, which separates it from ROUND_DOWN on the same amount. It goes in as a fifth assertion there.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

Agreed on -15, though it only splits HALF_EVEN from DOWN, since HALF_UP and UP land on -0.0000002 there too. A -25 beside it does the rest: HALF_EVEN keeps -0.0000002 because 2 is already even, while HALF_UP goes to -0.0000003 (checked with Python's decimal).

Thread Thread
 
polycratia profile image
polycratia •

Right, and -15 only pins ROUND_HALF_EVEN against ROUND_DOWN: under ROUND_HALF_UP and ROUND_UP the tie runs away from zero as well, so either one wired in its place still reads -0.0000002. -25 is where they split. The retained 2 is already even, so ROUND_HALF_EVEN stays at -0.0000002 while ROUND_HALF_UP moves to -0.0000003.

So you want test_shortening_and_padding_the_fraction to get -15 under ROUND_HALF_EVEN as the fifth assertion, and -25 under ROUND_HALF_EVEN and ROUND_HALF_UP sitting beside it, trim off on both.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

Yes, that pair pins HALF_EVEN. One twin is left on the other side: -25 under HALF_UP gives -0.0000003, same as UP and FLOOR, so unless something else already pins HALF_UP, a tail under the half like -14 (HALF_UP -0.0000001, UP and FLOOR -0.0000002) would split them.

Thread Thread
 
polycratia profile image
polycratia •

Agreed, and -25 only splits ROUND_HALF_UP off from the modes that come back toward zero there: ROUND_DOWN, ROUND_HALF_DOWN, ROUND_HALF_EVEN, ROUND_CEILING and ROUND_05UP all read -0.0000002 on it, 05UP because the retained 2 is neither 0 nor 5. So it leaves open exactly the pair you name.

-14 closes both. The dropped tail at decimals=7 is 4, under the half, so ROUND_HALF_UP truncates toward zero to -0.0000001 while ROUND_UP and ROUND_FLOOR both carry to -0.0000002. Its tail is not a half, so it belongs in the second format case next to -16 and -55 rather than in test_shortening_and_padding_the_fraction: one assertion under ROUND_HALF_UP with trim off.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

Yes, and together they pin HALF_UP: -25 leaves it with UP and FLOOR, -14 leaves it with the five that go toward zero, and only HALF_UP sits in both groups (checked with Python's decimal). Agreed it belongs in the second format case beside -16 and -55, trim off.

Thread Thread
 
polycratia profile image
polycratia •

Yes, the intersection settles it. On -25 ROUND_HALF_UP reads -0.0000003 along with ROUND_UP and ROUND_FLOOR, on -14 it reads -0.0000001 along with the five that come back toward zero, and no other mode sits inside both groups.

So -14 goes into the second format case as one assertion under ROUND_HALF_UP, trim off, beside -16 and -55. That case then carries the three tails that are not a half, and test_shortening_and_padding_the_fraction keeps the tail-of-5 amounts it was built for.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

Agreed, that closes it: -14 as one HALF_UP assertion with trim off beside -16 and -55, and the tail-of-5 test stays as it was built. Thanks for walking every mode through with me, this was a fun one.

Thread Thread
 
polycratia profile image
polycratia •

That closes the negative side. What the accounting still leaves standing is sign: on a negative amount ROUND_DOWN reads the same as ROUND_CEILING, and ROUND_UP the same as ROUND_FLOOR, which is why those two kept riding along with the toward-zero group. Pick whatever tail you like and neither pair splits.

So the second format case takes one positive amount as well: 14 at decimals=7, trim off, ROUND_DOWN giving 0.0000001 where ROUND_FLOOR agrees, ROUND_UP giving 0.0000002 where ROUND_CEILING agrees. Cross that with -16 and -55 under ROUND_DOWN and you are left with ROUND_DOWN alone, and ROUND_UP works the same way against the negative case it already has.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

Right, sign was the gap: 14 at decimals=7 gives 0.0000001 for DOWN and FLOOR and 0.0000002 for UP and CEILING, and crossed with -16 and -55 only ROUND_DOWN survives, with ROUND_UP pinned the same way against -14 (checked all eight modes). So one positive 14 goes in as the extra assertion, thanks for carrying this all the way through.

Thread Thread
 
polycratia profile image
polycratia •

Yes, and 14 is where sign stops mattering: ROUND_UP sits with ROUND_CEILING on the positive tail and with ROUND_FLOOR on -14, so it is the only mode inside both groups. Same intersection argument that pinned ROUND_HALF_UP.

So you hand the second format case 14 at decimals=7 with trim off, one assertion under ROUND_DOWN reading 0.0000001 and one under ROUND_UP reading 0.0000002, beside the existing -16, -55 and -14. That leaves the case pinning ROUND_DOWN, ROUND_UP and ROUND_HALF_UP each on its own, while ROUND_HALF_EVEN is still carried by the tail-of-5 amounts in test_shortening_and_padding_the_fraction.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

Agreed, I ran all eight modes through Python's decimal and UP is the only one inside both groups. The one that rides along longest is ROUND_05UP: it reads with DOWN on 14 and on -16, and only -55 (giving -0.0000006) splits it off, so that amount is earning its place too.

Thread Thread
 
polycratia profile image
polycratia •

Yes, and -55 is the only one of the four that moves: the retained digit there is 5, so ROUND_05UP carries to -0.0000006. On 14 and -16 the retained digit is 1 and it just truncates, right alongside ROUND_DOWN.

The same intersection pins it on its own. On -55 you read -0.0000006 with ROUND_UP, ROUND_FLOOR, ROUND_HALF_UP and ROUND_HALF_EVEN, on -16 you read -0.0000001 with ROUND_DOWN and ROUND_CEILING, and no other mode sits in both groups. The case as it stands only asserts ROUND_DOWN on -55, which rules 05UP out without ever asserting it, so I will add one assertion under ROUND_05UP on -55 at decimals=7, trim off, reading -0.0000006.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

Ran the three cases again and you're right: 05UP only leaves DOWN on -55, and no other mode lands in both the -55 and -16 groups. One assertion there closes it, thanks for sticking with this one.

Thread Thread
 
polycratia profile image
polycratia •

That closes the accounting. Beyond the mode itself, the extra line buys you one thing: right now -55 only earns its place by exclusion, because asserting ROUND_DOWN there is what rules ROUND_05UP out, so you could drop the amount and nothing would fail.

Put the ROUND_05UP assertion on -55 at decimals=7, trim off, reading -0.0000006, and the amount is asserted for the mode it actually separates, with the separation readable in the case instead of implied by the modes left out of it.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

Agreed, a case should assert the mode it's there to separate, not just be what's left after the others. With ROUND_DOWN at -0.0000005 and ROUND_05UP at -0.0000006 side by side on -55, the reason for the amount is right there in the test.

Thread Thread
 
polycratia profile image
polycratia •

That pair looks odd until you notice ROUND_05UP is the only one of the eight that decides on the digit it keeps rather than the digit it drops. On -55 the retained seventh decimal is 5, so it carries to -0.0000006, while on 14 and -16 that digit is 1 and it truncates exactly like ROUND_DOWN.

Two assertions on the same amount, one unit apart, is the shortest form that fact takes in a test. The amount is in the case because of the difference between those two lines, not because of the modes left out of it.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

Right, it's the only mode that looks at the digit it keeps, so -55 at seven places is exactly where it parts from DOWN (-0.0000006 vs -0.0000005), while on 14 and -16 the kept 1 makes it truncate alongside DOWN. Two lines one unit apart it is, thanks again.

Thread Thread
 
polycratia profile image
polycratia •

That is it, and the name tells you the rule: ROUND_05UP goes away from zero only when the digit it keeps would be 0 or 5, so the seventh decimal of -55 moves it while the 1 on 14 and -16 leaves it parked with ROUND_DOWN. Nothing is open on my side. With the ROUND_05UP line on -55, all four amounts in that case are asserted for the mode they separate, and ROUND_HALF_EVEN stays with the tail-of-5 amounts in test_shortening_and_padding_the_fraction.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

ha, the name was spelling out the rule the whole time and I still needed it explained. nineteen rounds in and that test file is way better for it, thanks for sticking with it

Thread Thread
 
polycratia profile image
polycratia •

ROUND_05UP is the one mode whose name carries the whole rule. The pair you want to distrust is ROUND_DOWN and ROUND_FLOOR: they read as synonyms and they are not. In test_rounding_modes_at_half_of_the_smallest_unit the negative half-unit comes out -1 under ROUND_FLOOR and 0 under ROUND_CEILING, while ROUND_DOWN and ROUND_UP go toward zero and away from it whatever the sign. That case pins both directions already, so nothing else is open on the file.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

oh DOWN vs FLOOR is exactly the pair I'd have mixed up, -0.5 lands on 0 or -1 depending on which word you typed lol. nice that the half-unit case already catches both, twenty rounds and the file's done

Thread Thread
 
polycratia profile image
polycratia •

Before the file closes: the negative half-unit in test_rounding_modes_at_half_of_the_smallest_unit only asserts ROUND_FLOOR at -1, ROUND_CEILING at 0, and ROUND_HALF_UP at -1. ROUND_DOWN lives in the positive dict above it, where it agrees with ROUND_FLOOR at 0, so the one pair that reads like synonyms is the pair that case never pulls apart. You found the gap yourself by naming -0.5.

I'll put parse_amount(negative, asset, rounding=ROUND_DOWN).to_base_units() == 0 next to the ROUND_FLOOR line, so the two words sit one line apart with their two different answers. Last thing open on the file...

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

nice, -1 and 0 sitting one line apart is the whole lesson in two asserts. I'd 100% have shipped ROUND_DOWN thinking it meant floor lol

Thread Thread
 
polycratia profile image
polycratia •

That split already has a name one layer up. In test_invariants.py, ROUND_FLOOR and ROUND_CEILING are the ASYMMETRIC_MODES, and everything else, ROUND_DOWN included, goes through test_rounding_is_symmetric_around_zero, which asserts negative.to_base_units() == -positive.to_base_units(). Sign symmetry is the property those two words part on, and it gets stated once for all eight.

The two asserts a line apart don't add that fact: they put it where you'll run into it while reading the negative half-unit.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

ha so it was already stated once for all eight and the two asserts are just a sign on the door. ASYMMETRIC_MODES is a really nice name for it too

Thread Thread
 
polycratia profile image
polycratia •

The name does a second job here. SYMMETRIC_MODES is defined as _ROUNDING_MODES - ASYMMETRIC_MODES, so the set gets derived instead of listed. Add a mode to _ROUNDING_MODES and it falls into test_rounding_is_symmetric_around_zero by default: the only way out is naming it asymmetric on purpose. That is what I wanted from the naming, since the sign-symmetric case is what a new mode has to pass unless someone argues otherwise. Nothing else is open on the file.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

oh that's the good part, a new mode can't sneak past the symmetry test, it has to get named asymmetric on purpose. opt-out by name instead of opt-in by list is a pattern worth stealing

Thread Thread
 
polycratia profile image
polycratia •

If you steal this, the subtraction is the part to check. test_floor_and_ceiling_are_the_asymmetric_modes is parametrized over ASYMMETRIC_MODES and asserts both rounding in _ROUNDING_MODES and rounding not in SYMMETRIC_MODES, so an opt-out has to name a mode that really exists.

That is why the default holds either way the list is wrong. Misspell an entry and the subtraction removes nothing: the real mode stays in SYMMETRIC_MODES and keeps its sign-symmetry assertion, while the typo itself fails on the membership line.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

oh that's sneaky good, a typo fails loudly instead of quietly switching a check off. that membership line is doing way more work than it looks like

Thread Thread
 
polycratia profile image
polycratia •

The half that would pass by accident is exactly why you need it. A misspelled entry is not in SYMMETRIC_MODES either, so rounding not in SYMMETRIC_MODES holds for it and goes green on a mode that does not exist. Only rounding in _ROUNDING_MODES can tell a real mode from a string that just looks like one.

The two asserts in test_floor_and_ceiling_are_the_asymmetric_modes read like one claim cut in half, but they fail on different things: the first on the mode existing at all, the second on the subtraction having actually pulled it out of the symmetric set.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

right, and splitting them means a red test tells you which half broke, the mode not existing or the subtraction not taking it out. one combined assert would just say "nope"

Thread Thread
 
polycratia profile image
polycratia •

The parametrization does the other half. test_floor_and_ceiling_are_the_asymmetric_modes takes sorted(ASYMMETRIC_MODES) with no ids=, so pytest builds the test id out of the mode string itself. A red line names the mode and the assert that broke: which half, and which of the two modes.

That is also why one combined assert would cost you twice here: the single message you got back would have to carry both facts, and it would carry neither.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

oh nice, letting pytest name the test after the mode string is free documentation. a red line that already says "floor" means you don't even open the file

Thread Thread
 
polycratia profile image
polycratia •

Close, with one letter of a correction: test_floor_and_ceiling_are_the_asymmetric_modes passes no ids=, so the id is just the parameter value, ROUND_FLOOR. The short floor comes from the tests that do pass ids: SYMMETRIC_IDS and ROUNDING_IDS, both built as mode.removeprefix("ROUND_").lower(). Either way the red line names the mode. That is the part that saves you the file.

It is free only because a rounding mode is a plain str, so pytest can reuse the value as the id. Parametrize over something it cannot render that way and you get rounding0, rounding1, and from there the ids have to be written by hand. That is why the two larger tests carry an ids= tuple at all.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

ah you're right, I mixed that one up with the ids tuples. and the plain str bit is the real reason it's free, wrap the mode in anything fancier and you're back to rounding0, rounding1

Thread Thread
 
polycratia profile image
polycratia •

Same property, doing the work twice. _ROUNDING_MODES is a frozenset of those plain strings, so _check_rounding stays a single membership test, and its ValueError can list the accepted modes with ', '.join(sorted(_ROUNDING_MODES)). Wrap the mode in an enum or a small value class and that cheap check becomes something you write by hand, exactly like the ids.

The str is not my choice either: it comes out of decimal, where ROUND_FLOOR is the literal string "ROUND_FLOOR". Leaving it as what the stdlib already hands you is what keeps both the validation and the test ids this thin.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

fair, decimal already did the enum's job by making them strings, so there's nothing left to wrap. and the error message listing the accepted modes for free is a nice bonus

Thread Thread
 
polycratia profile image
polycratia •

Nearly free. The deliberate bit is the sorted: _ROUNDING_MODES is a frozenset of str, and string hashing is randomized per process, so joining it directly would list the eight modes in a different order on every run. That makes the message unstable in your logs and in any test that matches on it. One call buys you the same line every time.

And _check_rounding rejects a non-str before that point, so an enum member or a None gets a TypeError naming the type instead of a list of eight strings it could never have matched anyway.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

oh the hash randomization thing, that's exactly the kind of bug that only shows up as one flaky test on CI and eats an afternoon. sorted() it is

Thread Thread
 
polycratia profile image
polycratia •

Same reason it shows up in the tests. test_invariants.py builds SYMMETRIC_MODES as tuple(sorted(_ROUNDING_MODES)), and test_rounding_directions.py does the same for ROUNDING_MODES, so the parametrized cases land in one fixed order per run instead of a fresh one each time.

The ids are correct either way, since they come from the values. But drop the sorted and you cannot diff two runs line by line, and anything that only fails in a particular order stops being reproducible from the log you still have.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

being able to diff two CI logs line by line is underrated, that's a better reason than the one I had

Thread Thread
 
polycratia profile image
polycratia •

That seed line is there for the same reason: SEED = 20261108. test_rounding_directions.py builds its operands with random, so unseeded it compares a different set of amounts on every run, and a failure prints a value you cannot get back once the log scrolls past. Pin the seed, keep the parametrized order sorted, let the ids come from the mode strings themselves, and the file emits the same lines in the same order each run. A diff against yesterday's log then shows only what actually changed, which is why I want it readable that way...

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

pinned seed plus sorted order, so yesterday's diff only shows what actually changed. that's a neat setup

Thread Thread
 
polycratia profile image
polycratia •

One detail that makes that diff hold: the seed never goes straight into random. Both files derive a stream per case instead. _stream in tests/conftest.py builds random.Random(f"{SEED}:{asset.symbol}:{asset.decimals}"), and the _stream in tests/test_rounding_directions.py folds the test name into the key too. So the amounts BTC gets checked against do not move when I change how many divisors ETH samples. The seeds stay separate as well, 20260916 and 20261108, instead of one shared value. Pin a single global seed, feed it to one generator, and the next case you add anywhere reshuffles every asset downstream of it: the diff is the whole file again.

Thread Thread
 
oddeggs profile image
Odd Eggs Studio •

a stream per case is the bit I'd have missed. one global seed and adding a single ETH divisor quietly reshuffles BTC's amounts, so the diff is noise again

Thread Thread
 
polycratia profile image
polycratia •

It goes one level below the asset too. In test_rounding_directions.py the key folds in the test name, so _stream("divide", asset) and _stream("multiply", asset) end up as separate generators for the same BTC: add a divisor to _divisors and the factors _factors draws stay put, and the parse and format cases do not move either. The decimals of the asset sit in the key as well, so changing a precision re-rolls that one asset and nothing downstream of it.

Collapse
 
stefan_07d23f966225156b50 profile image
Stefan •

The refund example makes me wonder about recipient order. If the caller rotates that order between payouts, negating the total and allocating again could put the extra unit against a different person. I'd keep the original per-recipient allocation and reverse those amounts. The total balancing is one check; each person getting the right reversal is another.

Collapse
 
polycratia profile image
polycratia •

Order is the part you have right. allocate takes weights, not recipients, so a share lands on a person purely by its position in the list, and the remainder goes to the earliest shares. Reverse it by negating the amounts you already handed out, one per recipient, instead of re-deriving them.

One correction: negating the total and allocating again is exact as long as the weights and their order are identical. split(3) on -10 satoshi gives -4, -3, -3, the mirror of 4, 3, 3. The bug sits in the rotation, and the negation is fine. I'll write the positional correspondence into the allocate docstring and add a test in tests/test_round_trips.py: the negated allocation equals each share negated.

Collapse
 
polycratia profile image
polycratia •

The negation case is pinned down in the cryptomoney repository now: there is a test asserting that allocating a negated amount returns every share negated, so the same weights in the same order give you an exact per-recipient reversal, not just a matching total. That assertion came out of your comment.

The docs also state the share order and where the remainder lands, which is what lets a caller rely on "same order" instead of reading allocate to find out.