msgspec-x¶

msgspec-x is a community-driven fork of the original msgspec library. It provides two namespaces: - msgspec: 100% compatible with the original API for drop-in replacement. - msgspec_x: Extended features and community contributions.

Do not install both msgspec and msgspec-x in the same environment.

msgspec-x 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 benchmark as the fastest options for Python.
🎉 Support for a wide variety of Python types. Additional types may be supported through extensions.
🔍 Zero-cost schema validation using familiar Python type annotations. In benchmarks msgspec-x 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, Structs should feel familiar. However, they’re 5-60x faster for common operations.
🆕 StructMeta subclasses support for advanced metaclass programming. Create custom struct behaviors while maintaining full compatibility with all msgspec operations. See StructMeta Subclasses (Advanced) for details.

All of this is included in a lightweight library with no required dependencies.

msgspec-x may be used for serialization alone, as a faster JSON or MessagePack library. For the greatest benefit though, we recommend using msgspec-x to handle the full serialization & validation workflow:

Define your message schemas using standard Python type annotations.

>>> 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.

>>> 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.

>>> 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-x 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-x can be ~10-80x faster than alternative libraries.

Highlights¶

msgspec-x is fast. It benchmarks as the fastest serialization library for Python, outperforming all other JSON/MessagePack libraries compared.
msgspec-x is friendly. Through use of Python’s type annotations, messages are validated during deserialization in a declarative way. msgspec-x also works well with other type-checking tooling like mypy and pyright, providing excellent editor integration.
msgspec-x is flexible. It natively supports a wide range of Python builtin types. Support for additional types can also be added through extensions.
msgspec-x is lightweight. It has no required dependencies, and the binary size is a fraction of that of comparable libraries.
msgspec-x is correct. The encoders/decoders implemented are strictly compliant with their respective specifications, providing stronger guarantees of compatibility with other systems.
msgspec-x is extensible. The new StructMeta subclasses support enables advanced users to create custom struct behaviors through metaclass programming while maintaining full compatibility with all msgspec operations.