Skip to content

Commit d5239aa

Browse files
committed
Expand list of differences between asdict/astuple and to_builtins
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.
1 parent e43b76a commit d5239aa

2 files changed

Lines changed: 55 additions & 26 deletions

File tree

‎docs/usage.rst‎

Lines changed: 24 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -169,10 +169,22 @@ and `msgspec.convert` convert between high-level types and plain builtin types
169169
(``dict``, ``list``, ``str``, ``int``, ...) without going through an encoded
170170
representation.
171171

172-
- `msgspec.to_builtins` is the "encoding" half: it recursively converts a
173-
``Struct`` (or other supported type) into builtin types, applying the same
174-
encoder settings that ``json.encode`` / ``msgpack.encode`` would. This means
175-
it respects :ref:`omit_defaults` and omits :ref:`UNSET <unset-type>` fields.
172+
- `msgspec.to_builtins` is the "encoding" half. It applies the same semantics
173+
as ``json.encode`` / ``msgpack.encode`` - just with builtin Python types as
174+
the output rather than an encoded byte string. This includes:
175+
176+
- Struct-level settings: ``rename``, :ref:`omit_defaults`, ``tag`` for
177+
:ref:`tagged unions <struct-tagged-unions>`, ``array_like``, and
178+
omission of :ref:`UNSET <unset-type>` fields.
179+
- Recursive expansion of nested ``Struct``, ``dataclass``, ``attrs``,
180+
``TypedDict``, and ``NamedTuple`` values.
181+
- Value-level conversions of types that don't map directly to builtin
182+
types: ``bytes`` / ``bytearray`` / ``memoryview`` to base64 string,
183+
``datetime`` / ``date`` / ``time`` / ``timedelta`` to ISO 8601 string,
184+
``uuid.UUID`` and ``decimal.Decimal`` to string, ``set`` / ``frozenset``
185+
to list, ``Enum`` to its member value.
186+
- ``enc_hook``, ``str_keys``, ``order``, and ``builtin_types`` kwargs for
187+
tuning the output to the wrapping protocol.
176188

177189
- `msgspec.convert` is the "decoding" half: it takes builtin types and
178190
validates them against a schema, producing high-level types.
@@ -201,11 +213,14 @@ functions to add ``msgspec`` support for additional serialization protocols.
201213

202214
Note that `msgspec.structs.asdict` and `msgspec.structs.astuple` are *not*
203215
equivalent to `msgspec.to_builtins`. They are modeled on
204-
`dataclasses.asdict` / `dataclasses.astuple`: they convert a single struct
205-
instance to a ``dict`` or ``tuple`` one-to-one, without applying any encoder
206-
settings and without recursing into nested ``Struct`` types. They always
207-
include every field, regardless of ``omit_defaults`` or ``UNSET``. Prefer
208-
`msgspec.to_builtins` when the output is intended for serialization.
216+
`dataclasses.asdict` / `dataclasses.astuple`: a one-to-one conversion of a
217+
single struct instance to a ``dict`` or ``tuple``. They include every field
218+
(regardless of ``omit_defaults`` or ``UNSET``), use the raw attribute names
219+
(ignoring ``rename``), don't inject a ``tag``, don't recurse into nested
220+
``Struct`` / ``dataclass`` / ``attrs`` values, and don't apply any of the
221+
value-level conversions listed above (``bytes``, ``datetime``, ``UUID``,
222+
``Decimal``, ``Enum``, ...). Prefer `msgspec.to_builtins` when the output
223+
is intended for serialization.
209224

210225

211226
.. _JSON: https://json.org

‎src/msgspec/_core.c‎

