dataclass-mapper 1.4.0

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 a library auto-generate them for you.

This library makes it easy to autogenerate mappers, makes sure that the types between source and target class match, and that all fields of the target class are actually mapped to. Most of those checks are already done at class definition time, not when the mappings are run. It supports Python’s dataclasses and also Pydantic models, and can also map between those two.

Installation

dataclass-mapper can be installed using:

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

Small 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 to_Person by hand:

@dataclass
class ContactInfo:
    first_name: str
    surname: str
    age: int

    def to_Person(self) -> Person:
        return Person(
            first_name=self.first_name,
            second_name=self.surname,
            age=self.age,
        )

person = some_contact.to_Person()

you can let the mapper autogenerate with:

from dataclass_mapper import map_to, mapper

@mapper(Person, {"second_name": "surname"})
@dataclass
class ContactInfo:
    first_name: str
    surname: str
    age: int

person = map_to(some_contact, Person)

The dataclass-mapper library autogenerated some 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

• pydantic classes

• Checks if all target fields are actually initialized. Raises a ValueError at class definition time when the type is different.

• Checks if the type on the target field is the same as the source field. Raises a TypeError at class definition time when the type is different.

• Recursive dataclasses

• IGNORE_MISSING_MAPPING for values that you don’t wanna set but have a default value/factory.

• Optional types (mapping from an non-optional to an optional field, or to an optional field with default values/fields). Raises a TypeError at class definition time when an optional type is mapped to a non-optional type.

• List types

• Mapper in both direction with mapper and mapper_from.

• Assign Values with lambdas (e.g. {"x": lambda: 42})

• Custom mapping computations with with lambdas (e.g. {"x": lambda self: self.x + 1})

• For Optional fields in Pydantic classes, only set those target fields that actually set in the source (__fields_set__).

• Use Pydantic’s .construct method if no validators are used (can give an up to 30x boost)

• Pydantic’s field aliases (including the allow_population_by_field_name configuration)

• Mappings between enums in both direction with enum_mapper and enum_mapper_from

Still missing features:

• Union types

• Dict types

• Checking if all source attributes were used

• SQLAlchemy ORM / attr

License

The project is released under the MIT license.