How does decimal.Decimal.quantize round a money amount, and what rounding does it use by default?

### Scale against precision Two different knobs get confused here. A decimal context's `prec` is the number of *significant digits* an arithmetic operation may produce — the default is 28. Scale is the number of digits after the point, which for a Decimal is just its exponent. Money is a scale problem: a euro amount has two decimal places whether it is 0.05 or 4,500,000.00. `prec` cannot express that, and `Decimal.quantize` is the operation that can. `x.quantize(exp)` returns a Decimal numerically equal to `x` rounded so that its exponent equals the exponent of `exp`. The pattern's value is irrelevant — only its exponent is read — so `Decimal("0.01")` and `Decimal("9.99")` behave identically as patterns, and the conventional choice is a one-at-the-last-place pattern because it reads as the shape you want. ### Which rounding, and where it comes from The rounding rule is not baked into quantize. It comes from the current context, and the default context's rounding is `ROUND_HALF_EVEN` — round a tie to the neighbour whose last digit is even, often called banker's rounding, chosen because it does not systematically drift upward over many roundings. You can override it per call: ```pycon >>> from decimal import Decimal, ROUND_HALF_UP >>> Decimal("2.665").quantize(Decimal("0.01")) Decimal('2.66') >>> Decimal("2.665").quantize(Decimal("0.01"), rounding=ROUND_HALF_UP) Decimal('2.67') ``` That difference matters commercially. Plenty of tax and invoicing rules mandate half-up (or half-away-from-zero) rounding, and plenty of accounting practice mandates half-even. The module also offers directed modes — ceiling, floor, up, down and the half-variants — and picking the one your domain specifies, explicitly, at the point of rounding, is the professional answer. Note also that the tie behaviour is only reachable at all because the value is exact: `Decimal("2.665")` really is two thousand six hundred sixty-five thousandths, whereas the float `2.665` is slightly below the tie and would never round up. ### Trailing zeros, and why they survive Decimal keeps the scale it was given, so arithmetic already produces sensible money shapes: `Decimal("10.00") + Decimal("2.5")` is `Decimal('12.50')`, not `12.5`. quantize is how you *set* that shape deliberately, which makes it the natural last step before formatting or persisting an amount. If you ever need the opposite — the shortest equal representation — that is `normalize`, and it is almost never what you want for currency. ### The InvalidOperation guard quantize raises `InvalidOperation` if the quantized result would need more digits than the context's precision: ```python from decimal import Decimal, InvalidOperation, localcontext with localcontext(prec=6): try: Decimal("12345678.9").quantize(Decimal("0.01")) except InvalidOperation: print("more digits than the context allows") ``` `InvalidOperation` is trapped in the default context, so this is an exception and not a quiet NaN. Treat it as a signal that your precision is too small for the magnitudes you are handling — a context wide enough for the largest total you can produce is part of designing money arithmetic, not an afterthought. ### quantize against round and against string formatting Three things look interchangeable and are not. `round(d, 2)` on a Decimal also returns a Decimal and also uses the context's rounding rule, so `round(Decimal("2.665"), 2)` is `2.66` too; it is a reasonable shorthand, but it takes a digit count rather than a pattern and gives you nowhere to pass a per-call rounding mode. Formatting with `format` or an f-string rounds only the *rendered text* and leaves the stored value untouched, which is right for display and wrong for a value you are about to store, sum or reconcile. And rounding a float first and converting afterwards reintroduces exactly the representation error you adopted Decimal to escape. ### Equal values, different shapes quantize changes the exponent, not the numeric value, and Decimal comparison ignores the exponent: `Decimal("1.10") == Decimal("1.1")` is `True`, and the two hash equal, so they are the same dictionary key. What differs is how they render and what a downstream system stores. That is why asserting on `str(amount)` in a test is really an assertion about scale, and why a value read back from storage may compare equal to yours while displaying with a different number of places. The pattern need not be sub-unit either — quantizing by `Decimal("1")` rounds to whole units, which is what currencies without minor units need. ### Where to apply it The usual rule is that intermediate arithmetic runs at full context precision and quantize happens at the boundaries the business defines: per invoice line, per tax component, before persisting, before display. Rounding early and repeatedly accumulates error; rounding at defined points makes the result reproducible and auditable, and makes it possible to state which rule was applied where.