Serialization

MODULE	DESCRIPTION
base	Serialization for supporting idempotency
custom_dict
dataclass
functions
no_op
pydantic

base

Serialization for supporting idempotency

CLASS	DESCRIPTION
BaseIdempotencyModelSerializer	Abstract Base Class for Idempotency serialization layer, for using a model as data object representation.
BaseIdempotencySerializer	Abstract Base Class for Idempotency serialization layer, supporting dict operations.

BaseIdempotencyModelSerializer

Bases: BaseIdempotencySerializer

Abstract Base Class for Idempotency serialization layer, for using a model as data object representation.

METHOD	DESCRIPTION
instantiate	Creates an instance of a serializer based on a provided model type.

instantiate abstractmethod classmethod

instantiate(model_type: Any) -> BaseIdempotencySerializer

Creates an instance of a serializer based on a provided model type. In case the model_type is unknown, None will be sent as model_type. It's on the implementer to verify that: - None is handled correctly - A model type not matching the expected types is handled

PARAMETER	DESCRIPTION
model_type	The model type to instantiate the class for TYPE: Any

RETURNS	DESCRIPTION
BaseIdempotencySerializer	Instance of the serializer class

Source code in aws_lambda_powertools/utilities/idempotency/serialization/base.py

@classmethod
@abstractmethod
def instantiate(cls, model_type: Any) -> BaseIdempotencySerializer:
    """
    Creates an instance of a serializer based on a provided model type.
    In case the model_type is unknown, None will be sent as `model_type`.
    It's on the implementer to verify that:
    - None is handled correctly
    - A model type not matching the expected types is handled

    Parameters
    ----------
    model_type: Any
        The model type to instantiate the class for

    Returns
    -------
    BaseIdempotencySerializer
        Instance of the serializer class
    """
    pass

BaseIdempotencySerializer

Bases: ABC

Abstract Base Class for Idempotency serialization layer, supporting dict operations.

custom_dict

CLASS	DESCRIPTION
CustomDictSerializer

CustomDictSerializer

CustomDictSerializer(
    to_dict: Callable[[Any], dict],
    from_dict: Callable[[dict], Any],
)

Bases: BaseIdempotencySerializer

Source code in aws_lambda_powertools/utilities/idempotency/serialization/custom_dict.py

def __init__(self, to_dict: Callable[[Any], dict], from_dict: Callable[[dict], Any]):
    """
    Parameters
    ----------
    to_dict: Callable[[Any], dict]
        A function capable of transforming the saved data object representation into a dictionary
    from_dict: Callable[[dict], Any]
        A function capable of transforming the saved dictionary into the original data object representation
    """
    self.__to_dict: Callable[[Any], dict] = to_dict
    self.__from_dict: Callable[[dict], Any] = from_dict

dataclass

CLASS	DESCRIPTION
DataclassSerializer	A serializer class for transforming data between dataclass objects and dictionaries.

DataclassSerializer

DataclassSerializer(model: type[DataClass])

Bases: BaseIdempotencyModelSerializer

A serializer class for transforming data between dataclass objects and dictionaries.

Source code in aws_lambda_powertools/utilities/idempotency/serialization/dataclass.py

def __init__(self, model: type[DataClass]):
    """
    Parameters
    ----------
    model: type[DataClass]
        A dataclass type to be used for serialization and deserialization
    """
    self.__model: type[DataClass] = model

functions

FUNCTION	DESCRIPTION
get_actual_type	Extract the actual type from a potentially Optional or Union type.

get_actual_type

get_actual_type(model_type: Any) -> Any

Extract the actual type from a potentially Optional or Union type. This function handles types that may be wrapped in Optional or Union, including the Python 3.10+ Union syntax (Type | None).

PARAMETER	DESCRIPTION
model_type	The type to analyze. Can be a simple type, Optional[Type], BaseModel, dataclass TYPE: Any

RETURNS	DESCRIPTION
The actual type without Optional or Union wrappers.
Raises	TYPE: Any

Source code in aws_lambda_powertools/utilities/idempotency/serialization/functions.py

def get_actual_type(model_type: Any) -> Any:
    """
    Extract the actual type from a potentially Optional or Union type.
    This function handles types that may be wrapped in Optional or Union,
    including the Python 3.10+ Union syntax (Type | None).
    Parameters
    ----------
    model_type: Any
        The type to analyze. Can be a simple type, Optional[Type], BaseModel, dataclass
    Returns
    -------
    The actual type without Optional or Union wrappers.
    Raises:
        IdempotencyModelTypeError: If the type specification is invalid
                                   (e.g., Union with multiple non-None types).
    """

    # Get the origin of the type (e.g., Union, Optional)
    origin = get_origin(model_type)

    # Check if type is Union, Optional, or UnionType (Python 3.10+)
    if origin in (Union, Optional) or (sys.version_info >= (3, 10) and origin in (Union, UnionType)):
        # Get type arguments
        args = get_args(model_type)

        # Filter out NoneType
        actual_type = _extract_non_none_types(args)

        # Ensure only one non-None type exists
        if len(actual_type) != 1:
            raise IdempotencyModelTypeError(
                "Invalid type: expected a single type, optionally wrapped in Optional or Union with None.",
            )

        return actual_type[0]

    # If not a Union/Optional type, return original type
    return model_type

no_op

CLASS	DESCRIPTION
NoOpSerializer

NoOpSerializer

NoOpSerializer()

Bases: BaseIdempotencySerializer

Default serializer, does not transform data

Source code in aws_lambda_powertools/utilities/idempotency/serialization/no_op.py

def __init__(self):
    """
    Parameters
    ----------
    Default serializer, does not transform data
    """

pydantic

CLASS	DESCRIPTION
PydanticSerializer	Pydantic serializer for idempotency models

PydanticSerializer

PydanticSerializer(model: type[BaseModel])

Bases: BaseIdempotencyModelSerializer

Pydantic serializer for idempotency models

Source code in aws_lambda_powertools/utilities/idempotency/serialization/pydantic.py

def __init__(self, model: type[BaseModel]):
    """
    Parameters
    ----------
    model: Model
        Pydantic model to be used for serialization
    """
    self.__model: type[BaseModel] = model