Skip to content
Back to top
View this page

# 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}

class msgspec.StructMeta(name, bases, namespace, /, *, **struct_config)

  The metaclass for creating `Struct` types. See its documentation for the available configuration options when subclassing.

  StructMeta can be subclassed, and may be combined with `abc.ABCMeta` to define abstract base Structs. Other metaclass combinations are not supported; they may work by accident but are not considered part of the public API.

  Examples

  Here we define a metaclass that modifies the default configuration and use it to create a new `Struct` base class.

      >>> from msgspec import Struct, StructMeta
      >>> class KwOnlyStructMeta(StructMeta):
      ...     def __new__(mcls, name, bases, namespace, **struct_config):
      ...         struct_config.setdefault("kw_only", True)
      ...         return super().__new__(mcls, name, bases, namespace, **struct_config)
      ...
      >>> class KwOnlyStruct(Struct, metaclass=KwOnlyStructMeta): ...

  Any subclass of `KwOnlyStruct` will have `kw_only` set to `True` by default.

      >>> class Example(KwOnlyStruct):
      ...     a: str =
      ...     b: int
      ...
      >>> Example(b=123)
      Example(a='', b=123)

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()

  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}

  See also

  `msgspec.structs.astuple`, `msgspec.to_builtins`

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)

  See also

  `msgspec.structs.asdict`, `msgspec.to_builtins`

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'`: Dict keys and set elements are sorted so that values which compare equal produce identical encoded output, regardless of insertion or iteration order. 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'`: Dict keys and set elements are sorted so that values which compare equal produce identical encoded output, regardless of insertion or iteration order. 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'`: Dict keys and set elements are sorted so that values which compare equal produce identical encoded output, regardless of insertion or iteration order. 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

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'`: Dict keys and set elements are sorted so that values which compare equal produce identical encoded output, regardless of insertion or iteration order. 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'`: Dict keys and set elements are sorted so that values which compare equal produce identical encoded output, regardless of insertion or iteration order. 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'`: Dict keys and set elements are sorted so that values which compare equal produce identical encoded output, regardless of insertion or iteration order. 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, ref_template='#/$defs/{name}')

  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.

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

    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'`: Dict keys and set elements are sorted so that values which compare equal produce identical converted output, regardless of insertion or iteration order. 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'}

  See also

  `msgspec.convert`, `msgspec.structs.asdict`, `msgspec.structs.astuple`

## Inspect

msgspec.inspect.is_struct(obj)

  Check whether `obj` is a `msgspec.Struct`-like instance.

  Parameters:

    obj – Object to check.

  Returns:

    bool – `True` if `obj` is an instance of a class whose metaclass is `msgspec.StructMeta` (or a subclass of it), and `False` otherwise. Static type checkers treat a successful `is_struct(obj)` check as narrowing `obj` to `msgspec.Struct` within the true branch, even if the runtime class does not literally inherit `msgspec.Struct`.

msgspec.inspect.is_struct_type(tp)

  Check whether `tp` is a `msgspec.Struct`-like class.

  Parameters:

    tp – Object to check, typically a class object.

  Returns:

    bool – `True` if `tp` is a class whose metaclass is `msgspec.StructMeta` (or a subclass of it), and `False` otherwise. Static type checkers treat a successful `is_struct_type(tp)` check as narrowing `tp` to `type[msgspec.Struct]` within the true branch.

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

## Exceptions

exception msgspec.MsgspecError

  Bases: `Exception`

  Base class for all Msgspec exceptions

exception msgspec.EncodeError

  Bases: `MsgspecError`

  An error occurred while encoding an object

exception msgspec.DecodeError

  Bases: `MsgspecError`, `ValueError`

  An error occurred while decoding an object

exception msgspec.ValidationError

  Bases: `DecodeError`

  The message didn’t match the expected schema