Skip to content

Commit 58197b4

Browse files
fix(idempotency): resolve postponed return annotations for serializer classes (#8738)
* fix(idempotency): resolve postponed return annotations for serializer classes With `from __future__ import annotations`, every annotation is a string. idempotent_function passed function.__annotations__["return"] straight to PydanticSerializer.instantiate, which ran issubclass() on a string and raised TypeError at decoration time, so the module failed to import. DataclassSerializer had the same root cause and rejected every postponed annotation with IdempotencyModelTypeError. Resolve the return annotation with typing.get_type_hints, falling back to the annotation as written when it can't be resolved (e.g. a model defined inside another function), which keeps today's behaviour for those cases. Guard PydanticSerializer.instantiate with inspect.isclass so annotations that aren't classes, like list[Model], raise IdempotencyModelTypeError instead of TypeError. * fix(idempotency): preserve return annotation inference compatibility Resolve only postponed return annotations, retaining evaluated types and custom Annotated metadata. Unrelated type-only parameters and no_type_check must not prevent serializer construction. Retrieve native deferred annotations safely on Python 3.14 and reject parameterized model aliases before subclass checks on Python 3.10. --------- Co-authored-by: Leandro Damascena <lcdama@amazon.pt>
1 parent 8932649 commit 58197b4

7 files changed

Lines changed: 340 additions & 7 deletions

File tree

‎aws_lambda_powertools/utilities/idempotency/idempotency.py‎

Lines changed: 32 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,10 @@
77
import functools
88
import logging
99
import os
10+
import sys
1011
import warnings
11-
from inspect import isclass
12-
from typing import TYPE_CHECKING, Any, Protocol, TypeVar, cast
12+
from inspect import isclass, unwrap
13+
from typing import TYPE_CHECKING, Any, Protocol, TypeVar, cast, get_type_hints
1314

1415
from aws_lambda_powertools.middleware_factory import lambda_handler_decorator
1516
from aws_lambda_powertools.shared import constants
@@ -145,6 +146,34 @@ def handler(event, context):
145146
idempotent = cast(_IdempotentDecorator, _idempotent)
146147

147148

149+
def _get_return_annotation(function: Callable) -> Any:
150+
"""Resolve only the return annotation, preserving evaluated types and custom metadata."""
151+
if sys.version_info >= (3, 14):
152+
from annotationlib import Format, get_annotations
153+
154+
# Deferred annotations can contain parameter names that only exist during type checking.
155+
annotation = get_annotations(function, format=Format.FORWARDREF).get("return")
156+
else:
157+
annotation = getattr(function, "__annotations__", {}).get("return")
158+
159+
if not isinstance(annotation, str):
160+
return annotation
161+
162+
def return_type(): ...
163+
164+
# A separate function avoids evaluating input annotations or copying __no_type_check__.
165+
return_type.__annotations__ = {"return": annotation}
166+
try:
167+
return get_type_hints(
168+
return_type,
169+
globalns=getattr(unwrap(function), "__globals__", {}),
170+
include_extras=True,
171+
)["return"]
172+
except Exception:
173+
# Let the serializer report an unsupported model, as for other invalid annotations.
174+
return annotation
175+
176+
148177
def idempotent_function(
149178
function: AnyCallableT | None = None,
150179
*,
@@ -208,7 +237,7 @@ def process_order(customer_id: str, order: dict, **kwargs):
208237

209238
if isclass(output_serializer) and issubclass(output_serializer, BaseIdempotencyModelSerializer):
210239
# instantiate an instance of the serializer class
211-
output_serializer = output_serializer.instantiate(function.__annotations__.get("return", None))
240+
output_serializer = output_serializer.instantiate(_get_return_annotation(function))
212241

213242
config = config or IdempotencyConfig()
214243

‎aws_lambda_powertools/utilities/idempotency/serialization/pydantic.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
from __future__ import annotations
22

3-
from typing import Any
3+
from inspect import isclass
4+
from typing import Any, get_origin
45

56
from pydantic import BaseModel
67

@@ -41,7 +42,7 @@ def instantiate(cls, model_type: Any) -> BaseIdempotencySerializer:
4142
if model_type is None:
4243
raise IdempotencyNoSerializationModelError("No serialization model was supplied")
4344

44-
if not issubclass(model_type, BaseModel):
45+
if get_origin(model_type) is not None or not isclass(model_type) or not issubclass(model_type, BaseModel):
4546
raise IdempotencyModelTypeError("Model type is not inherited from pydantic BaseModel")
4647

4748
return cls(model=model_type)

‎docs/utilities/idempotency.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -223,13 +223,17 @@ The output serializer supports any JSON serializable data, **Python Dataclasses*
223223

224224
Function returns must be annotated with a single type, optionally wrapped in `Optional` or `Union` with `None`.
225225

226+
Inference supports `from __future__ import annotations`. Define the output model at module scope so its name can be resolved when the function is decorated.
227+
If the model is local to another function, pass an explicit serializer instance, such as `PydanticSerializer(model=OrderOutput)` or `DataclassSerializer(model=OrderOutput)`.
228+
Containers such as `list[OrderOutput]` are not supported by these model serializers and raise `IdempotencyModelTypeError`.
229+
226230
=== "Pydantic"
227231

228232
Use `PydanticSerializer` to automatically serialize what's retrieved from the persistent storage based on the return type annotated.
229233

230234
=== "Inferring via the return type"
231235

232-
```python hl_lines="8 27 35 38 48"
236+
```python hl_lines="1 10 29 37 40 50"
233237
--8<-- "examples/idempotency/src/working_with_pydantic_deduced_output_serializer.py"
234238
```
235239

@@ -255,7 +259,7 @@ The output serializer supports any JSON serializable data, **Python Dataclasses*
255259

256260
=== "Inferring via the return type"
257261

258-
```python hl_lines="9 30 38 41 51"
262+
```python hl_lines="1 11 32 40 43 53"
259263
--8<-- "examples/idempotency/src/working_with_dataclass_deduced_output_serializer.py"
260264
```
261265

‎examples/idempotency/src/working_with_dataclass_deduced_output_serializer.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
from __future__ import annotations
2+
13
import os
24
from dataclasses import dataclass
35

‎examples/idempotency/src/working_with_pydantic_deduced_output_serializer.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
from __future__ import annotations
2+
13
import os
24

35
from aws_lambda_powertools.utilities.idempotency import (
Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
import functools
2+
import sys
3+
from typing import TYPE_CHECKING, Annotated, get_args, get_origin, no_type_check
4+
5+
import pytest
6+
7+
from aws_lambda_powertools.utilities.idempotency import IdempotencyConfig, idempotent_function
8+
from aws_lambda_powertools.utilities.idempotency.serialization.base import BaseIdempotencyModelSerializer
9+
from aws_lambda_powertools.utilities.idempotency.serialization.dataclass import DataclassSerializer
10+
from aws_lambda_powertools.utilities.idempotency.serialization.pydantic import PydanticSerializer
11+
from tests.functional.idempotency._pydantic.test_idempotency_with_postponed_annotations import (
12+
MOCK_EVENT,
13+
NoOpPersistenceLayer,
14+
PaymentOutput,
15+
PaymentOutputDataclass,
16+
)
17+
18+
if TYPE_CHECKING:
19+
from collections.abc import Mapping as InputOnlyAvailableToTypeChecker
20+
21+
22+
class MetadataSerializer(BaseIdempotencyModelSerializer):
23+
@classmethod
24+
def instantiate(cls, model_type):
25+
assert get_origin(model_type) is Annotated
26+
model, metadata = get_args(model_type)
27+
assert metadata == "v1"
28+
return PydanticSerializer(model=model)
29+
30+
def to_dict(self, data): ...
31+
32+
def from_dict(self, data): ...
33+
34+
35+
def replay(function, serializer, expected):
36+
config = IdempotencyConfig(use_local_cache=True)
37+
38+
# This fake Lambda context avoids depending on DynamoDB or warning about missing context.
39+
class Context:
40+
def get_remaining_time_in_millis(self):
41+
return 1000
42+
43+
config.register_lambda_context(Context())
44+
decorated = idempotent_function(
45+
function,
46+
data_keyword_argument="payment",
47+
persistence_store=NoOpPersistenceLayer(),
48+
config=config,
49+
output_serializer=serializer,
50+
)
51+
assert decorated(payment=MOCK_EVENT) == expected
52+
assert decorated(payment=MOCK_EVENT) == expected
53+
54+
55+
@pytest.mark.parametrize("postponed", [False, True])
56+
def test_custom_serializer_keeps_annotated_metadata(postponed):
57+
calls = []
58+
59+
def collect_payment(payment: dict) -> Annotated[PaymentOutput, "v1"]:
60+
calls.append(payment)
61+
return PaymentOutput(**payment)
62+
63+
if postponed:
64+
collect_payment.__annotations__["return"] = "Annotated[PaymentOutput, 'v1']"
65+
66+
replay(collect_payment, MetadataSerializer, PaymentOutput(**MOCK_EVENT))
67+
assert len(calls) == 1
68+
69+
70+
@pytest.mark.parametrize("postponed", [False, True])
71+
def test_no_type_check_keeps_return_model(postponed):
72+
calls = []
73+
74+
@no_type_check
75+
def collect_payment(payment: dict) -> PaymentOutput:
76+
calls.append(payment)
77+
return PaymentOutput(**payment)
78+
79+
if postponed:
80+
collect_payment.__annotations__["return"] = "PaymentOutput"
81+
82+
replay(collect_payment, PydanticSerializer, PaymentOutput(**MOCK_EVENT))
83+
assert len(calls) == 1
84+
85+
86+
@pytest.mark.parametrize(
87+
"model,serializer",
88+
[(PaymentOutput, PydanticSerializer), (PaymentOutputDataclass, DataclassSerializer)],
89+
)
90+
def test_unresolved_input_annotation_does_not_block_return_model(model, serializer):
91+
calls = []
92+
93+
def collect_payment(payment: "InputOnlyAvailableToTypeChecker"):
94+
calls.append(payment)
95+
return model(**payment)
96+
97+
collect_payment.__annotations__["return"] = model.__name__
98+
replay(collect_payment, serializer, model(**MOCK_EVENT))
99+
assert len(calls) == 1
100+
101+
102+
def test_wrapped_function_resolves_return_in_original_namespace():
103+
calls = []
104+
105+
def collect_payment(payment: dict) -> "PaymentOutput":
106+
calls.append(payment)
107+
return PaymentOutput(**payment)
108+
109+
# A wrapper from a different module has no PaymentOutput in its globals.
110+
namespace = {"functools": functools, "original": collect_payment}
111+
exec(
112+
compile(
113+
"@functools.wraps(original)\ndef wrapper(*args, **kwargs):\n return original(*args, **kwargs)\n",
114+
"<external_wrapper>",
115+
"exec",
116+
dont_inherit=True,
117+
),
118+
namespace,
119+
)
120+
replay(namespace["wrapper"], PydanticSerializer, PaymentOutput(**MOCK_EVENT))
121+
assert len(calls) == 1
122+
123+
124+
@pytest.mark.skipif(sys.version_info < (3, 14), reason="Native deferred annotations require Python 3.14")
125+
def test_native_deferred_annotations_allow_unresolved_input():
126+
calls = []
127+
namespace = {"PaymentOutput": PaymentOutput, "calls": calls}
128+
exec(
129+
compile(
130+
"def collect_payment(payment: InputOnlyAvailableToTypeChecker) -> PaymentOutput:\n"
131+
" calls.append(payment)\n"
132+
" return PaymentOutput(**payment)\n",
133+
"<native_deferred_annotations>",
134+
"exec",
135+
dont_inherit=True,
136+
),
137+
namespace,
138+
)
139+
replay(namespace["collect_payment"], PydanticSerializer, PaymentOutput(**MOCK_EVENT))
140+
assert len(calls) == 1

0 commit comments

Comments
 (0)