mashumaro

Warnings

• breaking In v3.15, deserialization behavior for Unions with `int | float`, `str`, `bool`, and `NoneType` changed. Values are now passed through without coercion for numeric types (if they match), `str` is guaranteed a string version, `bool` uses standard truth testing, and `NoneType` is guaranteed `None`. This can lead to different deserialization results if your application relied on previous implicit coercions or conversions.
  Fix: Review deserialization logic for fields using `Union` or basic types to align with the new, more precise behavior. Explicitly define serialization/deserialization strategies if specific coercions are required.
• breaking Support for Python 3.8 was dropped in mashumaro v3.15. Projects using Python 3.8 must pin mashumaro to a version prior to 3.15.
  Fix: Upgrade Python to 3.9 or higher, or pin `mashumaro<3.15` in your project dependencies.
• gotcha When using `DataClassORJSONMixin`, prior to v3.13.1, the `to_json` method's type annotation incorrectly returned `str`. This was fixed in v3.13.1 to return `str` or `bytes` correctly depending on `orjson_options`, affecting static analysis and potentially runtime if strict type checks are in place.
  Fix: Upgrade to mashumaro v3.13.1 or later to get correct type annotations for `DataClassORJSONMixin.to_json`. Consider using `to_jsonb()` if byte output is desired for performance.
• gotcha Mashumaro offers two primary approaches for serialization: Mixins (e.g., `DataClassJSONMixin`) for dataclass models, and Codecs (e.g., `JSONDecoder`, `JSONEncoder`) for converting arbitrary Python types or top-level collections. Choosing the wrong approach can lead to more verbose code or lack of desired functionality.
  Fix: Use Mixins when your root data structure is a dataclass. Use Codecs when you need to serialize/deserialize arbitrary types (like a `List[datetime]`) or top-level collections that are not directly represented by a single dataclass.
• gotcha The `forbid_extra_keys` configuration option (introduced in v3.13) and `Alias(...)` annotation for field aliasing (also v3.13) offer powerful control but can lead to deserialization failures if not configured correctly. Extra keys will be rejected if `forbid_extra_keys` is set to `True`, and fields might not deserialize by their original name if `Alias` is used without `allow_deserialization_not_by_alias`.
  Fix: Be explicit with `forbid_extra_keys` in your `Config` if you want strict validation. If using `Alias(...)` for field aliasing and require deserialization by both alias and original field name, set `allow_deserialization_not_by_alias=True` in your dataclass `Config`.

Install

• pip install mashumaro Default Install
• pip install mashumaro[orjson] Install with orjson for faster JSON

Imports

• DataClassJSONMixin

  from mashumaro.mixins.json import DataClassJSONMixin

  Primary mixin for JSON serialization/deserialization with dataclasses.
• DataClassDictMixin

  from mashumaro import DataClassDictMixin

  Core mixin for dictionary serialization/deserialization with dataclasses.
• build_json_schema

  from mashumaro.jsonschema import build_json_schema

  For generating JSON Schema from dataclasses.

Quickstart

Define a dataclass inheriting from `DataClassJSONMixin` to automatically gain `to_json()` and `from_json()` methods for seamless JSON serialization and deserialization.

from dataclasses import dataclass
from mashumaro.mixins.json import DataClassJSONMixin

@dataclass
class User(DataClassJSONMixin):
    name: str
    email: str
    age: int

# Serialize to JSON
user = User(name='Alice', email='alice@example.com', age=30)
json_str = user.to_json()
print(f"Serialized: {json_str}")

# Deserialize from JSON
restored_user = User.from_json(json_str)
print(f"Deserialized: {restored_user}")
assert restored_user == user