Lines changed: 31 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -8112,11 +8112,14 @@ PyDoc_STRVAR(struct_asdict__doc__,
81128112
"Convert a struct to a dict.\n"
81138113
"\n"
81148114
"This is a one-to-one conversion of the struct instance, modeled after\n"
8115-
"``dataclasses.asdict``. Every field is included unchanged - the\n"
8116-
"``omit_defaults`` struct option is ignored, ``UNSET`` values are kept,\n"
8117-
"and nested ``Struct`` fields are *not* recursively converted. Use\n"
8118-
"``msgspec.to_builtins`` instead when the output is intended for\n"
8119-
"serialization.\n"
8115+
"``dataclasses.asdict``. Every field is included unchanged using its raw\n"
8116+
"attribute name. Struct-level settings (``rename``, ``tag``,\n"
8117+
"``omit_defaults``, ``array_like``) are ignored, ``UNSET`` values are\n"
8118+
"kept, nested ``Struct`` / ``dataclass`` / ``attrs`` fields are not\n"
8119+
"recursively converted, and no value-level conversions are applied (e.g.\n"
8120+
"``bytes`` is not base64-encoded, ``datetime`` is not converted to a\n"
8121+
"string). Use ``msgspec.to_builtins`` instead when the output is intended\n"
8122+
"for serialization.\n"
81208123
"\n"
81218124
"Parameters\n"
81228125
"----------\n"
@@ -8177,11 +8180,13 @@ PyDoc_STRVAR(struct_astuple__doc__,
81778180
"Convert a struct to a tuple.\n"
81788181
"\n"
81798182
"This is a one-to-one conversion of the struct instance, modeled after\n"
8180-
"``dataclasses.astuple``. Every field is included unchanged - the\n"
8181-
"``omit_defaults`` struct option is ignored, ``UNSET`` values are kept,\n"
8182-
"and nested ``Struct`` fields are *not* recursively converted. Use\n"
8183-
"``msgspec.to_builtins`` instead when the output is intended for\n"
8184-
"serialization.\n"
8183+
"``dataclasses.astuple``. Every field value is included unchanged.\n"
8184+
"Struct-level settings (``omit_defaults``, ``array_like``, ``tag``) are\n"
8185+
"ignored, ``UNSET`` values are kept, nested ``Struct`` / ``dataclass`` /\n"
8186+
"``attrs`` fields are not recursively converted, and no value-level\n"
8187+
"conversions are applied (e.g. ``bytes`` is not base64-encoded,\n"
8188+
"``datetime`` is not converted to a string). Use ``msgspec.to_builtins``\n"
8189+
"instead when the output is intended for serialization.\n"
81858190
"\n"
81868191
"Parameters\n"
81878192
"----------\n"
@@ -20438,14 +20443,23 @@ PyDoc_STRVAR(msgspec_to_builtins__doc__,
2043820443
"commonly supported by Python serialization libraries.\n"
2043920444
"\n"
2044020445
"This is mainly useful for adding msgspec support for other protocols, or\n"
20441-
"for cases where msgspec is only processing part of a message. Encoder\n"
20442-
"settings are applied during conversion: ``omit_defaults`` on ``Struct``\n"
20443-
"types is honored, and fields containing ``msgspec.UNSET`` are omitted\n"
20444-
"from the output. Nested ``Struct`` / ``dataclass`` / ``attrs`` / ``TypedDict``\n"
20445-
"/ ``NamedTuple`` values are recursively converted.\n"
20446+
"for cases where msgspec is only processing part of a message. The\n"
20447+
"conversion applies the same semantics as the ``json``/``msgpack``\n"
20448+
"encoders:\n"
2044620449
"\n"
20447-
"``msgspec.structs.asdict`` and ``msgspec.structs.astuple`` perform a\n"
20448-
"one-to-one conversion and ignore these settings.\n"
20450+
"- Struct-level settings are honored: ``rename``, ``omit_defaults``,\n"
20451+
" ``tag`` for tagged unions, and ``array_like``.\n"
20452+
"- Fields containing ``msgspec.UNSET`` are omitted from the output.\n"
20453+
"- Nested ``Struct`` / ``dataclass`` / ``attrs`` / ``TypedDict`` /\n"
20454+
" ``NamedTuple`` values are recursively converted.\n"
20455+
"- Types that don't map directly to builtins are converted: ``bytes`` /\n"
20456+
" ``bytearray`` / ``memoryview`` to base64 string, ``datetime`` /\n"
20457+
" ``date`` / ``time`` / ``timedelta`` to ISO 8601 string, ``uuid.UUID``\n"
20458+
" and ``decimal.Decimal`` to string, ``set`` / ``frozenset`` to list,\n"
20459+
" ``Enum`` to its member value.\n"
20460+
"\n"
20461+
"``msgspec.structs.asdict`` and ``msgspec.structs.astuple`` do none of\n"
20462+
"this: they perform a one-to-one conversion of a single struct instance.\n"
2044920463
"\n"
2045020464
"Parameters\n"
2045120465
"----------\n"

0 commit comments

Comments
 (0)