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
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
|
msgspec
=======
``msgspec`` is a *fast* serialization and validation library, with builtin
support for JSON_, MessagePack_, YAML_, and TOML_. It features:
- 🚀 **High performance encoders/decoders** for common protocols. The JSON and
MessagePack implementations regularly :doc:`benchmark <benchmarks>` as the
fastest options for Python.
- 🎉 **Support for a wide variety of Python types**. Additional types may
be supported through :doc:`extensions <extending>`.
- 🔍 **Zero-cost schema validation** using familiar Python type annotations.
In :doc:`benchmarks <benchmarks>` ``msgspec`` decodes *and* validates JSON
faster than orjson_ can decode it alone.
- ✨ **A speedy Struct type** for representing structured data. If you already
use dataclasses_ or attrs_, :doc:`structs` should feel familiar. However,
they're :ref:`5-60x <struct-benchmark>` faster for common operations.
All of this is included in a :ref:`lightweight library
<benchmark-library-size>` with no required dependencies.
-----
``msgspec`` may be used for serialization alone, as a faster JSON or
MessagePack library. For the greatest benefit though, we recommend using
``msgspec`` to handle the full serialization & validation workflow:
**Define** your message schemas using standard Python type annotations.
.. code-block:: python
>>> import msgspec
>>> class User(msgspec.Struct):
... """A new type describing a User"""
... name: str
... groups: set[str] = set()
... email: str | None = None
**Encode** messages as JSON, or one of the many other supported protocols.
.. code-block:: python
>>> alice = User("alice", groups={"admin", "engineering"})
>>> alice
User(name='alice', groups={"admin", "engineering"}, email=None)
>>> msg = msgspec.json.encode(alice)
>>> msg
b'{"name":"alice","groups":["admin","engineering"],"email":null}'
**Decode** messages back into Python objects, with optional schema validation.
.. code-block:: python
>>> msgspec.json.decode(msg, type=User)
User(name='alice', groups={"admin", "engineering"}, email=None)
>>> msgspec.json.decode(b'{"name":"bob","groups":[123]}', type=User)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
msgspec.ValidationError: Expected `str`, got `int` - at `$.groups[0]`
``msgspec`` is designed to be as performant as possible, while retaining some
of the nicities of validation libraries like pydantic_. For supported types,
encoding/decoding a message with ``msgspec`` can be :doc:`~10-80x faster than
alternative libraries <benchmarks>`.
Highlights
----------
- ``msgspec`` is **fast**. It :doc:`benchmarks <benchmarks>` as the fastest
serialization library for Python, outperforming all other JSON/MessagePack
libraries compared.
- ``msgspec`` is **friendly**. Through use of Python's type annotations,
messages are :ref:`validated <typed-decoding>` during deserialization in a
declarative way. ``msgspec`` also works well with other type-checking tooling
like mypy_ and pyright_, providing excellent editor integration.
- ``msgspec`` is **flexible**. It natively supports a :doc:`wide range of
Python builtin types <supported-types>`. Support for additional types can
also be added through :doc:`extensions <extending>`.
- ``msgspec`` is **lightweight**. It has no required dependencies, and the
binary size is :ref:`a fraction of that of comparable libraries
<benchmark-library-size>`.
- ``msgspec`` is **correct**. The encoders/decoders implemented are strictly
compliant with their respective specifications, providing stronger guarantees
of compatibility with other systems.
Used By
-------
``msgspec`` is used by many organizations and `open source projects
<https://github.com/jcrist/msgspec/network/dependents>`__, here we highlight a
few:
.. grid:: 2 2 4 4
.. grid-item-card:: NautilusTrader
:link: https://nautilustrader.io/
.. image:: _static/nautilus-trader.png
.. grid-item-card:: Litestar
:link: https://litestar.dev/
.. image:: _static/litestar.png
.. grid-item-card:: Sanic
:link: https://sanic.dev/en/
.. image:: _static/sanic.png
.. grid-item-card:: Mosec
:link: https://mosecorg.github.io/mosec/
.. image:: _static/mosec.png
.. grid-item-card:: Pioreactor
:link: https://pioreactor.com/
.. image:: _static/pioreactor.png
.. grid-item-card:: Zero
:link: https://github.com/Ananto30/zero
.. image:: _static/zero.png
.. grid-item-card:: anywidget
:link: https://anywidget.dev/
.. image:: _static/anywidget.png
.. grid-item-card:: esmerald
:link: https://esmerald.dev/
.. image:: _static/esmerald.png
.. _type annotations: https://docs.python.org/3/library/typing.html
.. _JSON: https://json.org
.. _MessagePack: https://msgpack.org
.. _YAML: https://yaml.org
.. _TOML: https://toml.io
.. _attrs: https://www.attrs.org
.. _dataclasses: https://docs.python.org/3/library/dataclasses.html
.. _orjson: https://github.com/ijl/orjson
.. _pydantic: https://pydantic-docs.helpmanual.io/
.. _mypy: https://mypy.readthedocs.io
.. _pyright: https://github.com/microsoft/pyright
.. toctree::
:hidden:
:maxdepth: 2
:caption: Overview
why.rst
install.rst
benchmarks.rst
.. toctree::
:hidden:
:maxdepth: 2
:caption: User Guide
usage.rst
supported-types.rst
structs.rst
constraints.rst
converters.rst
jsonschema.rst
schema-evolution.rst
.. toctree::
:hidden:
:maxdepth: 2
:caption: Advanced
extending.rst
inspect.rst
perf-tips.rst
.. toctree::
:hidden:
:maxdepth: 2
:caption: Reference
api.rst
examples/index.rst
changelog.rst
|
