DEV Community

Why a money type should refuse the division operator

polycratia on October 26, 2026

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 oper...
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.

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.