Consider using stubtest to test the stubs #1056

Activity

1. Siyet commented on Jul 4, 2026

   

   Siyet

   on Jul 4, 2026

   Contributor

   More actions

   Agreed this is worth adding. I ran stubtest against current main (mypy 2.1.0) to see where we stand:

   $ python -m mypy.stubtest msgspec
   Found 130 errors (checked 12 modules)
   

   Breakdown:

   • ~110 (85%) are one structural false positive: stubtest can't see through the C-level __init__/__new__ signatures synthesized for Struct subclasses and for the Meta/Ext/UnsetType C types (70 come from the Struct subclasses in inspect.py alone). These want an allowlist, not a fix.
   • The remaining ~20 are actionable:
     • msgspec.structs.__all__ is not present in the stub.
     • msgspec.StructMeta is a disjoint base at runtime but isn't marked @disjoint_base in the stub (same class of drift Annotate types without Py_TPFLAGS_BASETYPE as @final #1043 fixed by hand).
     • 11 public json/msgpack callables (decode, encode, decode_lines, encode_lines, json.format, and the Decoder/Encoder methods) mark their first arg positional-only (/) in the stub, but the runtime accepts it as a keyword. Either the stub drops / or the runtime is made positional-only, needs a call.
     • 7 private msgspec._utils helpers leak into the check (no .pyi); simplest is to exclude _utils.

   So the real signal is ~13 items behind a roughly 10-line allowlist, with 85% of the raw output being one repeated false positive.

   This is exactly the stub/runtime drift the spring stub PRs fixed manually (#1043 @final/@disjoint_base, #1062 missing __class_getitem__), so wiring it into CI should stop that recurring. mypy is already in the test-typing group, so no new dependency.

   Happy to open a PR adding a stubtest step to the test-typing job with an allowlist plus the fixes above. @sobolevn does that split sound right, and any preference on the positional-only mismatch (relax the stubs vs make the runtime positional-only)?
2. sobolevn commented on Jul 4, 2026

   

   sobolevn

   on Jul 4, 2026

   Last edited by sobolevn

   MemberAuthor

   More actions

   Please, go ahead with the PR :)
   We must always prefer the real function over the typing one.

   Because some people might not use typing and use the keyword form for the call, if we replace it with posonly parameter, it will be a breaking change for them. But, allowing pos-or-keyword calls in the existing functions / methods is a new feature.
3. Siyet

   closed this as completedin #1116on Sep 5, 2026
4. pull

   added a commit that references this issue on Sep 5, 2026

   Run stubtest in the type-checking CI job (msgspec#1116)

   ...

   This issue will close once commit 7b18791 is merged into the 'main' branch.

   7b18791