API Reference

Convert an object from one type to anothere

mappr.convert

convert(
    dst_type: Type[T],
    src_obj: Any,
    strict: bool = True,
    strategy: Optional[Strategy] = None,
    **extra: Any,
) -> T

Convert an object to a given type.

PARAMETER	DESCRIPTION
dst_type	Target type. This is the type of the return value. TYPE: Type[T]
src_obj	An object to convert. A registered converter will be used to map between the attributes of this object and the target type. TYPE: Any
strict	If set to False and the converter is not found for the given type pair, it will create an ad-hoc one that maps the attributes by their name. Defaults to True TYPE: bool DEFAULT: True
strategy	Creation strategy TYPE: Optional[Strategy] DEFAULT: None
extra	Extra arguments to pass to the converter. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
T	A newly created instance of dst_type with values initialized
T	from src_obj.

Register new converter

mappr.register

register(
    src_type: Type,
    dst_type: Type,
    strategy: Strategy = Strategy.CONSTRUCTOR,
    mapping: Optional[FieldMapping] = None,
    strict: bool = True,
)

Register new converter.

PARAMETER	DESCRIPTION
src_type	TYPE: Type
dst_type	TYPE: Type
strategy	TYPE: Strategy DEFAULT: CONSTRUCTOR
mapping	TYPE: Optional[FieldMapping] DEFAULT: None
strict	TYPE: bool DEFAULT: True

Returns:

mappr.register_iso

register_iso(
    src_type: Type,
    dst_type: Type,
    strategy: Strategy = Strategy.CONSTRUCTOR,
    mapping: Optional[Dict[str, str]] = None,
    strict: bool = True,
)

mappr.custom_converter

custom_converter(
    src_type: Type[T_src],
    dst_type: Type[T_dst],
    strategy: Strategy = Strategy.CONSTRUCTOR,
    strict: bool = True,
)

Decorator for registering a custom conversion functions.

Built-in field mappers

mappr.use_default

use_default(value: Any, extra: Values) -> Any

Indicate we want to use default field value rather than value from source object

By default, if the attribute exists on the source object, it's value will be used when creating the result. That happens even if the destination type defines a default value for that field. If you want to use the default provided by the target type you can achive that with mappr.use_default mapper. You simply set the field to mappr.use_default and the attribute value from the source object won't be used (the target default is used). If the target type does not define a default value an exception will be raised during the creation of the final result.

Example:

>>> from dataclasses import dataclass
>>> import mappr
>>>
>>> @dataclass
... class Src:
...     text: str = 'hello'
...     num: int = 10
>>>
>>> @dataclass
... class Dst:
...     text: str
...     num: int = 20
>>>
>>> mappr.register(Src, Dst, mapping=dict(
...     num=mappr.use_default
... ))
>>>
>>> src = Src()
>>> dst = mappr.convert(Dst, src)
>>>
>>> dst.text
'hello'
>>> dst.num
20

mappr.set_const

set_const(value: Any) -> types.MappingFn

Always set the field to the given value during conversion.

You can use mappr.set_const if you want to set an attribute to a constant value during conversion, without concern about the source object. Every call to mappr.convert will return the same value.

PARAMETER	DESCRIPTION
value	The value to set on the field. Instead of using the source object attribute or target type field default, this value will be set on the field during conversion. TYPE: Any

RETURNS	DESCRIPTION
MappingFn	A mapping function.

Example:

>>> from dataclasses import dataclass
>>> import mappr
>>>
>>> @dataclass
... class Src:
...     text: str = 'hello'
...     num: int = 10
>>>
>>> @dataclass
... class Dst:
...     text: str
...     num: int = 20
>>>
>>> mappr.register(Src, Dst, mapping=dict(
...     num=mappr.set_const(100)
... ))
>>>
>>> src = Src()
>>> dst = mappr.convert(Dst, src)
>>>
>>> dst.text
'hello'
>>> dst.num
100

mappr.alias

alias(aliased_name: str) -> types.MappingFn

The value in the src object has just a different name than in the dst object.

Define field iterator for a custom type

mappr.field_iterator

field_iterator(test=types.TestFn)