github.com/Fatal1ty/mashumaro @v3.22

Fast and well tested serialization library

In Python, you often need to dump and load objects based on the schema you have. It can be a dataclass model, a list of third-party generic classes or whatever. Mashumaro not only lets you save and load things in different ways, but it also does it super quick.

Key features * 🚀 One of the fastest libraries * ☝️ Mature and time-tested * 👶 Easy to use out of the box * ⚙️ Highly customizable * 🎉 Built-in support for JSON, YAML, TOML, MessagePack * 📦 Built-in support for almost all Python types including typing-extensions * 📝 JSON Schema generation

Table of contents

• Table of contents
• Introduction
• Installation
• Changelog
• Supported data types
• Usage example
• How does it work?
• Benchmark
• Supported serialization formats
  • Basic form
  • JSON
    • json library
    • orjson library
  • YAML
  • TOML
  • MessagePack
• Customization
  • SerializableType interface
    • User-defined types
    • User-defined generic types
  • SerializationStrategy
    • Third-party types
    • Third-party generic types
  • Field options
    • serialize option
    • deserialize option
    • serialization_strategy option
    • alias option
  • Config options
    • debug config option
    • code_generation_options config option
    • serialization_strategy config option
    • aliases config option
    • serialize_by_alias config option
    • allow_deserialization_not_by_alias config option
    • omit_none config option
    • omit_default config option
    • namedtuple_as_dict config option
    • allow_postponed_evaluation config option
    • dialect config option
    • orjson_options config option
    • discriminator config option
    • lazy_compilation config option
    • sort_keys config option
    • forbid_extra_keys config option
  • Passing field values as is
  • Extending existing types
  • Field aliases
  • Dialects
    • serialization_strategy dialect option
    • serialize_by_alias dialect option
    • omit_none dialect option
    • omit_default dialect option
    • namedtuple_as_dict dialect option
    • no_copy_collections dialect option
    • Changing the default dialect
  • Discriminator
    • Subclasses distinguishable by a field
    • Subclasses without a common field
    • Class level discriminator
    • Working with union of classes
    • Using a custom variant tagger function
  • Code generation options
    • Add omit_none keyword argument
    • Add by_alias keyword argument
    • Add dialect keyword argument
    • Add context keyword argument
  • Generic dataclasses
    • Generic dataclass inheritance
    • Generic dataclass in a field type
  • GenericSerializableType interface
  • Serialization hooks
    • Before deserialization
    • After deserialization
    • Before serialization
    • After serialization
• JSON Schema
  • Building JSON Schema
  • JSON Schema constraints
  • JSON Schema plugins
  • Extending JSON Schema
  • JSON Schema and custom serialization methods

Introduction

This library provides two fundamentally different approaches to converting your data to and from various formats. Each of them is useful in different situations:

• Codecs
• Mixins

Codecs are represented by a set of decoder / encoder classes and decode / encode functions for each supported format. You can use them to convert data of any python built-in and third-party type to JSON, YAML, TOML, MessagePack or a basic form accepted by other serialization formats. For example, you can convert a list of datetime objects to JSON array containing string-represented datetimes and vice versa.

Mixins are primarily for dataclass models. They are represented by mixin classes that add methods for converting to and from JSON, YAML, TOML, MessagePack or a basic form accepted by other serialization formats. If you have a root dataclass model, then it will be the easiest way to make it serializable. All you have to do is inherit a particular mixin class.

In addition to serialization functionality, this library also provides JSON Schema builder that can be used in places where interoperability matters.

Installation

Use pip to install:

$ pip install mashumaro

The current version of mashumaro supports Python versions 3.10 — 3.14.

It's not recommended to use any version of Python that has reached its end of life and is no longer receiving security updates or bug fixes from the Python development team. For convenience, there is a table below that outlines the last version of mashumaro that can be installed on unmaintained versions of Python.

Changelog

This project follows the principles of Semantic Versioning. Changelog is available on GitHub Releases page.

Supported data types

There is support for generic types from the standard typing module: * List * Tuple * NamedTuple * Set * FrozenSet * Deque * Dict * OrderedDict * DefaultDict * TypedDict * Mapping * MutableMapping * Counter * ChainMap * Sequence

for standard generic types on PEP 585: * list * tuple * namedtuple * set * frozenset * collections.abc.Set * collections.abc.MutableSet * collections.deque * dict * collections.OrderedDict * collections.defaultdict * collections.abc.Mapping * collections.abc.MutableMapping * collections.Counter * collections.ChainMap * collections.abc.Sequence * collections.abc.MutableSequence

for special primitives from the typing module: * Any * Optional * Union * TypeVar * TypeVarTuple * NewType * Annotated * Literal * LiteralString * Final * Self * Unpack * ReadOnly

for standard interpreter types from types module: * NoneType * UnionType * MappingProxyType

for enumerations based on classes from the standard enum module: * Enum * IntEnum * StrEnum * [Flag](ht