Topics

#mapper #mapping #object-mapper #object-mapping #objectmapper #python #python3

Language breakdown

No language data available.

▸ Files click to expand

README

py-automapper

[!IMPORTANT]

Renewing maintanance of this library!

>

After a long pause, I see the library is still in use and receives more stars. Thank you all who likes and uses it. So, I renew the py-automapper maintanance.

Expect fixes and new version soon.

Build Status

Table of Contents:

Versions
About
Contribute
Usage

- Installation - Get started - Map dictionary source to target object - Different field names - Overwrite field value in mapping - Disable Deepcopy - Extensions - Pydantic/FastAPI Support - TortoiseORM Support - SQLAlchemy Support - Create your own extension (Advanced)

Versions

Check CHANGELOG.md

About

Python auto mapper is useful for multilayer architecture which requires constant mapping between objects from separate layers (data layer, presentation layer, etc).

Inspired by: object-mapper

The major advantage of py-automapper is its extensibility, that allows it to map practically any type, discover custom class fields and customize mapping rules. Read more in documentation.

Contribute

Read CONTRIBUTING.md guide.

Usage

Installation

Install package:

pip install py-automapper

Get started

Let's say we have domain model UserInfo and its API representation PublicUserInfo without exposing user age:

class UserInfo:
    def init(self, name: str, profession: str, age: int):
        self.name = name
        self.profession = profession
        self.age = age
class PublicUserInfo:     def init(self, name: str, profession: str):         self.name = name         self.profession = profession
user_info = UserInfo("John Malkovich", "engineer", 35)

To create PublicUserInfo object:

from automapper import mapper
publicuserinfo = mapper.to(PublicUserInfo).map(user_info)
print(vars(publicuserinfo)) {'name': 'John Malkovich', 'profession': 'engineer'}

You can register which class should map to which first:

# Register mapper.add(UserInfo, PublicUserInfo)
publicuserinfo = mapper.map(user_info)
print(vars(publicuserinfo)) {'name': 'John Malkovich', 'profession': 'engineer'}

Map dictionary source to target object

If source object is dictionary:

source = {
    "name": "John Carter",
    "profession": "hero"
}
public_info = mapper.to(PublicUserInfo).map(source)
print(vars(public_info)) {'name': 'John Carter', 'profession': 'hero'}

Different field names

If your target class field name is different from source class.

class PublicUserInfo:
    def init(self, full_name: str, profession: str):
        self.fullname = fullname       # UserInfo has name instead
        self.profession = profession

Simple map:

publicuserinfo = mapper.to(PublicUserInfo).map(userinfo, fieldsmapping={
    "fullname": userinfo.name
})

Preregister and map. Source field should start with class name followed by period sign and field name:

mapper.add(UserInfo, PublicUserInfo, fieldsmapping={"fullname": "UserInfo.name"})
publicuserinfo = mapper.map(user_info)
print(vars(publicuserinfo)) {'full_name': 'John Malkovich', 'profession': 'engineer'}

Overwrite field value in mapping

Very easy if you want to field just have different value, you provide a new value:

publicuserinfo = mapper.to(PublicUserInfo).map(userinfo, fieldsmapping={
    "full_name": "John Cusack"
})
print(vars(publicuserinfo)) {'full_name': 'John Cusack', 'profession': 'engineer'}

Disable Deepcopy

By default, py-automapper performs a recursive copy.deepcopy() call on all attributes when copying from source object into target class instance. This makes sure that changes in the attributes of the source do not affect the target and vice versa. If you need your target and source class share same instances of child objects, set use_deepcopy=False in map function.

from dataclasses import dataclass
from automapper import mapper
@dataclass class Address:     street: str     number: int     zip_code: int     city: str    class PersonInfo:     def init(self, name: str, age: int, address: Address):         self.name = name         self.age = age         self.address = address
class PublicPersonInfo:     def init(self, name: str, address: Address):         self.name = name         self.address = address
address = Address(street="Main Street", number=1, zip_code=100001, city='Test City') info = PersonInfo('John Doe', age=35, address=address)
default deepcopy behavior
public_info = mapper.to(PublicPersonInfo).map(info)
print("Target publicinfo.address is same as source address: ", address is publicinfo.address)
Target public_info.address is same as source address: False
disable deepcopy
publicinfo = mapper.to(PublicPersonInfo).map(info, usedeepcopy=False)
print("Target publicinfo.address is same as source address: ", address is publicinfo.address)
Target public_info.address is same as source address: True

Extensions

py-automapper has few predefined extensions for mapping support to classes for frameworks:

Pydantic/FastAPI Support

Out of the box Pydantic models support:

from pydantic import BaseModel
from typing import List
from automapper import mapper
class UserInfo(BaseModel):     id: int     full_name: str     public_name: str     hobbies: List[str]
class PublicUserInfo(BaseModel):     id: int     public_name: str     hobbies: List[str]
obj = UserInfo(     id=2,     full_name="Danny DeVito",     public_name="dannyd",     hobbies=["acting", "comedy", "swimming"] )
result = mapper.to(PublicUserInfo).map(obj) 
same behaviour with preregistered mapping

