dataclass-mapper

Register mappings

dataclass_mapper.create_mapper(SourceCls: Any, TargetCls: Any, mapping: Optional[Dict[Union[str, InstrumentedAttribute], Union[str, Callable[[], Any], Callable[[Any], Any], Ignore, AssumeNotNone, FromExtra, UpdateOnlyIfSet, Spezial, InstrumentedAttribute]]] = None, mapper_mode: MapperMode = MapperMode.CREATE_AND_UPDATE) → None

Creates a private mapper method, that maps the SourceCls to the TargetCls. The mapper method can be called using the map_to() function.

Parameters:

SourceCls – the class (source class) that you want to map an object from to the current (target) class.
TargetCls – The class (target class) that you want to map an object of the current (source) class to.
mapping –
An optional dictionary which which it’s possible to describe how each field in the target class gets initialized. Fields that are not specified will be mapped automatically. Every single field in the target class must have some mapping (in order to not forget about a field), either a default mapping (if the field names match), or an explicit mapping definition with this mapping parameter.
- {"x": "y"} means, that the field x of the target object will be initialized with the value of the y fields in the source object.
- {"x": lambda: 42} means, that the field x will be initialized with the value 42.
- {"x": lambda self: self.x + 1} means, that the field x will be initialized with the incremented value x of the source object.
- {"x": USE_DEFAULT} (deprecated) means, nothing is mapped to the field x, it will just be initialized with the default value / factory of that field, or simply ignored during an update.
- {"x": IGNORE_MISSING_MAPPING} (deprecated) means, nothing is mapped to the field x, it will just be initialized with the default value / factory of that field, or simply ignored during an update.
- {"x": init_with_default()} means, nothing is mapped to the field x, it will just be initialized with the default value / factory of that field, or simply ignored during an update.
- {"x": ignore()} means, nothing is mapped to the field x, it will just be initialized with the default value / factory of that field, or simply ignored during an update.
- {"x": assume_not_none("y")} means, that the target field x will be initialized with the value of the y source field, and the library will assume that the source field is not None. If no source field name is given, it will additionally assume that the source field is also called x.
- {"x": provide_with_extra()} means, that you don’t fill this field with any field of the source class, but with the extra dictionary given by the map_to() method.
mapper_mode – Per default the mapping is used both for creating a new object, and for updating an existing object. With mapper_mode you can change it, so that it is only used for only creating new objects or only for updating existing objects.

dataclass_mapper.mapper(TargetCls: Any, mapping: Optional[Dict[Union[str, InstrumentedAttribute], Union[str, Callable[[], Any], Callable[[Any], Any], Ignore, AssumeNotNone, FromExtra, UpdateOnlyIfSet, Spezial, InstrumentedAttribute]]] = None, mapper_mode: MapperMode = MapperMode.CREATE_AND_UPDATE) → Callable[[T], T]

Class decorator that adds a private mapper method, that maps the current class to the TargetCls. The mapper method can be called using the map_to() function.

Parameters:

TargetCls – The class (target class) that you want to map an object of the current (source) class to.
mapping – an optional dictionary which which it’s possible to describe how each field in the target class gets initialized (see create_mapper())
mapper_mode – Per default the mapping is used both for creating a new object, and for updating an existing object. With mapper_mode you can change it, so that it is only used for only creating new objects or only for updating existing objects.

dataclass_mapper.mapper_from(SourceCls: Any, mapping: Optional[Dict[Union[str, InstrumentedAttribute], Union[str, Callable[[], Any], Callable[[Any], Any], Ignore, AssumeNotNone, FromExtra, UpdateOnlyIfSet, Spezial, InstrumentedAttribute]]] = None, mapper_mode: MapperMode = MapperMode.CREATE_AND_UPDATE) → Callable[[T], T]

Class decorator that adds a private mapper method, that maps an object of SourceCls to the current class. The mapper method can be called using the map_to() function.

Parameters:

SourceCls – the class (source class) that you want to map an object from to the current (target) class.
mapping – an optional dictionary which which it’s possible to describe how each field in the target class gets initialized (see create_mapper())
mapper_mode – Per default the mapping is used both for creating a new object, and for updating an existing object. With mapper_mode you can change it, so that it is only used for only creating new objects or only for updating existing objects.

