Skip to main content

dragon

terramare

python: 3.10+ license: MIT PyPI PyPI - Downloads docs: pages

ci status coverage Checked with mypy Ruff Conventional Commits

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, tomllib.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:

>>> from dataclasses import dataclass
>>> import terramare

>>> @dataclass
... 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 collections.abc import Sequence
>>> from dataclasses import dataclass
>>> from typing import NamedTuple, NewType
>>> 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 f"Occupation('{self.title}', '{self.field}')"


>>> @dataclass
... 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 from Python type hints". 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.

Metadata

Release files for terramare 0.6.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for terramare 0.6.1
File Size Uploaded Provenance Actions
terramare-0.6.1.tar.gz 36.2 kB Without provenance Details for terramare-0.6.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for terramare 0.6.1
File Interpreter ABI Platform Actions
terramare-0.6.1-py3-none-any.whl Python 3 none any Details for terramare-0.6.1-py3-none-any.whl

Total release size: 82.7 kB

Release files / terramare-0.6.1.tar.gz

Download URL terramare-0.6.1.tar.gz
Size 36.2 kB
Tags Source
SHA-256 checksum
How to use checksums
a8f2b9ee7d0d12f5af0fc18083cc46c79743dfd28c5b1535fe0f60f90c54e2bc
BLAKE2b-256 checksum
How to use checksums
52938c099573158dc9dfb737895cdf8ea16f8a14020433e4059d13ac3e5c3a55
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.4.1 CPython/3.12.16 Linux/6.12.113+

Release files / terramare-0.6.1-py3-none-any.whl

Download URL terramare-0.6.1-py3-none-any.whl
Size 46.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
664e449369bb8848342011a2e60da5812cc9971051c77ee0ad9bed93dbbec52f
BLAKE2b-256 checksum
How to use checksums
a6c4d8c2f321bf7dcbab3f7963d4442af65bee288814ca37dbd564491e327c15
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.4.1 CPython/3.12.16 Linux/6.12.113+

Security for terramare 0.6.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page