###### Fast and well tested serialization library
[](https://github.com/Fatal1ty/mashumaro/actions)
[](https://coveralls.io/github/Fatal1ty/mashumaro?branch=master)
[](https://pypi.python.org/pypi/mashumaro)
[](https://pypi.python.org/pypi/mashumaro)
[](https://opensource.org/licenses/Apache-2.0)
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](#table-of-contents)
* [Introduction](#introduction)
* [Installation](#installation)
* [Changelog](#changelog)
* [Supported data types](#supported-data-types)
* [Usage example](#usage-example)
* [How does it work?](#how-does-it-work)
* [Benchmark](#benchmark)
* [Supported serialization formats](#supported-serialization-formats)
* [Basic form](#basic-form)
* [JSON](#json)
* [json library](#json-library)
* [orjson library](#orjson-library)
* [YAML](#yaml)
* [TOML](#toml)
* [MessagePack](#messagepack)
* [Customization](#customization)
* [SerializableType interface](#serializabletype-interface)
* [User-defined types](#user-defined-types)
* [User-defined generic types](#user-defined-generic-types)
* [SerializationStrategy](#serializationstrategy)
* [Third-party types](#third-party-types)
* [Third-party generic types](#third-party-generic-types)
* [Field options](#field-options)
* [`serialize` option](#serialize-option)
* [`deserialize` option](#deserialize-option)
* [`serialization_strategy` option](#serialization_strategy-option)
* [`alias` option](#alias-option)
* [Config options](#config-options)
* [`debug` config option](#debug-config-option)
* [`code_generation_options` config option](#code_generation_options-config-option)
* [`serialization_strategy` config option](#serialization_strategy-config-option)
* [`aliases` config option](#aliases-config-option)
* [`serialize_by_alias` config option](#serialize_by_alias-config-option)
* [`allow_deserialization_not_by_alias` config option](#allow_deserialization_not_by_alias-config-option)
* [`omit_none` config option](#omit_none-config-option)
* [`omit_default` config option](#omit_default-config-option)
* [`namedtuple_as_dict` config option](#namedtuple_as_dict-config-option)
* [`allow_postponed_evaluation` config option](#allow_postponed_evaluation-config-option)
* [`dialect` config option](#dialect-config-option)
* [`orjson_options` config option](#orjson_options-config-option)
* [`discriminator` config option](#discriminator-config-option)
* [`lazy_compilation` config option](#lazy_compilation-config-option)
* [`sort_keys` config option](#sort_keys-config-option)
* [`forbid_extra_keys` config option](#forbid_extra_keys-config-option)
* [Passing field values as is](#passing-field-values-as-is)
* [Extending existing types](#extending-existing-types)
* [Field aliases](#field-aliases)
* [Dialects](#dialects)
* [`serialization_strategy` dialect option](#serialization_strategy-dialect-option)
* [`serialize_by_alias` dialect option](#serialize_by_alias-dialect-option)
* [`omit_none` dialect option](#omit_none-dialect-option)
* [`omit_default` dialect option](#omit_default-dialect-option)
* [`namedtuple_as_dict` dialect option](#namedtuple_as_dict-dialect-option)
* [`no_copy_collections` dialect option](#no_copy_collections-dialect-option)
* [Changing the default dialect](#changing-the-default-dialect)
* [Discriminator](#discriminator)
* [Subclasses distinguishable by a field](#subclasses-distinguishable-by-a-field)
* [Subclasses without a common field](#subclasses-without-a-common-field)
* [Class level discriminator](#class-level-discriminator)
* [Working with union of classes](#working-with-union-of-classes)
* [Using a custom variant tagger function](#using-a-custom-variant-tagger-function)
* [Code generation options](#code-generation-options)
* [Add `omit_none` keyword argument](#add-omit_none-keyword-argument)
* [Add `by_alias` keyword argument](#add-by_alias-keyword-argument)
* [Add `dialect` keyword argument](#add-dialect-keyword-argument)
* [Add `context` keyword argument](#add-context-keyword-argument)
* [Generic dataclasses](#generic-dataclasses)
* [Generic dataclass inheritance](#generic-dataclass-inheritance)
* [Generic dataclass in a field type](#generic-dataclass-in-a-field-type)
* [GenericSerializableType interface](#genericserializabletype-interface)
* [Serialization hooks](#serialization-hooks)
* [Before deserialization](#before-deserialization)
* [After deserialization](#after-deserialization)
* [Before serialization](#before-serialization)
* [After serialization](#after-serialization)
* [JSON Schema](#json-schema)
* [Building JSON Schema](#building-json-schema)
* [JSON Schema constraints](#json-schema-constraints)
* [Extending JSON Schema](#extending-json-schema)
* [JSON Schema and custom serialization methods](#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:
```shell
$ pip install mashumaro
```
The current version of `mashumaro` supports Python versions 3.8 — 3.13.
It's not recommended to use any version of Python that has reached its
[end of life](https://devguide.python.org/versions/) 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.
| Python Version | Last Version of mashumaro | Python EOL |
|----------------|--------------------------------------------------------------------|------------|
| 3.7 | [3.9.1](https://github.com/Fatal1ty/mashumaro/releases/tag/v3.9.1) | 2023-06-27 |
| 3.6 | [3.1.1](https://github.com/Fatal1ty/mashumaro/releases/tag/v3.1.1) | 2021-12-23 |
Changelog
-------------------------------------------------------------------------------
This project follows the principles of [Semantic Versioning](https://semver.org).
Changelog is available on [GitHub Releases page](https://github.com/Fatal1ty/mashumaro/releases).
Supported data types
-------------------------------------------------------------------------------
There is support for generic types from the standard [`typing`](https://docs.python.org/3/library/typing.html) module:
* [`List`](https://docs.python.org/3/library/typing.html#typing.List)
* [`Tuple`](https://docs.python.org/3/library/typing.html#typing.Tuple)
* [`NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple)
* [`Set`](https://docs.python.org/3/library/typing.html#typing.Set)
* [`FrozenSet`](https://docs.python.org/3/library/typing.html#typing.FrozenSet)
* [`Deque`](https://docs.python.org/3/library/typing.html#typing.Deque)
* [`Dict`](https://docs.python.org/3/library/typing.html#typing.Dict)
* [`OrderedDict`](https://docs.python.org/3/library/typing.html#typing.OrderedDict)
* [`DefaultDict`](https://docs.python.org/3/library/typing.html#typing.DefaultDict)
* [`TypedDict`](https://docs.python.org/3/library/typing.html#typing.TypedDict)
* [`Mapping`](https://docs.python.org/3/library/typing.html#typing.Mapping)
* [`MutableMapping`](https://docs.python.org/3/library/typing.html#typing.MutableMapping)
* [`Counter`](https://docs.python.org/3/library/typing.html#typing.Counter)
* [`ChainMap`](https://docs.python.org/3/library/typing.html#typing.ChainMap)
* [`Sequence`](https://docs.python.org/3/library/typing.html#typing.Sequence)
for standard generic types on [PEP 585](https://www.python.org/dev/peps/pep-0585/) compatible Python (3.9+):
* [`list`](https://docs.python.org/3/library/stdtypes.html#list)
* [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)
* [`namedtuple`](https://docs.python.org/3/library/collections.html#collections.namedtuple)
* [`set`](https://docs.python.org/3/library/stdtypes.html#set)
* [`frozenset`](https://docs.python.org/3/library/stdtypes.html#frozenset)
* [`collections.abc.Set`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Set)
* [`collections.abc.MutableSet`](https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableSet)
* [`collections.deque`](https://docs.python.org/3/library/collections.html#collections.deque)
* [`dict`](https://docs.python.org/3/library/stdtypes.html#dict)
* [`collections.OrderedDict`](https://docs.python.org/3/library/collections.html#collections.OrderedDict)
* [`collections.defaultdict`](https://docs.python.org/3/library/collections.html#collections.defaultdict)
* [`collections.abc.Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)
* [`collections.abc.MutableMapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableMapping)
* [`collections.Counter`](https://docs.python.org/3/library/collections.html#collections.Counter)
* [`collections.ChainMap`](https://docs.python.org/3/library/collections.html#collections.ChainMap)
* [`collections.abc.Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)
* [`collections.abc.MutableSequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableSequence)
for special primitives from the [`typing`](https://docs.python.org/3/library/typing.html) module:
* [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)
* [`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional)
* [`Union`](https://docs.python.org/3/library/typing.html#typing.Union)
* [`TypeVar`](https://docs.python.org/3/library/typing.html#typing.TypeVar)
* [`TypeVarTuple`](https://docs.python.org/3/library/typing.html#typing.TypeVarTuple)
* [`NewType`](https://docs.python.org/3/library/typing.html#newtype)
* [`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated)
* [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)
* [`LiteralString`](https://docs.python.org/3/library/typing.html#typing.LiteralString)
* [`Final`](https://docs.python.org/3/library/typing.html#typing.Final)
* [`Self`](https://docs.python.org/3/library/typing.html#typing.Self)
* [`Unpack`](https://docs.python.org/3/library/typing.html#typing.Unpack)
for standard interpreter types from [`types`](https://docs.python.org/3/library/types.html#standard-interpreter-types) module:
* [`NoneType`](https://docs.python.org/3/library/types.html#types.NoneType)
* [`UnionType`](https://docs.python.org/3/library/types.html#types.UnionType)
* [`MappingProxyType`](https://docs.python.org/3/library/types.html#types.MappingProxyType)
for enumerations based on classes from the standard [`enum`](https://docs.python.org/3/library/enum.html) module:
* [`Enum`](https://docs.python.org/3/library/enum.html#enum.Enum)
* [`IntEnum`](https://docs.python.org/3/library/enum.html#enum.IntEnum)
* [`StrEnum`](https://docs.python.org/3/library/enum.html#enum.StrEnum)
* [`Flag`](https://docs.python.org/3/library/enum.html#enum.Flag)
* [`IntFlag`](https://docs.python.org/3/library/enum.html#enum.IntFlag)
for common built-in types:
* [`int`](https://docs.python.org/3/library/functions.html#int)
* [`float`](https://docs.python.org/3/library/functions.html#float)
* [`bool`](https://docs.python.org/3/library/stdtypes.html#bltin-boolean-values)
* [`str`](https://docs.python.org/3/library/stdtypes.html#str)
* [`bytes`](https://docs.python.org/3/library/stdtypes.html#bytes)
* [`bytearray`](https://docs.python.org/3/library/stdtypes.html#bytearray)
for built-in datetime oriented types (see [more](#deserialize-option) details):
* [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime)
* [`date`](https://docs.python.org/3/library/datetime.html#datetime.date)
* [`time`](https://docs.python.org/3/library/datetime.html#datetime.time)
* [`timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta)
* [`timezone`](https://docs.python.org/3/library/datetime.html#datetime.timezone)
* [`ZoneInfo`](https://docs.python.org/3/library/zoneinfo.html#zoneinfo.ZoneInfo)
for pathlike types:
* [`PurePath`](https://docs.python.org/3/library/pathlib.html#pathlib.PurePath)
* [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path)
* [`PurePosixPath`](https://docs.python.org/3/library/pathlib.html#pathlib.PurePosixPath)
* [`PosixPath`](https://docs.python.org/3/library/pathlib.html#pathlib.PosixPath)
* [`PureWindowsPath`](https://docs.python.org/3/library/pathlib.html#pathlib.PureWindowsPath)
* [`WindowsPath`](https://docs.python.org/3/library/pathlib.html#pathlib.WindowsPath)
* [`os.PathLike`](https://docs.python.org/3/library/os.html#os.PathLike)
for other less popular built-in types:
* [`uuid.UUID`](https://docs.python.org/3/library/uuid.html#uuid.UUID)
* [`decimal.Decimal`](https://docs.python.org/3/library/decimal.html#decimal.Decimal)
* [`fractions.Fraction`](https://docs.python.org/3/library/fractions.html#fractions.Fraction)
* [`ipaddress.IPv4Address`](https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Address)
* [`ipaddress.IPv6Address`](https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv6Address)
* [`ipaddress.IPv4Network`](https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Network)
* [`ipaddress.IPv6Network`](https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv6Network)
* [`ipaddress.IPv4Interface`](https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Interface)
* [`ipaddress.IPv6Interface`](https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv6Interface)
for backported types from [`typing-extensions`](https://github.com/python/typing_extensions):
* [`OrderedDict`](https://docs.python.org/3/library/typing.html#typing.OrderedDict)
* [`TypedDict`](https://docs.python.org/3/library/typing.html#typing.TypedDict)
* [`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated)
* [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)
* [`LiteralString`](https://docs.python.org/3/library/typing.html#typing.LiteralString)
* [`Self`](https://docs.python.org/3/library/typing.html#typing.Self)
* [`TypeVarTuple`](https://docs.python.org/3/library/typing.html#typing.TypeVarTuple)
* [`Unpack`](https://docs.python.org/3/library/typing.html#typing.Unpack)
for arbitrary types:
* [user-defined types](#user-defined-types)
* [third-party types](#third-party-types)
* [user-defined generic types](#user-defined-generic-types)
* [third-party generic types](#third-party-generic-types)
Usage example
-------------------------------------------------------------------------------
Suppose we're developing a financial application and we operate with currencies
and stocks:
```python
from dataclasses import dataclass
from enum import Enum
class Currency(Enum):
USD = "USD"
EUR = "EUR"
@dataclass
class CurrencyPosition:
currency: Currency
balance: float
@dataclass
class StockPosition:
ticker: str
name: str
balance: int
```
Now we want a dataclass for portfolio that will be serialized to and from JSON.
We inherit `DataClassJSONMixin` that adds this functionality:
```python
from mashumaro.mixins.json import DataClassJSONMixin
...
@dataclass
class Portfolio(DataClassJSONMixin):
currencies: list[CurrencyPosition]
stocks: list[StockPosition]
```
Let's create a portfolio instance and check methods `from_json` and `to_json`:
```python
portfolio = Portfolio(
currencies=[
CurrencyPosition(Currency.USD, 238.67),
CurrencyPosition(Currency.EUR, 361.84),
],
stocks=[
StockPosition("AAPL", "Apple", 10),
StockPosition("AMZN", "Amazon", 10),
]
)
portfolio_json = portfolio.to_json()
assert Portfolio.from_json(portfolio_json) == portfolio
```
If we need to serialize something different from a root dataclass,
we can use codecs. In the following example we create a JSON decoder and encoder
for a list of currencies:
```python
from mashumaro.codecs.json import JSONDecoder, JSONEncoder
...
decoder = JSONDecoder(list[CurrencyPosition])
encoder = JSONEncoder(list[CurrencyPosition])
currencies = [
CurrencyPosition(Currency.USD, 238.67),
CurrencyPosition(Currency.EUR, 361.84),
]
currencies_json = encoder.encode(currencies)
assert decoder.decode(currencies_json) == currencies
```
How does it work?
-------------------------------------------------------------------------------
This library works by taking the schema of the data and generating a
specific decoder and encoder for exactly that schema, taking into account the
specifics of serialization format. This is much faster than inspection of
data types on every call of decoding or encoding at runtime.
These specific decoders and encoders are generated by
[codecs and mixins](#supported-serialization-formats):
* When using codecs, these methods are compiled during the creation of the
decoder or encoder.
* When using serialization
mixins, these methods are compiled during import time (or at runtime in some
cases) and are set as attributes to your dataclasses. To minimize the import
time, you can explicitly enable
[lazy compilation](#lazy_compilation-config-option).
Benchmark
-------------------------------------------------------------------------------
* macOS 14.0 Sonoma
* Apple M1
* 16GB RAM
* Python 3.12.0
Benchmark using [pyperf](https://github.com/psf/pyperf) with GitHub Issue model. Please note that the
following charts use logarithmic scale, as it is convenient for displaying
very large ranges of values.
