Skip to main content

Fast serialization framework on top of dataclasses

Project description

mashumaro (マシュマロ)

mashumaro is a fast and well tested serialization framework on top of dataclasses.

Build Status Coverage Status Requirements Status Latest Version Python Version License

When using dataclasses, you often need to dump and load objects according to the described scheme. This framework not only adds this ability to serialize in different formats, but also makes serialization rapidly.

Table of contens

Installation

Use pip to install:

$ pip install mashumaro

Supported serialization formats

This framework adds methods for dumping to and loading from the following formats:

  • plain dict
  • json
  • yaml
  • msgpack

Plain dict can be useful when you need to pass a dict object to a third-party library, such as a client for MongoDB.

Supported field types

There is support for generic types from the standard typing module:

  • List
  • Tuple
  • Set
  • FrozenSet
  • Deque
  • Dict
  • Mapping
  • MutableMapping
  • ChainMap
  • Sequence

for special primitives from the typing module:

  • Optional
  • Any

for enumerations based on classes from the standard enum module:

  • Enum
  • IntEnum
  • Flag
  • IntFlag

for common built-in types:

  • int
  • float
  • bool
  • str
  • bytes
  • bytearray

for built-in datetime oriented types:

  • datetime
  • date
  • time
  • timedelta

for other less popular built-in types:

  • uuid.UUID

for other specific types like NoneType and for nested dataclasses itself.

Usage example

from enum import Enum
from typing import Set
from dataclasses import dataclass
from mashumaro import DataClassJsonMixin

class PetType(Enum):
    CAT = 'CAT'
    MOUSE = 'MOUSE'

@dataclass
class Pet(DataClassJsonMixin):
    name: str
    age: int
    pet_type: PetType

@dataclass
class Person(DataClassJsonMixin):
    first_name: str
    second_name: str
    age: int
    pets: Set[Pet]


tom = Pet(name='Tom', age=5, pet_type=PetType.CAT)
jerry = Pet(name='Jerry', age=3, pet_type=PetType.MOUSE)
john = Person(first_name='John', second_name='Smith', age=18, pets={tom, jerry})

dump = john.to_json()
person = Person.from_json(dump)
# person == john

Pet.from_json('{"name": "Tom", "age": 5, "pet_type": "CAT"}')
# Pet(name='Tom', age=5, pet_type=<PetType.CAT: 'CAT'>)

How does it work?

This framework works by taking the schema of the data and generating a specific parser and builder for exactly that schema. This is much faster than inspection of field types on every call of parsing or building at runtime.

API

Mashumaro provides a couple of mixins for each format.

DataClassJsonMixin.to_json()

Make a JSON formatted string from dataclass object based on the dataclass schema provided.

DataClassJsonMixin.from_json(data: str)

Make a new object from JSON formatted string based on the dataclass schema provided.

DataClassMessagePackMixin.to_msgpack()

Make a MessagePack formatted bytes object from dataclass object based on the dataclass schema provided.

DataClassMessagePackMixin.from_msgpack(data: bytes)

Make a new object from MessagePack formatted data based on the dataclass schema provided.

DataClassYAMLMixin.to_yaml()

Make an YAML formatted bytes object from dataclass object based on the dataclass schema provided.

DataClassYAMLMixin.from_yaml(data: bytes)

Make a new object from YAML formatted data based on the dataclass schema provided.

DataClassDictMixin.to_dict(use_bytes: bool, use_enum: bool, use_datetime: bool)

Make a dictionary from dataclass object based on the dataclass schema provided. Options include:

use_bytes: false     # False - convert bytes/bytearray objects to base64 encoded string, True - keep untouched
use_enum: false      # False - convert enum objects to enum values, True - keep untouched
use_datetime: false  # False - convert datetime oriented objects to ISO 8601 formatted string, True - keep untouched

DataClassDictMixin.from_dict(data: Mapping, use_bytes: bool, use_enum: bool, use_datetime: bool)

Make a new object from dict object based on the dataclass schema provided. Options include:

use_bytes: false     # False - load bytes/bytearray objects from base64 encoded string, True - keep untouched
use_enum: false      # False - load enum objects from enum values, True - keep untouched
use_datetime: false  # False - load datetime oriented objects from ISO 8601 formatted string, True - keep untouched

TODO

  • write benchmarks
  • add parameters to json serialization methods
  • add optional validation
  • write custom useful types such as URL, Email etc
  • write documentation

Project details


Release history Release notifications | RSS feed

This version

1.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mashumaro-1.1.tar.gz (10.0 kB view details)

Uploaded Source

File details

Details for the file mashumaro-1.1.tar.gz.

File metadata

  • Download URL: mashumaro-1.1.tar.gz
  • Upload date:
  • Size: 10.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/39.0.1 requests-toolbelt/0.8.0 tqdm/4.25.0 CPython/3.7.0

File hashes

Hashes for mashumaro-1.1.tar.gz
Algorithm Hash digest
SHA256 7c86514345dc42ac8029eb6d8f85b4a792d6d177c60954bfe4285b653c01a0be
MD5 4a4801548a9a320ce5ef4c8addae930c
BLAKE2b-256 ea2b60450664341e3185b08df78ac936515411f9a4d94bc38b82ab6c9449faf5

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page