API Docs¶

Structs¶

class msgspec.Struct¶

A base class for defining efficient serializable objects.

Fields are defined using type annotations. Fields may optionally have default values, which result in keyword parameters to the constructor.

Structs automatically define __init__, __eq__, __repr__, and __copy__ methods. Additional methods can be defined on the class as needed. Note that __init__/__new__ cannot be overridden, but other methods can. A tuple of the field names is available on the class via the __struct_fields__ attribute if needed.

Additional class options can be enabled by passing keywords to the class definition (see example below). These configuration options may also be inspected at runtime through the __struct_config__ attribute.

Configuration:

frozen (bool, default False) – Whether instances of this type are pseudo-immutable. If true, attribute assignment is disabled and a corresponding __hash__ is defined.
order (bool, default False) – If True, __lt__, __le__`, __gt__, and __ge__ methods will be generated for this type.
eq (bool, default True) – If True (the default), an __eq__ method will be generated for this type. Set to False to compare based on instance identity alone.
kw_only (bool, default False) – If True, all fields will be treated as keyword-only arguments in the generated __init__ method. Default is False.
omit_defaults (bool, default False) – Whether fields should be omitted from encoding if the corresponding value is the default for that field. Enabling this may reduce message size, and often also improve encoding & decoding performance.
forbid_unknown_fields (bool, default False) – If True, an error is raised if an unknown field is encountered while decoding structs of this type. If False (the default), no error is raised and the unknown field is skipped.
tag (str, int, bool, callable, or None, default None) – Used along with tag_field for configuring tagged union support. If either are non-None, then the struct is considered “tagged”. In this case, an extra field (the tag_field) and value (the tag) are added to the encoded message, which can be used to differentiate message types during decoding.

Set tag=True to enable the default tagged configuration (tag_field is "type", tag is the class name). Alternatively, you can provide a string (or less commonly int) value directly to be used as the tag (e.g. tag="my-tag-value").``tag`` can also be passed a callable that takes the class qualname and returns a valid tag value (e.g. tag=str.lower). See the docs for more information.
tag_field (str or None, default None) – The field name to use for tagged union support. If tag is non-None, then this defaults to "type". See the tag docs above for more information.
rename (str, mapping, callable, or None, default None) – Controls renaming the field names used when encoding/decoding the struct. May be one of "lower", "upper", "camel", "pascal", or "kebab" to rename in lowercase, UPPERCASE, camelCase, PascalCase, or kebab-case respectively. May also be a mapping from field names to the renamed names (missing fields are not renamed). Alternatively, may be a callable that takes the field name and returns a new name or None to not rename that field. Default is None for no field renaming.
repr_omit_defaults (bool, default False) – Whether fields should be omitted from the generated repr if the corresponding value is the default for that field.
array_like (bool, default False) – If True, this struct type will be treated as an array-like type during encoding/decoding, rather than a dict-like type (the default). This may improve performance, at the cost of a more inscrutable message encoding.
gc (bool, default True) – Whether garbage collection is enabled for this type. Disabling this may help reduce GC pressure, but will prevent reference cycles composed of only gc=False from being collected. It is the user’s responsibility to ensure that reference cycles don’t occur when setting gc=False.
weakref (bool, default False) – Whether instances of this type support weak references. Defaults to False.
dict (bool, default False) – Whether instances of this type will include a __dict__. Setting this to True will allow adding additional undeclared attributes to a struct instance, which may be useful for holding private runtime state. Defaults to False.
cache_hash (bool, default False) – If enabled, the hash of a frozen struct instance will be computed at most once, and then cached on the instance for further reuse. For expensive hash values this can improve performance at the cost of a small amount of memory usage.

Examples

Here we define a new Struct type for describing a dog. It has three fields; two required and one optional.

>>> class Dog(Struct):
...     name: str
...     breed: str
...     is_good_boy: bool = True
...
>>> Dog('snickers', breed='corgi')
Dog(name='snickers', breed='corgi', is_good_boy=True)

Additional struct options can be set as part of the class definition. Here we define a new Struct type for a frozen Point object.

>>> class Point(Struct, frozen=True):
...     x: float
...     y: float
...
>>> {Point(1.5, 2.0): 1}  # frozen structs are hashable
{Point(x=1.5, y=2.0): 1}

msgspec.field(*, default=NODEFAULT, default_factory=NODEFAULT, name=None)¶

Configuration for a Struct field.

Parameters:

default (Any, optional) – A default value to use for this field.
default_factory (callable, optional) – A zero-argument function called to generate a new default value per-instance, rather than using a constant value as in default.
name (str, optional) – The name to use when encoding/decoding this field. If present, this will override any struct-level configuration using the rename option for this field.

msgspec.defstruct(name, fields, *, bases=None, module=None, namespace=None, tag_field=None, tag=None, rename=None, omit_defaults=False, forbid_unknown_fields=False, frozen=False, eq=True, order=False, kw_only=False, repr_omit_defaults=False, array_like=False, gc=True, weakref=False, dict=False, cache_hash=False)¶

Dynamically define a new Struct class.

Parameters:

name (str) – The name of the new Struct class.
fields (iterable) – An iterable of fields in the new class. Elements may be either name, tuples of (name, type), (name, type, default), or (name, type, msgspec.field). Fields without a specified type will default to typing.Any.
bases (tuple, optional) – A tuple of any Struct base classes to use when defining the new class.
module (str, optional) – The module name to use for the new class. If not provided, will be inferred from the caller’s stack frame.
namespace (dict, optional) – If provided, will be used as the base namespace for the new class. This may be used to add additional methods to the class definition.
**kwargs – Additional Struct configuration options. See the Struct docs for more information.

Examples

>>> from msgspec import defstruct, field
>>> User = defstruct(
...     'User',
...     [
...         ('name', str),
...         ('email', str | None, None),
...         ('groups', set[str], field(default_factory=set)),
...     ],
... )
>>> User('alice')
User(name='alice', email=None, groups=set())

See also

Struct

msgspec.structs.replace(struct, /, **changes)¶

Create a new struct instance of the same type as struct, replacing fields with values from **changes.

Parameters:

struct (Struct) – The original struct instance.
**changes – Fields and values that should be replaced in the new struct instance.

Returns:

new_struct (Struct) – A new struct instance of the same type as struct.

Examples

>>> class Point(msgspec.Struct):
...     x: int
...     y: int
>>> obj = Point(x=1, y=2)
>>> msgspec.structs.replace(obj, x=3)
Point(x=3, y=2)

See also

copy.replace, dataclasses.replace

msgspec.structs.asdict(struct)¶

Convert a struct to a dict.

Parameters:: struct (Struct) – The struct instance.
Returns:: dict

Examples

>>> class Point(msgspec.Struct):
...     x: int
...     y: int
>>> obj = Point(x=1, y=2)
>>> msgspec.structs.asdict(obj)
{'x': 1, 'y': 2}

msgspec.structs.astuple(struct)¶

Convert a struct to a tuple.

Parameters:: struct (Struct) – The struct instance.
Returns:: tuple

Examples

>>> class Point(msgspec.Struct):
...     x: int
...     y: int
>>> obj = Point(x=1, y=2)
>>> msgspec.structs.astuple(obj)
(1, 2)

msgspec.structs.force_setattr(struct, name, value)¶

Set an attribute on a struct, even if the struct is frozen.

The main use case for this is modifying a frozen struct in a __post_init__ method before returning.

Warning

This function violates the guarantees of a frozen struct, and is potentially unsafe. Only use it if you know what you’re doing!

Parameters:

struct (Struct) – The struct instance.
name (str) – The attribute name.
value (Any) – The attribute value.

msgspec.structs.fields(type_or_instance)¶

Get information about the fields in a Struct.

Parameters:: type_or_instance – A struct type or instance.
Returns:: tuple[FieldInfo]

class msgspec.structs.FieldInfo(name, encode_name, type, default=<factory>, default_factory=<factory>)¶

A record describing a field in a struct type.

Parameters:

name (str) – The field name as seen by Python code (e.g. field_one).
encode_name (str) – The name used when encoding/decoding the field. This may differ if the field is renamed (e.g. fieldOne).
type (Any) – The full field type annotation.
default (Any, optional) – A default value for the field. Will be NODEFAULT if no default value is set.
default_factory (Any, optional) – A callable that creates a default value for the field. Will be NODEFAULT if no default_factory is set.

class msgspec.structs.StructConfig¶

Configuration settings for a given Struct type.

This object is accessible through the __struct_config__ field on a struct type or instance. It exposes the following attributes, matching the Struct configuration parameters of the same name. See the Struct docstring for details.

Configuration:

frozen (bool)
eq (bool)
order (bool)
array_like (bool)
gc (bool)
repr_omit_defaults (bool)
omit_defaults (bool)
forbid_unknown_fields (bool)
weakref (bool)
dict (bool)
cache_hash (bool)
tag_field (str | None)
tag (str | int | None)

msgspec.NODEFAULT¶: A singleton indicating no default value is configured.

Meta¶

class msgspec.Meta(*, gt=None, ge=None, lt=None, le=None, multiple_of=None, pattern=None, min_length=None, max_length=None, tz=None, title=None, description=None, examples=None, extra_json_schema=None, extra=None)¶

Extra metadata and constraints for a type or field.

Parameters:

gt (int or float, optional) – The annotated value must be greater than gt.
ge (int or float, optional) – The annotated value must be greater than or equal to ge.
lt (int or float, optional) – The annotated value must be less than lt.
le (int or float, optional) – The annotated value must be less than or equal to le.
multiple_of (int or float, optional) – The annotated value must be a multiple of multiple_of.
pattern (str, optional) – A regex pattern that the annotated value must match against. Note that the pattern is treated as unanchored, meaning the re.search method is used when matching.
min_length (int, optional) – The annotated value must have a length greater than or equal to min_length.
max_length (int, optional) – The annotated value must have a length less than or equal to max_length.
tz (bool, optional) – Configures the timezone-requirements for annotated datetime/time types. Set to True to require timezone-aware values, or False to require timezone-naive values. The default is None, which accepts either timezone-aware or timezone-naive values.
title (str, optional) – The title to use for the annotated value when generating a json-schema.
description (str, optional) – The description to use for the annotated value when generating a json-schema.
examples (list, optional) – A list of examples to use for the annotated value when generating a json-schema.
extra_json_schema (dict, optional) – A dict of extra fields to set for the annotated value when generating a json-schema. This dict is recursively merged with the generated schema, with extra_json_schema overriding any conflicting autogenerated fields.
extra (dict, optional) – Any additional user-defined metadata.

Examples

Here we use Meta to add constraints on two different types. The first defines a new type alias NonNegativeInt, which is an integer that must be >= 0. This type alias can be reused in multiple locations. The second uses Meta inline in a struct definition to restrict the name string field to a maximum length of 32 characters.

>>> import msgspec
>>> from typing import Annotated
>>> from msgspec import Struct, Meta
>>> NonNegativeInt = Annotated[int, Meta(ge=0)]
>>> class User(Struct):
...     name: Annotated[str, Meta(max_length=32)]
...     age: NonNegativeInt
...
>>> msgspec.json.decode(b'{"name": "alice", "age": 25}', type=User)
User(name='alice', age=25)

Raw¶

class msgspec.Raw¶

A buffer containing an encoded message.

Raw objects have two common uses:

During decoding. Fields annotated with the Raw type won’t be decoded immediately, but will instead return a Raw object with a view into the original message where that field is encoded. This is useful for decoding fields whose type may only be inferred after decoding other fields.
During encoding. Raw objects wrap pre-encoded messages. These can be added as components of larger messages without having to pay the cost of decoding and re-encoding them.

Parameters:: msg (bytes, bytearray, memoryview, or str, optional) – A buffer containing an encoded message. One of bytes, bytearray, memoryview, str, or any object that implements the buffer protocol. If not present, defaults to an empty buffer.

copy()¶

Copy a Raw object.

If the raw message is backed by a memoryview into a larger buffer (as happens during decoding), the message is copied and the reference to the larger buffer released. This may be useful to reduce memory usage if a Raw object created during decoding will be kept in memory for a while rather than immediately decoded and dropped.

Unset¶

msgspec.UNSET¶

A singleton indicating a field value is unset.

This may be useful for working with message schemas where an unset field in an object needs to be treated differently than one containing an explicit None value. In this case, you may use UNSET as the default value, rather than None when defining object schemas. This feature is supported for any msgspec.Struct, dataclasses or attrs types.

Examples

>>> from msgspec import Struct, UnsetType, UNSET, json
>>> class Example(Struct):
...     x: int
...     y: int | None | UnsetType = UNSET

During encoding, any field containing UNSET is omitted from the message.

>>> json.encode(Example(1))
b'{"x":1}'
>>> json.encode(Example(1, 2))
b'{"x":1,"y":2}'

During decoding, if a field isn’t explicitly set in the message, the default value of UNSET will be set instead. This lets downstream consumers determine whether a field was left unset, or explicitly set to None

>>> json.decode(b'{"x": 1}', type=Example)  # unset
Example(x=1, y=UNSET)
>>> json.decode(b'{"x": 1, "y": null}', type=Example)  # explicit null
Example(x=1, y=None)
>>> json.decode(b'{"x": 1, "y": 2}', type=Example)  # explicit value
Example(x=1, y=2)

class msgspec.UnsetType¶: The type of UNSET.

See also

UNSET

JSON¶

class msgspec.json.Encoder(*, enc_hook=None, decimal_format='string', uuid_format='canonical', order=None)¶

A JSON encoder.

Parameters:

enc_hook (callable, optional) – A callable to call for objects that aren’t supported msgspec types. Takes the unsupported object and should return a supported object, or raise a NotImplementedError if unsupported.
decimal_format ({'string', 'number'}, optional) – The format to use for encoding decimal.Decimal objects. If ‘string’ they’re encoded as strings, if ‘number’, they’re encoded as floats. Defaults to ‘string’, which is the recommended value since ‘number’ may result in precision loss when decoding for some JSON library implementations.
uuid_format ({'canonical', 'hex'}, optional) – The format to use for encoding uuid.UUID objects. The ‘canonical’ and ‘hex’ formats encode them as strings with and without hyphens respectively. Defaults to ‘canonical’.
order ({None, 'deterministic', 'sorted'}, optional) –
The ordering to use when encoding unordered compound types.
- None: All objects are encoded in the most efficient manner matching their in-memory representations. The default.
- 'deterministic': Unordered collections (sets, dicts) are sorted to ensure a consistent output between runs. Useful when comparison/hashing of the encoded binary output is necessary.
- 'sorted': Like 'deterministic', but all object-like types (structs, dataclasses, …) are also sorted by field name before encoding. This is slower than 'deterministic', but may produce more human-readable output.

encode(obj)¶

Serialize an object to bytes.

Parameters:: obj (Any) – The object to serialize.
Returns:: data (bytes) – The serialized object.

encode_into(obj, buffer, offset=0, /)¶

Serialize an object into an existing bytearray buffer.

Upon success, the buffer will be truncated to the end of the serialized message. Note that the underlying memory buffer won’t be truncated, allowing for efficiently appending additional bytes later.

Parameters:

obj (Any) – The object to serialize.
buffer (bytearray) – The buffer to serialize into.
offset (int, optional) – The offset into the buffer to start writing at. Defaults to 0. Set to -1 to start writing at the end of the buffer.

Returns:

None

encode_lines(items)¶

Encode an iterable of items as newline-delimited JSON, one item per line.

Parameters:: items (iterable) – An iterable of items to encode.
Returns:: data (bytes) – The items encoded as newline-delimited JSON, one item per line.

Examples

>>> import msgspec
>>> items = [{"name": "alice"}, {"name": "ben"}]
>>> encoder = msgspec.json.Encoder()
>>> encoder.encode_lines(items)
b'{"name":"alice"}\n{"name":"ben"}\n'

class msgspec.json.Decoder(type='Any', *, strict=True, dec_hook=None, float_hook=None)¶

A JSON decoder.

Parameters:

type (type, optional) – A Python type (in type annotation form) to decode the object as. If provided, the message will be type checked and decoded as the specified type. Defaults to Any, in which case the message will be decoded using the default JSON types.
strict (bool, optional) – Whether type coercion rules should be strict. Setting to False enables a wider set of coercion rules from string to non-string types for all values. Default is True.
dec_hook (callable, optional) – An optional callback for handling decoding custom types. Should have the signature dec_hook(type: Type, obj: Any) -> Any, where type is the expected message type, and obj is the decoded representation composed of only basic JSON types. This hook should transform obj into type type, or raise a NotImplementedError if unsupported.
float_hook (callable, optional) – An optional callback for handling decoding untyped float literals. Should have the signature float_hook(val: str) -> Any, where val is the raw string value of the JSON float. This hook is called to decode any “untyped” float value (e.g. typing.Any typed). The default is equivalent to float_hook=float, where all untyped JSON floats are decoded as python floats. Specifying float_hook=decimal.Decimal will decode all untyped JSON floats as decimals instead.

decode(buf)¶

Deserialize an object from JSON.

Parameters:: buf (bytes-like or str) – The message to decode.
Returns:: obj (Any) – The deserialized object.

decode_lines(buf)¶

Decode a list of items from newline-delimited JSON.

Parameters:: buf (bytes-like or str) – The message to decode.
Returns:: items (list) – A list of decoded objects.

Examples

>>> import msgspec
>>> msg = """
... {"x": 1, "y": 2}
... {"x": 3, "y": 4}
... """
>>> dec = msgspec.json.Decoder()
>>> dec.decode_lines(msg)
[{'x': 1, 'y': 2}, {'x': 3, 'y': 4}]

msgspec.json.encode(obj, *, enc_hook=None, order=None)¶

Serialize an object as JSON.

Parameters:

obj (Any) – The object to serialize.
enc_hook (callable, optional) – A callable to call for objects that aren’t supported msgspec types. Takes the unsupported object and should return a supported object, or raise a NotImplementedError if unsupported.
order ({None, 'deterministic', 'sorted'}, optional) –
The ordering to use when encoding unordered compound types.
- None: All objects are encoded in the most efficient manner matching their in-memory representations. The default.
- 'deterministic': Unordered collections (sets, dicts) are sorted to ensure a consistent output between runs. Useful when comparison/hashing of the encoded binary output is necessary.
- 'sorted': Like 'deterministic', but all object-like types (structs, dataclasses, …) are also sorted by field name before encoding. This is slower than 'deterministic', but may produce more human-readable output.

Returns:

data (bytes) – The serialized object.

See also

Encoder.encode

msgspec.json.decode(buf, *, type='Any', strict=True, dec_hook=None)¶

Deserialize an object from JSON.

Parameters:

buf (bytes-like or str) – The message to decode.
type (type, optional) – A Python type (in type annotation form) to decode the object as. If provided, the message will be type checked and decoded as the specified type. Defaults to Any, in which case the message will be decoded using the default JSON types.
strict (bool, optional) – Whether type coercion rules should be strict. Setting to False enables a wider set of coercion rules from string to non-string types for all values. Default is True.
dec_hook (callable, optional) – An optional callback for handling decoding custom types. Should have the signature dec_hook(type: Type, obj: Any) -> Any, where type is the expected message type, and obj is the decoded representation composed of only basic JSON types. This hook should transform obj into type type, or raise a TypeError if unsupported.

Returns:

obj (Any) – The deserialized object.

See also

Decoder.decode

msgspec.json.format(buf, *, indent=2)¶

Format an existing JSON message, usually to be more human readable.

Parameters:

buf (bytes-like or str) – The JSON message to format.
indent (int, optional) – How many spaces to indent for a single indentation level. Defaults to 2. Set to 0 to format the message as a single line, with spaces added between items for readability. Set to a negative number to strip all unnecessary whitespace, minimizing the message size.

Returns:

output (bytes or str) – The formatted JSON message. Returns a str if input is a str, bytes otherwise.

MessagePack¶

class msgspec.msgpack.Encoder(*, enc_hook=None, decimal_format='string', uuid_format='canonical', order=None)¶

A MessagePack encoder.

Parameters:

enc_hook (callable, optional) – A callable to call for objects that aren’t supported msgspec types. Takes the unsupported object and should return a supported object, or raise a NotImplementedError if unsupported.
decimal_format ({'string', 'number'}, optional) – The format to use for encoding decimal.Decimal objects. If ‘string’ they’re encoded as strings, if ‘number’, they’re encoded as floats. Defaults to ‘string’, which is the recommended value since ‘number’ may result in precision loss when decoding.
uuid_format ({'canonical', 'hex', 'bytes'}, optional) – The format to use for encoding uuid.UUID objects. The ‘canonical’ and ‘hex’ formats encode them as strings with and without hyphens respectively. The ‘bytes’ format encodes them as big-endian binary representations of the corresponding 128-bit integers. Defaults to ‘canonical’.
order ({None, 'deterministic', 'sorted'}, optional) –
The ordering to use when encoding unordered compound types.
- None: All objects are encoded in the most efficient manner matching their in-memory representations. The default.
- 'deterministic': Unordered collections (sets, dicts) are sorted to ensure a consistent output between runs. Useful when comparison/hashing of the encoded binary output is necessary.
- 'sorted': Like 'deterministic', but all object-like types (structs, dataclasses, …) are also sorted by field name before encoding. This is slower than 'deterministic', but may produce more human-readable output.

encode(obj)¶

Serialize an object to bytes.

Parameters:: obj (Any) – The object to serialize.
Returns:: data (bytes) – The serialized object.

encode_into(obj, buffer, offset=0, /)¶

Serialize an object into an existing bytearray buffer.

Parameters:

obj (Any) – The object to serialize.
buffer (bytearray) – The buffer to serialize into.
offset (int, optional) – The offset into the buffer to start writing at. Defaults to 0. Set to -1 to start writing at the end of the buffer.

Returns:

None

class msgspec.msgpack.Decoder(type='Any', *, strict=True, dec_hook=None, ext_hook=None)¶

A MessagePack decoder.

Parameters:

type (type, optional) – A Python type (in type annotation form) to decode the object as. If provided, the message will be type checked and decoded as the specified type. Defaults to Any, in which case the message will be decoded using the default MessagePack types.
strict (bool, optional) – Whether type coercion rules should be strict. Setting to False enables a wider set of coercion rules from string to non-string types for all values. Default is True.
dec_hook (callable, optional) – An optional callback for handling decoding custom types. Should have the signature dec_hook(type: Type, obj: Any) -> Any, where type is the expected message type, and obj is the decoded representation composed of only basic MessagePack types. This hook should transform obj into type type, or raise a NotImplementedError if unsupported.
ext_hook (callable, optional) – An optional callback for decoding MessagePack extensions. Should have the signature ext_hook(code: int, data: memoryview) -> Any. If provided, this will be called to deserialize all extension types found in the message. Note that data is a memoryview into the larger message buffer - any references created to the underlying buffer without copying the data out will cause the full message buffer to persist in memory. If not provided, extension types will decode as msgspec.Ext objects.

decode(buf)¶

Deserialize an object from MessagePack.

Parameters:: buf (bytes-like) – The message to decode.
Returns:: obj (Any) – The deserialized object.

class msgspec.msgpack.Ext(code, data)¶

A record representing a MessagePack Extension Type.

Parameters:

code (int) – The integer type code for this extension. Must be between -128 and 127.
data (bytes, bytearray, or memoryview) – The byte buffer for this extension. One of bytes, bytearray, memoryview, or any object that implements the buffer protocol.

code¶: The extension type code

data¶: The extension data payload

msgspec.msgpack.encode(obj, *, enc_hook=None, order=None)¶

Serialize an object as MessagePack.

Parameters:

obj (Any) – The object to serialize.
enc_hook (callable, optional) – A callable to call for objects that aren’t supported msgspec types. Takes the unsupported object and should return a supported object, or raise a NotImplementedError if unsupported.
order ({None, 'deterministic', 'sorted'}, optional) –
The ordering to use when encoding unordered compound types.
- None: All objects are encoded in the most efficient manner matching their in-memory representations. The default.
- 'deterministic': Unordered collections (sets, dicts) are sorted to ensure a consistent output between runs. Useful when comparison/hashing of the encoded binary output is necessary.
- 'sorted': Like 'deterministic', but all object-like types (structs, dataclasses, …) are also sorted by field name before encoding. This is slower than 'deterministic', but may produce more human-readable output.

Returns:

data (bytes) – The serialized object.

See also

Encoder.encode

msgspec.msgpack.decode(buf, *, type='Any', strict=True, dec_hook=None, ext_hook=None)¶

Deserialize an object from MessagePack.

Parameters:

buf (bytes-like) – The message to decode.
type (type, optional) – A Python type (in type annotation form) to decode the object as. If provided, the message will be type checked and decoded as the specified type. Defaults to Any, in which case the message will be decoded using the default MessagePack types.
strict (bool, optional) – Whether type coercion rules should be strict. Setting to False enables a wider set of coercion rules from string to non-string types for all values. Default is True.
dec_hook (callable, optional) – An optional callback for handling decoding custom types. Should have the signature dec_hook(type: Type, obj: Any) -> Any, where type is the expected message type, and obj is the decoded representation composed of only basic MessagePack types. This hook should transform obj into type type, or raise a NotImplementedError if unsupported.
ext_hook (callable, optional) – An optional callback for decoding MessagePack extensions. Should have the signature ext_hook(code: int, data: memoryview) -> Any. If provided, this will be called to deserialize all extension types found in the message. Note that data is a memoryview into the larger message buffer - any references created to the underlying buffer without copying the data out will cause the full message buffer to persist in memory. If not provided, extension types will decode as msgspec.Ext objects.

Returns:

obj (Any) – The deserialized object.

See also

Decoder.decode

YAML¶

msgspec.yaml.encode(obj, *, enc_hook=None, order=None)¶

Serialize an object as YAML.

Parameters:

obj (Any) – The object to serialize.
enc_hook (callable, optional) – A callable to call for objects that aren’t supported msgspec types. Takes the unsupported object and should return a supported object, or raise a NotImplementedError if unsupported.
order ({None, 'deterministic', 'sorted'}, optional) –
The ordering to use when encoding unordered compound types.
- None: All objects are encoded in the most efficient manner matching their in-memory representations. The default.
- 'deterministic': Unordered collections (sets, dicts) are sorted to ensure a consistent output between runs. Useful when comparison/hashing of the encoded binary output is necessary.
- 'sorted': Like 'deterministic', but all object-like types (structs, dataclasses, …) are also sorted by field name before encoding. This is slower than 'deterministic', but may produce more human-readable output.

Returns:

data (bytes) – The serialized object.

Notes

This function requires that the third-party PyYAML library is installed.

See also

decode

msgspec.yaml.decode(buf, *, type=typing.Any, strict=True, dec_hook=None)¶

Deserialize an object from YAML.

Parameters:

buf (bytes-like or str) – The message to decode.
type (type, optional) – A Python type (in type annotation form) to decode the object as. If provided, the message will be type checked and decoded as the specified type. Defaults to Any, in which case the message will be decoded using the default YAML types.
strict (bool, optional) – Whether type coercion rules should be strict. Setting to False enables a wider set of coercion rules from string to non-string types for all values. Default is True.
dec_hook (callable, optional) – An optional callback for handling decoding custom types. Should have the signature dec_hook(type: Type, obj: Any) -> Any, where type is the expected message type, and obj is the decoded representation composed of only basic YAML types. This hook should transform obj into type type, or raise a NotImplementedError if unsupported.

Returns:

obj (Any) – The deserialized object.

Notes

This function requires that the third-party PyYAML library is installed.

See also

encode

TOML¶

msgspec.toml.encode(obj, *, enc_hook=None, order=None)¶

Serialize an object as TOML.

Parameters:

obj (Any) – The object to serialize.
enc_hook (callable, optional) – A callable to call for objects that aren’t supported msgspec types. Takes the unsupported object and should return a supported object, or raise a NotImplementedError if unsupported.
order ({None, 'deterministic', 'sorted'}, optional) –
The ordering to use when encoding unordered compound types.
- None: All objects are encoded in the most efficient manner matching their in-memory representations. The default.
- 'deterministic': Unordered collections (sets, dicts) are sorted to ensure a consistent output between runs. Useful when comparison/hashing of the encoded binary output is necessary.
- 'sorted': Like 'deterministic', but all object-like types (structs, dataclasses, …) are also sorted by field name before encoding. This is slower than 'deterministic', but may produce more human-readable output.

Returns:

data (bytes) – The serialized object.

See also

decode

msgspec.toml.decode(buf, *, type=typing.Any, strict=True, dec_hook=None)¶

Deserialize an object from TOML.

Parameters:

buf (bytes-like or str) – The message to decode.
type (type, optional) – A Python type (in type annotation form) to decode the object as. If provided, the message will be type checked and decoded as the specified type. Defaults to Any, in which case the message will be decoded using the default TOML types.
strict (bool, optional) – Whether type coercion rules should be strict. Setting to False enables a wider set of coercion rules from string to non-string types for all values. Default is True.
dec_hook (callable, optional) – An optional callback for handling decoding custom types. Should have the signature dec_hook(type: Type, obj: Any) -> Any, where type is the expected message type, and obj is the decoded representation composed of only basic TOML types. This hook should transform obj into type type, or raise a NotImplementedError if unsupported.

Returns:

obj (Any) – The deserialized object.

See also

encode

JSON Schema¶

msgspec.json.schema(type, *, schema_hook=None)¶

Generate a JSON Schema for a given type.

Any schemas for (potentially) shared components are extracted and stored in a top-level "$defs" field.

If you want to generate schemas for multiple types, or to have more control over the generated schema you may want to use schema_components instead.

Parameters:

type (type) – The type to generate the schema for.
schema_hook (callable, optional) – An optional callback to use for generating JSON schemas of custom types. Will be called with the custom type, and should return a dict representation of the JSON schema for that type.

Returns:

schema (dict) – The generated JSON Schema.

See also

schema_components

msgspec.json.schema_components(types, *, schema_hook=None, ref_template='#/$defs/{name}')¶

Generate JSON Schemas for one or more types.

Any schemas for (potentially) shared components are extracted and returned in a separate components dict.

Parameters:

types (Iterable[type]) – An iterable of one or more types to generate schemas for.
schema_hook (callable, optional) – An optional callback to use for generating JSON schemas of custom types. Will be called with the custom type, and should return a dict representation of the JSON schema for that type.
ref_template (str, optional) – A template to use when generating "$ref" fields. This template is formatted with the type name as template.format(name=name). This can be useful if you intend to store the components mapping somewhere other than a top-level "$defs" field. For example, you might use ref_template="#/components/{name}" if generating an OpenAPI schema.

Returns:

schemas (tuple[dict]) – A tuple of JSON Schemas, one for each type in types.
components (dict) – A mapping of name to schema for any shared components used by schemas.

See also

schema

Converters¶

msgspec.convert(obj, type, *, strict=True, from_attributes=False, dec_hook=None, str_keys=False, builtin_types=None)¶

Convert the input object to the specified type, or error accordingly.

Parameters:

obj (Any) – The object to convert.
type (Type) – A Python type (in type annotation form) to convert the object to.
strict (bool, optional) – Whether type coercion rules should be strict. Setting to False enables a wider set of coercion rules from string to non-string types for all values. Setting strict=False implies str_keys=True, builtin_types=None. Default is True.
from_attributes (bool, optional) – If True, input objects may be coerced to Struct/dataclass/attrs types by extracting attributes from the input matching fields in the output type. One use case is converting database query results (ORM or otherwise) to msgspec structured types. Default is False.
dec_hook (callable, optional) – An optional callback for handling decoding custom types. Should have the signature dec_hook(type: Type, obj: Any) -> Any, where type is the expected message type, and obj is the decoded representation composed of only basic MessagePack types. This hook should transform obj into type type, or raise a NotImplementedError if unsupported.
builtin_types (Iterable[type], optional) – Useful for wrapping other serialization protocols. An iterable of types to treat as additional builtin types. Passing a type here indicates that the wrapped protocol natively supports that type, disabling any coercion to that type provided by convert. For example, passing builtin_types=(datetime,) disables the default str to datetime conversion; the wrapped protocol must provide a datetime object directly. Currently supports bytes, bytearray, datetime.datetime, datetime.time, datetime.date, datetime.timedelta, uuid.UUID, and decimal.Decimal.
str_keys (bool, optional) – Useful for wrapping other serialization protocols. Indicates whether the wrapped protocol only supports string keys. Setting to True enables a wider set of coercion rules from string to non-string types for dict keys. Default is False.

Returns:

Any – The converted object of the specified type.

Examples

>>> import msgspec
>>> class Example(msgspec.Struct):
...     x: set[int]
...     y: bytes
>>> msg = {'x': [1, 2, 3], 'y': 'AQI='}

Construct the message from a simpler set of builtin types.

>>> msgspec.convert(msg, Example)
Example({1, 2, 3}, b'\x01\x02')

See also

to_builtins

msgspec.to_builtins(obj, *, str_keys=False, builtin_types=None, enc_hook=None, order=None)¶

Convert a complex object to one composed only of simpler builtin types commonly supported by Python serialization libraries.

This is mainly useful for adding msgspec support for other protocols.

Parameters:

obj (Any) – The object to convert.
builtin_types (Iterable[type], optional) – An iterable of types to treat as additional builtin types. These types will be passed through to_builtins unchanged. Currently supports bytes, bytearray, memoryview, datetime.datetime, datetime.time, datetime.date, datetime.timedelta, uuid.UUID, decimal.Decimal, and custom types.
str_keys (bool, optional) – Whether to convert all object keys to strings. Default is False.
enc_hook (callable, optional) – A callable to call for objects that aren’t supported msgspec types. Takes the unsupported object and should return a supported object, or raise a NotImplementedError if unsupported.
order ({None, 'deterministic', 'sorted'}, optional) –
The ordering to use when converting unordered compound types.
- None: All objects are converted in the most efficient manner matching their in-memory representations. The default.
- 'deterministic': Unordered collections (sets, dicts) are sorted to ensure a consistent output between runs. Useful when comparison/hashing of the converted output is necessary.
- 'sorted': Like 'deterministic', but all object-like types (structs, dataclasses, …) are also sorted by field name before encoding. This is slower than 'deterministic', but may produce more human-readable output.

Returns:

Any – The converted object.

Examples

>>> import msgspec
>>> class Example(msgspec.Struct):
...     x: set[int]
...     y: bytes
>>> msg = Example({1, 2, 3}, b'\x01\x02')

Convert the message to a simpler set of builtin types. Note that by default all bytes-like objects are base64-encoded and converted to strings.

>>> msgspec.to_builtins(msg)
{'x': [1, 2, 3], 'y': 'AQI='}

If the downstream code supports binary objects natively, you can disable conversion by passing in the types to builtin_types.

>>> msgspec.to_builtins(msg, builtin_types=(bytes, bytearray, memoryview))
{'x': [1, 2, 3], 'y': b'\x01\x02'}

Inspect¶

msgspec.inspect.type_info(type)¶

Get information about a msgspec-compatible type.

Note that if you need to inspect multiple types it’s more efficient to call multi_type_info once with a sequence of types than calling type_info multiple times.

Parameters:: type (type) – The type to get info about.
Returns:: Type

Examples

>>> msgspec.inspect.type_info(bool)
BoolType()

>>> msgspec.inspect.type_info(int)
IntType(gt=None, ge=None, lt=None, le=None, multiple_of=None)

>>> msgspec.inspect.type_info(list[int])  
ListType(item_type=IntType(gt=None, ge=None, lt=None, le=None, multiple_of=None),
         min_length=None, max_length=None)

msgspec.inspect.multi_type_info(types)¶

Get information about multiple msgspec-compatible types.

Parameters:: types (an iterable of types) – The types to get info about.
Returns:: tuple[Type, …]

Examples

>>> msgspec.inspect.multi_type_info([int, float, list[str]])  
(IntType(gt=None, ge=None, lt=None, le=None, multiple_of=None),
 FloatType(gt=None, ge=None, lt=None, le=None, multiple_of=None),
 ListType(item_type=StrType(min_length=None, max_length=None, pattern=None),
          min_length=None, max_length=None))

class msgspec.inspect.Type¶: The base Type.

class msgspec.inspect.Metadata(type, extra_json_schema=None, extra=None)¶

A type wrapping a subtype with additional metadata.

Parameters:

type (Type) – The subtype.
extra_json_schema (dict, optional) – A dict of extra fields to set for the subtype when generating a json-schema.
extra (dict, optional) – A dict of extra user-defined metadata attached to the subtype.

class msgspec.inspect.AnyType¶: A type corresponding to typing.Any.

class msgspec.inspect.NoneType¶: A type corresponding to None.

class msgspec.inspect.BoolType¶: A type corresponding to bool.

class msgspec.inspect.IntType(gt=None, ge=None, lt=None, le=None, multiple_of=None)¶

A type corresponding to int.

Parameters:

gt (int, optional) – If set, an instance of this type must be greater than gt.
ge (int, optional) – If set, an instance of this type must be greater than or equal to ge.
lt (int, optional) – If set, an instance of this type must be less than to lt.
le (int, optional) – If set, an instance of this type must be less than or equal to le.
multiple_of (int, optional) – If set, an instance of this type must be a multiple of multiple_of.

class msgspec.inspect.FloatType(gt=None, ge=None, lt=None, le=None, multiple_of=None)¶

A type corresponding to float.

Parameters:

gt (float, optional) – If set, an instance of this type must be greater than gt.
ge (float, optional) – If set, an instance of this type must be greater than or equal to ge.
lt (float, optional) – If set, an instance of this type must be less than to lt.
le (float, optional) – If set, an instance of this type must be less than or equal to le.
multiple_of (float, optional) – If set, an instance of this type must be a multiple of multiple_of.

class msgspec.inspect.StrType(min_length=None, max_length=None, pattern=None)¶

A type corresponding to str.

Parameters:

min_length (int, optional) – If set, an instance of this type must have length greater than or equal to min_length.
max_length (int, optional) – If set, an instance of this type must have length less than or equal to max_length.
pattern (str, optional) – If set, an instance of this type must match against this regex pattern. Note that the pattern is treated as unanchored.

class msgspec.inspect.BytesType(min_length=None, max_length=None)¶

A type corresponding to bytes.

Parameters:

min_length (int, optional) – If set, an instance of this type must have length greater than or equal to min_length.
max_length (int, optional) – If set, an instance of this type must have length less than or equal to max_length.

class msgspec.inspect.ByteArrayType(min_length=None, max_length=None)¶

A type corresponding to bytearray.

Parameters:

min_length (int, optional) – If set, an instance of this type must have length greater than or equal to min_length.
max_length (int, optional) – If set, an instance of this type must have length less than or equal to max_length.

class msgspec.inspect.MemoryViewType(min_length=None, max_length=None)¶

A type corresponding to memoryview.

Parameters:

min_length (int, optional) – If set, an instance of this type must have length greater than or equal to min_length.
max_length (int, optional) – If set, an instance of this type must have length less than or equal to max_length.

class msgspec.inspect.DateTimeType(tz=None)¶

A type corresponding to datetime.datetime.

Parameters:: tz (bool) – The timezone-requirements for an instance of this type. True indicates a timezone-aware value is required, False indicates a timezone-aware value is required. The default is None, which accepts either timezone-aware or timezone-naive values.

class msgspec.inspect.TimeType(tz=None)¶

A type corresponding to datetime.time.

Parameters:: tz (bool) – The timezone-requirements for an instance of this type. True indicates a timezone-aware value is required, False indicates a timezone-aware value is required. The default is None, which accepts either timezone-aware or timezone-naive values.

class msgspec.inspect.DateType¶: A type corresponding to datetime.date.

class msgspec.inspect.TimeDeltaType¶: A type corresponding to datetime.timedelta.

class msgspec.inspect.UUIDType¶: A type corresponding to uuid.UUID.

class msgspec.inspect.DecimalType¶: A type corresponding to decimal.Decimal.

class msgspec.inspect.ExtType¶: A type corresponding to msgspec.msgpack.Ext.

class msgspec.inspect.RawType¶: A type corresponding to msgspec.Raw.

class msgspec.inspect.EnumType(cls)¶

A type corresponding to an enum.Enum type.

Parameters:: cls (type) – The corresponding enum.Enum type.

class msgspec.inspect.LiteralType(values)¶

A type corresponding to a typing.Literal type.

Parameters:: values (tuple) – A tuple of possible values for this literal instance. Only str or int literals are supported.

class msgspec.inspect.CustomType(cls)¶

A custom type.

Parameters:: cls (type) – The corresponding custom type.

class msgspec.inspect.UnionType(types)¶

A union type.

Parameters:: types (Tuple[Type, ...]) – A tuple of possible types for this union.

property includes_none¶: A helper for checking whether None is included in this union.

class msgspec.inspect.CollectionType(item_type, min_length=None, max_length=None)¶

A collection type.

This is the base type shared by collection types like ListType, SetType, etc.

Parameters:

item_type (Type) – The item type.
min_length (int, optional) – If set, an instance of this type must have length greater than or equal to min_length.
max_length (int, optional) – If set, an instance of this type must have length less than or equal to max_length.

class msgspec.inspect.ListType(item_type, min_length=None, max_length=None)¶

A type corresponding to a list.

Parameters:

item_type (Type) – The item type.
min_length (int, optional) – If set, an instance of this type must have length greater than or equal to min_length.
max_length (int, optional) – If set, an instance of this type must have length less than or equal to max_length.

class msgspec.inspect.SetType(item_type, min_length=None, max_length=None)¶

A type corresponding to a set.

Parameters:

item_type (Type) – The item type.
min_length (int, optional) – If set, an instance of this type must have length greater than or equal to min_length.
max_length (int, optional) – If set, an instance of this type must have length less than or equal to max_length.

class msgspec.inspect.FrozenSetType(item_type, min_length=None, max_length=None)¶

A type corresponding to a frozenset.

Parameters:

item_type (Type) – The item type.
min_length (int, optional) – If set, an instance of this type must have length greater than or equal to min_length.
max_length (int, optional) – If set, an instance of this type must have length less than or equal to max_length.

class msgspec.inspect.VarTupleType(item_type, min_length=None, max_length=None)¶

A type corresponding to a variadic tuple.

Parameters:

item_type (Type) – The item type.
min_length (int, optional) – If set, an instance of this type must have length greater than or equal to min_length.
max_length (int, optional) – If set, an instance of this type must have length less than or equal to max_length.

class msgspec.inspect.TupleType(item_types)¶

A type corresponding to tuple.

Parameters:: item_types (Tuple[Type, ...]) – A tuple of types for each element in the tuple.

class msgspec.inspect.DictType(key_type, value_type, min_length=None, max_length=None)¶

A type corresponding to dict.

Parameters:

key_type (Type) – The key type.
value_type (Type) – The value type.
min_length (int, optional) – If set, an instance of this type must have length greater than or equal to min_length.
max_length (int, optional) – If set, an instance of this type must have length less than or equal to max_length.

class msgspec.inspect.Field(name, encode_name, type, required=True, default=<factory>, default_factory=<factory>)¶

A record describing a field in an object-like type.

Parameters:

name (str) – The field name as seen by Python code (e.g. field_one).
encode_name (str) – The name used when encoding/decoding the field. This may differ if the field is renamed (e.g. fieldOne).
type (Type) – The field type.
required (bool, optional) – Whether the field is required. Note that if required is False doesn’t necessarily mean that default or default_factory will be set - optional fields may exist with no default value.
default (Any, optional) – A default value for the field. Will be NODEFAULT if no default value is set.
default_factory (Any, optional) – A callable that creates a default value for the field. Will be NODEFAULT if no default_factory is set.

class msgspec.inspect.TypedDictType(cls, fields)¶

A type corresponding to a typing.TypedDict type.

Parameters:

cls (type) – The corresponding TypedDict type.
fields (Tuple[Field, ...]) – A tuple of fields in the TypedDict.

class msgspec.inspect.NamedTupleType(cls, fields)¶

A type corresponding to a typing.NamedTuple type.

Parameters:

cls (type) – The corresponding NamedTuple type.
fields (Tuple[Field, ...]) – A tuple of fields in the NamedTuple.

class msgspec.inspect.DataclassType(cls, fields)¶

A type corresponding to a dataclasses or attrs type.

Parameters:

cls (type) – The corresponding dataclass type.
fields (Tuple[Field, ...]) – A tuple of fields in the dataclass.

class msgspec.inspect.StructType(cls, fields, tag_field=None, tag=None, array_like=False, forbid_unknown_fields=False)¶

A type corresponding to a msgspec.Struct type.

Parameters:

cls (type) – The corresponding Struct type.
fields (Tuple[Field, ...]) – A tuple of fields in the Struct.
tag_field (str or None, optional) – If set, the field name used for the tag in a tagged union.
tag (str, int, or None, optional) – If set, the value used for the tag in a tagged union.
array_like (bool, optional) – Whether the struct is encoded as an array rather than an object.
forbid_unknown_fields (bool, optional) – If False (the default) unknown fields are ignored when decoding. If True any unknown fields will result in an error.