mashumaro
Fast and well tested serialization library
Description
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
- Customization
- SerializableType interface
- SerializationStrategy
- Field options
- Config options
debugconfig optioncode_generation_optionsconfig optionserialization_strategyconfig optionaliasesconfig optionserialize_by_aliasconfig optionallow_deserialization_not_by_aliasconfig optionomit_noneconfig optionomit_defaultconfig optionnamedtuple_as_dictconfig optionallow_postponed_evaluationconfig optiondialectconfig optionorjson_optionsconfig optiondiscriminatorconfig optionlazy_compilationconfig optionsort_keysconfig optionforbid_extra_keysconfig option
- Passing field values as is
- Extending existing types
- Field aliases
- Dialects
- Discriminator
- Code generation options
- Generic dataclasses
- GenericSerializableType interface
- Serialization hooks
- JSON Schema
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.9 — 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.
| Python Version | Last Version of mashumaro | Python EOL |
|---|---|---|
| 3.8 | 3.14 | 2024-10-07 |
| 3.7 | 3.9.1 | 2023-06-27 |
| 3.6 | 3.1.1 | 2021-12-23 |
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: