pyserde 0.1.1

Serialization library on top of dataclasses.

pyserde

Serialization Library on top of dataclasses.

QuickStart

Install pyserde from PyPI.

$ pip install pyserde

You can serialize and deserialize a dataclass in various message formats quite easily!

# main.py
# /usr/bin/env python
from dataclasses import dataclass
from serde import deserialize, serialize
from serde.json import from_json, to_json

@deserialize
@serialize
@dataclass
class Foo:
    i: int
    s: str
    f: float
    b: bool

h = Foo(i=10, s='foo', f=100.0, b=True)
print(f"Into Json: {to_json(h)}")

s = '{"i": 10, "s": "foo", "f": 100.0, "b": true}'
print(f"From Json: {from_json(Foo, s)}")

$ python main.py
Into Json: {"i": 10, "s": "foo", "f": 100.0, "b": true}
From Json: Foo(i=10, s='foo', f=100.0, b=True)

Benchmark

• macOS 10.14 Mojave
• Intel 2.3GHz 8-core Intel Core i9
• DDR4 32GB RAM

Serialize and deserialize a struct into and from json 10,000 times.

Serialize	Deserialize

Convert the struct into tuple and dictionary representation.

astuple	asdict

• raw: Serialize and deserialize manually. Fastest in theory.
• dataclass: Serialize using dataclass's asdict.
• pyserde: This library.
• dacite: Simple creation of data classes from dictionaries.
• mashumaro: Fast and well tested serialization framework on top of dataclasses.
• marshallow: A lightweight library for converting complex objects to and from simple datatypes.
• attrs: Python Classes Without Boilerplate.
• cattrs: Complex custom class converters for attrs.

To run benchmark on your environment:

cd bench
pipenv run python bench.py --full

You can check the benchmark code for more information.

Features

Supported types

• primitives (int, float, str, bool)
• containers (List, Tuple, Dict)
• Optional
• Dataclass

Supported data formats

from dataclasses import dataclass
from serde import deserialize, serialize

@deserialize
@serialize
@dataclass
class Foo:
    i: int
    s: str
    f: float
    b: bool

h = Foo(i=10, s='foo', f=100.0, b=True)

• JSON

  from serde.json import from_json, to_json
  print(f"Into Json: {to_json(h)}")
  print(f"From Json: {from_json(Foo, s)}")
  

• Yaml

  from serde.yaml import from_yaml, to_yaml
  print(f"Into Yaml: {to_yaml(h)}")
  print(f"From Yaml: {from_yaml(Foo, s)}")
  

• Toml

  from serde.toml import from_toml, to_toml
  print(f"Into Toml: {to_toml(h)}")
  print(f"From Toml: {from_toml(Foo, s)}")
  

• MsgPack

  from serde.msgpack import from_msgpack, to_msgpack
  print(f"Into MsgPack: {to_msgpack(h)}")
  print(f"From MsgPack: {from_msgpack(Foo, s)}")
  

Case Conversion

Converting snake_case fields into supported case styles e.g. camelCase and kebab-case.

@serialize(rename_all = 'camelcase')
@dataclass
class Foo:
    int_field: int
    str_field: str

f = Foo(int_field=10, str_field='foo')
print(to_json(f))

Here, the output is all camelCase.

'{"intField": 10, "strField": "foo"}'

Rename Field

In case you want to use a keyword as field such as class, you can use serde_rename field attribute.

@serialize
@dataclass
class Foo:
    class_name: str = field(metadata={'serde_rename': 'class'})

print(to_json(Foo(class_name='Foo')))

Output json is having class instead of class_name.

{"class": "Foo"}

For complete example, please see ./examples/rename.py

Skip

You can skip serialization for a certain field, you can use serde_skip.

@serialize
@dataclass
class Resource:
    name: str
    hash: str
    metadata: Dict[str, str] = field(default_factory=dict, metadata={'serde_skip': True})

resources = [
    Resource("Stack Overflow", "hash1"),
    Resource("GitHub", "hash2", metadata={"headquarters": "San Francisco"}) ]
print(to_json(resources))

Here, metadata is not present in output json.

[{"name": "Stack Overflow", "hash": "hash1"}, {"name": "GitHub", "hash": "hash2"}]

For complete example, please see ./examples/skip.py

Conditional Skip

If you conditionally skip some fields, you can pass function or lambda in serde_skip_if.

@serialize
@dataclass
class World:
    player: str
    buddy: str = field(default='', metadata={'serde_skip_if': lambda v: v == 'Pikachu'})

world = World('satoshi', 'Pikachu')
print(to_json(world))

world = World('green', 'Charmander')
print(to_json(world))

As you can see below, field is skipped in serialization if buddy is "Pikachu".

{"player": "satoshi"}
{"player": "green", "buddy": "Charmander"}

For complete example, please see ./examples/skip.py

Documentation

https://yukinarit.github.io/pyserde/