dataclass_mapper.init_with_default() → Ignore: Initialize the target field with the default value, or default factory.

dataclass_mapper.ignore() → Ignore: If the mapping operation creates a new object, it will initialize the target field with the default value, or default factory. If the mapping operation updates a field, it will simply ignore that field and keep the old value.

dataclass_mapper.assume_not_none(field_name: Optional[str] = None) → AssumeNotNone: Assume that the source field is not none, even if it is an optional field. Allows a mapping from Optional[T] to T. If the field name is not specified, it is assumed that the source field has the same name as the target field.

dataclass_mapper.from_extra(name: str) → FromExtra: Don’t map this field using a source class field, fill it with a dictionary called extra duing map_to.

dataclass_mapper.update_only_if_set(field_name: Optional[str] = None) → UpdateOnlyIfSet: Only update the target field, if the source field is not None. Therefore this allows a mapping from Optional[T] to T. If the field name is not specified, it is assumed that the source field has the same name as the target field.

enum dataclass_mapper.MapperMode(value)

Enum that controlls which types of mappers should be created. By default it will create both a create and an update mapper. If the classes are however only used for one of the operations, it’s best practice to limit the scope. Then an exception is thrown, if somebody uses the classes in an unintentional way. The MapperMode.UPDATE mode is also not as strict, when it comes to filling all fields (as the target object already has them filled).

Valid values are as follows:

CREATE = <MapperMode.CREATE: 1>: only create a mapper for creating new objects

UPDATE = <MapperMode.UPDATE: 2>: only create a mapper for updating existing objects

CREATE_AND_UPDATE = <MapperMode.CREATE_AND_UPDATE: 3>: create mappers for both creating new objects and updating existing objects

Register enum mappings

dataclass_mapper.create_enum_mapper(SourceCls: Any, TargetCls: Any, mapping: Optional[Dict[Union[str, Enum], Union[str, Enum]]] = None) → None

Creates a private mapper method, that maps the enum class SourceCls to the enum class TargetCls. The mapper method can be called using the map_to() function.

Parameters:

SourceCls – The enum class (source class) that you want to map an object of the current (source) enum class to.
TargetCls – The enum class (source class) that you want to map members from to the current (target) enum class to.
mapping –
An optional dictionary which which it’s possible to describe to which member of the target class a member of the source class is mapped to. Key/value of the mapping can either be the names of the enum members, or the members themselves. Fields that are not specified will be mapped automatically. Every single field in the source class must have some mapping, either a default mapping (if the member names match), or an explicit mapping definition with this mapping parameter.
- {"x": "y"} means, that the member x of the source enum will get mapped to the member y in the target object.

dataclass_mapper.enum_mapper(TargetCls: Any, mapping: Optional[Dict[Union[str, Enum], Union[str, Enum]]] = None) → Callable[[T], T]

Class decorator that adds a private mapper method, that maps the current enum class to the enum class TargetCls. The mapper method can be called using the map_to() function.

Parameters:

TargetCls – The enum class (source class) that you want to map members from to the current (target) enum class to.
mapping – An optional dictionary which which it’s possible to describe to which member of the target class a member of the source class is mapped to (see create_enum_mapper()).

dataclass_mapper.enum_mapper_from(SourceCls: Any, mapping: Optional[Dict[Union[str, Enum], Union[str, Enum]]] = None) → Callable[[T], T]

Class decorator that adds a private mapper method, that maps members of the enum class SourceCls to members of the current enum class. The mapper method can be called using the map_to() function.

Parameters:

SourceCls – The enum class (source class) that you want to map an object of the current (source) enum class to.
mapping – An optional dictionary which which it’s possible to describe to which member of the target class a member of the source class is mapped to (see create_enum_mapper()).

Convert an object

dataclass_mapper.map_to(obj, target: Type[T], extra: Optional[Dict[str, Any]] = None) → T

dataclass_mapper.map_to(obj, target: T, extra: Optional[Dict[str, Any]] = None) → T

Given a target class, it will create a new object of that type using the defined mapping. Given a target object, it will update that object using the defined mapping.

If no suitable mapping was defined for the type, it will raise an NotImplementedError.

Parameters:

obj – the source object that you want to map to an object of type TargetCls
target – the target or the target class that you want to map to.
extra – dictionary with the values for the provide_with_extra() fields

Returns:

the mapped object