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
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
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
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
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
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)
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.
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!
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.
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 justallocate([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 aMoneyholds 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:
allocatesizes 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.
divideis the open one, where a unit really does end up outside the result. That is the whole reasondividetakes a mandatoryroundingwhilesplitandallocaterefuse one at all.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.
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_DOWNtruncates toward zero,ROUND_UPmoves away from it, so on a negative totaldivide(3, rounding=ROUND_DOWN)of -10 satoshi gives you -3 per share andROUND_UPgives -4. The names read like smaller and larger. They mean less magnitude and more magnitude.So
allocateagrees with six of the eight modes: both are symmetric about zero, so negating the input negates the result element by element.ROUND_FLOORandROUND_CEILINGare 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:allocatesizes the shares from the magnitude and puts the sign back,dividerounds relative to zero, and those two directional modes are where a negative amount stops mirroring a positive one. A case intests/test_precision_edges.pypinningdivideon a negative total across both of them goes on the list with it.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.
The test is missing more than I made it sound.
test_division_rounds_at_the_last_unitonly dividesMoney("1", BTC), so every assertion in it sits on a positive amount, and what negative coverage exists lives intest_rounding_modes_at_half_of_the_smallest_unit, which goes throughparse_amountinstead ofdivide. 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_directionsasserts thatnegative.convert(USDT, rate, rounding=ROUND_HALF_UP)equals-usdt, andROUND_HALF_UPis 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), withsplitandallocatechecked share by share, and thenROUND_FLOORandROUND_CEILINGwritten out as the explicit pair,-10satoshi over three giving-4under floor and-3under ceiling.test_shortened_text_truncates_towards_zeroalready phrases its claim the way I want it, asabs(shortened) <= abs(units). Nothing aboutdivideis 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.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.
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_MODESlater then picks up the symmetry assertion by default, and you have to exclude it deliberately.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).
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_05UPmoves away from zero and gives 6, and -6 on the negative. It agrees withROUND_UPthere, 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 whereROUND_UPgives 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_CEILINGcase intest_division_rounds_at_the_last_unit, which right now divides nothing butMoney("1", BTC).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.
The same gap sits one method over.
multiplyreaches_quantizewith the mode you pass, exactly likedividedoes, 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 thestr-factor path that can round has no negative case and no asymmetric mode anywhere.So
multiplywith a fractionalstrrate goes into the same symmetry invariant over the base-unit fixtures, with theROUND_FLOOR/ROUND_CEILINGpair written out beside it.convertrides 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.
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.
Three of the roads, not every one.
parse_amountcalls_quantizedirectly when the text carries more decimals than the asset has, andformatdoes its own rounding whendecimalssits 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
dividewas. The only negative case inparse_amountassertsrounding=ROUND_HALF_UPon half a satoshi, and that negates cleanly, whileformat's rounding case is positive underROUND_DOWNalone.So the explicit
ROUND_FLOOR/ROUND_CEILINGpair gets written out twice more. Once onparse_amount, with a negative string a half satoshi fine, floor giving -1 satoshi and ceiling 0, and once onformat, withdecimalsbelow the asset's on a negative amount, intest_shortening_and_padding_the_fraction.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.
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 atdecimals=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_fractioninstead of replacing it, withtrimleft off so the digit under assertion is the last retained one and not something the trimming already took away.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.
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_DOWNreads the same as DOWN on both signs, andROUND_05UPdoes 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...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.
At
decimals=7the tail you drop on -16 is 6, past the half, soROUND_HALF_DOWNrounds away from zero to -0.0000002 whileROUND_DOWNholds at -0.0000001. -55 is different: its last retained digit is 5, the one conditionROUND_05UPreads, so it lands on -0.0000006 whereDOWNandHALF_DOWNboth stay at -0.0000005. Neither amount fitstest_shortening_and_padding_the_fraction, since that fixture exists to carry a tail of exactly 5, so the two go into a secondformatcase beside it, trim off: -16 underROUND_DOWNandROUND_HALF_DOWN, -55 underROUND_DOWN,ROUND_HALF_DOWNandROUND_05UP.That leaves
ROUND_HALF_EVENas the only modeformathas 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 fromROUND_DOWNon the same amount. It goes in as a fifth assertion there.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).
Right, and -15 only pins
ROUND_HALF_EVENagainstROUND_DOWN: underROUND_HALF_UPandROUND_UPthe 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, soROUND_HALF_EVENstays at -0.0000002 whileROUND_HALF_UPmoves to -0.0000003.So you want
test_shortening_and_padding_the_fractionto get -15 underROUND_HALF_EVENas the fifth assertion, and -25 underROUND_HALF_EVENandROUND_HALF_UPsitting beside it, trim off on both.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.
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.
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.
Yes, the intersection settles it. On -25
ROUND_HALF_UPreads -0.0000003 along withROUND_UPandROUND_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, andtest_shortening_and_padding_the_fractionkeeps the tail-of-5 amounts it was built for.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.
That closes the negative side. What the accounting still leaves standing is sign: on a negative amount
ROUND_DOWNreads the same asROUND_CEILING, andROUND_UPthe same asROUND_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_DOWNgiving 0.0000001 whereROUND_FLOORagrees,ROUND_UPgiving 0.0000002 whereROUND_CEILINGagrees. Cross that with -16 and -55 underROUND_DOWNand you are left withROUND_DOWNalone, andROUND_UPworks the same way against the negative case it already has.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.
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.
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.
Yes, and -55 is the only one of the four that moves: the retained digit there is 5, so
ROUND_05UPcarries to -0.0000006. On 14 and -16 the retained digit is 1 and it just truncates, right alongsideROUND_DOWN.The same intersection pins it on its own. On -55 you read -0.0000006 with
ROUND_UP,ROUND_FLOOR,ROUND_HALF_UPandROUND_HALF_EVEN, on -16 you read -0.0000001 withROUND_DOWNandROUND_CEILING, and no other mode sits in both groups. The case as it stands only assertsROUND_DOWNon -55, which rules 05UP out without ever asserting it, so I will add one assertion underROUND_05UPon -55 at decimals=7, trim off, reading -0.0000006.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.
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_DOWNthere is what rulesROUND_05UPout, so you could drop the amount and nothing would fail.Put the
ROUND_05UPassertion 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.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.
That pair looks odd until you notice
ROUND_05UPis 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 likeROUND_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.
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.
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.
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
ROUND_05UP is the one mode whose name carries the whole rule. The pair you want to distrust is
ROUND_DOWNandROUND_FLOOR: they read as synonyms and they are not. Intest_rounding_modes_at_half_of_the_smallest_unitthe negative half-unit comes out -1 underROUND_FLOORand 0 underROUND_CEILING, whileROUND_DOWNandROUND_UPgo toward zero and away from it whatever the sign. That case pins both directions already, so nothing else is open on the file.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
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() == 0next to the ROUND_FLOOR line, so the two words sit one line apart with their two different answers. Last thing open on the file...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
That split already has a name one layer up. In
test_invariants.py,ROUND_FLOORandROUND_CEILINGare theASYMMETRIC_MODES, and everything else,ROUND_DOWNincluded, goes throughtest_rounding_is_symmetric_around_zero, which assertsnegative.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.
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
The name does a second job here.
SYMMETRIC_MODESis defined as_ROUNDING_MODES - ASYMMETRIC_MODES, so the set gets derived instead of listed. Add a mode to_ROUNDING_MODESand it falls intotest_rounding_is_symmetric_around_zeroby 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.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
If you steal this, the subtraction is the part to check.
test_floor_and_ceiling_are_the_asymmetric_modesis parametrized overASYMMETRIC_MODESand asserts bothrounding in _ROUNDING_MODESandrounding 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_MODESand keeps its sign-symmetry assertion, while the typo itself fails on the membership line.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
The half that would pass by accident is exactly why you need it. A misspelled entry is not in
SYMMETRIC_MODESeither, sorounding not in SYMMETRIC_MODESholds for it and goes green on a mode that does not exist. Onlyrounding in _ROUNDING_MODEScan tell a real mode from a string that just looks like one.The two asserts in
test_floor_and_ceiling_are_the_asymmetric_modesread 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.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"
The parametrization does the other half.
test_floor_and_ceiling_are_the_asymmetric_modestakessorted(ASYMMETRIC_MODES)with noids=, 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.
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
Close, with one letter of a correction:
test_floor_and_ceiling_are_the_asymmetric_modespasses noids=, so the id is just the parameter value,ROUND_FLOOR. The shortfloorcomes from the tests that do pass ids:SYMMETRIC_IDSandROUNDING_IDS, both built asmode.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 getrounding0,rounding1, and from there the ids have to be written by hand. That is why the two larger tests carry anids=tuple at all.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
Same property, doing the work twice.
_ROUNDING_MODESis a frozenset of those plain strings, so_check_roundingstays 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, whereROUND_FLOORis 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.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
Nearly free. The deliberate bit is the
sorted:_ROUNDING_MODESis a frozenset ofstr, 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_roundingrejects a non-strbefore that point, so an enum member or aNonegets aTypeErrornaming the type instead of a list of eight strings it could never have matched anyway.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
Same reason it shows up in the tests.
test_invariants.pybuildsSYMMETRIC_MODESastuple(sorted(_ROUNDING_MODES)), andtest_rounding_directions.pydoes the same forROUNDING_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
sortedand 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.being able to diff two CI logs line by line is underrated, that's a better reason than the one I had
That seed line is there for the same reason:
SEED = 20261108.test_rounding_directions.pybuilds its operands withrandom, 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 ordersorted, 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...pinned seed plus sorted order, so yesterday's diff only shows what actually changed. that's a neat setup
One detail that makes that diff hold: the seed never goes straight into
random. Both files derive a stream per case instead._streamintests/conftest.pybuildsrandom.Random(f"{SEED}:{asset.symbol}:{asset.decimals}"), and the_streamintests/test_rounding_directions.pyfolds 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,20260916and20261108, 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.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
It goes one level below the asset too. In
test_rounding_directions.pythe 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_divisorsand the factors_factorsdraws 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.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.
Order is the part you have right.
allocatetakes 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 theallocatedocstring and add a test intests/test_round_trips.py: the negated allocation equals each share negated.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
allocateto find out.