dataclass-mapper 2.0.0a4
Autogenerate mappings between dataclasses
License: MIT
Requires Python: <4.0,>=3.8
Keywords: dataclass, pydantic, python, automation

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/develop/graphs/badge.svg?branch=develop
    :target: https://codecov.io/gh/dataclass-mapper/dataclass-mapper?branch=develop
    :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, 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:

.. code-block:: bash

   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``.

.. 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, update existing 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 models <https://dataclass-mapper.readthedocs.io/en/latest/pydantic.html>`_
* SQLAlchemy ORM models:  see `SQLAlchemy ORM models <https://dataclass-mapper.readthedocs.io/en/latest/sqlalchemy.html>`_
* Type/Value checks:  see `Type safety <https://dataclass-mapper.readthedocs.io/en/latest/type_safety.html>`_

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 <https://github.com/dataclass-mapper/todo-app-demo>`_.

Contributing
------------

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

License
-------

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