Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

Marshal/unmarshal attrs-based data classes to and from JSON

Project description

fieldmarshal – marshal/unmarshal attrs-based data classes to and from JSON

Build Status

Note: This is module is still in development - APIs might change in backwards-incompatible ways.


>>> from fieldmarshal import struct, field, marshal, unmarshal
>>> from typing import List, Set
>>> @struct
... class Post:
...     title: str
...     tags: Set[str]
>>> @struct
... class User:
...     id: int
...     name: str
...     posts: List[Post]
...     is_admin: bool = field("is-admin", default=False)
>>> fred = User(1, "fred", [Post("hello world!", tags={"a", "b"})])
>>> data = marshal(fred)
>>> data
{'id': 1, 'name': 'fred', 'posts': [{'title': 'hello world!', 'tags': ['a', 'b']}], 'is-admin': False}
>>> assert unmarshal(data, User) == fred

The struct and field helpers are just convenience wrappers around attr.s and attr.ib. The equivalent code with attrs is:

>>> import attr
>>> from fieldmarshal import Options
>>> @attr.s(slots=True, auto_attribs=True)
... class User:
...     # ...
...     is_admin: bool = attr.ib(
...         default=False,
...         metadata={'fieldmarshal': Options(name="is-admin")},
...     )

This module provides marshalling/unmarshalling (or serialization/deserialization) of attrs-based "data classes" to and from JSON.

The main goal is to make it easy to quickly build useful (partial) class representations for real-world JSON data, such as those received from HTTP APIs (See the examples subdirectory), and to allow efficient marshalling/unmarshalling to and from JSON.


  • Support for renaming fields (see Example above).
  • Unknown/extra JSON keys are ignored by default.
  • Hook system to customize marshalling/unmarshalling of custom or complex types (e.g. Unions)
  • Built-in handling of common cases, such as Enums, simple Unions.
  • Limited support for non-string dict keys (bool, int, float, Enum).
  • Tries to be unobtrusive: Does not require subclassing and can work with plain attrs-based classes.

The API is inspired by Go's json.Marshal/json.Unmarshal and cattrs.

Project details

Download files

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

Files for fieldmarshal, version 0.0.2
Filename, size File type Python version Upload date Hashes
Filename, size fieldmarshal-0.0.2-py3-none-any.whl (8.5 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size fieldmarshal-0.0.2.tar.gz (14.1 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page