1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
Usage
=====
``msgspec`` supports multiple serialization protocols, accessed through
separate submodules:
- ``msgspec.json`` (JSON_)
- ``msgspec.msgpack`` (MessagePack_)
- ``msgspec.yaml`` (YAML_)
- ``msgspec.toml`` (TOML_)
Each supports a consistent interface, making it simple to switch between
protocols as needed.
Encoding
--------
Each submodule has an ``encode`` method for encoding Python objects using the
respective protocol.
.. code-block:: python
>>> import msgspec
>>> # Encode as JSON
... msgspec.json.encode({"hello": "world"})
b'{"hello":"world"}'
>>> # Encode as msgpack
... msgspec.msgpack.encode({"hello": "world"})
b'\x81\xa5hello\xa5world'
Note that if you're making multiple calls to ``encode``, it's more efficient to
create an ``Encoder`` once and use the ``Encoder.encode`` method instead.
.. code-block:: python
>>> import msgspec
>>> # Create a JSON encoder
... encoder = msgspec.json.Encoder()
>>> # Encode as JSON using the encoder
... encoder.encode({"hello": "world"})
b'{"hello":"world"}'
Decoding
--------
Each submodule has ``decode`` method for decoding messages using the respective
protocol.
.. code-block:: python
>>> import msgspec
>>> # Decode JSON
... msgspec.json.decode(b'{"hello":"world"}')
{'hello': 'world'}
>>> # Decode msgpack
... msgspec.msgpack.decode(b'\x81\xa5hello\xa5world')
{'hello': 'world'}
Note that if you're making multiple calls to ``decode``, it's more efficient to
create a ``Decoder`` once and use the ``Decoder.decode`` method instead.
.. code-block:: python
>>> import msgspec
>>> # Create a JSON decoder
... decoder = msgspec.json.Decoder()
>>> # Decode JSON using the decoder
... decoder.decode(b'{"hello":"world"}')
{'hello': 'world'}
.. _typed-decoding:
Typed Decoding
--------------
``msgspec`` optionally supports specifying the expected output types during
decoding. This serves a few purposes:
- Often serialized data has a fixed schema (e.g. a request handler in a REST
api expects a certain JSON structure). Specifying the expected types allows
``msgspec`` to perform validation during decoding, with *no* added runtime
cost.
- Python has a much richer type system than serialization protocols like JSON_
or MessagePack_. Specifying the output types lets ``msgspec`` decode messages
into types other than the defaults described above (e.g. decoding JSON
objects into a :doc:`Struct <structs>` instead of the default `dict`).
- The `type annotations`_ used to describe the expected types are compatible
with tools like mypy_ or pyright_, providing excellent editor integration.
``msgspec`` uses Python `type annotations`_ to describe the expected types. A
:doc:`wide variety of builtin types are supported <supported-types>`.
Here we define a user schema as a :doc:`Struct <structs>` type. We then pass
the type to ``decode`` via the ``type`` keyword argument:
.. code-block:: python
>>> import msgspec
>>> class User(msgspec.Struct):
... name: str
... groups: set[str] = set()
... email: str | None = None
>>> msgspec.json.decode(
... b'{"name": "alice", "groups": ["admin", "engineering"]}',
... type=User
... )
User(name='alice', groups={'admin', 'engineering'}, email=None)
If a message doesn't match the expected type, an error is raised.
.. code-block:: python
>>> msgspec.json.decode(
... b'{"name": "bill", "groups": ["devops", 123]}',
... type=User
... )
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
msgspec.ValidationError: Expected `str`, got `int` - at `$.groups[1]`
.. _strict-vs-lax:
"Strict" vs "Lax" Mode
~~~~~~~~~~~~~~~~~~~~~~
Unlike some other libraries (e.g. pydantic_), ``msgspec`` won't perform any
unsafe implicit conversion by default ("strict" mode). For example, if an
integer is specified and a string is provided instead, an error is raised
rather than attempting to cast the string to an int.
.. code-block:: python
>>> msgspec.json.decode(b'[1, 2, "3"]', type=list[int])
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
msgspec.ValidationError: Expected `int`, got `str` - at `$[2]`
For cases where you'd like a more lax set of conversion rules, you can pass
``strict=False`` to any ``decode`` function or ``Decoder`` class ("lax" mode).
See :doc:`supported-types` for information on how this affects individual
types.
.. code-block:: python
>>> msgspec.json.decode(b'[1, 2, "3"]', type=list[int], strict=False)
[1, 2, 3]
.. _JSON: https://json.org
.. _MessagePack: https://msgpack.org
.. _YAML: https://yaml.org
.. _TOML: https://toml.io
.. _type annotations: https://docs.python.org/3/library/typing.html
.. _pydantic: https://pydantic-docs.helpmanual.io/
.. _mypy: https://mypy.readthedocs.io
.. _pyright: https://github.com/microsoft/pyright
|
