From 2e6ebfb26163a3e2d3c46f6445669175f79d0d91 Mon Sep 17 00:00:00 2001
From: Alyssa Coghlan <ncoghlan@gmail.com>
Date: Thu, 5 Dec 2024 20:56:11 +1000
Subject: [PATCH 1/3] Cover conversion to/from builtins in usage docs

Also clarify differences between `to_builtins` and `asdict`.

Closes #778
---
 docs/source/usage.rst | 34 ++++++++++++++++++++++++++++++++++
 msgspec/_core.c       |  9 ++++++++-
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/docs/source/usage.rst b/docs/source/usage.rst
index cf876624..ef9f7f6a 100644
--- a/docs/source/usage.rst
+++ b/docs/source/usage.rst
@@ -158,6 +158,40 @@ types.
     >>> msgspec.json.decode(b'[1, 2, "3"]', type=list[int], strict=False)
     [1, 2, 3]
 
+.. _builtin-conversion:
+
+Converting to and from builtin types
+------------------------------------
+
+In some cases, ``msgspec`` will only be processing part of a message,
+so full serialization to or from text or bytes isn't desirable. For
+these situations, ``msgspec`` supports conversion to and from builtin
+types which are otherwised handled (or created) by another library.
+
+"Decoding" is handled by :func:`~msgspec.convert`, while "encoding" is handled by
+:func:`~msgspec.to_builtins` (note that the input/output in this example is a
+Python dictionary, *not* an encoded string):
+
+.. code-block:: python
+
+    >>> import msgspec
+
+    >>> class User(msgspec.Struct):
+    ...     name: str
+    ...     groups: set[str] = set()
+    ...     email: str | None = None
+
+    >>> data = {"name": "bill", "groups": ["devops", "engineering"]}
+
+    >>> # Convert already decoded data into typed structs
+    ... msgspec.convert(data, User)
+    User(name='bill', groups={'devops', 'engineering'}, email=None)
+
+    >>> user = User(name="alice", groups={"admin", "engineering"}, email=None)
+
+    >>> # Convert to builtin types for subsequent encoding
+    ... msgspec.to_builtins(user)
+    {'name': 'alice', 'groups': ['engineering', 'admin']}
 
 .. _JSON: https://json.org
 .. _MessagePack: https://msgpack.org
diff --git a/msgspec/_core.c b/msgspec/_core.c
index bfb73680..12aa31ba 100644
--- a/msgspec/_core.c
+++ b/msgspec/_core.c
@@ -7798,6 +7798,10 @@ PyDoc_STRVAR(struct_asdict__doc__,
 "\n"
 "Convert a struct to a dict.\n"
 "\n"
+"This function converts all fields, regardless of the ``omit_defaults`` setting.\n"
+"\n"
+"Use ``to_builtins`` for recursive conversion with more encoding-like behavior.\n"
+"\n"
 "Parameters\n"
 "----------\n"
 "struct: Struct\n"
@@ -19995,7 +19999,10 @@ PyDoc_STRVAR(msgspec_to_builtins__doc__,
 "Convert a complex object to one composed only of simpler builtin types\n"
 "commonly supported by Python serialization libraries.\n"
 "\n"
-"This is mainly useful for adding msgspec support for other protocols.\n"
+"This is useful for adding msgspec support for other protocols, as well as\n"
+"to handle cases where msgspec is only processing part of a data structure."
+"\n"
+"This function respects the ``omit_defaults`` setting on structs.\n"
 "\n"
 "Parameters\n"
 "----------\n"

From c0df467e752016f8984f637d0f28d29e19aced21 Mon Sep 17 00:00:00 2001
From: Alyssa Coghlan <ncoghlan@gmail.com>
Date: Sun, 8 Dec 2024 14:42:50 +1000
Subject: [PATCH 2/3] Fix typo

---
 docs/source/usage.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/source/usage.rst b/docs/source/usage.rst
index ef9f7f6a..4752de00 100644
--- a/docs/source/usage.rst
+++ b/docs/source/usage.rst
@@ -166,7 +166,7 @@ Converting to and from builtin types
 In some cases, ``msgspec`` will only be processing part of a message,
 so full serialization to or from text or bytes isn't desirable. For
 these situations, ``msgspec`` supports conversion to and from builtin
-types which are otherwised handled (or created) by another library.
+types which are otherwise handled (or created) by another library.
 
 "Decoding" is handled by :func:`~msgspec.convert`, while "encoding" is handled by
 :func:`~msgspec.to_builtins` (note that the input/output in this example is a

From 0b666fd39da7162b85d2ae77e9c45ff361dee43d Mon Sep 17 00:00:00 2001
From: Alyssa Coghlan <ncoghlan@gmail.com>
Date: Mon, 16 Dec 2024 13:48:11 +1000
Subject: [PATCH 3/3] Add missing newline in docstring

---
 msgspec/_core.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/msgspec/_core.c b/msgspec/_core.c
index 12aa31ba..3b9732ee 100644
--- a/msgspec/_core.c
+++ b/msgspec/_core.c
@@ -20000,7 +20000,7 @@ PyDoc_STRVAR(msgspec_to_builtins__doc__,
 "commonly supported by Python serialization libraries.\n"
 "\n"
 "This is useful for adding msgspec support for other protocols, as well as\n"
-"to handle cases where msgspec is only processing part of a data structure."
+"to handle cases where msgspec is only processing part of a data structure.\n"
 "\n"
 "This function respects the ``omit_defaults`` setting on structs.\n"
 "\n"