https://github.com/trendels/fieldmarshal

https://github.com/trendels/fieldmarshal

attrs json marshalling serialization

Last synced: 6 days ago
JSON representation

• Host: GitHub
• URL: https://github.com/trendels/fieldmarshal
• Owner: trendels
• License: mit
• Created: 2019-11-09T21:40:32.000Z (about 5 years ago)
• Default Branch: main
• Last Pushed: 2021-05-07T08:41:49.000Z (over 3 years ago)
• Last Synced: 2024-09-21T21:42:28.880Z (about 2 months ago)
• Topics: attrs, json, marshalling, serialization
• Language: Python
• Homepage: https://fieldmarshal.readthedocs.io/
• Size: 46.9 KB
• Stars: 0
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

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

[![Build Status](https://travis-ci.org/trendels/fieldmarshal.svg?branch=master)](https://travis-ci.org/trendels/fieldmarshal)

**Note: This is module is still in development - APIs might change in

backwards-incompatible ways.**

## Example

~~~python

>>> 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:

~~~python

>>> 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][1]-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.

Features:

-   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. `Union`s)

-   Built-in handling of common cases, such as `Enums`, simple `Union`s.

-   Limited support for non-string dict keys (bool, int, float, Enum).

-   Tries to be unobtrusive: Does not require subclassing and can work with

    plain `attr`s-based classes.

The API is inspired by Go's [`json.Marshal/json.Unmarshal`][2] and [cattrs][3].

[1]: https://www.attrs.org/

[2]: https://golang.org/pkg/encoding/json/

[3]: https://pypi.org/project/cattrs/