added 4 commits
April 20, 2026 20:01Add a usage docs section explaining that to_builtins is the encoding half (respects omit_defaults, UNSET, and recurses into nested struct-like types) while structs.asdict/astuple perform a one-to-one conversion following the dataclasses.asdict/astuple contract. Cross-reference the new section from the omit_defaults and UNSET sections, and update the C docstrings for asdict, astuple, and to_builtins. Fixes #778. Supersedes #780.
The previous wording only called out omit_defaults and UNSET, but to_builtins differs from asdict/astuple in more ways: rename, tag injection, array_like, recursion into nested Struct/dataclass/attrs/ TypedDict/NamedTuple values, and all the value-level conversions (bytes to base64, datetime to ISO 8601, UUID/Decimal to string, set to list, Enum to member value). This matters because prior confused-user reports cover all of these axes: #748 tripped on rename, #830 on array_like plus recursion.
The msgspec docs use default_role='obj', so single-backtick references like `msgspec.to_builtins` and `dataclasses.dataclass` auto-link to the api page or (via intersphinx) to the Python stdlib docs. Switch Python-object references from double backticks (literal) to single backticks so they link, and use fully-qualified names so they resolve. Double backticks are kept for kwarg names and setting values that aren't importable objects (rename, tag, omit_defaults, array_like, enc_hook, str_keys, order, builtin_types). Also add an attrs_ target in usage.rst for the attrs library link.
- Unify the order of Struct-level settings across docstrings and usage docs to `rename, omit_defaults, array_like, tag`. - Split the 60-word sentence at the end of the usage section into three shorter paragraphs (what asdict/astuple do, what they don't do, when to prefer to_builtins). - Condense the value-level conversions bullet in the `to_builtins` docstring; the full list now lives in the usage docs via a cross-reference. - Soften the closing sentence of the `to_builtins` docstring: 'do none of this' -> 'perform a plain one-to-one conversion, applying none of the above'. - In the usage bullet list, split 'struct-level settings' and 'UNSET omission' into separate bullets so UNSET isn't lumped in with settings.
Siyet
mentioned this pull request
Closed