Support numeric constraints for decimal.Decimal - #1006

It looks like the Git history needs to be fixed on this one.

The failing build job here is unrelated to this PR: it's the link checker tripping on the Pydantic docs redirect (docs.pydantic.dev/latest/ → pydantic.dev/docs/validation/...), which is fixed in #1008. Once #1008 lands and this branch is rebased, CI should go green.

@ofek done — force-pushed a clean rewrite of the branch:

• Squashed into a single commit with a proper message and Closes #683 reference.
• Rebased onto current main, dropping all the leftover commits from the deleted fork (CODEOWNERS, package rename, doc-link rewrites, plus changes that belong to other PRs).
• Scope is now strictly the four Decimal-relevant files: _core.c, __init__.pyi, docs/constraints.rst, tests/unit/test_constraints.py. Diff stat is +353/-52.
• MS_CONSTR_DECIMAL_* flags claim bits 36-40, the lowest unused slots in TypeNode->types. If Support Literal[True] and Literal[False] types #1004 lands first, I'll rebase to whatever bits are next free.

Build job is still red on the link checker but that's the unrelated #1008 fix; nothing in this branch touches it.

Rebased onto main now that #1004 has landed. #1004 took bits 36-37 for MS_TYPE_BOOLLITERAL_TRUE/FALSE, so I shifted the Decimal constraint flags to the next free slots:

