Siyet · GitHub

added 4 commits

April 20, 2026 20:01
Add 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

@Siyet Siyet mentioned this pull request

May 26, 2026

Closed

Read the original on github.com ↗