py-automapper: Object Mapping Library

Common errors

• NameError: name 'Automapper' is not defined

  cause Attempting to use the `Automapper` class which was removed in `v2.0.0`.
  fix Replace usage of `Automapper` class with direct calls to the `automap` function: `from py_automapper import automap`.

• TypeError: automap() got multiple values for argument 'destination_type' (or similar signature error for destination object)

  cause Passing an instance of the destination object (e.g., `DestinationClass()`) instead of the destination class (e.g., `DestinationClass`) to `automap` after v2.0.0.
  fix Modify the `automap` call to pass the destination *type* (class) as the second argument, e.g., `automap(source_obj, DestinationClass)`.

• TypeError: automap() got an unexpected keyword argument 'map_config'

  cause Using the old keyword argument name `map_config` which was renamed to `mapping_cfg` in `v2.0.0`.
  fix Update the argument name from `map_config` to `mapping_cfg` in your `automap` calls.

• AttributeError: 'SourceDTO' object has no attribute 'full_name' (or similar for an unmatched field)

  cause The destination object has a field (e.g., `full_name`) that does not exist in the source object and no custom mapping or function was provided for it.
  fix Provide a `mapping_cfg` dictionary to specify how the destination field should be populated, or use `func_cfg` for complex transformations. For example: `mapping_cfg={'first_name': 'full_name'}` or `func_cfg={'full_name': lambda src: f'{src.first_name} {src.last_name}'}`.

Warnings

• breaking The `automap` function signature changed significantly in v2.0.0. It now expects the destination *type* (class) as the second argument, not an instance. The `Automapper` class was also removed.
  Fix: Update calls to `automap` to pass the destination class, e.g., `automap(source_obj, DestinationClass)` instead of `automap(source_obj, DestinationClass())`.
• breaking The argument for custom field mapping was renamed from `map_config` to `mapping_cfg` in v2.0.0.
  Fix: Replace `map_config=...` with `mapping_cfg=...` in `automap` calls.
• breaking The `automap_list` function was removed in v2.0.0. For mapping lists, use the `automap` function with a `list` type hint for the destination and pass `many=True`.
  Fix: Change `automap_list(source_list, Destination)` to `automap(source_list, List[Destination], many=True)`.
• gotcha If source and destination field names do not match exactly, `automap` will raise an `AttributeError` unless a `mapping_cfg` dictionary is provided.
  Fix: Always provide a `mapping_cfg` dictionary when field names differ, or use `func_cfg` for value transformations.

Install

• pip install py-automapper Install stable version

Imports

• automap
  wrong:

  from py_automapper import Automapper

  correct:

  from py_automapper import automap

  The Automapper class was removed in v2.0.0; use the automap function directly.

Quickstart

This quickstart demonstrates how to map a SourceDTO object to a UserDomainModel. It includes mapping configuration for different field names and a function configuration for custom value transformations, specifically concatenating first and last names into a full name.

from py_automapper import automap

class SourceDTO:
    def __init__(self, first_name: str, last_name: str, age: int):
        self.first_name = first_name
        self.last_name = last_name
        self.age = age

class UserDomainModel:
    def __init__(self, full_name: str, years_old: int):
        self.full_name = full_name
        self.years_old = years_old

source_data = SourceDTO(first_name="Alice", last_name="Smith", age=30)

# Map with custom field names and a transformation function
domain_model = automap(
    source_data,
    UserDomainModel,
    mapping_cfg={
        "first_name": "full_name",
        "last_name": lambda src: src.last_name, # Can also use lambdas for complex transformations
        "age": "years_old"
    },
    func_cfg={
        "full_name": lambda src: f"{src.first_name} {src.last_name}"
    }
)

print(f"Full Name: {domain_model.full_name}")
print(f"Years Old: {domain_model.years_old}")