dataclass-mapper 2.0.0a3

Autogenerate mappings between dataclasses

Writing mapper methods between two similar dataclasses is boring, need to be actively maintained and are error-prone. Much better to let this library auto-generate them for you.

The focus of this library is:

• Concise and easy syntax:

  • using it has to be a lot less overhead than writing the mappers by hand

  • trivial mappings should not require code

  • identical syntax for mapping between dataclasses, Pydantic and SQLAlchemy models

• Safety:

  • using this library must give equal or more type safety than writing the mappers by hand

  • the types between source and target classes must matches (including optional checks)

  • all target fields must be actually initialized

  • mappings cannot reference non-existing fields

  • in case of an error a clean exception must be raised

• Performance:

  • mapping an object using this library must be the same speed than mapping using a custom mapper function

  • the type checks shouldn’t slow down the program

  • because of the first two points, all type checks and the generation of the mapper functions happen during the definition of the classes

Motivation

A couple of example usecases, that show why this library might be useful.

• Given an API with multiple, different interfaces (e.g. different API versions), that are all connected to a common algorithm with some common datamodel. All the different API models needs to be mapped to the common datamodel, and afterwards mapped back to the API model.

• Given an API that has a POST and a GET endpoint. Both models (POST request body model and GET response body model) are almost the same, but there are some minor differences. E.g. response model has an additional id parameter. You need a way of mapping the request model to a response model.

Installation

dataclass-mapper can be installed using:

pip install dataclass-mapper
# or for Pydantic support
pip install 'dataclass-mapper[pydantic]'
# or for SQLAlchemy support
pip install 'dataclass-mapper[sqlalchemy]'

Example

We have the following target data structure, a class called Person.

>>> from dataclasses import dataclass

>>> @dataclass
... class Person:
...     first_name: str
...     second_name: str
...     age: int

We want to have a mapper from the source data structure, a class called ContactInfo. Notice that the attribute second_name of Person is called surname in ContactInfo. Other than that, all the attribute names are the same.

Instead of writing a mapper function by hand, you can let it autogenerate one using this library:

>>> from dataclass_mapper import map_to, mapper
>>>
>>> @mapper(Person, {"second_name": "surname"})
... @dataclass
... class ContactInfo:
...     first_name: str
...     surname: str
...     age: int
>>>
>>> contact = ContactInfo(first_name="Henry", surname="Kaye", age=42)
>>> map_to(contact, Person)
Person(first_name='Henry', second_name='Kaye', age=42)

The dataclass-mapper library autogenerated a mapper, that can be used with the map_to function. All we had to specify was the name of the target class, and optionally specify which fields map to which other fields. Notice that we only had to specify that the second_name field has to be mapped to surname, all other fields were mapped automatically because the field names didn’t change.

And the dataclass-mapper library will perform a lot of checks around this mapping. It will check if the data types match, if some fields would be left uninitialized, etc.

Features

The current version has support for:

• Python’s dataclass (with recursive models, update existing models, custom initializers, optional types, extra-context, …): see Supported features for the full list and examples

• Mappings between Enum classes: see Enum mappings

• Pydantic models: see Pydantic models

• SQLAlchemy ORM models: see SQLAlchemy ORM models

• Type/Value checks: see Type safety

Demo project

We maintain a small demo project, whichs shows some of the interworkings of the library together with a FastAPI API and SQLAlchemy ORM: todo-app-demo.

Contributing

See CONTRIBUTING.rst.

License

The project is released under the MIT license.