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 ` as the fastest options for Python. - 🎉 **Support for a wide variety of Python types**. Additional types may be supported through :doc:`extensions `. - 🔍 **Zero-cost schema validation** using familiar Python type annotations. In :doc:`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 ` faster for common operations. All of this is included in a :ref:`lightweight library ` 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 "", line 1, in 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 `. Highlights ---------- - ``msgspec`` is **fast**. It :doc:`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 ` 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 `. Support for additional types can also be added through :doc:`extensions `. - ``msgspec`` is **lightweight**. It has no required dependencies, and the binary size is :ref:`a fraction of that of comparable libraries `. - ``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 `__, 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