@@ -288,6 +288,53 @@ average another ~2x speedup for decoding (and ~1.5x speedup for encoding).
288288 Example(my_first_field = " some string" , my_second_field = 2 )
289289
290290
291+ Think about type conversion
292+ ---------------------------
293+
294+ When converting raw data into Python types, the internal machinery
295+ will treat different datastructures differently.
296+ Some type conversions are faster than others.
297+
298+ For example, this model:
299+
300+ .. code-block :: python
301+
302+ class Example (msgspec .Struct ):
303+ items: frozendict[str , int ] # requires Python3.15+ to be used
304+
305+ msg = b ' {"items": {"pen": 1, "book": 2}}'
306+ msgspec.json.decode(msg, type = Example)
307+ # Example(items=frozendict({"pen": 1, "book": 2}))
308+
309+ As ``frozendict `` does not allow adding items one at a time,
310+ ``msgspec `` will first parse ``items `` as a regular :class: `dict `,
311+ and will then convert it to ``frozendict ``, which results in the
312+ total decoding operation having ``O(n*2) `` time complexity.
313+ Which might be slow on big dictionaries and consume more memory.
314+ Regular :class: `dict ` would be more efficient to use.
315+
316+ The same can be said for :class: `tuple ` vs :class: `list `:
317+
318+ .. code-block :: python
319+
320+ >> > class Example (msgspec .Struct ):
321+ ... items: tuple[str , ... ]
322+
323+ >> > msg = b ' {"items": ["pen", "book"]}'
324+
325+ >> > msgspec.json.decode(msg, type = Example)
326+ Example(items = (" pen" , " book" ))
327+
328+ We would first create a ``list `` object and then convert
329+ it to variable-sized ``tuple ``,
330+ using double the memory and ``O(n*2) `` time to do that.
331+ This is true for all conversions, that require an intermediate representation.
332+
333+ To achieve the best performance,
334+ use collection types that can be constructed natively:
335+ ``list ``, ``set ``, ``frozenset ``, fixed-sized ``tuple ``, and ``dict ``.
336+
337+
291338.. _JSON : https://json.org
292339.. _MessagePack : https://msgpack.org
293340.. _line-delimited JSON : https://en.wikipedia.org/wiki/JSON_streaming#Line-delimited_JSON
0 commit comments