dataclass-mapper

dataclass-mapper

|pypi| |support| |licence| |readthedocs| |build| |coverage|

.. |pypi| image:: https://img.shields.io/pypi/v/dataclass-mapper.svg?style=flat-square :target: https://pypi.org/project/dataclass-mapper/ :alt: pypi version

.. |support| image:: https://img.shields.io/pypi/pyversions/dataclass-mapper.svg?style=flat-square :target: https://pypi.org/project/dataclass-mapper/ :alt: supported Python version

.. |build| image:: https://github.com/dataclass-mapper/dataclass-mapper/actions/workflows/test.yml/badge.svg :target: https://github.com/dataclass-mapper/dataclass-mapper/actions :alt: build status

.. |coverage| image:: https://codecov.io/gh/dataclass-mapper/dataclass-mapper/branch/main/graphs/badge.svg?branch=main :target: https://codecov.io/gh/dataclass-mapper/dataclass-mapper?branch=main :alt: Code coverage

.. |licence| image:: https://img.shields.io/pypi/l/dataclass-mapper.svg?style=flat-square :target: https://pypi.org/project/dataclass-mapper/ :alt: licence

.. |readthedocs| image:: https://img.shields.io/readthedocs/dataclass-mapper/latest.svg?style=flat-square&label=Read%20the%20Docs :alt: Read the documentation at https://dataclass-mapper.readthedocs.io/en/latest/ :target: https://dataclass-mapper.readthedocs.io/en/latest/

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

.. code-block:: bash

pip install dataclass-mapper

or for Pydantic support

pip install 'dataclass-mapper[pydantic]'

Example

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

.. code-block:: python

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:

.. code-block:: python

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, custom initializers, optional types, extra-context, ...): see Supported features <https://dataclass-mapper.readthedocs.io/en/latest/features.html>_ for the full list and examples
• Mappings between Enum classes: see Enum mappings <https://dataclass-mapper.readthedocs.io/en/latest/enums.html>_
• Pydantic models: see Pydantic support <https://dataclass-mapper.readthedocs.io/en/latest/pydantic.html>_
• Type/Value checks: see Type safety <https://dataclass-mapper.readthedocs.io/en/latest/type_safety.html>_

Contributing

See CONTRIBUTING.rst <https://github.com/dataclass-mapper/dataclass-mapper/blob/main/CONTRIBUTING.rst>_.

License

The project is released under the MIT license <https://github.com/dataclass-mapper/dataclass-mapper/blob/main/LICENSE.md>_.