print(vars(result)) {'id': 2, 'public_name': 'dannyd', 'hobbies': ['acting', 'comedy', 'swimming']}

TortoiseORM Support

Out of the box TortoiseORM models support:

from tortoise import Model, fields
from automapper import mapper
class UserInfo(Model):     id = fields.IntField(primary_key=True)     full_name = fields.TextField()     public_name = fields.TextField()     hobbies = fields.JSONField()
class PublicUserInfo(Model):     id = fields.IntField(primary_key=True)     public_name = fields.TextField()     hobbies = fields.JSONField()
obj = UserInfo(     id=2,     full_name="Danny DeVito",     public_name="dannyd",     hobbies=["acting", "comedy", "swimming"],     using_db=True )
result = mapper.to(PublicUserInfo).map(obj) 
same behaviour with preregistered mapping

filtering out protected fields that start with underscore "_..."
print({key: value for key, value in vars(result) if not key.startswith("_")})
{'id': 2, 'public_name': 'dannyd', 'hobbies': ['acting', 'comedy', 'swimming']}

SQLAlchemy Support

Out of the box SQLAlchemy models support:

from sqlalchemy.orm import declarative_base
from sqlalchemy import Column, Integer, String
from automapper import mapper
Base = declarative_base()
class UserInfo(Base):     tablename = "users"     id = Column(Integer, primary_key=True)     full_name = Column(String)     public_name = Column(String)     hobbies = Column(String)     def repr(self):         return "<User(fullname='%s', publicname='%s', hobbies='%s')>" % (             self.full_name,             self.public_name,             self.hobbies,         )
class PublicUserInfo(Base):     tablename = 'public_users'     id = Column(Integer, primary_key=True)     public_name = Column(String)     hobbies = Column(String)      obj = UserInfo(             id=2,             full_name="Danny DeVito",             public_name="dannyd",             hobbies="acting, comedy, swimming",         )
result = mapper.to(PublicUserInfo).map(obj) 
same behaviour with preregistered mapping

filtering out protected fields that start with underscore "_..."
print({key: value for key, value in vars(result) if not key.startswith("_")})
{'id': 2, 'public_name': 'dannyd', 'hobbies': "acting, comedy, swimming"}

Create your own extension (Advanced)

When you first time import mapper from automapper it checks default extensions and if modules are found for these extensions, then they will be automatically loaded for default mapper object.

What does extension do? To know what fields in Target class are available for mapping, py-automapper needs to know how to extract the list of fields. There is no generic way to do that for all Python objects. For this purpose py-automapper uses extensions.

List of default extensions can be found in /automapper/extensions folder. You can take a look how it's done for a class with init method or for Pydantic or TortoiseORM models.

You can create your own extension and register in mapper:

from automapper import mapper
class TargetClass:     def init(self, **kwargs):         self.name = kwargs["name"]         self.age = kwargs["age"]          @staticmethod     def get_fields(cls):         return ["name", "age"]
source_obj = {"name": "Andrii", "age": 30}
try:     # Map object     targetobj = mapper.to(TargetClass).map(sourceobj) except Exception as e:     print(f"Exception: {repr(e)}")     # Output:     # Exception: KeyError('name')
# mapper could not find list of fields from BaseClass     # let's register extension for class BaseClass and all inherited ones     mapper.addspec(TargetClass, TargetClass.getfields)     targetobj = mapper.to(TargetClass).map(sourceobj)
print(f"Name: {targetobj.name}; Age: {targetobj.age}")

You can also create your own clean Mapper without any extensions and define extension for very specific classes, e.g. if class accepts kwargs parameter in init method and you want to copy only specific fields. Next example is a bit complex but probably rarely will be needed:

from typing import Type, TypeVar
from automapper import Mapper
Create your own Mapper object without any predefined extensions
mapper = Mapper()
class TargetClass:     def init(self, **kwargs):         self.data = kwargs.copy()
@classmethod     def fields(cls):         return ["name", "age", "profession"]
source_obj = {"name": "Andrii", "age": 30, "profession": None}
try:     targetobj = mapper.to(TargetClass).map(sourceobj) except Exception as e:     print(f"Exception: {repr(e)}")     # Output:     # Exception: MappingError("No spec function is added for base class of <class 'type'>")
Instead of using base class, we define spec for all classes that have fields property
T = TypeVar("T")
def classhasfieldsproperty(targetcls: Type[T]) -> bool:     return callable(getattr(target_cls, "fields", None))      mapper.addspec(classhasfieldsproperty, lambda t: getattr(t, "fields")())
targetobj = mapper.to(TargetClass).map(sourceobj) print(f"Name: {targetobj.data['name']}; Age: {targetobj.data['age']}; Profession: {target_obj.data['profession']}") 
Output:
 Name: Andrii; Age: 30; Profession: None

Skip None value
targetobj = mapper.to(TargetClass).map(sourceobj, skipnonevalues=True)
print(f"Name: {targetobj.data['name']}; Age: {targetobj.data['age']}; Has profession: {hasattr(target_obj, 'profession')}")
Output:
Name: Andrii; Age: 30; Has profession: False