{"author":"Alexander Tikhonov","author_email":"random.gauss@gmail.com","bugtrack_url":null,"classifiers":["Development Status :: 5 - Production/Stable","Intended Audience :: Developers","License :: OSI Approved :: Apache Software License","Programming Language :: Python :: 3 :: Only","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.13","Programming Language :: Python :: 3.9"],"description":"

\n\n $\"logo\"$ \n\n###### Fast and well tested serialization library\n\n[![Build Status](https://github.com/Fatal1ty/mashumaro/workflows/tests/badge.svg)](https://github.com/Fatal1ty/mashumaro/actions)\n[![Coverage Status](https://coveralls.io/repos/github/Fatal1ty/mashumaro/badge.svg?branch=master)](https://coveralls.io/github/Fatal1ty/mashumaro?branch=master)\n[![Latest Version](https://img.shields.io/pypi/v/mashumaro.svg)](https://pypi.python.org/pypi/mashumaro)\n[![Python Version](https://img.shields.io/pypi/pyversions/mashumaro.svg)](https://pypi.python.org/pypi/mashumaro)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n

\n\nIn Python, you often need to dump and load objects based on the schema you\nhave. It can be a dataclass model, a list of third-party generic classes or\nwhatever. Mashumaro not only lets you save and load things in different ways,\nbut it also does it _super quick_.\n\n**Key features**\n* 🚀 One of the fastest libraries\n* ☝️ Mature and time-tested\n* 👶 Easy to use out of the box\n* ⚙️ Highly customizable\n* 🎉 Built-in support for JSON, YAML, TOML, MessagePack\n* 📦 Built-in support for almost all Python types including typing-extensions\n* 📝 JSON Schema generation\n\nTable of contents\n-------------------------------------------------------------------------------\n* [Table of contents](#table-of-contents)\n* [Introduction](#introduction)\n* [Installation](#installation)\n* [Changelog](#changelog)\n* [Supported data types](#supported-data-types)\n* [Usage example](#usage-example)\n* [How does it work?](#how-does-it-work)\n* [Benchmark](#benchmark)\n* [Supported serialization formats](#supported-serialization-formats)\n * [Basic form](#basic-form)\n * [JSON](#json)\n * [json library](#json-library)\n * [orjson library](#orjson-library)\n * [YAML](#yaml)\n * [TOML](#toml)\n * [MessagePack](#messagepack)\n* [Customization](#customization)\n * [SerializableType interface](#serializabletype-interface)\n * [User-defined types](#user-defined-types)\n * [User-defined generic types](#user-defined-generic-types)\n * [SerializationStrategy](#serializationstrategy)\n * [Third-party types](#third-party-types)\n * [Third-party generic types](#third-party-generic-types)\n * [Field options](#field-options)\n * [`serialize` option](#serialize-option)\n * [`deserialize` option](#deserialize-option)\n * [`serialization_strategy` option](#serialization_strategy-option)\n * [`alias` option](#alias-option)\n * [Config options](#config-options)\n * [`debug` config option](#debug-config-option)\n * [`code_generation_options` config option](#code_generation_options-config-option)\n * [`serialization_strategy` config option](#serialization_strategy-config-option)\n * [`aliases` config option](#aliases-config-option)\n * [`serialize_by_alias` config option](#serialize_by_alias-config-option)\n * [`allow_deserialization_not_by_alias` config option](#allow_deserialization_not_by_alias-config-option)\n * [`omit_none` config option](#omit_none-config-option)\n * [`omit_default` config option](#omit_default-config-option)\n * [`namedtuple_as_dict` config option](#namedtuple_as_dict-config-option)\n * [`allow_postponed_evaluation` config option](#allow_postponed_evaluation-config-option)\n * [`dialect` config option](#dialect-config-option)\n * [`orjson_options` config option](#orjson_options-config-option)\n * [`discriminator` config option](#discriminator-config-option)\n * [`lazy_compilation` config option](#lazy_compilation-config-option)\n * [`sort_keys` config option](#sort_keys-config-option)\n * [`forbid_extra_keys` config option](#forbid_extra_keys-config-option)\n * [Passing field values as is](#passing-field-values-as-is)\n * [Extending existing types](#extending-existing-types)\n * [Field aliases](#field-aliases)\n * [Dialects](#dialects)\n * [`serialization_strategy` dialect option](#serialization_strategy-dialect-option)\n * [`serialize_by_alias` dialect option](#serialize_by_alias-dialect-option)\n * [`omit_none` dialect option](#omit_none-dialect-option)\n * [`omit_default` dialect option](#omit_default-dialect-option)\n * [`namedtuple_as_dict` dialect option](#namedtuple_as_dict-dialect-option)\n * [`no_copy_collections` dialect option](#no_copy_collections-dialect-option)\n * [Changing the default dialect](#changing-the-default-dialect)\n * [Discriminator](#discriminator)\n * [Subclasses distinguishable by a field](#subclasses-distinguishable-by-a-field)\n * [Subclasses without a common field](#subclasses-without-a-common-field)\n * [Class level discriminator](#class-level-discriminator)\n * [Working with union of classes](#working-with-union-of-classes)\n * [Using a custom variant tagger function](#using-a-custom-variant-tagger-function)\n * [Code generation options](#code-generation-options)\n * [Add `omit_none` keyword argument](#add-omit_none-keyword-argument)\n * [Add `by_alias` keyword argument](#add-by_alias-keyword-argument)\n * [Add `dialect` keyword argument](#add-dialect-keyword-argument)\n * [Add `context` keyword argument](#add-context-keyword-argument)\n * [Generic dataclasses](#generic-dataclasses)\n * [Generic dataclass inheritance](#generic-dataclass-inheritance)\n * [Generic dataclass in a field type](#generic-dataclass-in-a-field-type)\n * [GenericSerializableType interface](#genericserializabletype-interface)\n * [Serialization hooks](#serialization-hooks)\n * [Before deserialization](#before-deserialization)\n * [After deserialization](#after-deserialization)\n * [Before serialization](#before-serialization)\n * [After serialization](#after-serialization)\n* [JSON Schema](#json-schema)\n * [Building JSON Schema](#building-json-schema)\n * [JSON Schema constraints](#json-schema-constraints)\n * [JSON Schema plugins](#json-schema-plugins)\n * [Extending JSON Schema](#extending-json-schema)\n * [JSON Schema and custom serialization methods](#json-schema-and-custom-serialization-methods)\n\nIntroduction\n-------------------------------------------------------------------------------\n\nThis library provides two fundamentally different approaches to converting\nyour data to and from various formats. Each of them is useful in different\nsituations:\n\n* Codecs\n* Mixins\n\nCodecs are represented by a set of decoder / encoder classes and\ndecode / encode functions for each supported format. You can use them\nto convert data of any python built-in and third-party type to JSON, YAML,\nTOML, MessagePack or a basic form accepted by other serialization formats.\nFor example, you can convert a list of datetime objects to JSON array\ncontaining string-represented datetimes and vice versa.\n\nMixins are primarily for dataclass models. They are represented by mixin\nclasses that add methods for converting to and from JSON, YAML, TOML,\nMessagePack or a basic form accepted by other serialization formats.\nIf you have a root dataclass model, then it will be the easiest way to make it\nserializable. All you have to do is inherit a particular mixin class.\n\nIn addition to serialization functionality, this library also provides JSON\nSchema builder that can be used in places where interoperability matters.\n\nInstallation\n-------------------------------------------------------------------------------\n\nUse pip to install:\n```shell\n$ pip install mashumaro\n```\n\nThe current version of `mashumaro` supports Python versions 3.9 — 3.13.\n\n\nIt's not recommended to use any version of Python that has reached its\n[end of life](https://devguide.python.org/versions/) and is no longer receiving\nsecurity updates or bug fixes from the Python development team.\nFor convenience, there is a table below that outlines the\nlast version of `mashumaro` that can be installed on unmaintained versions\nof Python.\n\n| Python Version | Last Version of mashumaro | Python EOL |\n|----------------|--------------------------------------------------------------------|------------|\n| 3.8 | [3.14](https://github.com/Fatal1ty/mashumaro/releases/tag/v3.14) | 2024-10-07 |\n| 3.7 | [3.9.1](https://github.com/Fatal1ty/mashumaro/releases/tag/v3.9.1) | 2023-06-27 |\n| 3.6 | [3.1.1](https://github.com/Fatal1ty/mashumaro/releases/tag/v3.1.1) | 2021-12-23 |\n\n\nChangelog\n-------------------------------------------------------------------------------\n\nThis project follows the principles of [Semantic Versioning](https://semver.org).\nChangelog is available on [GitHub Releases page](https://github.com/Fatal1ty/mashumaro/releases).\n\nSupported data types\n-------------------------------------------------------------------------------\n\nThere is support for generic types from the standard [`typing`](https://docs.python.org/3/library/typing.html) module:\n* [`List`](https://docs.python.org/3/library/typing.html#typing.List)\n* [`Tuple`](https://docs.python.org/3/library/typing.html#typing.Tuple)\n* [`NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple)\n* [`Set`](https://docs.python.org/3/library/typing.html#typing.Set)\n* [`FrozenSet`](https://docs.python.org/3/library/typing.html#typing.FrozenSet)\n* [`Deque`](https://docs.python.org/3/library/typing.html#typing.Deque)\n* [`Dict`](https://docs.python.org/3/library/typing.html#typing.Dict)\n* [`OrderedDict`](https://docs.python.org/3/library/typing.html#typing.OrderedDict)\n* [`DefaultDict`](https://docs.python.org/3/library/typing.html#typing.DefaultDict)\n* [`TypedDict`](https://docs.python.org/3/library/typing.html#typing.TypedDict)\n* [`Mapping`](https://docs.python.org/3/library/typing.html#typing.Mapping)\n* [`MutableMapping`](https://docs.python.org/3/library/typing.html#typing.MutableMapping)\n* [`Counter`](https://docs.python.org/3/library/typing.html#typing.Counter)\n* [`ChainMap`](https://docs.python.org/3/library/typing.html#typing.ChainMap)\n* [`Sequence`](https://docs.python.org/3/library/typing.html#typing.Sequence)\n\nfor standard generic types on [PEP 585](https://www.python.org/dev/peps/pep-0585/) compatible Python (3.9+):\n* [`list`](https://docs.python.org/3/library/stdtypes.html#list)\n* [`tuple`](https://docs.python.org/3/library/stdtypes.html#tuple)\n* [`namedtuple`](https://docs.python.org/3/library/collections.html#collections.namedtuple)\n* [`set`](https://docs.python.org/3/library/stdtypes.html#set)\n* [`frozenset`](https://docs.python.org/3/library/stdtypes.html#frozenset)\n* [`collections.abc.Set`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Set)\n* [`collections.abc.MutableSet`](https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableSet)\n* [`collections.deque`](https://docs.python.org/3/library/collections.html#collections.deque)\n* [`dict`](https://docs.python.org/3/library/stdtypes.html#dict)\n* [`collections.OrderedDict`](https://docs.python.org/3/library/collections.html#collections.OrderedDict)\n* [`collections.defaultdict`](https://docs.python.org/3/library/collections.html#collections.defaultdict)\n* [`collections.abc.Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)\n* [`collections.abc.MutableMapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableMapping)\n* [`collections.Counter`](https://docs.python.org/3/library/collections.html#collections.Counter)\n* [`collections.ChainMap`](https://docs.python.org/3/library/collections.html#collections.ChainMap)\n* [`collections.abc.Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)\n* [`collections.abc.MutableSequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableSequence)\n\nfor special primitives from the [`typing`](https://docs.python.org/3/library/typing.html) module:\n* [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)\n* [`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional)\n* [`Union`](https://docs.python.org/3/library/typing.html#typing.Union)\n* [`TypeVar`](https://docs.python.org/3/library/typing.html#typing.TypeVar)\n* [`TypeVarTuple`](https://docs.python.org/3/library/typing.html#typing.TypeVarTuple)\n* [`NewType`](https://docs.python.org/3/library/typing.html#newtype)\n* [`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated)\n* [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\n* [`LiteralString`](https://docs.python.org/3/library/typing.html#typing.LiteralString)\n* [`Final`](https://docs.python.org/3/library/typing.html#typing.Final)\n* [`Self`](https://docs.python.org/3/library/typing.html#typing.Self)\n* [`Unpack`](https://docs.python.org/3/library/typing.html#typing.Unpack)\n* [`ReadOnly`](https://docs.python.org/3/library/typing.html#typing.ReadOnly)\n\nfor standard interpreter types from [`types`](https://docs.python.org/3/library/types.html#standard-interpreter-types) module:\n* [`NoneType`](https://docs.python.org/3/library/types.html#types.NoneType)\n* [`UnionType`](https://docs.python.org/3/library/types.html#types.UnionType)\n* [`MappingProxyType`](https://docs.python.org/3/library/types.html#types.MappingProxyType)\n\nfor enumerations based on classes from the standard [`enum`](https://docs.python.org/3/library/enum.html) module:\n* [`Enum`](https://docs.python.org/3/library/enum.html#enum.Enum)\n* [`IntEnum`](https://docs.python.org/3/library/enum.html#enum.IntEnum)\n* [`StrEnum`](https://docs.python.org/3/library/enum.html#enum.StrEnum)\n* [`Flag`](https://docs.python.org/3/library/enum.html#enum.Flag)\n* [`IntFlag`](https://docs.python.org/3/library/enum.html#enum.IntFlag)\n\nfor common built-in types:\n* [`int`](https://docs.python.org/3/library/functions.html#int)\n* [`float`](https://docs.python.org/3/library/functions.html#float)\n* [`bool`](https://docs.python.org/3/library/stdtypes.html#bltin-boolean-values)\n* [`str`](https://docs.python.org/3/library/stdtypes.html#str)\n* [`bytes`](https://docs.python.org/3/library/stdtypes.html#bytes)\n* [`bytearray`](https://docs.python.org/3/library/stdtypes.html#bytearray)\n\nfor built-in datetime oriented types (see [more](#deserialize-option) details):\n* [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime)\n* [`date`](https://docs.python.org/3/library/datetime.html#datetime.date)\n* [`time`](https://docs.python.org/3/library/datetime.html#datetime.time)\n* [`timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta)\n* [`timezone`](https://docs.python.org/3/library/datetime.html#datetime.timezone)\n* [`ZoneInfo`](https://docs.python.org/3/library/zoneinfo.html#zoneinfo.ZoneInfo)\n\nfor pathlike types:\n* [`PurePath`](https://docs.python.org/3/library/pathlib.html#pathlib.PurePath)\n* [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path)\n* [`PurePosixPath`](https://docs.python.org/3/library/pathlib.html#pathlib.PurePosixPath)\n* [`PosixPath`](https://docs.python.org/3/library/pathlib.html#pathlib.PosixPath)\n* [`PureWindowsPath`](https://docs.python.org/3/library/pathlib.html#pathlib.PureWindowsPath)\n* [`WindowsPath`](https://docs.python.org/3/library/pathlib.html#pathlib.WindowsPath)\n* [`os.PathLike`](https://docs.python.org/3/library/os.html#os.PathLike)\n\nfor other less popular built-in types:\n* [`uuid.UUID`](https://docs.python.org/3/library/uuid.html#uuid.UUID)\n* [`decimal.Decimal`](https://docs.python.org/3/library/decimal.html#decimal.Decimal)\n* [`fractions.Fraction`](https://docs.python.org/3/library/fractions.html#fractions.Fraction)\n* [`ipaddress.IPv4Address`](https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Address)\n* [`ipaddress.IPv6Address`](https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv6Address)\n* [`ipaddress.IPv4Network`](https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Network)\n* [`ipaddress.IPv6Network`](https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv6Network)\n* [`ipaddress.IPv4Interface`](https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Interface)\n* [`ipaddress.IPv6Interface`](https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv6Interface)\n* [`typing.Pattern`](https://docs.python.org/3/library/typing.html#typing.Pattern)\n* [`re.Pattern`](https://docs.python.org/3/library/re.html#re.Pattern)\n\nfor backported types from [`typing-extensions`](https://github.com/python/typing_extensions):\n* [`OrderedDict`](https://docs.python.org/3/library/typing.html#typing.OrderedDict)\n* [`TypedDict`](https://docs.python.org/3/library/typing.html#typing.TypedDict)\n* [`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated)\n* [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)\n* [`LiteralString`](https://docs.python.org/3/library/typing.html#typing.LiteralString)\n* [`Self`](https://docs.python.org/3/library/typing.html#typing.Self)\n* [`TypeVarTuple`](https://docs.python.org/3/library/typing.html#typing.TypeVarTuple)\n* [`Unpack`](https://docs.python.org/3/library/typing.html#typing.Unpack)\n* [`ReadOnly`](https://docs.python.org/3/library/typing.html#typing.ReadOnly)\n\nfor arbitrary types:\n* [user-defined types](#user-defined-types)\n* [third-party types](#third-party-types)\n* [user-defined generic types](#user-defined-generic-types)\n* [third-party generic types](#third-party-generic-types)\n\nUsage example\n-------------------------------------------------------------------------------\n\nSuppose we're developing a financial application and we operate with currencies\nand stocks:\n\n```python\nfrom dataclasses import dataclass\nfrom enum import Enum\n\nclass Currency(Enum):\n USD = \"USD\"\n EUR = \"EUR\"\n\n@dataclass\nclass CurrencyPosition:\n currency: Currency\n balance: float\n\n@dataclass\nclass StockPosition:\n ticker: str\n name: str\n balance: int\n```\n\nNow we want a dataclass for portfolio that will be serialized to and from JSON.\nWe inherit `DataClassJSONMixin` that adds this functionality:\n\n```python\nfrom mashumaro.mixins.json import DataClassJSONMixin\n\n...\n\n@dataclass\nclass Portfolio(DataClassJSONMixin):\n currencies: list[CurrencyPosition]\n stocks: list[StockPosition]\n```\n\nLet's create a portfolio instance and check methods `from_json` and `to_json`:\n\n```python\nportfolio = Portfolio(\n currencies=[\n CurrencyPosition(Currency.USD, 238.67),\n CurrencyPosition(Currency.EUR, 361.84),\n ],\n stocks=[\n StockPosition(\"AAPL\", \"Apple\", 10),\n StockPosition(\"AMZN\", \"Amazon\", 10),\n ]\n)\n\nportfolio_json = portfolio.to_json()\nassert Portfolio.from_json(portfolio_json) == portfolio\n```\n\nIf we need to serialize something different from a root dataclass,\nwe can use codecs. In the following example we create a JSON decoder and encoder\nfor a list of currencies:\n\n```python\nfrom mashumaro.codecs.json import JSONDecoder, JSONEncoder\n\n...\n\ndecoder = JSONDecoder(list[CurrencyPosition])\nencoder = JSONEncoder(list[CurrencyPosition])\n\ncurrencies = [\n CurrencyPosition(Currency.USD, 238.67),\n CurrencyPosition(Currency.EUR, 361.84),\n]\ncurrencies_json = encoder.encode(currencies)\nassert decoder.decode(currencies_json) == currencies\n\n```\n\nHow does it work?\n-------------------------------------------------------------------------------\n\nThis library works by taking the schema of the data and generating a\nspecific decoder and encoder for exactly that schema, taking into account the\nspecifics of serialization format. This is much faster than inspection of\ndata types on every call of decoding or encoding at runtime.\n\nThese specific decoders and encoders are generated by\n[codecs and mixins](#supported-serialization-formats):\n* When using codecs, these methods are compiled during the creation of the\n decoder or encoder.\n* When using serialization\nmixins, these methods are compiled during import time (or at runtime in some\ncases) and are set as attributes to your dataclasses. To minimize the import\ntime, you can explicitly enable\n[lazy compilation](#lazy_compilation-config-option).\n\nBenchmark\n-------------------------------------------------------------------------------\n\n* macOS 15.1 Sequoia\n* Apple M3 Max\n* 36GB RAM\n* Python 3.13.0\n\nBenchmark using [pyperf](https://github.com/psf/pyperf) with GitHub Issue model. Please note that the\nfollowing charts use logarithmic scale, as it is convenient for displaying\nvery large ranges of values.\n\n

\n\n> [!NOTE]\\\n> Benchmark results may vary depending on the specific configuration and\n> parameters used for serialization and deserialization. However, we have made\n> an attempt to use the available options that can speed up and smooth out the\n> differences in how libraries work.\n\nTo run benchmark in your environment:\n```bash\ngit clone git@github.com:Fatal1ty/mashumaro.git\ncd mashumaro\npython3 -m venv env && source env/bin/activate\npip install -e .\npip install -r requirements-dev.txt\n./benchmark/run.sh\n```\n\nSupported serialization formats\n-------------------------------------------------------------------------------\n\nThis library has built-in support for multiple popular formats:\n\n* [JSON](https://www.json.org)\n* [YAML](https://yaml.org)\n* [TOML](https://toml.io)\n* [MessagePack](https://msgpack.org)\n\nThere are preconfigured codecs and mixin classes. However, you're free\nto override some settings if necessary.\n\n> [!IMPORTANT]\\\n> As for codecs, you are\n> offered to choose between convenience and efficiency. When you need to decode\n> or encode typed data more than once, it's highly recommended to create\n> and reuse a decoder or encoder specifically for that data type. For one-time\n> use with default settings it may be convenient to use global functions that\n> create a disposable decoder or encoder under the hood. Remember that you\n> should not use these convenient global functions more that once for the same\n> data type if performance is important to you.\n\n### Basic form\n\nBasic form denotes a python object consisting only of basic data types\nsupported by most serialization formats. These types are:\n[`str`](https://docs.python.org/3/library/stdtypes.html#str),\n[`int`](https://docs.python.org/3/library/functions.html#int),\n[`float`](https://docs.python.org/3/library/functions.html#float),\n[`bool`](https://docs.python.org/3/library/stdtypes.html#bltin-boolean-values),\n[`list`](https://docs.python.org/3/library/stdtypes.html#list),\n[`dict`](https://docs.python.org/3/library/stdtypes.html#dict).\n\nThis is also a starting point you can play with for a comprehensive\ntransformation of your data.\n\nEfficient decoder and encoder can be used as follows:\n\n```python\nfrom mashumaro.codecs import BasicDecoder, BasicEncoder\n# or from mashumaro.codecs.basic import BasicDecoder, BasicEncoder\n\ndecoder = BasicDecoder(, ...)\ndecoder.decode(...)\n\nencoder = BasicEncoder(, ...)\nencoder.encode(...)\n```\n\nConvenient functions are recommended to be used as follows:\n```python\nimport mashumaro.codecs.basic as basic_codec\n\nbasic_codec.decode(..., )\nbasic_codec.encode(..., )\n```\n\nMixin can be used as follows:\n```python\nfrom mashumaro import DataClassDictMixin\n# or from mashumaro.mixins.dict import DataClassDictMixin\n\n@dataclass\nclass MyModel(DataClassDictMixin):\n ...\n\nMyModel.from_dict(...)\nMyModel(...).to_dict()\n```\n\n> [!TIP]\\\n> You don't need to inherit `DataClassDictMixin` along with other serialization\n> mixins because it's a base class for them.\n\n### JSON\n\n[JSON](https://www.json.org) is a lightweight data-interchange format. You can\nchoose between standard library\n[json](https://docs.python.org/3/library/json.html) for compatibility and\nthird-party dependency [orjson](https://pypi.org/project/orjson/) for better\nperformance.\n\n#### json library\n\nEfficient decoder and encoder can be used as follows:\n```python\nfrom mashumaro.codecs.json import JSONDecoder, JSONEncoder\n\ndecoder = JSONDecoder(, ...)\ndecoder.decode(...)\n\nencoder = JSONEncoder(, ...)\nencoder.encode(...)\n```\n\nConvenient functions can be used as follows:\n```python\nfrom mashumaro.codecs.json import json_decode, json_encode\n\njson_decode(..., )\njson_encode(..., )\n```\n\nConvenient function aliases are recommended to be used as follows:\n```python\nimport mashumaro.codecs.json as json_codec\n\njson_codec.decode(...)\njson_codec.encode(..., )\n```\n\nMixin can be used as follows:\n```python\nfrom mashumaro.mixins.json import DataClassJSONMixin\n\n@dataclass\nclass MyModel(DataClassJSONMixin):\n ...\n\nMyModel.from_json(...)\nMyModel(...).to_json()\n```\n\n#### orjson library\n\nIn order to use [`orjson`](https://pypi.org/project/orjson/) library, it must\nbe installed manually or using an extra option for `mashumaro`:\n\n```shell\npip install mashumaro[orjson]\n```\n\nThe following data types will be handled by\n[`orjson`](https://pypi.org/project/orjson/) library by default:\n* [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime)\n* [`date`](https://docs.python.org/3/library/datetime.html#datetime.date)\n* [`time`](https://docs.python.org/3/library/datetime.html#datetime.time)\n* [`uuid.UUID`](https://docs.python.org/3/library/uuid.html#uuid.UUID)\n\nEfficient decoder and encoder can be used as follows:\n```python\nfrom mashumaro.codecs.orjson import ORJSONDecoder, ORJSONEncoder\n\ndecoder = ORJSONDecoder(, ...)\ndecoder.decode(...)\n\nencoder = ORJSONEncoder(, ...)\nencoder.encode(...)\n```\n\nConvenient functions can be used as follows:\n```python\nfrom mashumaro.codecs.orjson import json_decode, json_encode\n\njson_decode(..., )\njson_encode(..., )\n```\n\nConvenient function aliases are recommended to be used as follows:\n```python\nimport mashumaro.codecs.orjson as json_codec\n\njson_codec.decode(...)\njson_codec.encode(..., )\n```\n\nMixin can be used as follows:\n```python\nfrom mashumaro.mixins.orjson import DataClassORJSONMixin\n\n@dataclass\nclass MyModel(DataClassORJSONMixin):\n ...\n\nMyModel.from_json(...)\nMyModel(...).to_json()\nMyModel(...).to_jsonb()\n```\n\n### YAML\n\n[YAML](https://yaml.org) is a human-friendly data serialization language for\nall programming languages. In order to use this format, the\n[`pyyaml`](https://pypi.org/project/PyYAML/) package must be installed.\nYou can install it manually or using an extra option for `mashumaro`:\n\n```shell\npip install mashumaro[yaml]\n```\n\nEfficient decoder and encoder can be used as follows:\n```python\nfrom mashumaro.codecs.yaml import YAMLDecoder, YAMLEncoder\n\ndecoder = YAMLDecoder(, ...)\ndecoder.decode(...)\n\nencoder = YAMLEncoder(, ...)\nencoder.encode(...)\n```\n\nConvenient functions can be used as follows:\n```python\nfrom mashumaro.codecs.yaml import yaml_decode, yaml_encode\n\nyaml_decode(..., )\nyaml_encode(..., )\n```\n\nConvenient function aliases are recommended to be used as follows:\n```python\nimport mashumaro.codecs.yaml as yaml_codec\n\nyaml_codec.decode(...)\nyaml_codec.encode(..., )\n```\n\nMixin can be used as follows:\n```python\nfrom mashumaro.mixins.yaml import DataClassYAMLMixin\n\n@dataclass\nclass MyModel(DataClassYAMLMixin):\n ...\n\nMyModel.from_yaml(...)\nMyModel(...).to_yaml()\n```\n\n### TOML\n\n[TOML](https://toml.io) is config file format for humans.\nIn order to use this format, the [`tomli`](https://pypi.org/project/tomli/) and\n[`tomli-w`](https://pypi.org/project/tomli-w/) packages must be installed.\nIn Python 3.11+, `tomli` is included as\n[`tomlib`](https://docs.python.org/3/library/tomllib.html) standard library\nmodule and is used for this format. You can install the missing packages\nmanually or using an extra option\nfor `mashumaro`:\n\n```shell\npip install mashumaro[toml]\n```\n\nThe following data types will be handled by\n[`tomli`](https://pypi.org/project/tomli/)/\n[`tomli-w`](https://pypi.org/project/tomli-w/) library by default:\n* [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime)\n* [`date`](https://docs.python.org/3/library/datetime.html#datetime.date)\n* [`time`](https://docs.python.org/3/library/datetime.html#datetime.time)\n\nFields with value `None` will be omitted on serialization because TOML\ndoesn't support null values.\n\nEfficient decoder and encoder can be used as follows:\n```python\nfrom mashumaro.codecs.toml import TOMLDecoder, TOMLEncoder\n\ndecoder = TOMLDecoder(, ...)\ndecoder.decode(...)\n\nencoder = TOMLEncoder(, ...)\nencoder.encode(...)\n```\n\nConvenient functions can be used as follows:\n```python\nfrom mashumaro.codecs.toml import toml_decode, toml_encode\n\ntoml_decode(..., )\ntoml_encode(..., )\n```\n\nConvenient function aliases are recommended to be used as follows:\n```python\nimport mashumaro.codecs.toml as toml_codec\n\ntoml_codec.decode(...)\ntoml_codec.encode(..., )\n```\n\nMixin can be used as follows:\n```python\nfrom mashumaro.mixins.toml import DataClassTOMLMixin\n\n@dataclass\nclass MyModel(DataClassTOMLMixin):\n ...\n\nMyModel.from_toml(...)\nMyModel(...).to_toml()\n```\n\n### MessagePack\n\n[MessagePack](https://msgpack.org) is an efficient binary serialization format.\nIn order to use this mixin, the [`msgpack`](https://pypi.org/project/msgpack/)\npackage must be installed. You can install it manually or using an extra\noption for `mashumaro`:\n\n```shell\npip install mashumaro[msgpack]\n```\n\nThe following data types will be handled by\n[`msgpack`](https://pypi.org/project/msgpack/) library by default:\n* [`bytes`](https://docs.python.org/3/library/stdtypes.html#bytes)\n* [`bytearray`](https://docs.python.org/3/library/stdtypes.html#bytearray)\n\nEfficient decoder and encoder can be used as follows:\n```python\nfrom mashumaro.codecs.msgpack import MessagePackDecoder, MessagePackEncoder\n\ndecoder = MessagePackDecoder(, ...)\ndecoder.decode(...)\n\nencoder = MessagePackEncoder(, ...)\nencoder.encode(...)\n```\n\nConvenient functions can be used as follows:\n```python\nfrom mashumaro.codecs.msgpack import msgpack_decode, msgpack_encode\n\nmsgpack_decode(..., )\nmsgpack_encode(..., )\n```\n\nConvenient function aliases are recommended to be used as follows:\n```python\nimport mashumaro.codecs.msgpack as msgpack_codec\n\nmsgpack_codec.decode(...)\nmsgpack_codec.encode(..., )\n```\n\nMixin can be used as follows:\n```python\nfrom mashumaro.mixins.msgpack import DataClassMessagePackMixin\n\n@dataclass\nclass MyModel(DataClassMessagePackMixin):\n ...\n\nMyModel.from_msgpack(...)\nMyModel(...).to_msgpack()\n```\n\nCustomization\n-------------------------------------------------------------------------------\n\nCustomization options of `mashumaro` are extensive and will most likely cover your needs.\nWhen it comes to non-standard data types and non-standard serialization support, you can do the following:\n* Turn an existing regular or generic class into a serializable one\nby inheriting the [`SerializableType`](#serializabletype-interface) class\n* Write different serialization strategies for an existing regular or generic type that is not under your control\nusing [`SerializationStrategy`](#serializationstrategy) class\n* Define serialization / deserialization methods:\n * for a specific dataclass field by using [field options](#field-options)\n * for a specific data type used in the dataclass by using [`Config`](#config-options) class\n* Alter input and output data with serialization / deserialization [hooks](#serialization-hooks)\n* Separate serialization scheme from a dataclass in a reusable manner using [dialects](#dialects)\n* Choose from predefined serialization engines for the specific data types, e.g. `datetime` and `NamedTuple`\n\n### SerializableType interface\n\nIf you have a custom class or hierarchy of classes whose instances you want\nto serialize with `mashumaro`, the first option is to implement\n`SerializableType` interface.\n\n#### User-defined types\n\nLet's look at this not very practicable example:\n\n```python\nfrom dataclasses import dataclass\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.types import SerializableType\n\nclass Airport(SerializableType):\n def __init__(self, code, city):\n self.code, self.city = code, city\n\n def _serialize(self):\n return [self.code, self.city]\n\n @classmethod\n def _deserialize(cls, value):\n return cls(*value)\n\n def __eq__(self, other):\n return self.code, self.city == other.code, other.city\n\n@dataclass\nclass Flight(DataClassDictMixin):\n origin: Airport\n destination: Airport\n\nJFK = Airport(\"JFK\", \"New York City\")\nLAX = Airport(\"LAX\", \"Los Angeles\")\n\ninput_data = {\n \"origin\": [\"JFK\", \"New York City\"],\n \"destination\": [\"LAX\", \"Los Angeles\"]\n}\nmy_flight = Flight.from_dict(input_data)\nassert my_flight == Flight(JFK, LAX)\nassert my_flight.to_dict() == input_data\n```\n\nYou can see how `Airport` instances are seamlessly created from lists of two\nstrings and serialized into them.\n\nBy default `_deserialize` method will get raw input data without any\ntransformations before. This should be enough in many cases, especially when\nyou need to perform non-standard transformations yourself, but let's extend\nour example:\n\n```python\nclass Itinerary(SerializableType):\n def __init__(self, flights):\n self.flights = flights\n\n def _serialize(self):\n return self.flights\n\n @classmethod\n def _deserialize(cls, flights):\n return cls(flights)\n\n@dataclass\nclass TravelPlan(DataClassDictMixin):\n budget: float\n itinerary: Itinerary\n\ninput_data = {\n \"budget\": 10_000,\n \"itinerary\": [\n {\n \"origin\": [\"JFK\", \"New York City\"],\n \"destination\": [\"LAX\", \"Los Angeles\"]\n },\n {\n \"origin\": [\"LAX\", \"Los Angeles\"],\n \"destination\": [\"SFO\", \"San Fransisco\"]\n }\n ]\n}\n```\n\nIf we pass the flight list as is into `Itinerary._deserialize`, our itinerary\nwill have something that we may not expect — `list[dict]` instead of\n`list[Flight]`. The solution is quite simple. Instead of calling\n`Flight._deserialize` yourself, just use annotations:\n\n```python\nclass Itinerary(SerializableType, use_annotations=True):\n def __init__(self, flights):\n self.flights = flights\n\n def _serialize(self) -> list[Flight]:\n return self.flights\n\n @classmethod\n def _deserialize(cls, flights: list[Flight]):\n return cls(flights)\n\nmy_plan = TravelPlan.from_dict(input_data)\nassert isinstance(my_plan.itinerary.flights[0], Flight)\nassert isinstance(my_plan.itinerary.flights[1], Flight)\nassert my_plan.to_dict() == input_data\n```\n\nHere we add annotations to the only argument of `_deserialize` method and\nto the return value of `_serialize` method as well. The latter is needed for\ncorrect serialization.\n\n> [!IMPORTANT]\\\n> The importance of explicit passing `use_annotations=True` when defining a\n> class is that otherwise implicit using annotations might break compatibility\n> with old code that wasn't aware of this feature. It will be enabled by\n> default in the future major release.\n\n#### User-defined generic types\n\nThe great thing to note about using annotations in `SerializableType` is that\nthey work seamlessly with [generic](https://docs.python.org/3/library/typing.html#user-defined-generic-types)\nand [variadic generic](https://peps.python.org/pep-0646/) types.\nLet's see how this can be useful:\n\n```python\nfrom datetime import date\nfrom typing import TypeVar\nfrom dataclasses import dataclass\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.types import SerializableType\n\nKT = TypeVar(\"KT\")\nVT = TypeVar(\"VT\")\n\nclass DictWrapper(dict[KT, VT], SerializableType, use_annotations=True):\n def _serialize(self) -> dict[KT, VT]:\n return dict(self)\n\n @classmethod\n def _deserialize(cls, value: dict[KT, VT]) -> 'DictWrapper[KT, VT]':\n return cls(value)\n\n@dataclass\nclass DataClass(DataClassDictMixin):\n x: DictWrapper[date, str]\n y: DictWrapper[str, date]\n\ninput_data = {\n \"x\": {\"2022-12-07\": \"2022-12-07\"},\n \"y\": {\"2022-12-07\": \"2022-12-07\"}\n}\nobj = DataClass.from_dict(input_data)\nassert obj == DataClass(\n x=DictWrapper({date(2022, 12, 7): \"2022-12-07\"}),\n y=DictWrapper({\"2022-12-07\": date(2022, 12, 7)})\n)\nassert obj.to_dict() == input_data\n```\n\nYou can see that formatted date is deserialized to `date` object before passing\nto `DictWrapper._deserialize` in a key or value according to the generic\nparameters.\n\nIf you have generic dataclass types, you can use `SerializableType` for them as well, but it's not necessary since\nthey're [supported](#generic-dataclasses) out of the box.\n\n### SerializationStrategy\n\nIf you want to add support for a custom third-party type that is not under your control,\nyou can write serialization and deserialization logic inside `SerializationStrategy` class,\nwhich will be reusable and so well suited in case that third-party type is widely used.\n`SerializationStrategy` is also good if you want to create strategies that are slightly different from each other,\nbecause you can add the strategy differentiator in the `__init__` method.\n\n#### Third-party types\n\nTo demonstrate how `SerializationStrategy` works let's write a simple strategy for datetime serialization\nin different formats. In this example we will use the same strategy class for two dataclass fields,\nbut a string representing the date and time will be different.\n\n```python\nfrom dataclasses import dataclass, field\nfrom datetime import datetime\nfrom mashumaro import DataClassDictMixin, field_options\nfrom mashumaro.types import SerializationStrategy\n\nclass FormattedDateTime(SerializationStrategy):\n def __init__(self, fmt):\n self.fmt = fmt\n\n def serialize(self, value: datetime) -> str:\n return value.strftime(self.fmt)\n\n def deserialize(self, value: str) -> datetime:\n return datetime.strptime(value, self.fmt)\n\n@dataclass\nclass DateTimeFormats(DataClassDictMixin):\n short: datetime = field(\n metadata=field_options(\n serialization_strategy=FormattedDateTime(\"%d%m%Y%H%M%S\")\n )\n )\n verbose: datetime = field(\n metadata=field_options(\n serialization_strategy=FormattedDateTime(\"%A %B %d, %Y, %H:%M:%S\")\n )\n )\n\nformats = DateTimeFormats(\n short=datetime(2019, 1, 1, 12),\n verbose=datetime(2019, 1, 1, 12),\n)\ndictionary = formats.to_dict()\n# {'short': '01012019120000', 'verbose': 'Tuesday January 01, 2019, 12:00:00'}\nassert DateTimeFormats.from_dict(dictionary) == formats\n```\n\nSimilarly to `SerializableType`, `SerializationStrategy` could also take advantage of annotations:\n\n```python\nfrom dataclasses import dataclass\nfrom datetime import datetime\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.types import SerializationStrategy\n\nclass TsSerializationStrategy(SerializationStrategy, use_annotations=True):\n def serialize(self, value: datetime) -> float:\n return value.timestamp()\n\n def deserialize(self, value: float) -> datetime:\n # value will be converted to float before being passed to this method\n return datetime.fromtimestamp(value)\n\n@dataclass\nclass Example(DataClassDictMixin):\n dt: datetime\n\n class Config:\n serialization_strategy = {\n datetime: TsSerializationStrategy(),\n }\n\nexample = Example.from_dict({\"dt\": \"1672531200\"})\nprint(example)\n# Example(dt=datetime.datetime(2023, 1, 1, 3, 0))\nprint(example.to_dict())\n# {'dt': 1672531200.0}\n```\n\nHere the passed string value `\"1672531200\"` will be converted to `float` before being passed to `deserialize` method\nthanks to the `float` annotation.\n\n> [!IMPORTANT]\\\n> As well as for `SerializableType`, the value of `use_annotatons` will be\n> `True` by default in the future major release.\n\n#### Third-party generic types\n\nTo create a generic version of a serialization strategy you need to follow these steps:\n* inherit [`Generic[...]`](https://docs.python.org/3/library/typing.html#typing.Generic) type\nwith the number of parameters matching the number of parameters\nof the target generic type\n* Write generic annotations for `serialize` method's return type and for `deserialize` method's argument type\n* Use the origin type of the target generic type in the [`serialization_strategy`](#serialization_strategy-config-option) config section\n([`typing.get_origin`](https://docs.python.org/3/library/typing.html#typing.get_origin) might be helpful)\n\nThere is no need to add `use_annotations=True` here because it's enabled implicitly\nfor generic serialization strategies.\n\nFor example, there is a third-party [multidict](https://pypi.org/project/multidict/) package that has a generic `MultiDict` type.\nA generic serialization strategy for it might look like this:\n\n```python\nfrom dataclasses import dataclass\nfrom datetime import date\nfrom pprint import pprint\nfrom typing import Generic, List, Tuple, TypeVar\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.types import SerializationStrategy\n\nfrom multidict import MultiDict\n\nT = TypeVar(\"T\")\n\nclass MultiDictSerializationStrategy(SerializationStrategy, Generic[T]):\n def serialize(self, value: MultiDict[T]) -> List[Tuple[str, T]]:\n return [(k, v) for k, v in value.items()]\n\n def deserialize(self, value: List[Tuple[str, T]]) -> MultiDict[T]:\n return MultiDict(value)\n\n\n@dataclass\nclass Example(DataClassDictMixin):\n floats: MultiDict[float]\n date_lists: MultiDict[List[date]]\n\n class Config:\n serialization_strategy = {\n MultiDict: MultiDictSerializationStrategy()\n }\n\nexample = Example(\n floats=MultiDict([(\"x\", 1.1), (\"x\", 2.2)]),\n date_lists=MultiDict(\n [(\"x\", [date(2023, 1, 1), date(2023, 1, 2)]),\n (\"x\", [date(2023, 2, 1), date(2023, 2, 2)])]\n ),\n)\npprint(example.to_dict())\n# {'date_lists': [['x', ['2023-01-01', '2023-01-02']],\n# ['x', ['2023-02-01', '2023-02-02']]],\n# 'floats': [['x', 1.1], ['x', 2.2]]}\nassert Example.from_dict(example.to_dict()) == example\n```\n\n### Field options\n\nIn some cases creating a new class just for one little thing could be\nexcessive. Moreover, you may need to deal with third party classes that you are\nnot allowed to change. You can use [`dataclasses.field`](https://docs.python.org/3/library/dataclasses.html#dataclasses.field) function to\nconfigure some serialization aspects through its `metadata` parameter. Next\nsection describes all supported options to use in `metadata` mapping.\n\nIf you don't want to remember the names of the options you can use\n`field_options` helper function:\n\n```python\nfrom dataclasses import dataclass, field\nfrom mashumaro import field_options\n\n@dataclass\nclass A:\n x: int = field(metadata=field_options(...))\n```\n\n#### `serialize` option\n\nThis option allows you to change the serialization method. When using\nthis option, the serialization behaviour depends on what type of value the\noption has. It could be either `Callable[[Any], Any]` or `str`.\n\nA value of type `Callable[[Any], Any]` is a generic way to specify any callable\nobject like a function, a class method, a class instance method, an instance\nof a callable class or even a lambda function to be called for serialization.\n\nA value of type `str` sets a specific engine for serialization. Keep in mind\nthat all possible engines depend on the data type that this option is used\nwith. At this moment there are next serialization engines to choose from:\n\n| Applicable data types | Supported engines | Description |\n|:---------------------------|:---------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `NamedTuple`, `namedtuple` | `as_list`, `as_dict` | How to pack named tuples. By default `as_list` engine is used that means your named tuple class instance will be packed into a list of its values. You can pack it into a dictionary using `as_dict` engine. |\n| `Any` | `omit` | Skip the field during serialization |\n\n> [!TIP]\\\n> You can pass a field value as is without changes on serialization using\n[`pass_through`](#passing-field-values-as-is).\n\nExample:\n\n```python\nfrom datetime import datetime\nfrom dataclasses import dataclass, field\nfrom typing import NamedTuple\nfrom mashumaro import DataClassDictMixin\n\nclass MyNamedTuple(NamedTuple):\n x: int\n y: float\n\n@dataclass\nclass A(DataClassDictMixin):\n dt: datetime = field(\n metadata={\n \"serialize\": lambda v: v.strftime('%Y-%m-%d %H:%M:%S')\n }\n )\n t: MyNamedTuple = field(metadata={\"serialize\": \"as_dict\"})\n```\n\n#### `deserialize` option\n\nThis option allows you to change the deserialization method. When using\nthis option, the deserialization behaviour depends on what type of value the\noption has. It could be either `Callable[[Any], Any]` or `str`.\n\nA value of type `Callable[[Any], Any]` is a generic way to specify any callable\nobject like a function, a class method, a class instance method, an instance\nof a callable class or even a lambda function to be called for deserialization.\n\nA value of type `str` sets a specific engine for deserialization. Keep in mind\nthat all possible engines depend on the data type that this option is used\nwith. At this moment there are next deserialization engines to choose from:\n\n| Applicable data types | Supported engines | Description |\n|:---------------------------|:------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `datetime`, `date`, `time` | [`ciso8601`](https://github.com/closeio/ciso8601#supported-subset-of-iso-8601), [`pendulum`](https://github.com/sdispater/pendulum) | How to parse datetime string. By default native [`fromisoformat`](https://docs.python.org/3/library/datetime.html#datetime.datetime.fromisoformat) of corresponding class will be used for `datetime`, `date` and `time` fields. It's the fastest way in most cases, but you can choose an alternative. |\n| `NamedTuple`, `namedtuple` | `as_list`, `as_dict` | How to unpack named tuples. By default `as_list` engine is used that means your named tuple class instance will be created from a list of its values. You can unpack it from a dictionary using `as_dict` engine. |\n\n> [!TIP]\\\n> You can pass a field value as is without changes on deserialization using\n[`pass_through`](#passing-field-values-as-is).\n\nExample:\n\n```python\nfrom datetime import datetime\nfrom dataclasses import dataclass, field\nfrom typing import List, NamedTuple\nfrom mashumaro import DataClassDictMixin\nimport ciso8601\nimport dateutil\n\nclass MyNamedTuple(NamedTuple):\n x: int\n y: float\n\n@dataclass\nclass A(DataClassDictMixin):\n x: datetime = field(\n metadata={\"deserialize\": \"pendulum\"}\n )\n\nclass B(DataClassDictMixin):\n x: datetime = field(\n metadata={\"deserialize\": ciso8601.parse_datetime_as_naive}\n )\n\n@dataclass\nclass C(DataClassDictMixin):\n dt: List[datetime] = field(\n metadata={\n \"deserialize\": lambda l: list(map(dateutil.parser.isoparse, l))\n }\n )\n\n@dataclass\nclass D(DataClassDictMixin):\n x: MyNamedTuple = field(metadata={\"deserialize\": \"as_dict\"})\n```\n\n#### `serialization_strategy` option\n\nThis option is useful when you want to change the serialization logic\nfor a dataclass field depending on some defined parameters using a reusable\nserialization scheme. You can find an example in the\n[`SerializationStrategy`](#serializationstrategy) chapter.\n\n> [!TIP]\\\n> You can pass a field value as is without changes on\n> serialization / deserialization using\n[`pass_through`](#passing-field-values-as-is).\n\n#### `alias` option\n\nThis option can be used to assign [field aliases](#field-aliases):\n\n\n```python\nfrom dataclasses import dataclass, field\nfrom mashumaro import DataClassDictMixin, field_options\n\n@dataclass\nclass DataClass(DataClassDictMixin):\n a: int = field(metadata=field_options(alias=\"FieldA\"))\n b: int = field(metadata=field_options(alias=\"#invalid\"))\n\nx = DataClass.from_dict({\"FieldA\": 1, \"#invalid\": 2}) # DataClass(a=1, b=2)\n```\n\n### Config options\n\nIf inheritance is not an empty word for you, you'll fall in love with the\n`Config` class. You can register `serialize` and `deserialize` methods, define\ncode generation options and other things just in one place. Or in some\nclasses in different ways if you need flexibility. Inheritance is always on the\nfirst place.\n\nThere is a base class `BaseConfig` that you can inherit for the sake of\nconvenience, but it's not mandatory.\n\nIn the following example you can see how\nthe `debug` flag is changed from class to class: `ModelA` will have debug mode enabled but\n`ModelB` will not.\n\n```python\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.config import BaseConfig\n\nclass BaseModel(DataClassDictMixin):\n class Config(BaseConfig):\n debug = True\n\nclass ModelA(BaseModel):\n a: int\n\nclass ModelB(BaseModel):\n b: int\n\n class Config(BaseConfig):\n debug = False\n```\n\nNext section describes all supported options to use in the config.\n\n#### `debug` config option\n\nIf you enable the `debug` option the generated code for your data class\nwill be printed.\n\n#### `code_generation_options` config option\n\nSome users may need functionality that wouldn't exist without extra cost such\nas valuable cpu time to execute additional instructions. Since not everyone\nneeds such instructions, they can be enabled by a constant in the list,\nso the fastest basic behavior of the library will always remain by default.\nThe following table provides a brief overview of all the available constants\ndescribed below.\n\n| Constant | Description |\n|:----------------------------------------------------------------|:---------------------------------------------------------------------|\n| [`TO_DICT_ADD_OMIT_NONE_FLAG`](#add-omit_none-keyword-argument) | Adds `omit_none` keyword-only argument to `to_*` methods. |\n| [`TO_DICT_ADD_BY_ALIAS_FLAG`](#add-by_alias-keyword-argument) | Adds `by_alias` keyword-only argument to `to_*` methods. |\n| [`ADD_DIALECT_SUPPORT`](#add-dialect-keyword-argument) | Adds `dialect` keyword-only argument to `from_*` and `to_*` methods. |\n| [`ADD_SERIALIZATION_CONTEXT`](#add-context-keyword-argument) | Adds `context` keyword-only argument to `to_*` methods. |\n\n#### `serialization_strategy` config option\n\nYou can register custom [`SerializationStrategy`](#serializationstrategy), `serialize` and `deserialize`\nmethods for specific types just in one place. It could be configured using\na dictionary with types as keys. The value could be either a\n[`SerializationStrategy`](#serializationstrategy) instance or a dictionary with `serialize` and\n`deserialize` values with the same meaning as in the\n[field options](#field-options).\n\n```python\nfrom dataclasses import dataclass\nfrom datetime import datetime, date\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.config import BaseConfig\nfrom mashumaro.types import SerializationStrategy\n\nclass FormattedDateTime(SerializationStrategy):\n def __init__(self, fmt):\n self.fmt = fmt\n\n def serialize(self, value: datetime) -> str:\n return value.strftime(self.fmt)\n\n def deserialize(self, value: str) -> datetime:\n return datetime.strptime(value, self.fmt)\n\n@dataclass\nclass DataClass(DataClassDictMixin):\n\n x: datetime\n y: date\n\n class Config(BaseConfig):\n serialization_strategy = {\n datetime: FormattedDateTime(\"%Y\"),\n date: {\n # you can use specific str values for datetime here as well\n \"deserialize\": \"pendulum\",\n \"serialize\": date.isoformat,\n },\n }\n\ninstance = DataClass.from_dict({\"x\": \"2021\", \"y\": \"2021\"})\n# DataClass(x=datetime.datetime(2021, 1, 1, 0, 0), y=Date(2021, 1, 1))\ndictionary = instance.to_dict()\n# {'x': '2021', 'y': '2021-01-01'}\n```\n\nNote that you can register different methods for multiple logical types which\nare based on the same type using `NewType` and `Annotated`,\nsee [Extending existing types](#extending-existing-types) for details.\n\nIt's also possible to define a generic (de)serialization method for a generic\ntype by registering a method for its\n[origin](https://docs.python.org/3/library/typing.html#typing.get_origin) type.\nAlthough this technique is widely used when working with [third-party generic\ntypes](#third-party-generic-types) using generic strategies, it can also be\napplied in simple scenarios:\n\n```python\nfrom dataclasses import dataclass\nfrom mashumaro import DataClassDictMixin\n\n@dataclass\nclass C(DataClassDictMixin):\n ints: list[int]\n floats: list[float]\n\n class Config:\n serialization_strategy = {\n list: { # origin type for list[int] and list[float] is list\n \"serialize\": lambda x: list(map(str, x)),\n }\n }\n\nassert C([1], [2.2]).to_dict() == {'ints': ['1'], 'floats': ['2.2']}\n```\n\n#### `aliases` config option\n\nSometimes it's better to write the [field aliases](#field-aliases) in one place. You can mix\naliases here with [aliases in the field options](#alias-option), but the last ones will always\ntake precedence.\n\n```python\nfrom dataclasses import dataclass\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.config import BaseConfig\n\n@dataclass\nclass DataClass(DataClassDictMixin):\n a: int\n b: int\n\n class Config(BaseConfig):\n aliases = {\n \"a\": \"FieldA\",\n \"b\": \"FieldB\",\n }\n\nDataClass.from_dict({\"FieldA\": 1, \"FieldB\": 2}) # DataClass(a=1, b=2)\n```\n\n#### `serialize_by_alias` config option\n\nAll the fields with [aliases](#field-aliases) will be serialized by them by\ndefault when this option is enabled. You can mix this config option with\n[`by_alias`](#add-by_alias-keyword-argument) keyword argument.\n\n```python\nfrom dataclasses import dataclass, field\nfrom mashumaro import DataClassDictMixin, field_options\nfrom mashumaro.config import BaseConfig\n\n@dataclass\nclass DataClass(DataClassDictMixin):\n field_a: int = field(metadata=field_options(alias=\"FieldA\"))\n\n class Config(BaseConfig):\n serialize_by_alias = True\n\nDataClass(field_a=1).to_dict() # {'FieldA': 1}\n```\n\n#### `allow_deserialization_not_by_alias` config option\n\nWhen using aliases, the deserializer defaults to requiring the keys to match\nwhat is defined as the alias.\nIf the flexibility to deserialize aliased and unaliased keys is required then\nthe config option `allow_deserialization_not_by_alias ` can be set to\nenable the feature.\n\n```python\nfrom dataclasses import dataclass, field\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.config import BaseConfig\n\n\n@dataclass\nclass AliasedDataClass(DataClassDictMixin):\n foo: int = field(metadata={\"alias\": \"alias_foo\"})\n bar: int = field(metadata={\"alias\": \"alias_bar\"})\n\n class Config(BaseConfig):\n allow_deserialization_not_by_alias = True\n\n\nalias_dict = {\"alias_foo\": 1, \"alias_bar\": 2}\nt1 = AliasedDataClass.from_dict(alias_dict)\n\nno_alias_dict = {\"foo\": 1, \"bar\": 2}\n# This would raise `mashumaro.exceptions.MissingField`\n# if allow_deserialization_not_by_alias was False\nt2 = AliasedDataClass.from_dict(no_alias_dict)\nassert t1 == t2\n```\n\n#### `omit_none` config option\n\nAll the fields with `None` values will be skipped during serialization by\ndefault when this option is enabled. You can mix this config option with\n[`omit_none`](#add-omit_none-keyword-argument) keyword argument.\n\n```python\nfrom dataclasses import dataclass\nfrom typing import Optional\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.config import BaseConfig\n\n@dataclass\nclass DataClass(DataClassDictMixin):\n x: Optional[int] = 42\n\n class Config(BaseConfig):\n omit_none = True\n\nDataClass(x=None).to_dict() # {}\n```\n\n#### `omit_default` config option\n\nWhen this option enabled, all the fields that have values equal to the defaults\nor the default_factory results will be skipped during serialization.\n\n```python\nfrom dataclasses import dataclass, field\nfrom typing import List, Optional, Tuple\nfrom mashumaro import DataClassDictMixin, field_options\nfrom mashumaro.config import BaseConfig\n\n@dataclass\nclass Foo:\n foo: str\n\n@dataclass\nclass DataClass(DataClassDictMixin):\n a: int = 42\n b: Tuple[int, ...] = field(default=(1, 2, 3))\n c: List[Foo] = field(default_factory=lambda: [Foo(\"foo\")])\n d: Optional[str] = None\n\n class Config(BaseConfig):\n omit_default = True\n\nDataClass(a=42, b=(1, 2, 3), c=[Foo(\"foo\")]).to_dict() # {}\n```\n\n#### `namedtuple_as_dict` config option\n\nDataclasses are a great way to declare and use data models. But it's not the only way.\nPython has a typed version of [namedtuple](https://docs.python.org/3/library/collections.html#collections.namedtuple)\ncalled [NamedTuple](https://docs.python.org/3/library/typing.html#typing.NamedTuple)\nwhich looks similar to dataclasses:\n\n```python\nfrom typing import NamedTuple\n\nclass Point(NamedTuple):\n x: int\n y: int\n```\n\nthe same with a dataclass will look like this:\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass Point:\n x: int\n y: int\n```\n\nAt first glance, you can use both options. But imagine that you need to create\na bunch of instances of the `Point` class. Due to how dataclasses work you will\nhave more memory consumption compared to named tuples. In such a case it could\nbe more appropriate to use named tuples.\n\nBy default, all named tuples are packed into lists. But with `namedtuple_as_dict`\noption you have a drop-in replacement for dataclasses:\n\n```python\nfrom dataclasses import dataclass\nfrom typing import List, NamedTuple\nfrom mashumaro import DataClassDictMixin\n\nclass Point(NamedTuple):\n x: int\n y: int\n\n@dataclass\nclass DataClass(DataClassDictMixin):\n points: List[Point]\n\n class Config:\n namedtuple_as_dict = True\n\nobj = DataClass.from_dict({\"points\": [{\"x\": 0, \"y\": 0}, {\"x\": 1, \"y\": 1}]})\nprint(obj.to_dict()) # {\"points\": [{\"x\": 0, \"y\": 0}, {\"x\": 1, \"y\": 1}]}\n```\n\nIf you want to serialize only certain named tuple fields as dictionaries, you\ncan use the corresponding [serialization](#serialize-option) and\n[deserialization](#deserialize-option) engines.\n\n#### `allow_postponed_evaluation` config option\n\n[PEP 563](https://www.python.org/dev/peps/pep-0563/) solved the problem of forward references by postponing the evaluation\nof annotations, so you can write the following code:\n\n```python\nfrom __future__ import annotations\nfrom dataclasses import dataclass\nfrom mashumaro import DataClassDictMixin\n\n@dataclass\nclass A(DataClassDictMixin):\n x: B\n\n@dataclass\nclass B(DataClassDictMixin):\n y: int\n\nobj = A.from_dict({'x': {'y': 1}})\n```\n\nYou don't need to write anything special here, forward references work out of\nthe box. If a field of a dataclass has a forward reference in the type\nannotations, building of `from_*` and `to_*` methods of this dataclass\nwill be postponed until they are called once. However, if for some reason you\ndon't want the evaluation to be possibly postponed, you can disable it using\n`allow_postponed_evaluation` option:\n\n```python\nfrom __future__ import annotations\nfrom dataclasses import dataclass\nfrom mashumaro import DataClassDictMixin\n\n@dataclass\nclass A(DataClassDictMixin):\n x: B\n\n class Config:\n allow_postponed_evaluation = False\n\n# UnresolvedTypeReferenceError: Class A has unresolved type reference B\n# in some of its fields\n\n@dataclass\nclass B(DataClassDictMixin):\n y: int\n```\n\nIn this case you will get `UnresolvedTypeReferenceError` regardless of whether\nclass B is declared below or not.\n\n#### `dialect` config option\n\nThis option is described [below](#changing-the-default-dialect) in the\nDialects section.\n\n#### `orjson_options` config option\n\nThis option changes default options for `orjson.dumps` encoder which is\nused in [`DataClassORJSONMixin`](#dataclassorjsonmixin). For example, you can\ntell orjson to handle non-`str` `dict` keys as the built-in `json.dumps`\nencoder does. See [orjson documentation](https://github.com/ijl/orjson#option)\nto read more about these options.\n\n```python\nimport orjson\nfrom dataclasses import dataclass\nfrom typing import Dict\nfrom mashumaro.config import BaseConfig\nfrom mashumaro.mixins.orjson import DataClassORJSONMixin\n\n@dataclass\nclass MyClass(DataClassORJSONMixin):\n x: Dict[int, int]\n\n class Config(BaseConfig):\n orjson_options = orjson.OPT_NON_STR_KEYS\n\nassert MyClass({1: 2}).to_json() == {\"1\": 2}\n```\n\n#### `discriminator` config option\n\nThis option is described in the\n[Class level discriminator](#class-level-discriminator) section.\n\n#### `lazy_compilation` config option\n\nBy using this option, the compilation of the `from_*` and `to_*` methods will\nbe deferred until they are called first time. This will reduce the import time\nand, in certain instances, may enhance the speed of deserialization\nby leveraging the data that is accessible after the class has been created.\n\n> [!CAUTION]\\\n> If you need to save a reference to `from_*` or `to_*` method, you should\n> do it after the method is compiled. To be safe, you can always use lambda\n> function:\n> ```python\n> from_dict = lambda x: MyModel.from_dict(x)\n> to_dict = lambda x: x.to_dict()\n> ```\n\n#### `sort_keys` config option\n\nWhen set, the keys on serialized dataclasses will be sorted in alphabetical order.\n\nUnlike the `sort_keys` option in the standard library's `json.dumps` function, this option acts at class creation time and has no effect on the performance of serialization.\n\n```python\nfrom dataclasses import dataclass\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.config import BaseConfig\n\n@dataclass\nclass SortedDataClass(DataClassDictMixin):\n foo: int\n bar: int\n\n class Config(BaseConfig):\n sort_keys = True\n\nt = SortedDataClass(1, 2)\nassert t.to_dict() == {\"bar\": 2, \"foo\": 1}\n```\n\n#### `forbid_extra_keys` config option\n\nWhen set, the deserialization of dataclasses will fail if the input dictionary contains keys that are not present in the dataclass.\n\n```python\nfrom dataclasses import dataclass\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.config import BaseConfig\n\n@dataclass\nclass DataClass(DataClassDictMixin):\n a: int\n\n class Config(BaseConfig):\n forbid_extra_keys = True\n\nDataClass.from_dict({\"a\": 1, \"b\": 2}) # ExtraKeysError: Extra keys: {'b'}\n```\n\nIt plays well with `aliases` and `allow_deserialization_not_by_alias` options.\n\n### Passing field values as is\n\nIn some cases it's needed to pass a field value as is without any changes\nduring serialization / deserialization. There is a predefined\n[`pass_through`](https://github.com/Fatal1ty/mashumaro/blob/master/mashumaro/helper.py#L58)\nobject that can be used as `serialization_strategy` or\n`serialize` / `deserialize` options:\n\n```python\nfrom dataclasses import dataclass, field\nfrom mashumaro import DataClassDictMixin, pass_through\n\nclass MyClass:\n def __init__(self, some_value):\n self.some_value = some_value\n\n@dataclass\nclass A1(DataClassDictMixin):\n x: MyClass = field(\n metadata={\n \"serialize\": pass_through,\n \"deserialize\": pass_through,\n }\n )\n\n@dataclass\nclass A2(DataClassDictMixin):\n x: MyClass = field(\n metadata={\n \"serialization_strategy\": pass_through,\n }\n )\n\n@dataclass\nclass A3(DataClassDictMixin):\n x: MyClass\n\n class Config:\n serialization_strategy = {\n MyClass: pass_through,\n }\n\n@dataclass\nclass A4(DataClassDictMixin):\n x: MyClass\n\n class Config:\n serialization_strategy = {\n MyClass: {\n \"serialize\": pass_through,\n \"deserialize\": pass_through,\n }\n }\n\nmy_class_instance = MyClass(42)\n\nassert A1.from_dict({'x': my_class_instance}).x == my_class_instance\nassert A2.from_dict({'x': my_class_instance}).x == my_class_instance\nassert A3.from_dict({'x': my_class_instance}).x == my_class_instance\nassert A4.from_dict({'x': my_class_instance}).x == my_class_instance\n\na1_dict = A1(my_class_instance).to_dict()\na2_dict = A2(my_class_instance).to_dict()\na3_dict = A3(my_class_instance).to_dict()\na4_dict = A4(my_class_instance).to_dict()\n\nassert a1_dict == a2_dict == a3_dict == a4_dict == {\"x\": my_class_instance}\n```\n\n### Extending existing types\n\nThere are situations where you might want some values of the same type to be\ntreated as their own type. You can create new logical types with\n[`NewType`](https://docs.python.org/3/library/typing.html#newtype),\n[`Annotated`](https://docs.python.org/3/library/typing.html#typing.Annotated)\nor [`TypeAliasType`](https://docs.python.org/3/library/typing.html#typing.TypeAliasType)\nand register serialization strategies for them:\n\n```python\nfrom typing import Mapping, NewType, Annotated\nfrom dataclasses import dataclass\nfrom mashumaro import DataClassDictMixin\n\nSessionID = NewType(\"SessionID\", str)\nAccountID = Annotated[str, \"AccountID\"]\n\ntype DeviceID = str\n\n@dataclass\nclass Context(DataClassDictMixin):\n account_sessions: Mapping[AccountID, SessionID]\n account_devices: list[DeviceID]\n\n class Config:\n serialization_strategy = {\n AccountID: {\n \"deserialize\": lambda x: ...,\n \"serialize\": lambda x: ...,\n },\n SessionID: {\n \"deserialize\": lambda x: ...,\n \"serialize\": lambda x: ...,\n },\n DeviceID: {\n \"deserialize\": lambda x: ...,\n \"serialize\": lambda x: ...,\n }\n }\n```\n\nAlthough using `NewType` is usually the most reliable way to avoid logical\nerrors, you have to pay for it with notable overhead. If you are creating\ndataclass instances manually, then you know that type checkers will\nenforce you to enclose a value in your `\"NewType\"` callable, which leads\nto performance degradation:\n\n```python\npython -m timeit -s \"from typing import NewType; MyInt = NewType('MyInt', int)\" \"MyInt(42)\"\n10000000 loops, best of 5: 31.1 nsec per loop\n\npython -m timeit -s \"from typing import NewType; MyInt = NewType('MyInt', int)\" \"42\"\n50000000 loops, best of 5: 4.35 nsec per loop\n```\n\nHowever, when you create dataclass instances using the `from_*` method provided\nby one of the mixins or using one of the decoders, there will be no performance\ndegradation, because the value won't be enclosed in the callable in the\ngenerated code. Therefore, if performance is more important to you than\ncatching logical errors by type checkers, and you are actively creating or\nchanging dataclasses manually, then you should take a closer look at using\n`Annotated`.\n\n### Field aliases\n\nIn some cases it's better to have different names for a field in your dataclass\nand in its serialized view. For example, a third-party legacy API you are\nworking with might operate with camel case style, but you stick to snake case\nstyle in your code base. Or you want to load data with keys that are\ninvalid identifiers in Python. Aliases can solve this problem.\n\nThere are multiple ways to assign an alias:\n* Using `Alias(...)` annotation in a field type\n* Using `alias` parameter in field metadata\n* Using `aliases` parameter in a dataclass config\n\nBy default, aliases only affect deserialization, but it can be extended to\nserialization as well. If you want to serialize all the fields by aliases you\nhave two options to do so:\n* [`serialize_by_alias` config option](#serialize_by_alias-config-option)\n* [`serialize_by_alias` dialect option](#serialize_by_alias-dialect-option)\n* [`by_alias` keyword argument in `to_*` methods](#add-by_alias-keyword-argument)\n\nHere is an example with `Alias` annotation in a field type:\n\n```python\nfrom dataclasses import dataclass\nfrom typing import Annotated\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.types import Alias\n\n@dataclass\nclass DataClass(DataClassDictMixin):\n foo_bar: Annotated[int, Alias(\"fooBar\")]\n\nobj = DataClass.from_dict({\"fooBar\": 42}) # DataClass(foo_bar=42)\nobj.to_dict() # {\"foo_bar\": 42} # no aliases on serialization by default\n```\n\nThe same with field metadata:\n\n```python\nfrom dataclasses import dataclass, field\nfrom mashumaro import field_options\n\n@dataclass\nclass DataClass:\n foo_bar: str = field(metadata=field_options(alias=\"fooBar\"))\n```\n\nAnd with a dataclass config:\n\n```python\nfrom dataclasses import dataclass\nfrom mashumaro.config import BaseConfig\n\n@dataclass\nclass DataClass:\n foo_bar: str\n\n class Config(BaseConfig):\n aliases = {\"foo_bar\": \"fooBar\"}\n```\n\n> [!TIP]\\\n> If you want to deserialize all the fields by its names along with aliases,\n> there is [a config option](#allow_deserialization_not_by_alias-config-option)\n> for that.\n\n### Dialects\n\nSometimes it's needed to have different serialization and deserialization\nmethods depending on the data source where entities of the dataclass are\nstored or on the API to which the entities are being sent or received from.\nThere is a special `Dialect` type that may contain all the differences from the\ndefault serialization and deserialization methods. You can create different\ndialects and use each of them for the same dataclass depending on\nthe situation.\n\nSuppose we have the following dataclass with a field of type `date`:\n```python\n@dataclass\nclass Entity(DataClassDictMixin):\n dt: date\n```\n\nBy default, a field of `date` type serializes to a string in ISO 8601 format,\nso the serialized entity will look like `{'dt': '2021-12-31'}`. But what if we\nhave, for example, two sensitive legacy Ethiopian and Japanese APIs that use\ntwo different formats for dates — `dd/mm/yyyy` and `yyyy年mm月dd日`? Instead of\ncreating two similar dataclasses we can have one dataclass and two dialects:\n```python\nfrom dataclasses import dataclass\nfrom datetime import date, datetime\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.config import ADD_DIALECT_SUPPORT\nfrom mashumaro.dialect import Dialect\nfrom mashumaro.types import SerializationStrategy\n\nclass DateTimeSerializationStrategy(SerializationStrategy):\n def __init__(self, fmt: str):\n self.fmt = fmt\n\n def serialize(self, value: date) -> str:\n return value.strftime(self.fmt)\n\n def deserialize(self, value: str) -> date:\n return datetime.strptime(value, self.fmt).date()\n\nclass EthiopianDialect(Dialect):\n serialization_strategy = {\n date: DateTimeSerializationStrategy(\"%d/%m/%Y\")\n }\n\nclass JapaneseDialect(Dialect):\n serialization_strategy = {\n date: DateTimeSerializationStrategy(\"%Y年%m月%d日\")\n }\n\n@dataclass\nclass Entity(DataClassDictMixin):\n dt: date\n\n class Config:\n code_generation_options = [ADD_DIALECT_SUPPORT]\n\nentity = Entity(date(2021, 12, 31))\nentity.to_dict(dialect=EthiopianDialect) # {'dt': '31/12/2021'}\nentity.to_dict(dialect=JapaneseDialect) # {'dt': '2021年12月31日'}\nEntity.from_dict({'dt': '2021年12月31日'}, dialect=JapaneseDialect)\n```\n\n#### `serialization_strategy` dialect option\n\nThis dialect option has the same meaning as the\n[similar config option](#serialization_strategy-config-option)\nbut for the dialect scope. You can register custom [`SerializationStrategy`](#serializationstrategy),\n`serialize` and `deserialize` methods for the specific types.\n\n#### `serialize_by_alias` dialect option\n\nThis dialect option has the same meaning as the\n[similar config option](#serialize_by_alias-config-option)\nbut for the dialect scope.\n\n#### `omit_none` dialect option\n\nThis dialect option has the same meaning as the\n[similar config option](#omit_none-config-option) but for the dialect scope.\n\n#### `omit_default` dialect option\n\nThis dialect option has the same meaning as the\n[similar config option](#omitdefault-config-option) but for the dialect scope.\n\n#### `namedtuple_as_dict` dialect option\n\nThis dialect option has the same meaning as the\n[similar config option](#namedtuple_as_dict-config-option)\nbut for the dialect scope.\n\n#### `no_copy_collections` dialect option\n\nBy default, all collection data types are serialized as a copy to prevent\nmutation of the original collection. As an example, if a dataclass contains\na field of type `list[str]`, then it will be serialized as a copy of the\noriginal list, so you can safely mutate it after. The downside is that copying\nis always slower than using a reference to the original collection. In some\ncases we know beforehand that mutation doesn't take place or is even desirable,\nso we can benefit from avoiding unnecessary copies by setting\n`no_copy_collections` to a sequence of origin collection data types.\nThis is applicable only for collections containing elements that do not\nrequire conversion.\n\n```python\nfrom dataclasses import dataclass\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.config import BaseConfig\nfrom mashumaro.dialect import Dialect\n\nclass NoCopyDialect(Dialect):\n no_copy_collections = (list, dict, set)\n\n@dataclass\nclass DataClass(DataClassDictMixin):\n simple_list: list[str]\n simple_dict: dict[str, str]\n simple_set: set[str]\n\n class Config(BaseConfig):\n dialect = NoCopyDialect\n\nobj = DataClass([\"foo\"], {\"bar\": \"baz\"}, {\"foobar\"})\ndata = obj.to_dict()\n\nassert data[\"simple_list\"] is obj.simple_list\nassert data[\"simple_dict\"] is obj.simple_dict\nassert data[\"simple_set\"] is obj.simple_set\n```\n\nThis option is enabled for `list` and `dict` in the default dialects that\nbelong to mixins and codecs for the following formats:\n* [JSON (orjson library)](#orjson-library)\n* [TOML](#toml)\n* [MessagePack](#messagepack)\n\n#### Changing the default dialect\n\nYou can change the default serialization and deserialization methods not only\nin the [`serialization_strategy`](#serialization_strategy-config-option) config\noption but also using the `dialect` config option. If you have multiple\ndataclasses without a common parent class the default dialect can help you\nto reduce the number of code lines written:\n\n```python\n@dataclass\nclass Entity(DataClassDictMixin):\n dt: date\n\n class Config:\n dialect = JapaneseDialect\n\nentity = Entity(date(2021, 12, 31))\nentity.to_dict() # {'dt': '2021年12月31日'}\nassert Entity.from_dict({'dt': '2021年12月31日'}) == entity\n```\n\nDefault dialect can also be set when using codecs:\n```python\nfrom mashumaro.codecs import BasicDecoder, BasicEncoder\n\n@dataclass\nclass Entity:\n dt: date\n\ndecoder = BasicDecoder(Entity, default_dialect=JapaneseDialect)\nencoder = BasicEncoder(Entity, default_dialect=JapaneseDialect)\n\nentity = Entity(date(2021, 12, 31))\nencoder.encode(entity) # {'dt': '2021年12月31日'}\nassert decoder.decode({'dt': '2021年12月31日'}) == entity\n```\n\n### Discriminator\n\nThere is a special `Discriminator` class that allows you to customize how\na union of dataclasses or their hierarchy will be deserialized.\nIt has the following parameters that affects class selection rules:\n\n* `field` — optional name of the input dictionary key (also known as tag)\n by which all the variants can be distinguished\n* `include_subtypes` — allow to deserialize subclasses\n* `include_supertypes` — allow to deserialize superclasses\n* `variant_tagger_fn` — a custom function used to generate tag values\n associated with a variant\n\nBy default, each variant that you want to discriminate by tags should have a\nclass-level attribute containing an associated tag value. This attribute should\nhave a name defined by `field` parameter. The tag value coule be in the\nfollowing forms:\n\n* without annotations: `type = 42`\n* annotated as ClassVar: `type: ClassVar[int] = 42`\n* annotated as Final: `type: Final[int] = 42`\n* annotated as Literal: `type: Literal[42] = 42`\n* annotated as StrEnum: `type: ResponseType = ResponseType.OK`\n\n> [!NOTE]\\\n> Keep in mind that by default only Final, Literal and StrEnum fields are\n> processed during serialization.\n\nHowever, it is possible to use discriminator without the class-level\nattribute. You can provide a custom function that generates one or many variant\ntag values. This function should take a class as the only argument and return\neither a single value of the basic type like `str` or `int` or a list of them\nto associate multiple tags with a variant. The common practice is to use\na class name as a single tag value:\n\n```python\nvariant_tagger_fn = lambda cls: cls.__name__\n```\n\nNext, we will look at different use cases, as well as their pros and cons.\n\n#### Subclasses distinguishable by a field\n\nOften you have a base dataclass and multiple subclasses that are easily\ndistinguishable from each other by the value of a particular field.\nFor example, there may be different events, messages or requests with\na discriminator field \"event_type\", \"message_type\" or just \"type\". You could've\nlisted all of them within `Union` type, but it would be too verbose and\nimpractical. Moreover, deserialization of the union would be slow, since we\nneed to iterate over each variant in the list until we find the right one.\n\nWe can improve subclass deserialization using `Discriminator` as annotation\nwithin `Annotated` type. We will use `field` parameter and set\n`include_subtypes` to `True`.\n\n> [!IMPORTANT]\\\n> The discriminator field should be accessible from the `__dict__` attribute\n> of a specific descendant, i.e. defined at the level of that descendant.\n> A descendant class without a discriminator field will be ignored, but\n> its descendants won't.\n\nSuppose we have a hierarchy of client events distinguishable by a class\nattribute \"type\":\n\n```python\nfrom dataclasses import dataclass\nfrom ipaddress import IPv4Address\nfrom mashumaro import DataClassDictMixin\n\n@dataclass\nclass ClientEvent(DataClassDictMixin):\n pass\n\n@dataclass\nclass ClientConnectedEvent(ClientEvent):\n type = \"connected\"\n client_ip: IPv4Address\n\n@dataclass\nclass ClientDisconnectedEvent(ClientEvent):\n type = \"disconnected\"\n client_ip: IPv4Address\n```\n\nWe use base dataclass `ClientEvent` for a field of another dataclass:\n\n```python\nfrom typing import Annotated, List\n# or from typing_extensions import Annotated\nfrom mashumaro.types import Discriminator\n\n\n@dataclass\nclass AggregatedEvents(DataClassDictMixin):\n list: List[\n Annotated[\n ClientEvent, Discriminator(field=\"type\", include_subtypes=True)\n ]\n ]\n```\n\nNow we can deserialize events based on \"type\" value:\n\n```python\nevents = AggregatedEvents.from_dict(\n {\n \"list\": [\n {\"type\": \"connected\", \"client_ip\": \"10.0.0.42\"},\n {\"type\": \"disconnected\", \"client_ip\": \"10.0.0.42\"},\n ]\n }\n)\nassert events == AggregatedEvents(\n list=[\n ClientConnectedEvent(client_ip=IPv4Address(\"10.0.0.42\")),\n ClientDisconnectedEvent(client_ip=IPv4Address(\"10.0.0.42\")),\n ]\n)\n```\n\n#### Subclasses without a common field\n\nIn rare cases you have to deal with subclasses that don't have a common field\nname which they can be distinguished by. Since `Discriminator` can be\ninitialized without \"field\" parameter you can use it with only\n`include_subclasses` enabled. The drawback is that we will have to go through all\nthe subclasses until we find the suitable one. It's almost like using `Union`\ntype but with subclasses support.\n\nSuppose we're making a brunch. We have some ingredients:\n\n```python\n@dataclass\nclass Ingredient(DataClassDictMixin):\n name: str\n\n@dataclass\nclass Hummus(Ingredient):\n made_of: Literal[\"chickpeas\", \"beet\", \"artichoke\"]\n grams: int\n\n@dataclass\nclass Celery(Ingredient):\n pieces: int\n```\n\nLet's create a plate:\n\n```python\n@dataclass\nclass Plate(DataClassDictMixin):\n ingredients: List[\n Annotated[Ingredient, Discriminator(include_subtypes=True)]\n ]\n```\n\nAnd now we can put our ingredients on the plate:\n\n```python\nplate = Plate.from_dict(\n {\n \"ingredients\": [\n {\n \"name\": \"hummus from the shop\",\n \"made_of\": \"chickpeas\",\n \"grams\": 150,\n },\n {\"name\": \"celery from my garden\", \"pieces\": 5},\n ]\n }\n)\nassert plate == Plate(\n ingredients=[\n Hummus(name=\"hummus from the shop\", made_of=\"chickpeas\", grams=150),\n Celery(name=\"celery from my garden\", pieces=5),\n ]\n)\n```\n\nIn some cases it's necessary to fall back to the base class if there is no\nsuitable subclass. We can set `include_supertypes` to `True`:\n\n```python\n@dataclass\nclass Plate(DataClassDictMixin):\n ingredients: List[\n Annotated[\n Ingredient,\n Discriminator(include_subtypes=True, include_supertypes=True),\n ]\n ]\n\nplate = Plate.from_dict(\n {\n \"ingredients\": [\n {\n \"name\": \"hummus from the shop\",\n \"made_of\": \"chickpeas\",\n \"grams\": 150,\n },\n {\"name\": \"celery from my garden\", \"pieces\": 5},\n {\"name\": \"cumin\"} # <- new unknown ingredient\n ]\n }\n)\nassert plate == Plate(\n ingredients=[\n Hummus(name=\"hummus from the shop\", made_of=\"chickpeas\", grams=150),\n Celery(name=\"celery from my garden\", pieces=5),\n Ingredient(name=\"cumin\"), # <- unknown ingredient added\n ]\n)\n```\n\n#### Class level discriminator\n\nIt may often be more convenient to specify a `Discriminator` once at the class\nlevel and use that class without `Annotated` type for subclass deserialization.\nDepending on the `Discriminator` parameters, it can be used as a replacement for\n[subclasses distinguishable by a field](#subclasses-distinguishable-by-a-field)\nas well as for [subclasses without a common field](#subclasses-without-a-common-field).\nThe only difference is that you can't use `include_supertypes=True` because\nit would lead to a recursion error.\n\nReworked example will look like this:\n\n```python\nfrom dataclasses import dataclass\nfrom ipaddress import IPv4Address\nfrom typing import List\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.config import BaseConfig\nfrom mashumaro.types import Discriminator\n\n@dataclass\nclass ClientEvent(DataClassDictMixin):\n class Config(BaseConfig):\n discriminator = Discriminator( # <- add discriminator\n field=\"type\",\n include_subtypes=True,\n )\n\n@dataclass\nclass ClientConnectedEvent(ClientEvent):\n type = \"connected\"\n client_ip: IPv4Address\n\n@dataclass\nclass ClientDisconnectedEvent(ClientEvent):\n type = \"disconnected\"\n client_ip: IPv4Address\n\n@dataclass\nclass AggregatedEvents(DataClassDictMixin):\n list: List[ClientEvent] # <- use base class here\n```\n\nAnd now we can deserialize events based on \"type\" value as we did earlier:\n\n```python\nevents = AggregatedEvents.from_dict(\n {\n \"list\": [\n {\"type\": \"connected\", \"client_ip\": \"10.0.0.42\"},\n {\"type\": \"disconnected\", \"client_ip\": \"10.0.0.42\"},\n ]\n }\n)\nassert events == AggregatedEvents(\n list=[\n ClientConnectedEvent(client_ip=IPv4Address(\"10.0.0.42\")),\n ClientDisconnectedEvent(client_ip=IPv4Address(\"10.0.0.42\")),\n ]\n)\n```\n\nWhat's more interesting is that you can now deserialize subclasses simply by\ncalling the superclass `from_*` method, which is very useful:\n```python\ndisconnected_event = ClientEvent.from_dict(\n {\"type\": \"disconnected\", \"client_ip\": \"10.0.0.42\"}\n)\nassert disconnected_event == ClientDisconnectedEvent(IPv4Address(\"10.0.0.42\"))\n```\n\nThe same is applicable for subclasses without a common field:\n\n```python\n@dataclass\nclass Ingredient(DataClassDictMixin):\n name: str\n\n class Config:\n discriminator = Discriminator(include_subtypes=True)\n\n...\n\ncelery = Ingredient.from_dict({\"name\": \"celery from my garden\", \"pieces\": 5})\nassert celery == Celery(name=\"celery from my garden\", pieces=5)\n```\n\n#### Working with union of classes\n\nDeserialization of union of types distinguishable by a particular field will\nbe much faster using `Discriminator` because there will be no traversal\nof all classes and an attempt to deserialize each of them.\nUsually this approach can be used when you have multiple classes without a\ncommon superclass or when you only need to deserialize some of the subclasses.\nIn the following example we will use `include_supertypes=True` to\ndeserialize two subclasses out of three:\n\n```python\nfrom dataclasses import dataclass\nfrom typing import Annotated, Literal, Union\n# or from typing_extensions import Annotated\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.types import Discriminator\n\n@dataclass\nclass Event(DataClassDictMixin):\n pass\n\n@dataclass\nclass Event1(Event):\n code: Literal[1] = 1\n ...\n\n@dataclass\nclass Event2(Event):\n code: Literal[2] = 2\n ...\n\n@dataclass\nclass Event3(Event):\n code: Literal[3] = 3\n ...\n\n@dataclass\nclass Message(DataClassDictMixin):\n event: Annotated[\n Union[Event1, Event2],\n Discriminator(field=\"code\", include_supertypes=True),\n ]\n\nevent1_msg = Message.from_dict({\"event\": {\"code\": 1, ...}})\nevent2_msg = Message.from_dict({\"event\": {\"code\": 2, ...}})\nassert isinstance(event1_msg.event, Event1)\nassert isinstance(event2_msg.event, Event2)\n\n# raises InvalidFieldValue:\nMessage.from_dict({\"event\": {\"code\": 3, ...}})\n```\n\nAgain, it's not necessary to have a common superclass. If you have a union of\ndataclasses without a field that they can be distinguishable by, you can still\nuse `Discriminator`, but deserialization will almost be the same as for `Union`\ntype without `Discriminator` except that it could be possible to deserialize\nsubclasses with `include_subtypes=True`.\n\n> [!IMPORTANT]\\\n> When both `include_subtypes` and `include_supertypes` are enabled,\n> all subclasses will be attempted to be deserialized first,\n> superclasses — at the end.\n\nIn the following example you can see how priority works — first we try\nto deserialize `ChickpeaHummus`, and if it fails, then we try `Hummus`:\n\n```python\n@dataclass\nclass Hummus(DataClassDictMixin):\n made_of: Literal[\"chickpeas\", \"artichoke\"]\n grams: int\n\n@dataclass\nclass ChickpeaHummus(Hummus):\n made_of: Literal[\"chickpeas\"]\n\n@dataclass\nclass Celery(DataClassDictMixin):\n pieces: int\n\n@dataclass\nclass Plate(DataClassDictMixin):\n ingredients: List[\n Annotated[\n Union[Hummus, Celery],\n Discriminator(include_subtypes=True, include_supertypes=True),\n ]\n ]\n\nplate = Plate.from_dict(\n {\n \"ingredients\": [\n {\"made_of\": \"chickpeas\", \"grams\": 100},\n {\"made_of\": \"artichoke\", \"grams\": 50},\n {\"pieces\": 4},\n ]\n }\n)\nassert plate == Plate(\n ingredients=[\n ChickpeaHummus(made_of='chickpeas', grams=100), # <- subclass\n Hummus(made_of='artichoke', grams=50), # <- superclass\n Celery(pieces=4),\n ]\n)\n```\n\n#### Using a custom variant tagger function\n\nSometimes it is impractical to have a class-level attribute with a tag value,\nespecially when you have a lot of classes. We can have a custom tagger\nfunction instead. This method is applicable for all scenarios of using\nthe discriminator, but for demonstration purposes, let's focus only on one\nof them.\n\nSuppose we want to use the middle part of `Client*Event` as a tag value:\n\n```python\nfrom dataclasses import dataclass\nfrom ipaddress import IPv4Address\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.config import BaseConfig\nfrom mashumaro.types import Discriminator\n\n\ndef client_event_tagger(cls):\n # not the best way of doing it, it's just a demo\n return cls.__name__[6:-5].lower()\n\n@dataclass\nclass ClientEvent(DataClassDictMixin):\n class Config(BaseConfig):\n discriminator = Discriminator(\n field=\"type\",\n include_subtypes=True,\n variant_tagger_fn=client_event_tagger,\n )\n\n@dataclass\nclass ClientConnectedEvent(ClientEvent):\n client_ip: IPv4Address\n\n@dataclass\nclass ClientDisconnectedEvent(ClientEvent):\n client_ip: IPv4Address\n```\n\nWe can now deserialize subclasses as we did it earlier\n[without variant tagger](#class-level-discriminator):\n```python\ndisconnected_event = ClientEvent.from_dict(\n {\"type\": \"disconnected\", \"client_ip\": \"10.0.0.42\"}\n)\nassert disconnected_event == ClientDisconnectedEvent(IPv4Address(\"10.0.0.42\"))\n```\n\nIf we need to associate multiple tags with a single variant, we can return\na list of tags:\n\n```python\ndef client_event_tagger(cls):\n name = cls.__name__[6:-5]\n return [name.lower(), name.upper()]\n```\n\n### Code generation options\n\n#### Add `omit_none` keyword argument\n\nIf you want to have control over whether to skip `None` values on serialization\nyou can add `omit_none` parameter to `to_*` methods using the\n`code_generation_options` list. The default value of `omit_none`\nparameter depends on whether the [`omit_none`](#omit_none-config-option)\nconfig option or [`omit_none`](#omit_none-dialect-option) dialect option is enabled.\n\n```python\nfrom dataclasses import dataclass\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.config import BaseConfig, TO_DICT_ADD_OMIT_NONE_FLAG\n\n@dataclass\nclass Inner(DataClassDictMixin):\n x: int = None\n # \"x\" won't be omitted since there is no TO_DICT_ADD_OMIT_NONE_FLAG here\n\n@dataclass\nclass Model(DataClassDictMixin):\n x: Inner\n a: int = None\n b: str = None # will be omitted\n\n class Config(BaseConfig):\n code_generation_options = [TO_DICT_ADD_OMIT_NONE_FLAG]\n\nModel(x=Inner(), a=1).to_dict(omit_none=True) # {'x': {'x': None}, 'a': 1}\n```\n\n#### Add `by_alias` keyword argument\n\nIf you want to have control over whether to serialize fields by their\n[aliases](#field-aliases) you can add `by_alias` parameter to `to_*` methods\nusing the `code_generation_options` list. The default value of `by_alias`\nparameter depends on whether the [`serialize_by_alias`](#serialize_by_alias-config-option)\nconfig option is enabled.\n\n```python\nfrom dataclasses import dataclass, field\nfrom mashumaro import DataClassDictMixin, field_options\nfrom mashumaro.config import BaseConfig, TO_DICT_ADD_BY_ALIAS_FLAG\n\n@dataclass\nclass DataClass(DataClassDictMixin):\n field_a: int = field(metadata=field_options(alias=\"FieldA\"))\n\n class Config(BaseConfig):\n code_generation_options = [TO_DICT_ADD_BY_ALIAS_FLAG]\n\nDataClass(field_a=1).to_dict() # {'field_a': 1}\nDataClass(field_a=1).to_dict(by_alias=True) # {'FieldA': 1}\n```\n\n#### Add `dialect` keyword argument\n\nSupport for [dialects](#dialects) is disabled by default for performance reasons. You can enable\nit using a `ADD_DIALECT_SUPPORT` constant:\n```python\nfrom dataclasses import dataclass\nfrom datetime import date\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.config import BaseConfig, ADD_DIALECT_SUPPORT\n\n@dataclass\nclass Entity(DataClassDictMixin):\n dt: date\n\n class Config(BaseConfig):\n code_generation_options = [ADD_DIALECT_SUPPORT]\n```\n\n#### Add `context` keyword argument\n\nSometimes it's needed to pass a \"context\" object to the serialization hooks\nthat will take it into account. For example, you could want to have an option\nto remove sensitive data from the serialization result if you need to.\nYou can add `context` parameter to `to_*` methods that will be passed to\n[`__pre_serialize__`](#before-serialization) and\n[`__post_serialize__`](#after-serialization) hooks. The type of this context\nas well as its mutability is up to you.\n\n```python\nfrom dataclasses import dataclass\nfrom typing import Dict, Optional\nfrom uuid import UUID\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.config import BaseConfig, ADD_SERIALIZATION_CONTEXT\n\nclass BaseModel(DataClassDictMixin):\n class Config(BaseConfig):\n code_generation_options = [ADD_SERIALIZATION_CONTEXT]\n\n@dataclass\nclass Account(BaseModel):\n id: UUID\n username: str\n name: str\n\n def __pre_serialize__(self, context: Optional[Dict] = None):\n return self\n\n def __post_serialize__(self, d: Dict, context: Optional[Dict] = None):\n if context and context.get(\"remove_sensitive_data\"):\n d[\"username\"] = \"***\"\n d[\"name\"] = \"***\"\n return d\n\n@dataclass\nclass Session(BaseModel):\n id: UUID\n key: str\n account: Account\n\n def __pre_serialize__(self, context: Optional[Dict] = None):\n return self\n\n def __post_serialize__(self, d: Dict, context: Optional[Dict] = None):\n if context and context.get(\"remove_sensitive_data\"):\n d[\"key\"] = \"***\"\n return d\n\n\nfoo = Session(\n id=UUID('03321c9f-6a97-421e-9869-918ff2867a71'),\n key=\"VQ6Q9bX4c8s\",\n account=Account(\n id=UUID('4ef2baa7-edef-4d6a-b496-71e6d72c58fb'),\n username=\"john_doe\",\n name=\"John\"\n )\n)\nassert foo.to_dict() == {\n 'id': '03321c9f-6a97-421e-9869-918ff2867a71',\n 'key': 'VQ6Q9bX4c8s',\n 'account': {\n 'id': '4ef2baa7-edef-4d6a-b496-71e6d72c58fb',\n 'username': 'john_doe',\n 'name': 'John'\n }\n}\nassert foo.to_dict(context={\"remove_sensitive_data\": True}) == {\n 'id': '03321c9f-6a97-421e-9869-918ff2867a71',\n 'key': '***',\n 'account': {\n 'id': '4ef2baa7-edef-4d6a-b496-71e6d72c58fb',\n 'username': '***',\n 'name': '***'\n }\n}\n```\n\n### Generic dataclasses\n\nAlong with [user-defined generic types](#user-defined-generic-types)\nimplementing `SerializableType` interface, generic and variadic\ngeneric dataclasses can also be used. There are two applicable scenarios\nfor them.\n\n#### Generic dataclass inheritance\n\nIf you have a generic dataclass and want to serialize and deserialize its\ninstances depending on the concrete types, you can use inheritance for that:\n\n```python\nfrom dataclasses import dataclass\nfrom datetime import date\nfrom typing import Generic, Mapping, TypeVar, TypeVarTuple\nfrom mashumaro import DataClassDictMixin\n\nKT = TypeVar(\"KT\")\nVT = TypeVar(\"VT\", date, str)\nTs = TypeVarTuple(\"Ts\")\n\n@dataclass\nclass GenericDataClass(Generic[KT, VT, *Ts]):\n x: Mapping[KT, VT]\n y: Tuple[*Ts, KT]\n\n@dataclass\nclass ConcreteDataClass(\n GenericDataClass[str, date, *Tuple[float, ...]],\n DataClassDictMixin,\n):\n pass\n\nConcreteDataClass.from_dict({\"x\": {\"a\": \"2021-01-01\"}, \"y\": [1, 2, \"a\"]})\n# ConcreteDataClass(x={'a': datetime.date(2021, 1, 1)}, y=(1.0, 2.0, 'a'))\n```\n\nYou can override `TypeVar` field with a concrete type or another `TypeVar`.\nPartial specification of concrete types is also allowed. If a generic dataclass\nis inherited without type overriding the types of its fields remain untouched.\n\n#### Generic dataclass in a field type\n\nAnother approach is to specify concrete types in the field type hints. This can\nhelp to have different versions of the same generic dataclass:\n\n```python\nfrom dataclasses import dataclass\nfrom datetime import date\nfrom typing import Generic, TypeVar\nfrom mashumaro import DataClassDictMixin\n\nT = TypeVar('T')\n\n@dataclass\nclass GenericDataClass(Generic[T], DataClassDictMixin):\n x: T\n\n@dataclass\nclass DataClass(DataClassDictMixin):\n date: GenericDataClass[date]\n str: GenericDataClass[str]\n\ninstance = DataClass(\n date=GenericDataClass(x=date(2021, 1, 1)),\n str=GenericDataClass(x='2021-01-01'),\n)\ndictionary = {'date': {'x': '2021-01-01'}, 'str': {'x': '2021-01-01'}}\nassert DataClass.from_dict(dictionary) == instance\n```\n\n### GenericSerializableType interface\n\nThere is a generic alternative to [`SerializableType`](#serializabletype-interface)\ncalled `GenericSerializableType`. It makes it possible to decide yourself how\nto serialize and deserialize input data depending on the types provided:\n\n```python\nfrom dataclasses import dataclass\nfrom datetime import date\nfrom typing import Dict, TypeVar\nfrom mashumaro import DataClassDictMixin\nfrom mashumaro.types import GenericSerializableType\n\nKT = TypeVar(\"KT\")\nVT = TypeVar(\"VT\")\n\nclass DictWrapper(Dict[KT, VT], GenericSerializableType):\n __packers__ = {date: lambda x: x.isoformat(), str: str}\n __unpackers__ = {date: date.fromisoformat, str: str}\n\n def _serialize(self, types) -> Dict[KT, VT]:\n k_type, v_type = types\n k_conv = self.__packers__[k_type]\n v_conv = self.__packers__[v_type]\n return {k_conv(k): v_conv(v) for k, v in self.items()}\n\n @classmethod\n def _deserialize(cls, value, types) -> \"DictWrapper[KT, VT]\":\n k_type, v_type = types\n k_conv = cls.__unpackers__[k_type]\n v_conv = cls.__unpackers__[v_type]\n return cls({k_conv(k): v_conv(v) for k, v in value.items()})\n\n@dataclass\nclass DataClass(DataClassDictMixin):\n x: DictWrapper[date, str]\n y: DictWrapper[str, date]\n\ninput_data = {\n \"x\": {\"2022-12-07\": \"2022-12-07\"},\n \"y\": {\"2022-12-07\": \"2022-12-07\"},\n}\nobj = DataClass.from_dict(input_data)\nassert obj == DataClass(\n x=DictWrapper({date(2022, 12, 7): \"2022-12-07\"}),\n y=DictWrapper({\"2022-12-07\": date(2022, 12, 7)}),\n)\nassert obj.to_dict() == input_data\n```\n\nAs you can see, the code turns out to be massive compared to the\n[alternative](#user-defined-generic-types) but in rare cases such flexibility\ncan be useful. You should think twice about whether it's really worth using it.\n\n### Serialization hooks\n\nIn some cases you need to prepare input / output data or do some extraordinary\nactions at different stages of the deserialization / serialization lifecycle.\nYou can do this with different types of hooks.\n\n#### Before deserialization\n\nFor doing something with a dictionary that will be passed to deserialization\nyou can use `__pre_deserialize__` class method:\n\n```python\n@dataclass\nclass A(DataClassJSONMixin):\n abc: int\n\n @classmethod\n def __pre_deserialize__(cls, d: Dict[Any, Any]) -> Dict[Any, Any]:\n return {k.lower(): v for k, v in d.items()}\n\nprint(DataClass.from_dict({\"ABC\": 123})) # DataClass(abc=123)\nprint(DataClass.from_json('{\"ABC\": 123}')) # DataClass(abc=123)\n```\n\n#### After deserialization\n\nFor doing something with a dataclass instance that was created as a result\nof deserialization you can use `__post_deserialize__` class method:\n\n```python\n@dataclass\nclass A(DataClassJSONMixin):\n abc: int\n\n @classmethod\n def __post_deserialize__(cls, obj: 'A') -> 'A':\n obj.abc = 456\n return obj\n\nprint(DataClass.from_dict({\"abc\": 123})) # DataClass(abc=456)\nprint(DataClass.from_json('{\"abc\": 123}')) # DataClass(abc=456)\n```\n\n#### Before serialization\n\nFor doing something before serialization you can use `__pre_serialize__`\nmethod:\n\n```python\n@dataclass\nclass A(DataClassJSONMixin):\n abc: int\n counter: ClassVar[int] = 0\n\n def __pre_serialize__(self) -> 'A':\n self.counter += 1\n return self\n\nobj = DataClass(abc=123)\nobj.to_dict()\nobj.to_json()\nprint(obj.counter) # 2\n```\n\nNote that you can add an additional `context` argument using the\n[corresponding](#add-context-keyword-argument) code generation option.\n\n#### After serialization\n\nFor doing something with a dictionary that was created as a result of\nserialization you can use `__post_serialize__` method:\n\n```python\n@dataclass\nclass A(DataClassJSONMixin):\n user: str\n password: str\n\n def __post_serialize__(self, d: Dict[Any, Any]) -> Dict[Any, Any]:\n d.pop('password')\n return d\n\nobj = DataClass(user=\"name\", password=\"secret\")\nprint(obj.to_dict()) # {\"user\": \"name\"}\nprint(obj.to_json()) # '{\"user\": \"name\"}'\n```\n\nNote that you can add an additional `context` argument using the\n[corresponding](#add-context-keyword-argument) code generation option.\n\nJSON Schema\n-------------------------------------------------------------------------------\n\nYou can build JSON Schema not only for dataclasses but also for any other\n[supported](#supported-data-types) data\ntypes. There is support for the following standards:\n* [Draft 2020-12](https://json-schema.org/specification.html)\n* [OpenAPI Specification 3.1.1](https://spec.openapis.org/oas/v3.1.1)\n\n### Building JSON Schema\n\nFor simple one-time cases it's recommended to start from using a configurable\n`build_json_schema` function. It returns `JSONSchema` object that can be\nserialized to json or to dict:\n\n```python\nfrom dataclasses import dataclass, field\nfrom typing import List\nfrom uuid import UUID\n\nfrom mashumaro.jsonschema import build_json_schema\n\n\n@dataclass\nclass User:\n id: UUID\n name: str = field(metadata={\"description\": \"User name\"})\n\n\nprint(build_json_schema(List[User]).to_json())\n```\n\n

Click to show the result

\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"title\": \"User\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\",\n \"format\": \"uuid\"\n },\n \"name\": {\n \"type\": \"string\",\n \"description\": \"User name\"\n }\n },\n \"additionalProperties\": false,\n \"required\": [\n \"id\",\n \"name\"\n ]\n }\n}\n```\n

\n\nAdditional validation keywords ([see below](#json-schema-constraints))\ncan be added using annotations:\n\n```python\nfrom typing import Annotated, List\nfrom mashumaro.jsonschema import build_json_schema\nfrom mashumaro.jsonschema.annotations import Maximum, MaxItems\n\nprint(\n build_json_schema(\n Annotated[\n List[Annotated[int, Maximum(42)]],\n MaxItems(4)\n ]\n ).to_json()\n)\n```\n\n

Click to show the result

\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"type\": \"integer\",\n \"maximum\": 42\n },\n \"maxItems\": 4\n}\n```\n

\n\nThe [`$schema`](https://json-schema.org/draft/2020-12/json-schema-core.html#name-the-schema-keyword)\nkeyword can be added by setting `with_dialect_uri` to True:\n\n```python\nprint(build_json_schema(str, with_dialect_uri=True).to_json())\n```\n\n

Click to show the result

\n\n```json\n{\n \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n \"type\": \"string\"\n}\n```\n

\n\nBy default, Draft 2022-12 dialect is being used, but you can change it to\nanother one by setting `dialect` parameter:\n\n```python\nfrom mashumaro.jsonschema import OPEN_API_3_1\n\nprint(\n build_json_schema(\n str, dialect=OPEN_API_3_1, with_dialect_uri=True\n ).to_json()\n)\n```\n\n

Click to show the result

\n\n```json\n{\n \"$schema\": \"https://spec.openapis.org/oas/3.1/dialect/base\",\n \"type\": \"string\"\n}\n```\n

\n\nAll dataclass JSON Schemas can or can not be placed in the\n[definitions](https://json-schema.org/draft/2020-12/json-schema-core.html#name-schema-re-use-with-defs)\nsection, depending on the `all_refs` parameter, which default value comes\nfrom a dialect used (`False` for Draft 2022-12, `True` for OpenAPI\nSpecification 3.1.1):\n\n```python\nprint(build_json_schema(List[User], all_refs=True).to_json())\n```\n

Click to show the result

\n\n```json\n{\n \"type\": \"array\",\n \"$defs\": {\n \"User\": {\n \"type\": \"object\",\n \"title\": \"User\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\",\n \"format\": \"uuid\"\n },\n \"name\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false,\n \"required\": [\n \"id\",\n \"name\"\n ]\n }\n },\n \"items\": {\n \"$ref\": \"#/$defs/User\"\n }\n}\n```\n

\n\nThe definitions section can be omitted from the final document by setting\n`with_definitions` parameter to `False`:\n\n```python\nprint(\n build_json_schema(\n List[User], dialect=OPEN_API_3_1, with_definitions=False\n ).to_json()\n)\n```\n\n

Click to show the result

\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"$ref\": \"#/components/schemas/User\"\n }\n}\n```\n

\n\nReference prefix can be changed by using `ref_prefix` parameter:\n\n```python\nprint(\n build_json_schema(\n List[User],\n all_refs=True,\n with_definitions=False,\n ref_prefix=\"#/components/responses\",\n ).to_json()\n)\n```\n\n

Click to show the result

\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"$ref\": \"#/components/responses/User\"\n }\n}\n```\n

\n\nThe omitted definitions could be found later in the `Context` object that\nyou could have created and passed to the function, but it could be easier\nto use `JSONSchemaBuilder` for that. For example, you might found it handy\nto build OpenAPI Specification step by step passing your models to the builder\nand get all the registered definitions later. This builder has reasonable\ndefaults but can be customized if necessary.\n\n```python\nfrom mashumaro.jsonschema import JSONSchemaBuilder, OPEN_API_3_1\n\nbuilder = JSONSchemaBuilder(OPEN_API_3_1)\n\n@dataclass\nclass User:\n id: UUID\n name: str\n\n@dataclass\nclass Device:\n id: UUID\n model: str\n\nprint(builder.build(List[User]).to_json())\nprint(builder.build(List[Device]).to_json())\nprint(builder.get_definitions().to_json())\n```\n\n

Click to show the result

\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"$ref\": \"#/components/schemas/User\"\n }\n}\n```\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"$ref\": \"#/components/schemas/Device\"\n }\n}\n```\n```json\n{\n \"User\": {\n \"type\": \"object\",\n \"title\": \"User\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\",\n \"format\": \"uuid\"\n },\n \"name\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false,\n \"required\": [\n \"id\",\n \"name\"\n ]\n },\n \"Device\": {\n \"type\": \"object\",\n \"title\": \"Device\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\",\n \"format\": \"uuid\"\n },\n \"model\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false,\n \"required\": [\n \"id\",\n \"model\"\n ]\n }\n}\n```\n

\n\n### JSON Schema constraints\n\nApart from required keywords, that are added automatically for certain data\ntypes, you're free to use additional validation keywords.\nThey're presented by the corresponding classes in\n[`mashumaro.jsonschema.annotations`](https://github.com/Fatal1ty/mashumaro/blob/master/mashumaro/jsonschema/annotations.py):\n\nNumber constraints:\n* [`Minimum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-minimum)\n* [`Maximum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-maximum)\n* [`ExclusiveMinimum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-exclusiveminimum)\n* [`ExclusiveMaximum`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-exclusivemaximum)\n* [`MultipleOf`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-multipleof)\n\nString constraints:\n* [`MinLength`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-minlength)\n* [`MaxLength`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-maxlength)\n* [`Pattern`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-pattern)\n\nArray constraints:\n* [`MinItems`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-minitems)\n* [`MaxItems`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-maxitems)\n* [`UniqueItems`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-uniqueitems)\n* [`Contains`](https://json-schema.org/draft/2020-12/json-schema-core.html#name-contains)\n* [`MinContains`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-mincontains)\n* [`MaxContains`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-maxcontains)\n\nObject constraints:\n* [`MaxProperties`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-maxproperties)\n* [`MinProperties`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-minproperties)\n* [`DependentRequired`](https://json-schema.org/draft/2020-12/json-schema-validation.html#name-dependentrequired)\n\n### JSON Schema plugins\n\nIf the built-in functionality doesn't meet your needs, you can customize the\nJSON Schema generation or add support for additional types using plugins.\nThe [`mashumaro.jsonschema.plugins.BasePlugin`](https://github.com/Fatal1ty/mashumaro/blob/32179eac1927483f4da015f711b07c04e8b2b2b9/mashumaro/jsonschema/plugins.py#L9-L16)\nclass provides a `get_schema` method that you can override to implement custom\nbehavior.\n\nThe plugin system works by iterating through all registered plugins and calling\ntheir `get_schema` methods. If a plugin's `get_schema` method raises a\n`NotImplementedError` or returns `None`, it indicates that the plugin doesn't\nprovide the required functionality for that particular case.\n\nYou can apply multiple plugins sequentially, allowing each to modify the schema\nin turn. This approach enables a step-by-step transformation of the schema,\nwith each plugin contributing its specific modifications.\n\nPlugins can be registered using the `plugins` argument in either the\n`build_json_schema` function or the `JSONSchemaBuilder` class.\n\nThe [`mashumaro.jsonschema.plugins`](https://github.com/Fatal1ty/mashumaro/blob/master/mashumaro/jsonschema/plugins.py)\nmodule contains several built-in plugins. Currently, one of these plugins adds\ndescriptions to JSON schemas using docstrings from dataclasses:\n\n```python\nfrom dataclasses import dataclass\n\nfrom mashumaro.jsonschema import build_json_schema\nfrom mashumaro.jsonschema.plugins import DocstringDescriptionPlugin\n\n\n@dataclass\nclass MyClass:\n \"\"\"My class\"\"\"\n\n x: int\n\n\nschema = build_json_schema(MyClass, plugins=[DocstringDescriptionPlugin()])\nprint(schema.to_json())\n```\n\n

Click to show the result

\n\n```json\n{\n \"type\": \"object\",\n \"title\": \"MyClass\",\n \"description\": \"My class\",\n \"properties\": {\n \"x\": {\n \"type\": \"integer\"\n }\n },\n \"additionalProperties\": false,\n \"required\": [\n \"x\"\n ]\n}\n```\n

\n\nCreating your own custom plugin is straightforward. For instance, if you want\nto add support for Pydantic models, you could write a plugin similar to the\nfollowing:\n\n```python\nfrom dataclasses import dataclass\n\nfrom pydantic import BaseModel\n\nfrom mashumaro.jsonschema import build_json_schema\nfrom mashumaro.jsonschema.models import Context, JSONSchema\nfrom mashumaro.jsonschema.plugins import BasePlugin\nfrom mashumaro.jsonschema.schema import Instance\n\n\nclass PydanticSchemaPlugin(BasePlugin):\n def get_schema(\n self,\n instance: Instance,\n ctx: Context,\n schema: JSONSchema | None = None,\n ) -> JSONSchema | None:\n try:\n if issubclass(instance.type, BaseModel):\n pydantic_schema = instance.type.model_json_schema()\n return JSONSchema.from_dict(pydantic_schema)\n except TypeError:\n return None\n\n\nclass MyPydanticClass(BaseModel):\n x: int\n\n\n@dataclass\nclass MyDataClass:\n y: MyPydanticClass\n\n\nschema = build_json_schema(MyDataClass, plugins=[PydanticSchemaPlugin()])\nprint(schema.to_json())\n```\n\n

Click to show the result

\n\n```json\n{\n \"type\": \"object\",\n \"title\": \"MyDataClass\",\n \"properties\": {\n \"y\": {\n \"type\": \"object\",\n \"title\": \"MyPydanticClass\",\n \"properties\": {\n \"x\": {\n \"type\": \"integer\",\n \"title\": \"X\"\n }\n },\n \"required\": [\n \"x\"\n ]\n }\n },\n \"additionalProperties\": false,\n \"required\": [\n \"y\"\n ]\n}\n```\n

\n\n\n### Extending JSON Schema\n\nUsing a `Config` class it is possible to override some parts of the schema.\nCurrently, you can do the following:\n* override some field schemas using the \"properties\" key\n* change `additionalProperties` using the \"additionalProperties\" key\n\n```python\nfrom dataclasses import dataclass\nfrom mashumaro.jsonschema import build_json_schema\n\n@dataclass\nclass FooBar:\n foo: str\n bar: int\n\n class Config:\n json_schema = {\n \"properties\": {\n \"foo\": {\n \"type\": \"string\",\n \"description\": \"bar\"\n }\n },\n \"additionalProperties\": True,\n }\n\nprint(build_json_schema(FooBar).to_json())\n```\n\n

Click to show the result

\n\n```json\n{\n \"type\": \"object\",\n \"title\": \"FooBar\",\n \"properties\": {\n \"foo\": {\n \"type\": \"string\",\n \"description\": \"bar\"\n },\n \"bar\": {\n \"type\": \"integer\"\n }\n },\n \"additionalProperties\": true,\n \"required\": [\n \"foo\",\n \"bar\"\n ]\n}\n```\n

\n\nYou can also change the \"additionalProperties\" key to a specific schema\nby passing it a `JSONSchema` instance instead of a bool value.\n\n### JSON Schema and custom serialization methods\n\nMashumaro provides different ways to override default serialization methods for\ndataclass fields or specific data types. In order for these overrides to be\nreflected in the schema, you need to make sure that the methods have\nannotations of the return value type.\n\n```python\nfrom dataclasses import dataclass, field\nfrom mashumaro.config import BaseConfig\nfrom mashumaro.jsonschema import build_json_schema\n\ndef str_as_list(s: str) -> list[str]:\n return list(s)\n\ndef int_as_str(i: int) -> str:\n return str(i)\n\n@dataclass\nclass FooBar:\n foo: str = field(metadata={\"serialize\": str_as_list})\n bar: int\n\n class Config(BaseConfig):\n serialization_strategy = {\n int: {\n \"serialize\": int_as_str\n }\n }\n\nprint(build_json_schema(FooBar).to_json())\n```\n\n

Click to show the result

\n\n```json\n{\n \"type\": \"object\",\n \"title\": \"FooBar\",\n \"properties\": {\n \"foo\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"bar\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false,\n \"required\": [\n \"foo\",\n \"bar\"\n ]\n}\n```\n

\n","description_content_type":"text/markdown","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":"https://github.com/Fatal1ty/mashumaro","keywords":null,"license":"Apache License, Version 2.0","license_expression":null,"license_files":null,"maintainer":null,"maintainer_email":null,"name":"mashumaro","package_url":"https://pypi.org/project/mashumaro/","platform":"all","project_url":"https://pypi.org/project/mashumaro/","project_urls":{"Homepage":"https://github.com/Fatal1ty/mashumaro"},"provides_extra":["msgpack","orjson","toml","yaml"],"release_url":"https://pypi.org/project/mashumaro/3.16/","requires_dist":["typing-extensions>=4.1.0","msgpack>=0.5.6; extra == \"msgpack\"","orjson; extra == \"orjson\"","tomli-w>=1.0; extra == \"toml\"","tomli>=1.1.0; python_version < \"3.11\" and extra == \"toml\"","pyyaml>=3.13; extra == \"yaml\""],"requires_python":">=3.9","summary":"Fast and well tested serialization library","version":"3.16","yanked":false,"yanked_reason":null}

Dependency	Optional
typing-extensions	false
msgpack	true
orjson	true
pyyaml	true
tomli	true
tomli-w	true

Package search

mashumaro

project_urls

Dependencies

All package metadata

Releases