terramare

Automatically construct complex objects from simple Python types.

Highlights:

• No boilerplate: terramare uses Python's standard type hints to determine how to construct instances of a class;
• Format-agnostic: terramare takes simple Python types as input - pass it the output from json.load, toml.load, or yaml.load;
• Non-invasive: terramare requires no modifications to your existing classes and functions beyond standard type hints;

Full documentation available at https://tomwatson1024.gitlab.io/terramare/.

Example

Deserializing a Simple Class

Consider the following simple class, defined using attrs for brevity:

>>> from typing import List
>>> import attr
>>> import terramare

>>> @attr.s(auto_attribs=True)
... class Example:
...     words: List[str]
...
...     def __str__(self):
...         return " ".join(self.words)

Deserializing an instance of the class from a dictionary is as simple as:

>>> print(terramare.structure({"words": ["hello", "world!"]}, into=Example))
hello world!

Deserializing a More Complex Class

Consider the Person class defined below:

>>> from typing import NamedTuple, NewType, Sequence
>>> import attr
>>> import terramare

    # `terramare` handles NamedTuples
>>> class Location(NamedTuple):
...     longitude: float
...     latitude: float


    # `terramare` handles NewType aliases
>>> JobTitle = NewType("JobTitle", str)


    # `terramare` handles custom classes [experimental]
>>> @terramare.auto
... class Occupation:
...     def __init__(self, title: JobTitle, field: str):
...         self.title = title
...         self.field = field
...
...     def __eq__(self, other):
...         if isinstance(other, self.__class__):
...             return vars(self) == vars(other)
...         return False
...
...     def __repr__(self):
...         return "Occupation('{0.title}', '{0.field}')".format(self)


>>> @attr.s(auto_attribs=True)
... class Person:
...     name: str
...     age: int
...     friends: Sequence[str]
...
...     # `terramare` handles complex member variable types
...     location: Location
...     occupation: Occupation

Again, deserialization is a single function call:

>>> terramare.structure(
...     {
...         "name": "Alice",
...         "age": 20,
...         "friends": ["Bob", "Charlie"],
...         "location": [51.5074, 0.1278],
...         "occupation": {"title": "programmer", "field": "technology"}
...     },
...     into=Person,
... )
Person(name='Alice', age=20, friends=['Bob', 'Charlie'], location=Location(longitude=51.5074, latitude=0.1278), occupation=Occupation('programmer', 'technology'))

Installation

Install using pip:

pip install terramare

Alternatives

Check out:

• pydantic - "Data validation and settings management using python type annotations". A much more mature library also using Python's standard type hints for deserialization that requires a little more integration with your code;
• schematics - "...combine types into structures, validate them, and transform the shapes of your data based on simple descriptions". Uses custom types instead of Python's standard type hints;
• cerberus - "...provides powerful yet simple and lightweight data validation functionality out of the box and is designed to be easily extensible, allowing for custom validation". Schema validation that doesn't change the type of the primitive value.