msgspec Struct

msgspec.Struct is a powerful data class in the msgspec library that's used to define the schema of your data. It's similar to Python's built-in dataclasses or typing.NamedTuple, but it's specifically optimized for high-performance serialization and validation. When you use a Struct, msgspec can perform operations like JSON encoding and decoding significantly faster than standard Python methods because it has a predefined, static understanding of your data's layout.

Defining a Struct

You define a Struct by inheriting from msgspec.Struct and using Python's type hints to specify the fields and their types. All fields must have a type annotation.

import msgspec

class User(msgspec.Struct):
    name: str
    age: int
    is_active: bool

Key Features of msgspec.Struct

Feature	Description	Example
Type Validation	msgspec validates the types of data you pass to the Struct at creation.	User(name="Alice", age=30, is_active=True)
Default Values	You can set default values for fields, similar to dataclasses.	class User(msgspec.Struct): name: str; age: int = 0
Field Aliases	Use msgspec.field to map a Python attribute to a different name in the serialized data (e.g., camelCase for JSON).	username: str = msgspec.field(name="userName")
Validation	Add constraints like minimum values or string patterns directly in the field definition.	age: int = msgspec.field(ge=18)
__slots__	All msgspec.Structs automatically use __slots__ for memory efficiency, which can be important for applications handling a large number of objects.

Practical Example

The primary use of Structs is with msgspec's I/O functions for encoding and decoding.

import msgspec
import json

class Product(msgspec.Struct):
    name: str
    price: float
    tags: list[str] = msgspec.field(default_factory=list)

# 1. Encoding a Struct to JSON
product_obj = Product(name="Laptop", price=1200.50, tags=["electronics", "sale"])
json_bytes = msgspec.json.encode(product_obj)
print(json_bytes)
# Output: b'{"name":"Laptop","price":1200.5,"tags":["electronics","sale"]}'

# 2. Decoding JSON into a Struct
json_data = b'{"name":"Keyboard","price":75.0,"tags":["gaming"]}'
decoded_obj = msgspec.json.decode(json_data, type=Product)
print(decoded_obj)
# Output: Product(name='Keyboard', price=75.0, tags=['gaming'])

Why Use msgspec.Struct?

msgspec.Structs are designed for performance. They compile a fast, static representation of your data schema at runtime, which allows msgspec to be significantly faster than other libraries for serialization and validation. They are an excellent choice for building high-performance APIs or data pipelines where every millisecond counts. 🚀

Sources

• msgspec Documentation: Structs