• MS_CONSTR_DECIMAL_GT/GE/LT/LE -> bits 38-41 (the remaining gap between types and existing constraints)
• MS_CONSTR_DECIMAL_MULTIPLE_OF -> bit 61 (the only free slot that's left below the reserved MS_EXTRA_FLAG at 63)

No other constraint bits were moved. SLOT numbering and the TypeNode->details[] ordering are unchanged (SLOTs use the named constants, not raw bit positions).

@provinzkraut added the check: a Decimal in gt/ge/lt/le/multiple_of now raises TypeError at encoder construction time when the annotated type isn't Decimal. Coercing to int/float loses precision, so a Decimal bound there is pointless.

Covered with a parametrized test, docs updated.

@provinzkraut this is already handled in this PR: a Decimal bound on an int/float type is rejected with a TypeError (typenode_collect_constraints, via PyObject_IsInstance(..., DecimalType)), covered by test_invalid_decimal_bound_on_non_decimal for all five of gt/ge/lt/le/multiple_of. The check runs at TypeNode construction, so it's protocol-agnostic (msgpack behaves identically).

Rebased on main and reworked the constraint storage, two commits:

1. Storage redesign (38f7e7c): decimal constraints now live in a single details slot holding a 5-tuple (gt, ge, lt, le, multiple_of) (None for unset), gated by one MS_CONSTR_DECIMAL bit. This was forced by bit-space math: Add frozendict support for 3.15+ #1052 took bits 38-39 for frozendict, leaving only 4 free bits (40, 41, 61, 62) in the types mask while the old per-constraint layout needed 5. Sharing bits with the float constraints isn't an option since constrained members of different numeric types can coexist in one union (test_mix_float_and_int). The single-slot shape follows the literal-lookup precedent (one bit, one object holding the details). Validation is unchanged behavior-wise; the check is already a cold path gated by one bit test.
2. Merge main (def7a7b): trivial after the redesign, MS_CONSTR_DECIMAL landed on bit 40.

Also addressed the PyObject_IsTrue review comment: the remainder is now compared against zero explicitly (see inline reply), with a regression test for a __bool__-overriding subclass.

Verified locally on 3.12 and 3.15.0a7 (WSL): full unit suite green on both (6351 / 6439 passed), decimal constraints + frozendict coexist correctly in one union on 3.15 (slot ordering with bits 38-39 + 40), and 100k decoder create/destroy cycles show zero RSS growth (constraint tuple lifecycle is leak-free).

Merging this PR will degrade performance by 10.27%

❌ 1 regressed benchmark
✅ 138 untouched benchmarks
⏩ 135 skipped benchmarks¹

Performance Changes

_{Comparing decimal-constraints-683 (3e7d11e) with main (3f67b34)}

Merged current main in, resolving the stub against the Meta overloads from #700: the five overloads are kept and the numeric params are retyped to int | float | Decimal | None.

Holding this PR. Re-reviewing it turned up a real defect of mine: decimal.InvalidOperation escapes json.decode on ordinary input. Annotated[Decimal, Meta(multiple_of=Decimal("3"))] with "1E+30" raises [DivisionImpossible], and Annotated[Decimal, Meta(gt=Decimal("1"))] with "NaN" raises InvalidOperation. Both float equivalents raise a clean ValidationError, so as it stands this PR throws a non-msgspec exception out of decoding untrusted input.

Fixed in this push: Decimal bounds now get the finiteness check the float bounds always had, and both that check and the multiple_of > 0 check run against an exact Decimal, so a subclass overriding is_finite or __gt__ cannot slip a NaN or a negative bound past them. That also fixed Decimal("1E+400") being rejected and multiple_of=Decimal("1E-400") being rejected as "must be > 0", both from routing the check through a double. The Meta C docstring no longer says "int or float".

Not fixed, because it is a semantics call that also decides how the remainder gets computed: for non-finite input, either follow float parity and let it fail the comparison as a ValidationError, or reject it outright on a constrained Decimal. Which do you want? @sobolevn @provinzkraut

This adds public API and touches TypeNodes, so it needs a real review rather than a merge on silence.

Pushed two things: current main merged in (this was four merges stale), and a fix for an overflow bug in ensure_is_finite_numeric that this branch made worse.

Why it belongs here rather than in its own PR. The unchecked PyLong_AsDouble in that function predates this work: on main today, Meta(gt=10**400) raises SystemError, and Meta(multiple_of=10**400) reports a large positive bound as must be > 0, because the -1.0 sentinel trips the positivity check. It is the same root cause as the convert_int bug fixed in #1162. What makes it this branch's problem is that the branch degraded it. On main:

>>> msgspec.Meta(gt=10**400, lt=Decimal("5"))
TypeError: `lt` must be an int or float, got decimal.Decimal

and here, before this push:

>>> msgspec.Meta(gt=10**400, lt=Decimal("5"))
SystemError: <class 'decimal.Decimal'> returned a result with an exception set

A typed error became a SystemError blaming decimal.Decimal, because the new Decimal branch now runs with a pending OverflowError.

Accept rather than reject. The obvious fix is to raise a ValueError for out-of-double int bounds, and I had that written before discarding it. It cannot be right here, because Meta already treats the two spellings as one value:

>>> Meta(gt=10**400) == Meta(gt=Decimal("1E+400"))
True
>>> hash(Meta(gt=10**400)) == hash(Meta(gt=Decimal("1E+400")))
True

Annotated is cached by equality, so Annotated[Decimal, Meta(gt=10**400)] and Annotated[Decimal, Meta(gt=Decimal("1E+400"))] are the same object. Rejecting one and accepting the other would also contradict this branch's own argument, that a double is the wrong gate for large-but-finite bounds, applied to ints instead of Decimals. And it would add a third representability threshold at construction time, so ge=10**308 would pass and ge=10**309 would not, even on a Decimal field where both work.

So the int branch stops going through a double at all. Every int is finite, and the only remaining check, positivity for multiple_of, is done exactly against zero, which is what the Decimal branch already did; that block is now shared as ensure_is_positive. PyLong_CheckExact keeps subclasses out of the comparison, so a lying __gt__ cannot slip past it.

Usability stays a per-type question, as it already was for Meta(gt=2**64), which this branch accepts and then refuses only for int targets. _constr_as_f64 grows the missing half: instead of the comment "should never be hit, types already checked" (an invariant that held only because the bug crashed first), an out-of-double bound on a float target now gets the same shape of message _constr_as_i64 already gives. The result:

Verified on the merge with current main, CPython 3.14.6: unit suite 6466 passed, 143 skipped (26 new tests, no regressions); stubtest clean across 12 modules, which matters now that #1116 has landed and gates the stubs; mypy on tests/typing clean; ruff, format and codespell clean; docs build green with --fail-on-warning.

One cosmetic wart, disclosed rather than hidden: the int spelling produces Expected Decimal > Decimal('1000...000') with 401 digits, where the Decimal spelling gives Decimal('1E+400'), because _constr_as_decimal builds an unnormalised Decimal from the int. Harmless, and I would rather not normalise silently, but say the word if it bothers you.

Deliberately not in this push: ensure_is_nonnegative_integer has the same shape with PyLong_AsSsize_t, so Meta(min_length=10**400) claims a positive value is negative. No causal link to this branch and no design question in it, so it goes separately.

@sobolevn this is still held on the semantics question from my last comment, and it has grown a third case. All three, on this branch:

# 1. remainder against a bound that cannot divide
multiple_of=Decimal("3"), input "1E+30"   -> InvalidOperation: [DivisionImpossible]
# 2. comparison against NaN
gt=Decimal("1"),          input "NaN"     -> InvalidOperation: [InvalidOperation]
# 3. Infinity satisfies any lower bound, silently
gt=Decimal("1"),          input "Infinity" -> Decimal('Infinity')

The third is the worst of them: it is a wrong answer rather than an exception, and the float path disagrees, rejecting 1e400 with ValidationError: Number out of range. Note none of this depends on Decimal bounds; multiple_of=3 with a plain int bound reaches case 1 too, so it is about what the decoder does with non-finite and very large input, not about the bounds feature.

My inclination is that all three should be ValidationError, with Infinity failing every finite bound and NaN failing all of them, but that is a semantics call I would rather not make alone. Your review of the Decimal storage was the substantive one on this PR, so I would value your read on this in particular.

@provinzkraut your check that a Decimal bound is only valid on a Decimal type is still in and still enforced; the new table above is what happens to int bounds, which that guard does not cover.

CI is green apart from CodSpeed, which is the known false flag, not something to look at.

The single regressed benchmark is test_pickle_load[arm], 1.6 ms to 1.8 ms. That is the bimodal one tracked in #1110: it flips between those two exact values on commits that do not touch the pickle path, including on main itself. Today it flipped the other way on #1116, a stubtest-only PR, where the same benchmark was reported as 1.8 ms to 1.6 ms, +11.48%. This branch touches Meta.__new__ argument validation and constraint setup, neither of which runs while unpickling a Struct.

Everything else passed: tests on 3.10 through 3.15-dev, all seven wheel builds, Pyodide, integration, docs, memory benchmarks and the Deploy preview.