From a0ddd46f040c6ee2c34b48f005fc83bf3a4f06d7 Mon Sep 17 00:00:00 2001
From: Heitor Lessa <lessa@amazon.com>
Date: Thu, 28 Jul 2022 13:11:56 +0200
Subject: [PATCH 1/6] chore(ci): drop 3.6 from workflows (#1395)

---
 .github/workflows/python_build.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/python_build.yml b/.github/workflows/python_build.yml
index 4280fe531e5..901c593ebce 100644
--- a/.github/workflows/python_build.yml
+++ b/.github/workflows/python_build.yml
@@ -26,7 +26,7 @@ jobs:
     strategy:
       max-parallel: 4
       matrix:
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        python-version: [3.7, 3.8, 3.9]
     env:
       OS: ${{ matrix.os }}
       PYTHON: ${{ matrix.python-version }}

From 723effce9b2589e755d2a4ce288f3fa7bf4d3ee5 Mon Sep 17 00:00:00 2001
From: Heitor Lessa <lessa@amazon.com>
Date: Thu, 28 Jul 2022 13:56:46 +0200
Subject: [PATCH 2/6] docs(examples): enforce and fix all mypy errors (#1393)

---
 Makefile                                      |   2 +-
 .../event_handler/__init__.py                 |   9 +-
 .../event_handler/appsync.py                  |   1 +
 aws_lambda_powertools/tracing/base.py         | 118 +++++++++---------
 aws_lambda_powertools/tracing/tracer.py       |   2 +-
 docs/core/event_handler/api_gateway.md        |   2 +-
 docs/core/event_handler/appsync.md            |  20 +--
 .../src/assert_async_graphql_response.py      |   5 +-
 .../assert_async_graphql_response_module.py   |  15 ++-
 .../src/assert_graphql_response_module.py     |  11 +-
 .../src/async_resolvers.py                    |  11 +-
 .../src/custom_models.py                      |  19 ++-
 .../getting_started_graphql_api_resolver.py   |  11 +-
 .../src/graphql_transformer_merchant_info.py  |  13 +-
 .../graphql_transformer_search_merchant.py    |  17 ++-
 .../src/nested_mappings.py                    |  11 +-
 .../src/scalar_functions.py                   |  10 +-
 .../src/split_operation_module.py             |  11 +-
 .../src/binary_responses.py                   |   2 +-
 .../src/exception_handling.py                 |   5 +-
 .../src/split_route_module.py                 |   2 +-
 .../src/split_route_prefix_module.py          |   2 +-
 .../bring_your_own_formatter_from_scratch.py  |   2 +-
 mypy.ini                                      |   9 ++
 poetry.lock                                   |  75 +++++------
 pyproject.toml                                |   3 +-
 26 files changed, 230 insertions(+), 158 deletions(-)

diff --git a/Makefile b/Makefile
index a024f340263..e4f908614a6 100644
--- a/Makefile
+++ b/Makefile
@@ -99,4 +99,4 @@ changelog:
 	docker run -v "${PWD}":/workdir quay.io/git-chglog/git-chglog > CHANGELOG.md
 
 mypy:
-	poetry run mypy --pretty aws_lambda_powertools
+	poetry run mypy --pretty aws_lambda_powertools examples
diff --git a/aws_lambda_powertools/event_handler/__init__.py b/aws_lambda_powertools/event_handler/__init__.py
index 112e2fe69d6..e7dc4608ee9 100644
--- a/aws_lambda_powertools/event_handler/__init__.py
+++ b/aws_lambda_powertools/event_handler/__init__.py
@@ -2,7 +2,14 @@
 Event handler decorators for common Lambda events
 """
 
-from .api_gateway import ALBResolver, APIGatewayHttpResolver, ApiGatewayResolver, APIGatewayRestResolver, CORSConfig, Response
+from .api_gateway import (
+    ALBResolver,
+    APIGatewayHttpResolver,
+    ApiGatewayResolver,
+    APIGatewayRestResolver,
+    CORSConfig,
+    Response,
+)
 from .appsync import AppSyncResolver
 
 __all__ = [
diff --git a/aws_lambda_powertools/event_handler/appsync.py b/aws_lambda_powertools/event_handler/appsync.py
index 6a4bf989169..896b303cd08 100644
--- a/aws_lambda_powertools/event_handler/appsync.py
+++ b/aws_lambda_powertools/event_handler/appsync.py
@@ -142,6 +142,7 @@ def lambda_handler(event, context):
         ValueError
             If we could not find a field resolver
         """
+        # Maintenance: revisit generics/overload to fix [attr-defined] in mypy usage
         BaseRouter.current_event = data_model(event)
         BaseRouter.lambda_context = context
         resolver = self._get_resolver(BaseRouter.current_event.type_name, BaseRouter.current_event.field_name)
diff --git a/aws_lambda_powertools/tracing/base.py b/aws_lambda_powertools/tracing/base.py
index 722652ce08b..d044817f920 100644
--- a/aws_lambda_powertools/tracing/base.py
+++ b/aws_lambda_powertools/tracing/base.py
@@ -2,39 +2,34 @@
 import numbers
 import traceback
 from contextlib import contextmanager
-from typing import Any, AsyncContextManager, ContextManager, List, NoReturn, Optional, Set, Union
+from typing import Any, Generator, List, NoReturn, Optional, Sequence, Union
 
 
-class BaseProvider(abc.ABC):
-    @abc.abstractmethod  # type: ignore
-    @contextmanager
-    def in_subsegment(self, name=None, **kwargs) -> ContextManager:
-        """Return a subsegment context manger.
+class BaseSegment(abc.ABC):
+    """Holds common properties and methods on segment and subsegment."""
+
+    @abc.abstractmethod
+    def close(self, end_time: Optional[int] = None):
+        """Close the trace entity by setting `end_time`
+        and flip the in progress flag to False.
 
         Parameters
         ----------
-        name: str
-            Subsegment name
-        kwargs: Optional[dict]
-            Optional parameters to be propagated to segment
+        end_time: int
+            Time in epoch seconds, by default current time will be used.
         """
 
-    @abc.abstractmethod  # type: ignore
-    @contextmanager
-    def in_subsegment_async(self, name=None, **kwargs) -> AsyncContextManager:
-        """Return a subsegment async context manger.
+    @abc.abstractmethod
+    def add_subsegment(self, subsegment: Any):
+        """Add input subsegment as a child subsegment."""
 
-        Parameters
-        ----------
-        name: str
-            Subsegment name
-        kwargs: Optional[dict]
-            Optional parameters to be propagated to segment
-        """
+    @abc.abstractmethod
+    def remove_subsegment(self, subsegment: Any):
+        """Remove input subsegment from child subsegments."""
 
     @abc.abstractmethod
     def put_annotation(self, key: str, value: Union[str, numbers.Number, bool]) -> NoReturn:
-        """Annotate current active trace entity with a key-value pair.
+        """Annotate segment or subsegment with a key-value pair.
 
         Note: Annotations will be indexed for later search query.
 
@@ -48,9 +43,8 @@ def put_annotation(self, key: str, value: Union[str, numbers.Number, bool]) -> N
 
     @abc.abstractmethod
     def put_metadata(self, key: str, value: Any, namespace: str = "default") -> NoReturn:
-        """Add metadata to the current active trace entity.
-
-        Note: Metadata is not indexed but can be later retrieved by BatchGetTraces API.
+        """Add metadata to segment or subsegment. Metadata is not indexed
+        but can be later retrieved by BatchGetTraces API.
 
         Parameters
         ----------
@@ -63,45 +57,52 @@ def put_metadata(self, key: str, value: Any, namespace: str = "default") -> NoRe
         """
 
     @abc.abstractmethod
-    def patch(self, modules: Set[str]) -> NoReturn:
-        """Instrument a set of supported libraries
+    def add_exception(self, exception: BaseException, stack: List[traceback.StackSummary], remote: bool = False):
+        """Add an exception to trace entities.
 
         Parameters
         ----------
-        modules: Set[str]
-            Set of modules to be patched
-        """
-
-    @abc.abstractmethod
-    def patch_all(self) -> NoReturn:
-        """Instrument all supported libraries"""
+        exception: Exception
+            Caught exception
+        stack: List[traceback.StackSummary]
+            List of traceback summaries
 
+            Output from `traceback.extract_stack()`.
+        remote: bool
+            Whether it's a client error (False) or downstream service error (True), by default False
+        """
 
-class BaseSegment(abc.ABC):
-    """Holds common properties and methods on segment and subsegment."""
 
+class BaseProvider(abc.ABC):
     @abc.abstractmethod
-    def close(self, end_time: Optional[int] = None):
-        """Close the trace entity by setting `end_time`
-        and flip the in progress flag to False.
+    @contextmanager
+    def in_subsegment(self, name=None, **kwargs) -> Generator[BaseSegment, None, None]:
+        """Return a subsegment context manger.
 
         Parameters
         ----------
-        end_time: int
-            Time in epoch seconds, by default current time will be used.
+        name: str
+            Subsegment name
+        kwargs: Optional[dict]
+            Optional parameters to be propagated to segment
         """
 
     @abc.abstractmethod
-    def add_subsegment(self, subsegment: Any):
-        """Add input subsegment as a child subsegment."""
+    @contextmanager
+    def in_subsegment_async(self, name=None, **kwargs) -> Generator[BaseSegment, None, None]:
+        """Return a subsegment async context manger.
 
-    @abc.abstractmethod
-    def remove_subsegment(self, subsegment: Any):
-        """Remove input subsegment from child subsegments."""
+        Parameters
+        ----------
+        name: str
+            Subsegment name
+        kwargs: Optional[dict]
+            Optional parameters to be propagated to segment
+        """
 
     @abc.abstractmethod
     def put_annotation(self, key: str, value: Union[str, numbers.Number, bool]) -> NoReturn:
-        """Annotate segment or subsegment with a key-value pair.
+        """Annotate current active trace entity with a key-value pair.
 
         Note: Annotations will be indexed for later search query.
 
@@ -115,8 +116,9 @@ def put_annotation(self, key: str, value: Union[str, numbers.Number, bool]) -> N
 
     @abc.abstractmethod
     def put_metadata(self, key: str, value: Any, namespace: str = "default") -> NoReturn:
-        """Add metadata to segment or subsegment. Metadata is not indexed
-        but can be later retrieved by BatchGetTraces API.
+        """Add metadata to the current active trace entity.
+
+        Note: Metadata is not indexed but can be later retrieved by BatchGetTraces API.
 
         Parameters
         ----------
@@ -129,17 +131,15 @@ def put_metadata(self, key: str, value: Any, namespace: str = "default") -> NoRe
         """
 
     @abc.abstractmethod
-    def add_exception(self, exception: BaseException, stack: List[traceback.StackSummary], remote: bool = False):
-        """Add an exception to trace entities.
+    def patch(self, modules: Sequence[str]) -> NoReturn:
+        """Instrument a set of supported libraries
 
         Parameters
         ----------
-        exception: Exception
-            Caught exception
-        stack: List[traceback.StackSummary]
-            List of traceback summaries
-
-            Output from `traceback.extract_stack()`.
-        remote: bool
-            Whether it's a client error (False) or downstream service error (True), by default False
+        modules: Set[str]
+            Set of modules to be patched
         """
+
+    @abc.abstractmethod
+    def patch_all(self) -> NoReturn:
+        """Instrument all supported libraries"""
diff --git a/aws_lambda_powertools/tracing/tracer.py b/aws_lambda_powertools/tracing/tracer.py
index 200325cfe9a..8d9ad16a3d0 100644
--- a/aws_lambda_powertools/tracing/tracer.py
+++ b/aws_lambda_powertools/tracing/tracer.py
@@ -155,7 +155,7 @@ def __init__(
         self.__build_config(
             service=service, disabled=disabled, auto_patch=auto_patch, patch_modules=patch_modules, provider=provider
         )
-        self.provider = self._config["provider"]
+        self.provider: BaseProvider = self._config["provider"]
         self.disabled = self._config["disabled"]
         self.service = self._config["service"]
         self.auto_patch = self._config["auto_patch"]
diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md
index 38d4bfb0617..707d9687e63 100644
--- a/docs/core/event_handler/api_gateway.md
+++ b/docs/core/event_handler/api_gateway.md
@@ -201,7 +201,7 @@ You can use **`not_found`** decorator to override this behavior, and return a cu
 
 You can use **`exception_handler`** decorator with any Python exception. This allows you to handle a common exception outside your route, for example validation errors.
 
-```python hl_lines="14 15" title="Exception handling"
+```python hl_lines="13-14" title="Exception handling"
 --8<-- "examples/event_handler_rest/src/exception_handling.py"
 ```
 
diff --git a/docs/core/event_handler/appsync.md b/docs/core/event_handler/appsync.md
index 4d28b41a81f..dd9d1dd2d63 100644
--- a/docs/core/event_handler/appsync.md
+++ b/docs/core/event_handler/appsync.md
@@ -58,7 +58,7 @@ Here's an example where we have two separate functions to resolve `getTodo` and
 
 === "getting_started_graphql_api_resolver.py"
 
-    ```python hl_lines="7 13 23 25-26 35 37 48"
+    ```python hl_lines="14 20 30 32-33 42 44 55"
     --8<-- "examples/event_handler_graphql/src/getting_started_graphql_api_resolver.py"
     ```
 
@@ -112,7 +112,7 @@ You can nest `app.resolver()` decorator multiple times when resolving fields wit
 
 === "nested_mappings.py"
 
-    ```python hl_lines="4 10 20-21 23 30"
+    ```python hl_lines="11 17 27-28 28 30 37"
     --8<-- "examples/event_handler_graphql/src/nested_mappings.py"
     ```
 
@@ -126,7 +126,7 @@ You can nest `app.resolver()` decorator multiple times when resolving fields wit
 
 For Lambda Python3.8+ runtime, this utility supports async functions when you use in conjunction with `asyncio.run`.
 
-```python hl_lines="7 14 24-25 34 36" title="Resolving GraphQL resolvers async"
+```python hl_lines="14 21 31-32 41 43" title="Resolving GraphQL resolvers async"
 --8<-- "examples/event_handler_graphql/src/async_resolvers.py"
 ```
 
@@ -151,13 +151,13 @@ Use the following code for `merchantInfo` and `searchMerchant` functions respect
 
 === "graphql_transformer_merchant_info.py"
 
-    ```python hl_lines="4 6 22-23 27-28 36"
+    ```python hl_lines="11 13 29-30 34-35 43"
     --8<-- "examples/event_handler_graphql/src/graphql_transformer_merchant_info.py"
     ```
 
 === "graphql_transformer_search_merchant.py"
 
-    ```python hl_lines="4 6 21-22 36 42"
+    ```python hl_lines="11 13 28-29 43 49"
     --8<-- "examples/event_handler_graphql/src/graphql_transformer_search_merchant.py"
     ```
 
@@ -185,7 +185,7 @@ You can subclass [AppSyncResolverEvent](../../utilities/data_classes.md#appsync-
 
 === "custom_models.py.py"
 
-    ```python hl_lines="4 7 23-25 28-29 36 43"
+    ```python hl_lines="11 14 30-32 35-36 43 50"
     --8<-- "examples/event_handler_graphql/src/custom_models.py"
     ```
 
@@ -214,7 +214,7 @@ Let's assume you have `split_operation.py` as your Lambda function entrypoint an
 
     We import **Router** instead of **AppSyncResolver**; syntax wise is exactly the same.
 
-  	```python hl_lines="4 8 18-19"
+  	```python hl_lines="11 15 25-26"
     --8<-- "examples/event_handler_graphql/src/split_operation_module.py"
   	```
 
@@ -242,7 +242,7 @@ Here's an example of how you can test your synchronous resolvers:
 
 === "assert_graphql_response_module.py"
 
-    ```python hl_lines="10"
+    ```python hl_lines="17"
     --8<-- "examples/event_handler_graphql/src/assert_graphql_response_module.py"
     ```
 
@@ -259,13 +259,13 @@ And an example for testing asynchronous resolvers. Note that this requires the `
 
 === "assert_async_graphql_response.py"
 
-    ```python hl_lines="27"
+    ```python hl_lines="28"
     --8<-- "examples/event_handler_graphql/src/assert_async_graphql_response.py"
     ```
 
 === "assert_async_graphql_response_module.py"
 
-    ```python hl_lines="14"
+    ```python hl_lines="21"
     --8<-- "examples/event_handler_graphql/src/assert_async_graphql_response_module.py"
     ```
 
diff --git a/examples/event_handler_graphql/src/assert_async_graphql_response.py b/examples/event_handler_graphql/src/assert_async_graphql_response.py
index 22eceb1c5d0..e85816f2ca1 100644
--- a/examples/event_handler_graphql/src/assert_async_graphql_response.py
+++ b/examples/event_handler_graphql/src/assert_async_graphql_response.py
@@ -1,9 +1,10 @@
 import json
 from dataclasses import dataclass
 from pathlib import Path
+from typing import List
 
 import pytest
-from assert_async_graphql_response_module import Location, app  # instance of AppSyncResolver
+from assert_async_graphql_response_module import Todo, app  # instance of AppSyncResolver
 
 
 @pytest.fixture
@@ -24,7 +25,7 @@ async def test_async_direct_resolver(lambda_context):
     fake_event = json.loads(Path("assert_async_graphql_response.json").read_text())
 
     # WHEN
-    result: list[Location] = await app(fake_event, lambda_context)
+    result: List[Todo] = await app(fake_event, lambda_context)
     # alternatively, you can also run a sync test against `lambda_handler`
     # since `lambda_handler` awaits the coroutine to complete
 
diff --git a/examples/event_handler_graphql/src/assert_async_graphql_response_module.py b/examples/event_handler_graphql/src/assert_async_graphql_response_module.py
index 892da71fb0f..8ef072a02f7 100644
--- a/examples/event_handler_graphql/src/assert_async_graphql_response_module.py
+++ b/examples/event_handler_graphql/src/assert_async_graphql_response_module.py
@@ -1,5 +1,12 @@
+import sys
+
+if sys.version_info >= (3, 8):
+    from typing import TypedDict
+else:
+    from typing_extensions import TypedDict
+
 import asyncio
-from typing import TypedDict
+from typing import List
 
 import aiohttp
 
@@ -22,11 +29,11 @@ class Todo(TypedDict, total=False):
 
 
 @app.resolver(type_name="Query", field_name="listTodos")
-async def list_todos() -> list[Todo]:
+async def list_todos() -> List[Todo]:
     async with aiohttp.ClientSession(trace_configs=[aiohttp_trace_config()]) as session:
         async with session.get("https://jsonplaceholder.typicode.com/todos") as resp:
-            # first two results to demo assertion
-            return await resp.json()[:2]
+            result: List[Todo] = await resp.json()
+            return result[:2]  # first two results to demo assertion
 
 
 @logger.inject_lambda_context(correlation_id_path=correlation_paths.APPSYNC_RESOLVER)
diff --git a/examples/event_handler_graphql/src/assert_graphql_response_module.py b/examples/event_handler_graphql/src/assert_graphql_response_module.py
index 2f9c8ac3c41..c7869a587fc 100644
--- a/examples/event_handler_graphql/src/assert_graphql_response_module.py
+++ b/examples/event_handler_graphql/src/assert_graphql_response_module.py
@@ -1,4 +1,11 @@
-from typing import TypedDict
+import sys
+
+if sys.version_info >= (3, 8):
+    from typing import TypedDict
+else:
+    from typing_extensions import TypedDict
+
+from typing import List
 
 from aws_lambda_powertools import Logger, Tracer
 from aws_lambda_powertools.event_handler import AppSyncResolver
@@ -20,7 +27,7 @@ class Location(TypedDict, total=False):
 @app.resolver(field_name="listLocations")
 @app.resolver(field_name="locations")
 @tracer.capture_method
-def get_locations(name: str, description: str = "") -> list[Location]:  # match GraphQL Query arguments
+def get_locations(name: str, description: str = "") -> List[Location]:  # match GraphQL Query arguments
     return [{"name": name, "description": description}]
 
 
diff --git a/examples/event_handler_graphql/src/async_resolvers.py b/examples/event_handler_graphql/src/async_resolvers.py
index 229e015c886..072f42dbba9 100644
--- a/examples/event_handler_graphql/src/async_resolvers.py
+++ b/examples/event_handler_graphql/src/async_resolvers.py
@@ -1,5 +1,12 @@
 import asyncio
-from typing import TypedDict
+import sys
+
+if sys.version_info >= (3, 8):
+    from typing import TypedDict
+else:
+    from typing_extensions import TypedDict
+
+from typing import List
 
 import aiohttp
 
@@ -22,7 +29,7 @@ class Todo(TypedDict, total=False):
 
 
 @app.resolver(type_name="Query", field_name="listTodos")
-async def list_todos() -> list[Todo]:
+async def list_todos() -> List[Todo]:
     async with aiohttp.ClientSession(trace_configs=[aiohttp_trace_config()]) as session:
         async with session.get("https://jsonplaceholder.typicode.com/todos") as resp:
             return await resp.json()
diff --git a/examples/event_handler_graphql/src/custom_models.py b/examples/event_handler_graphql/src/custom_models.py
index 92763ca3401..594ef5ee248 100644
--- a/examples/event_handler_graphql/src/custom_models.py
+++ b/examples/event_handler_graphql/src/custom_models.py
@@ -1,4 +1,11 @@
-from typing import TypedDict
+import sys
+
+if sys.version_info >= (3, 8):
+    from typing import TypedDict
+else:
+    from typing_extensions import TypedDict
+
+from typing import List
 
 from aws_lambda_powertools import Logger, Tracer
 from aws_lambda_powertools.event_handler import AppSyncResolver
@@ -23,21 +30,21 @@ class Location(TypedDict, total=False):
 class MyCustomModel(AppSyncResolverEvent):
     @property
     def country_viewer(self) -> str:
-        return self.get_header_value(name="cloudfront-viewer-country", default_value="", case_sensitive=False)
+        return self.get_header_value(name="cloudfront-viewer-country", default_value="", case_sensitive=False)  # type: ignore[return-value] # sentinel typing # noqa: E501
 
     @property
     def api_key(self) -> str:
-        return self.get_header_value(name="x-api-key", default_value="", case_sensitive=False)
+        return self.get_header_value(name="x-api-key", default_value="", case_sensitive=False)  # type: ignore[return-value] # sentinel typing # noqa: E501
 
 
 @app.resolver(type_name="Query", field_name="listLocations")
-def list_locations(page: int = 0, size: int = 10) -> list[Location]:
+def list_locations(page: int = 0, size: int = 10) -> List[Location]:
     # additional properties/methods will now be available under current_event
-    logger.debug(f"Request country origin: {app.current_event.country_viewer}")
+    logger.debug(f"Request country origin: {app.current_event.country_viewer}")  # type: ignore[attr-defined]
     return [{"id": scalar_types_utils.make_id(), "name": "Perry, James and Carroll"}]
 
 
 @tracer.capture_lambda_handler
 @logger.inject_lambda_context(correlation_id_path=correlation_paths.APPSYNC_RESOLVER)
 def lambda_handler(event: dict, context: LambdaContext) -> dict:
-    app.resolve(event, context, data_model=MyCustomModel)
+    return app.resolve(event, context, data_model=MyCustomModel)
diff --git a/examples/event_handler_graphql/src/getting_started_graphql_api_resolver.py b/examples/event_handler_graphql/src/getting_started_graphql_api_resolver.py
index 4e42bd42f58..e4879d609f2 100644
--- a/examples/event_handler_graphql/src/getting_started_graphql_api_resolver.py
+++ b/examples/event_handler_graphql/src/getting_started_graphql_api_resolver.py
@@ -1,4 +1,11 @@
-from typing import TypedDict
+import sys
+
+if sys.version_info >= (3, 8):
+    from typing import TypedDict
+else:
+    from typing_extensions import TypedDict
+
+from typing import List
 
 import requests
 from requests import Response
@@ -34,7 +41,7 @@ def get_todo(
 
 @app.resolver(type_name="Query", field_name="listTodos")
 @tracer.capture_method
-def list_todos() -> list[Todo]:
+def list_todos() -> List[Todo]:
     todos: Response = requests.get("https://jsonplaceholder.typicode.com/todos")
     todos.raise_for_status()
 
diff --git a/examples/event_handler_graphql/src/graphql_transformer_merchant_info.py b/examples/event_handler_graphql/src/graphql_transformer_merchant_info.py
index 272f119f3b8..55f963bb8d5 100644
--- a/examples/event_handler_graphql/src/graphql_transformer_merchant_info.py
+++ b/examples/event_handler_graphql/src/graphql_transformer_merchant_info.py
@@ -1,4 +1,11 @@
-from typing import TypedDict
+import sys
+
+if sys.version_info >= (3, 8):
+    from typing import TypedDict
+else:
+    from typing_extensions import TypedDict
+
+from typing import List
 
 from aws_lambda_powertools import Logger, Tracer
 from aws_lambda_powertools.event_handler import AppSyncResolver
@@ -20,7 +27,7 @@ class Location(TypedDict, total=False):
 
 
 @app.resolver(type_name="Query", field_name="listLocations")
-def list_locations(page: int = 0, size: int = 10) -> list[Location]:
+def list_locations(page: int = 0, size: int = 10) -> List[Location]:
     return [{"id": scalar_types_utils.make_id(), "name": "Smooth Grooves"}]
 
 
@@ -33,4 +40,4 @@ def common_field() -> str:
 @tracer.capture_lambda_handler
 @logger.inject_lambda_context(correlation_id_path=correlation_paths.APPSYNC_RESOLVER)
 def lambda_handler(event: dict, context: LambdaContext) -> dict:
-    app.resolve(event, context)
+    return app.resolve(event, context)
diff --git a/examples/event_handler_graphql/src/graphql_transformer_search_merchant.py b/examples/event_handler_graphql/src/graphql_transformer_search_merchant.py
index e2adb566f93..1dd52945f93 100644
--- a/examples/event_handler_graphql/src/graphql_transformer_search_merchant.py
+++ b/examples/event_handler_graphql/src/graphql_transformer_search_merchant.py
@@ -1,4 +1,11 @@
-from typing import TypedDict
+import sys
+
+if sys.version_info >= (3, 8):
+    from typing import TypedDict
+else:
+    from typing_extensions import TypedDict
+
+from typing import List
 
 from aws_lambda_powertools import Logger, Tracer
 from aws_lambda_powertools.event_handler import AppSyncResolver
@@ -19,8 +26,8 @@ class Merchant(TypedDict, total=False):
 
 
 @app.resolver(type_name="Query", field_name="findMerchant")
-def find_merchant(search: str) -> list[Merchant]:
-    merchants: list[Merchant] = [
+def find_merchant(search: str) -> List[Merchant]:
+    merchants: List[Merchant] = [
         {
             "id": scalar_types_utils.make_id(),
             "name": "Parry-Wood",
@@ -33,10 +40,10 @@ def find_merchant(search: str) -> list[Merchant]:
         },
     ]
 
-    return next((merchant for merchant in merchants if search == merchant["name"]), [{}])
+    return [merchant for merchant in merchants if search == merchant["name"]]
 
 
 @tracer.capture_lambda_handler
 @logger.inject_lambda_context(correlation_id_path=correlation_paths.APPSYNC_RESOLVER)
 def lambda_handler(event: dict, context: LambdaContext) -> dict:
-    app.resolve(event, context)
+    return app.resolve(event, context)
diff --git a/examples/event_handler_graphql/src/nested_mappings.py b/examples/event_handler_graphql/src/nested_mappings.py
index 2f9c8ac3c41..c7869a587fc 100644
--- a/examples/event_handler_graphql/src/nested_mappings.py
+++ b/examples/event_handler_graphql/src/nested_mappings.py
@@ -1,4 +1,11 @@
-from typing import TypedDict
+import sys
+
+if sys.version_info >= (3, 8):
+    from typing import TypedDict
+else:
+    from typing_extensions import TypedDict
+
+from typing import List
 
 from aws_lambda_powertools import Logger, Tracer
 from aws_lambda_powertools.event_handler import AppSyncResolver
@@ -20,7 +27,7 @@ class Location(TypedDict, total=False):
 @app.resolver(field_name="listLocations")
 @app.resolver(field_name="locations")
 @tracer.capture_method
-def get_locations(name: str, description: str = "") -> list[Location]:  # match GraphQL Query arguments
+def get_locations(name: str, description: str = "") -> List[Location]:  # match GraphQL Query arguments
     return [{"name": name, "description": description}]
 
 
diff --git a/examples/event_handler_graphql/src/scalar_functions.py b/examples/event_handler_graphql/src/scalar_functions.py
index 0d8fa98b7b3..9b241f6c30d 100644
--- a/examples/event_handler_graphql/src/scalar_functions.py
+++ b/examples/event_handler_graphql/src/scalar_functions.py
@@ -8,8 +8,8 @@
 
 # Scalars: https://docs.aws.amazon.com/appsync/latest/devguide/scalars.html
 
-_: str = make_id()  # Scalar: ID!
-_: str = aws_date()  # Scalar: AWSDate
-_: str = aws_time()  # Scalar: AWSTime
-_: str = aws_datetime()  # Scalar: AWSDateTime
-_: int = aws_timestamp()  # Scalar: AWSTimestamp
+my_id: str = make_id()  # Scalar: ID!
+my_date: str = aws_date()  # Scalar: AWSDate
+my_timestamp: str = aws_time()  # Scalar: AWSTime
+my_datetime: str = aws_datetime()  # Scalar: AWSDateTime
+my_epoch_timestamp: int = aws_timestamp()  # Scalar: AWSTimestamp
diff --git a/examples/event_handler_graphql/src/split_operation_module.py b/examples/event_handler_graphql/src/split_operation_module.py
index 43c413672b6..12569bc23bc 100644
--- a/examples/event_handler_graphql/src/split_operation_module.py
+++ b/examples/event_handler_graphql/src/split_operation_module.py
@@ -1,4 +1,11 @@
-from typing import TypedDict
+import sys
+
+if sys.version_info >= (3, 8):
+    from typing import TypedDict
+else:
+    from typing_extensions import TypedDict
+
+from typing import List
 
 from aws_lambda_powertools import Logger, Tracer
 from aws_lambda_powertools.event_handler.appsync import Router
@@ -18,5 +25,5 @@ class Location(TypedDict, total=False):
 @router.resolver(field_name="listLocations")
 @router.resolver(field_name="locations")
 @tracer.capture_method
-def get_locations(name: str, description: str = "") -> list[Location]:  # match GraphQL Query arguments
+def get_locations(name: str, description: str = "") -> List[Location]:  # match GraphQL Query arguments
     return [{"name": name, "description": description}]
diff --git a/examples/event_handler_rest/src/binary_responses.py b/examples/event_handler_rest/src/binary_responses.py
index 00c027937b8..d56eda1afe8 100644
--- a/examples/event_handler_rest/src/binary_responses.py
+++ b/examples/event_handler_rest/src/binary_responses.py
@@ -11,7 +11,7 @@
 
 
 app = APIGatewayRestResolver()
-logo_file: bytes = Path(os.getenv("LAMBDA_TASK_ROOT") + "/logo.svg").read_bytes()
+logo_file: bytes = Path(f"{os.getenv('LAMBDA_TASK_ROOT')}/logo.svg").read_bytes()
 
 
 @app.get("/logo")
diff --git a/examples/event_handler_rest/src/exception_handling.py b/examples/event_handler_rest/src/exception_handling.py
index fdac8589299..89a31e60bf1 100644
--- a/examples/event_handler_rest/src/exception_handling.py
+++ b/examples/event_handler_rest/src/exception_handling.py
@@ -1,8 +1,7 @@
 import requests
-from requests import Response
 
 from aws_lambda_powertools import Logger, Tracer
-from aws_lambda_powertools.event_handler import APIGatewayRestResolver, content_types
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Response, content_types
 from aws_lambda_powertools.logging import correlation_paths
 from aws_lambda_powertools.utilities.typing import LambdaContext
 
@@ -30,7 +29,7 @@ def get_todos():
     # if a query string value for `limit` cannot be coerced to int
     max_results: int = int(app.current_event.get_query_string_value(name="limit", default_value=0))
 
-    todos: Response = requests.get(f"https://jsonplaceholder.typicode.com/todos?limit={max_results}")
+    todos: requests.Response = requests.get(f"https://jsonplaceholder.typicode.com/todos?limit={max_results}")
     todos.raise_for_status()
 
     return {"todos": todos.json()}
diff --git a/examples/event_handler_rest/src/split_route_module.py b/examples/event_handler_rest/src/split_route_module.py
index eeb696ede56..0462623f90b 100644
--- a/examples/event_handler_rest/src/split_route_module.py
+++ b/examples/event_handler_rest/src/split_route_module.py
@@ -25,7 +25,7 @@ def get_todos():
 @router.get("/todos/<todo_id>")
 @tracer.capture_method
 def get_todo_by_id(todo_id: str):  # value come as str
-    api_key: str = router.current_event.get_header_value(name="X-Api-Key", case_sensitive=True, default_value="")
+    api_key: str = router.current_event.get_header_value(name="X-Api-Key", case_sensitive=True, default_value="")  # type: ignore[assignment] # sentinel typing # noqa: E501
 
     todos: Response = requests.get(f"{endpoint}/{todo_id}", headers={"X-Api-Key": api_key})
     todos.raise_for_status()
diff --git a/examples/event_handler_rest/src/split_route_prefix_module.py b/examples/event_handler_rest/src/split_route_prefix_module.py
index b4035282776..41fcf8eed31 100644
--- a/examples/event_handler_rest/src/split_route_prefix_module.py
+++ b/examples/event_handler_rest/src/split_route_prefix_module.py
@@ -25,7 +25,7 @@ def get_todos():
 @router.get("/<todo_id>")
 @tracer.capture_method
 def get_todo_by_id(todo_id: str):  # value come as str
-    api_key: str = router.current_event.get_header_value(name="X-Api-Key", case_sensitive=True, default_value="")
+    api_key: str = router.current_event.get_header_value(name="X-Api-Key", case_sensitive=True, default_value="")  # type: ignore[assignment] # sentinel typing # noqa: E501
 
     todos: Response = requests.get(f"{endpoint}/{todo_id}", headers={"X-Api-Key": api_key})
     todos.raise_for_status()
diff --git a/examples/logger/src/bring_your_own_formatter_from_scratch.py b/examples/logger/src/bring_your_own_formatter_from_scratch.py
index 3088bf2a80f..c591b421cc6 100644
--- a/examples/logger/src/bring_your_own_formatter_from_scratch.py
+++ b/examples/logger/src/bring_your_own_formatter_from_scratch.py
@@ -7,7 +7,7 @@
 
 
 class CustomFormatter(BasePowertoolsFormatter):
-    def __init__(self, log_record_order: Optional[List[str]], *args, **kwargs):
+    def __init__(self, log_record_order: Optional[List[str]] = None, *args, **kwargs):
         self.log_record_order = log_record_order or ["level", "location", "message", "timestamp"]
         self.log_format = dict.fromkeys(self.log_record_order)
         super().__init__(*args, **kwargs)
diff --git a/mypy.ini b/mypy.ini
index 3061cc4a2d9..8274442fe4b 100644
--- a/mypy.ini
+++ b/mypy.ini
@@ -20,6 +20,9 @@ ignore_missing_imports=True
 [mypy-boto3]
 ignore_missing_imports = True
 
+[mypy-botocore.response]
+ignore_missing_imports = True
+
 [mypy-boto3.dynamodb.conditions]
 ignore_missing_imports = True
 
@@ -33,4 +36,10 @@ ignore_missing_imports = True
 ignore_missing_imports = True
 
 [mypy-dataclasses]
+ignore_missing_imports = True
+
+[mypy-orjson]
+ignore_missing_imports = True
+
+[mypy-aiohttp]
 ignore_missing_imports = True
\ No newline at end of file
diff --git a/poetry.lock b/poetry.lock
index 76fa6c625e4..bdea1decfde 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -1252,13 +1252,32 @@ category = "dev"
 optional = false
 python-versions = "*"
 
+[[package]]
+name = "types-requests"
+version = "2.28.5"
+description = "Typing stubs for requests"
+category = "dev"
+optional = false
+python-versions = "*"
+
+[package.dependencies]
+types-urllib3 = "<1.27"
+
+[[package]]
+name = "types-urllib3"
+version = "1.26.17"
+description = "Typing stubs for urllib3"
+category = "dev"
+optional = false
+python-versions = "*"
+
 [[package]]
 name = "typing-extensions"
-version = "4.1.1"
-description = "Backported and Experimental Type Hints for Python 3.6+"
+version = "4.3.0"
+description = "Backported and Experimental Type Hints for Python 3.7+"
 category = "main"
 optional = false
-python-versions = ">=3.6"
+python-versions = ">=3.7"
 
 [[package]]
 name = "urllib3"
@@ -1323,7 +1342,7 @@ pydantic = ["pydantic", "email-validator"]
 [metadata]
 lock-version = "1.1"
 python-versions = "^3.6.2"
-content-hash = "242d708424414a3e52bf02ccbb2b6f49d88724c1d4583a133ebc703548b28e88"
+content-hash = "783598fdfeef6abc4615ac9ba1ab8ade3cc2ad03859d0ea22d22bc1afe3cbb20"
 
 [metadata.files]
 atomicwrites = [
@@ -1563,28 +1582,12 @@ markdown = [
     {file = "Markdown-3.3.5.tar.gz", hash = "sha256:26e9546bfbcde5fcd072bd8f612c9c1b6e2677cb8aadbdf65206674f46dde069"},
 ]
 markupsafe = [
-    {file = "MarkupSafe-2.0.1-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:d8446c54dc28c01e5a2dbac5a25f071f6653e6e40f3a8818e8b45d790fe6ef53"},
-    {file = "MarkupSafe-2.0.1-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:36bc903cbb393720fad60fc28c10de6acf10dc6cc883f3e24ee4012371399a38"},
-    {file = "MarkupSafe-2.0.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:2d7d807855b419fc2ed3e631034685db6079889a1f01d5d9dac950f764da3dad"},
-    {file = "MarkupSafe-2.0.1-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:add36cb2dbb8b736611303cd3bfcee00afd96471b09cda130da3581cbdc56a6d"},
-    {file = "MarkupSafe-2.0.1-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl", hash = "sha256:168cd0a3642de83558a5153c8bd34f175a9a6e7f6dc6384b9655d2697312a646"},
-    {file = "MarkupSafe-2.0.1-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:4dc8f9fb58f7364b63fd9f85013b780ef83c11857ae79f2feda41e270468dd9b"},
-    {file = "MarkupSafe-2.0.1-cp310-cp310-musllinux_1_1_i686.whl", hash = "sha256:20dca64a3ef2d6e4d5d615a3fd418ad3bde77a47ec8a23d984a12b5b4c74491a"},
-    {file = "MarkupSafe-2.0.1-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:cdfba22ea2f0029c9261a4bd07e830a8da012291fbe44dc794e488b6c9bb353a"},
-    {file = "MarkupSafe-2.0.1-cp310-cp310-win32.whl", hash = "sha256:99df47edb6bda1249d3e80fdabb1dab8c08ef3975f69aed437cb69d0a5de1e28"},
-    {file = "MarkupSafe-2.0.1-cp310-cp310-win_amd64.whl", hash = "sha256:e0f138900af21926a02425cf736db95be9f4af72ba1bb21453432a07f6082134"},
     {file = "MarkupSafe-2.0.1-cp36-cp36m-macosx_10_9_x86_64.whl", hash = "sha256:f9081981fe268bd86831e5c75f7de206ef275defcb82bc70740ae6dc507aee51"},
     {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux1_i686.whl", hash = "sha256:0955295dd5eec6cb6cc2fe1698f4c6d84af2e92de33fbcac4111913cd100a6ff"},
     {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux1_x86_64.whl", hash = "sha256:0446679737af14f45767963a1a9ef7620189912317d095f2d9ffa183a4d25d2b"},
     {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux2010_i686.whl", hash = "sha256:f826e31d18b516f653fe296d967d700fddad5901ae07c622bb3705955e1faa94"},
     {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux2010_x86_64.whl", hash = "sha256:fa130dd50c57d53368c9d59395cb5526eda596d3ffe36666cd81a44d56e48872"},
     {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux2014_aarch64.whl", hash = "sha256:905fec760bd2fa1388bb5b489ee8ee5f7291d692638ea5f67982d968366bef9f"},
-    {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:bf5d821ffabf0ef3533c39c518f3357b171a1651c1ff6827325e4489b0e46c3c"},
-    {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux_2_5_i686.manylinux1_i686.manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:0d4b31cc67ab36e3392bbf3862cfbadac3db12bdd8b02a2731f509ed5b829724"},
-    {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl", hash = "sha256:baa1a4e8f868845af802979fcdbf0bb11f94f1cb7ced4c4b8a351bb60d108145"},
-    {file = "MarkupSafe-2.0.1-cp36-cp36m-musllinux_1_1_aarch64.whl", hash = "sha256:deb993cacb280823246a026e3b2d81c493c53de6acfd5e6bfe31ab3402bb37dd"},
-    {file = "MarkupSafe-2.0.1-cp36-cp36m-musllinux_1_1_i686.whl", hash = "sha256:63f3268ba69ace99cab4e3e3b5840b03340efed0948ab8f78d2fd87ee5442a4f"},
-    {file = "MarkupSafe-2.0.1-cp36-cp36m-musllinux_1_1_x86_64.whl", hash = "sha256:8d206346619592c6200148b01a2142798c989edcb9c896f9ac9722a99d4e77e6"},
     {file = "MarkupSafe-2.0.1-cp36-cp36m-win32.whl", hash = "sha256:6c4ca60fa24e85fe25b912b01e62cb969d69a23a5d5867682dd3e80b5b02581d"},
     {file = "MarkupSafe-2.0.1-cp36-cp36m-win_amd64.whl", hash = "sha256:b2f4bf27480f5e5e8ce285a8c8fd176c0b03e93dcc6646477d4630e83440c6a9"},
     {file = "MarkupSafe-2.0.1-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:0717a7390a68be14b8c793ba258e075c6f4ca819f15edfc2a3a027c823718567"},
@@ -1593,27 +1596,14 @@ markupsafe = [
     {file = "MarkupSafe-2.0.1-cp37-cp37m-manylinux2010_i686.whl", hash = "sha256:d7f9850398e85aba693bb640262d3611788b1f29a79f0c93c565694658f4071f"},
     {file = "MarkupSafe-2.0.1-cp37-cp37m-manylinux2010_x86_64.whl", hash = "sha256:6a7fae0dd14cf60ad5ff42baa2e95727c3d81ded453457771d02b7d2b3f9c0c2"},
     {file = "MarkupSafe-2.0.1-cp37-cp37m-manylinux2014_aarch64.whl", hash = "sha256:b7f2d075102dc8c794cbde1947378051c4e5180d52d276987b8d28a3bd58c17d"},
-    {file = "MarkupSafe-2.0.1-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e9936f0b261d4df76ad22f8fee3ae83b60d7c3e871292cd42f40b81b70afae85"},
-    {file = "MarkupSafe-2.0.1-cp37-cp37m-manylinux_2_5_i686.manylinux1_i686.manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:2a7d351cbd8cfeb19ca00de495e224dea7e7d919659c2841bbb7f420ad03e2d6"},
-    {file = "MarkupSafe-2.0.1-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl", hash = "sha256:60bf42e36abfaf9aff1f50f52644b336d4f0a3fd6d8a60ca0d054ac9f713a864"},
-    {file = "MarkupSafe-2.0.1-cp37-cp37m-musllinux_1_1_aarch64.whl", hash = "sha256:d6c7ebd4e944c85e2c3421e612a7057a2f48d478d79e61800d81468a8d842207"},
-    {file = "MarkupSafe-2.0.1-cp37-cp37m-musllinux_1_1_i686.whl", hash = "sha256:f0567c4dc99f264f49fe27da5f735f414c4e7e7dd850cfd8e69f0862d7c74ea9"},
-    {file = "MarkupSafe-2.0.1-cp37-cp37m-musllinux_1_1_x86_64.whl", hash = "sha256:89c687013cb1cd489a0f0ac24febe8c7a666e6e221b783e53ac50ebf68e45d86"},
     {file = "MarkupSafe-2.0.1-cp37-cp37m-win32.whl", hash = "sha256:a30e67a65b53ea0a5e62fe23682cfe22712e01f453b95233b25502f7c61cb415"},
     {file = "MarkupSafe-2.0.1-cp37-cp37m-win_amd64.whl", hash = "sha256:611d1ad9a4288cf3e3c16014564df047fe08410e628f89805e475368bd304914"},
-    {file = "MarkupSafe-2.0.1-cp38-cp38-macosx_10_9_universal2.whl", hash = "sha256:5bb28c636d87e840583ee3adeb78172efc47c8b26127267f54a9c0ec251d41a9"},
     {file = "MarkupSafe-2.0.1-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:be98f628055368795d818ebf93da628541e10b75b41c559fdf36d104c5787066"},
     {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux1_i686.whl", hash = "sha256:1d609f577dc6e1aa17d746f8bd3c31aa4d258f4070d61b2aa5c4166c1539de35"},
     {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux1_x86_64.whl", hash = "sha256:7d91275b0245b1da4d4cfa07e0faedd5b0812efc15b702576d103293e252af1b"},
     {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux2010_i686.whl", hash = "sha256:01a9b8ea66f1658938f65b93a85ebe8bc016e6769611be228d797c9d998dd298"},
     {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux2010_x86_64.whl", hash = "sha256:47ab1e7b91c098ab893b828deafa1203de86d0bc6ab587b160f78fe6c4011f75"},
     {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux2014_aarch64.whl", hash = "sha256:97383d78eb34da7e1fa37dd273c20ad4320929af65d156e35a5e2d89566d9dfb"},
-    {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6fcf051089389abe060c9cd7caa212c707e58153afa2c649f00346ce6d260f1b"},
-    {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:5855f8438a7d1d458206a2466bf82b0f104a3724bf96a1c781ab731e4201731a"},
-    {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl", hash = "sha256:3dd007d54ee88b46be476e293f48c85048603f5f516008bee124ddd891398ed6"},
-    {file = "MarkupSafe-2.0.1-cp38-cp38-musllinux_1_1_aarch64.whl", hash = "sha256:aca6377c0cb8a8253e493c6b451565ac77e98c2951c45f913e0b52facdcff83f"},
-    {file = "MarkupSafe-2.0.1-cp38-cp38-musllinux_1_1_i686.whl", hash = "sha256:04635854b943835a6ea959e948d19dcd311762c5c0c6e1f0e16ee57022669194"},
-    {file = "MarkupSafe-2.0.1-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:6300b8454aa6930a24b9618fbb54b5a68135092bc666f7b06901f897fa5c2fee"},
     {file = "MarkupSafe-2.0.1-cp38-cp38-win32.whl", hash = "sha256:023cb26ec21ece8dc3907c0e8320058b2e0cb3c55cf9564da612bc325bed5e64"},
     {file = "MarkupSafe-2.0.1-cp38-cp38-win_amd64.whl", hash = "sha256:984d76483eb32f1bcb536dc27e4ad56bba4baa70be32fa87152832cdd9db0833"},
     {file = "MarkupSafe-2.0.1-cp39-cp39-macosx_10_9_universal2.whl", hash = "sha256:2ef54abee730b502252bcdf31b10dacb0a416229b72c18b19e24a4509f273d26"},
@@ -1623,12 +1613,6 @@ markupsafe = [
     {file = "MarkupSafe-2.0.1-cp39-cp39-manylinux2010_i686.whl", hash = "sha256:4efca8f86c54b22348a5467704e3fec767b2db12fc39c6d963168ab1d3fc9135"},
     {file = "MarkupSafe-2.0.1-cp39-cp39-manylinux2010_x86_64.whl", hash = "sha256:ab3ef638ace319fa26553db0624c4699e31a28bb2a835c5faca8f8acf6a5a902"},
     {file = "MarkupSafe-2.0.1-cp39-cp39-manylinux2014_aarch64.whl", hash = "sha256:f8ba0e8349a38d3001fae7eadded3f6606f0da5d748ee53cc1dab1d6527b9509"},
-    {file = "MarkupSafe-2.0.1-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:c47adbc92fc1bb2b3274c4b3a43ae0e4573d9fbff4f54cd484555edbf030baf1"},
-    {file = "MarkupSafe-2.0.1-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:37205cac2a79194e3750b0af2a5720d95f786a55ce7df90c3af697bfa100eaac"},
-    {file = "MarkupSafe-2.0.1-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl", hash = "sha256:1f2ade76b9903f39aa442b4aadd2177decb66525062db244b35d71d0ee8599b6"},
-    {file = "MarkupSafe-2.0.1-cp39-cp39-musllinux_1_1_aarch64.whl", hash = "sha256:4296f2b1ce8c86a6aea78613c34bb1a672ea0e3de9c6ba08a960efe0b0a09047"},
-    {file = "MarkupSafe-2.0.1-cp39-cp39-musllinux_1_1_i686.whl", hash = "sha256:9f02365d4e99430a12647f09b6cc8bab61a6564363f313126f775eb4f6ef798e"},
-    {file = "MarkupSafe-2.0.1-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:5b6d930f030f8ed98e3e6c98ffa0652bdb82601e7a016ec2ab5d7ff23baa78d1"},
     {file = "MarkupSafe-2.0.1-cp39-cp39-win32.whl", hash = "sha256:10f82115e21dc0dfec9ab5c0223652f7197feb168c940f3ef61563fc2d6beb74"},
     {file = "MarkupSafe-2.0.1-cp39-cp39-win_amd64.whl", hash = "sha256:693ce3f9e70a6cf7d2fb9e6c9d8b204b6b39897a2c4a1aa65728d5ac97dcc1d8"},
     {file = "MarkupSafe-2.0.1.tar.gz", hash = "sha256:594c67807fb16238b30c44bdf74f36c02cdf22d1c8cda91ef8a0ed8dabf5620a"},
@@ -1730,7 +1714,6 @@ pbr = [
     {file = "pbr-5.8.0.tar.gz", hash = "sha256:672d8ebee84921862110f23fcec2acea191ef58543d34dfe9ef3d9f13c31cddf"},
 ]
 pdoc3 = [
-    {file = "pdoc3-0.10.0-py3-none-any.whl", hash = "sha256:ba45d1ada1bd987427d2bf5cdec30b2631a3ff5fb01f6d0e77648a572ce6028b"},
     {file = "pdoc3-0.10.0.tar.gz", hash = "sha256:5f22e7bcb969006738e1aa4219c75a32f34c2d62d46dc9d2fb2d3e0b0287e4b7"},
 ]
 platformdirs = [
@@ -1979,9 +1962,17 @@ typed-ast = [
     {file = "typed_ast-1.4.3-cp39-cp39-win_amd64.whl", hash = "sha256:9c6d1a54552b5330bc657b7ef0eae25d00ba7ffe85d9ea8ae6540d2197a3788c"},
     {file = "typed_ast-1.4.3.tar.gz", hash = "sha256:fb1bbeac803adea29cedd70781399c99138358c26d05fcbd23c13016b7f5ec65"},
 ]
+types-requests = [
+    {file = "types-requests-2.28.5.tar.gz", hash = "sha256:ac618bfefcb3742eaf97c961e13e9e5a226e545eda4a3dbe293b898d40933ad1"},
+    {file = "types_requests-2.28.5-py3-none-any.whl", hash = "sha256:98ab647ae88b5e2c41d6d20cfcb5117da1bea561110000b6fdeeea07b3e89877"},
+]
+types-urllib3 = [
+    {file = "types-urllib3-1.26.17.tar.gz", hash = "sha256:73fd274524c3fc7cd8cd9ceb0cb67ed99b45f9cb2831013e46d50c1451044800"},
+    {file = "types_urllib3-1.26.17-py3-none-any.whl", hash = "sha256:0d027fcd27dbb3cb532453b4d977e05bc1e13aefd70519866af211b3003d895d"},
+]
 typing-extensions = [
-    {file = "typing_extensions-4.1.1-py3-none-any.whl", hash = "sha256:21c85e0fe4b9a155d0799430b0ad741cdce7e359660ccbd8b530613e8df88ce2"},
-    {file = "typing_extensions-4.1.1.tar.gz", hash = "sha256:1a9462dcc3347a79b1f1c0271fbe79e844580bb598bafa1ed208b94da3cdcd42"},
+    {file = "typing_extensions-4.3.0-py3-none-any.whl", hash = "sha256:25642c956049920a5aa49edcdd6ab1e06d7e5d467fc00e0506c44ac86fbfca02"},
+    {file = "typing_extensions-4.3.0.tar.gz", hash = "sha256:e6d2677a32f47fc7eb2795db1dd15c1f34eff616bcaf2cfb5e997f854fa1c4a6"},
 ]
 urllib3 = [
     {file = "urllib3-1.26.7-py2.py3-none-any.whl", hash = "sha256:c4fdf4019605b6e5423637e01bc9fe4daef873709a7973e195ceba0a62bbc844"},
diff --git a/pyproject.toml b/pyproject.toml
index ebf6d3a0e9b..a07ce065857 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -66,7 +66,8 @@ pytest-benchmark = "^3.4.1"
 mypy-boto3-cloudwatch = "^1.24.35"
 mypy-boto3-lambda = "^1.24.0"
 mypy-boto3-xray = "^1.24.0"
-
+types-requests = "^2.28.5"
+typing-extensions = { version = "^4.3.0", python = ">=3.7" }
 
 [tool.poetry.extras]
 pydantic = ["pydantic", "email-validator"]

From ec3b952f424a77dec28a525e9144b4c24b63cf70 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Thu, 28 Jul 2022 14:09:08 +0200
Subject: [PATCH 3/6] chore(deps-dev): bump flake8-isort from 4.1.1 to
 4.1.2.post0 (#1384)

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 poetry.lock    | 88 ++++++++++++++++++++++++++++++--------------------
 pyproject.toml |  2 +-
 2 files changed, 54 insertions(+), 36 deletions(-)

diff --git a/poetry.lock b/poetry.lock
index bdea1decfde..cd052245f61 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -131,7 +131,7 @@ python-versions = "*"
 attrs = ">=17.3"
 
 [package.extras]
-dev = ["bumpversion", "wheel", "watchdog", "flake8", "tox", "coverage", "sphinx", "pytest", "hypothesis", "pendulum"]
+dev = ["pendulum", "hypothesis", "pytest", "sphinx", "coverage", "tox", "flake8", "watchdog", "wheel", "bumpversion"]
 
 [[package]]
 name = "cattrs"
@@ -236,11 +236,11 @@ optional = true
 python-versions = ">=3.6"
 
 [package.extras]
-dnssec = ["cryptography (>=2.6)"]
-doh = ["requests", "requests-toolbelt"]
+trio = ["sniffio (>=1.1)", "trio (>=0.14.0)"]
+curio = ["sniffio (>=1.1)", "curio (>=1.2)"]
 idna = ["idna (>=2.1)"]
-curio = ["curio (>=1.2)", "sniffio (>=1.1)"]
-trio = ["trio (>=0.14.0)", "sniffio (>=1.1)"]
+doh = ["requests-toolbelt", "requests"]
+dnssec = ["cryptography (>=2.6)"]
 
 [[package]]
 name = "email-validator"
@@ -399,7 +399,7 @@ python-versions = "*"
 
 [[package]]
 name = "flake8-isort"
-version = "4.1.1"
+version = "4.1.2.post0"
 description = "flake8 plugin that integrates isort ."
 category = "dev"
 optional = false
@@ -408,7 +408,6 @@ python-versions = "*"
 [package.dependencies]
 flake8 = ">=3.2.1,<5"
 isort = ">=4.3.5,<6"
-testfixtures = ">=6.8.0,<7"
 
 [package.extras]
 test = ["pytest-cov"]
@@ -441,7 +440,7 @@ python-versions = "*"
 python-dateutil = ">=2.8.1"
 
 [package.extras]
-dev = ["twine", "markdown", "flake8", "wheel"]
+dev = ["wheel", "flake8", "markdown", "twine"]
 
 [[package]]
 name = "gitdb"
@@ -646,8 +645,8 @@ packaging = "*"
 "ruamel.yaml" = "*"
 
 [package.extras]
-dev = ["coverage", "flake8 (>=3.0)", "pypandoc (>=1.4)"]
-test = ["coverage", "flake8 (>=3.0)"]
+test = ["flake8 (>=3.0)", "coverage"]
+dev = ["pypandoc (>=1.4)", "flake8 (>=3.0)", "coverage"]
 
 [[package]]
 name = "mkdocs"
@@ -861,8 +860,8 @@ optional = false
 python-versions = ">=3.6"
 
 [package.extras]
-docs = ["Sphinx (>=4)", "furo (>=2021.7.5b38)", "proselint (>=0.10.2)", "sphinx-autodoc-typehints (>=1.12)"]
-test = ["appdirs (==1.4.4)", "pytest (>=6)", "pytest-cov (>=2.7)", "pytest-mock (>=3.6)"]
+test = ["pytest-mock (>=3.6)", "pytest-cov (>=2.7)", "pytest (>=6)", "appdirs (==1.4.4)"]
+docs = ["sphinx-autodoc-typehints (>=1.12)", "proselint (>=0.10.2)", "furo (>=2021.7.5b38)", "Sphinx (>=4)"]
 
 [[package]]
 name = "pluggy"
@@ -876,8 +875,8 @@ python-versions = ">=3.6"
 importlib-metadata = {version = ">=0.12", markers = "python_version < \"3.8\""}
 
 [package.extras]
-dev = ["pre-commit", "tox"]
-testing = ["pytest", "pytest-benchmark"]
+testing = ["pytest-benchmark", "pytest"]
+dev = ["tox", "pre-commit"]
 
 [[package]]
 name = "publication"
@@ -1031,7 +1030,7 @@ coverage = {version = ">=5.2.1", extras = ["toml"]}
 pytest = ">=4.6"
 
 [package.extras]
-testing = ["fields", "hunter", "process-tests", "six", "pytest-xdist", "virtualenv"]
+testing = ["virtualenv", "pytest-xdist", "six", "process-tests", "hunter", "fields"]
 
 [[package]]
 name = "pytest-forked"
@@ -1215,19 +1214,6 @@ python-versions = ">=3.6"
 importlib-metadata = {version = ">=1.7.0", markers = "python_version < \"3.8\""}
 pbr = ">=2.0.0,<2.1.0 || >2.1.0"
 
-[[package]]
-name = "testfixtures"
-version = "6.18.3"
-description = "A collection of helpers and mock objects for unit tests and doc tests."
-category = "dev"
-optional = false
-python-versions = "*"
-
-[package.extras]
-build = ["setuptools-git", "wheel", "twine"]
-docs = ["sphinx", "zope.component", "sybil", "twisted", "mock", "django (<2)", "django"]
-test = ["pytest (>=3.6)", "pytest-cov", "pytest-django", "zope.component", "sybil", "twisted", "mock", "django (<2)", "django"]
-
 [[package]]
 name = "toml"
 version = "0.10.2"
@@ -1342,7 +1328,7 @@ pydantic = ["pydantic", "email-validator"]
 [metadata]
 lock-version = "1.1"
 python-versions = "^3.6.2"
-content-hash = "783598fdfeef6abc4615ac9ba1ab8ade3cc2ad03859d0ea22d22bc1afe3cbb20"
+content-hash = "f728d2bb00dfcca0cacf38bb7a7f95cf15a2dc1a11efc79ae4dc5e214efa91da"
 
 [metadata.files]
 atomicwrites = [
@@ -1516,8 +1502,8 @@ flake8-fixme = [
     {file = "flake8_fixme-1.1.1-py2.py3-none-any.whl", hash = "sha256:226a6f2ef916730899f29ac140bed5d4a17e5aba79f00a0e3ae1eff1997cb1ac"},
 ]
 flake8-isort = [
-    {file = "flake8-isort-4.1.1.tar.gz", hash = "sha256:d814304ab70e6e58859bc5c3e221e2e6e71c958e7005239202fee19c24f82717"},
-    {file = "flake8_isort-4.1.1-py3-none-any.whl", hash = "sha256:c4e8b6dcb7be9b71a02e6e5d4196cefcef0f3447be51e82730fb336fff164949"},
+    {file = "flake8-isort-4.1.2.post0.tar.gz", hash = "sha256:dee69bc3c09f0832df88acf795845db8a6673b79237371a05fa927ce095248e5"},
+    {file = "flake8_isort-4.1.2.post0-py3-none-any.whl", hash = "sha256:4f95b40706dbb507cff872b34683283662e945d6028d3c8257e69de5fc6b7446"},
 ]
 flake8-variables-names = [
     {file = "flake8_variables_names-0.0.4.tar.gz", hash = "sha256:d6fa0571a807c72940b5773827c5760421ea6f8206595ff0a8ecfa01e42bf2cf"},
@@ -1582,12 +1568,28 @@ markdown = [
     {file = "Markdown-3.3.5.tar.gz", hash = "sha256:26e9546bfbcde5fcd072bd8f612c9c1b6e2677cb8aadbdf65206674f46dde069"},
 ]
 markupsafe = [
+    {file = "MarkupSafe-2.0.1-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:d8446c54dc28c01e5a2dbac5a25f071f6653e6e40f3a8818e8b45d790fe6ef53"},
+    {file = "MarkupSafe-2.0.1-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:36bc903cbb393720fad60fc28c10de6acf10dc6cc883f3e24ee4012371399a38"},
+    {file = "MarkupSafe-2.0.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:2d7d807855b419fc2ed3e631034685db6079889a1f01d5d9dac950f764da3dad"},
+    {file = "MarkupSafe-2.0.1-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:add36cb2dbb8b736611303cd3bfcee00afd96471b09cda130da3581cbdc56a6d"},
+    {file = "MarkupSafe-2.0.1-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl", hash = "sha256:168cd0a3642de83558a5153c8bd34f175a9a6e7f6dc6384b9655d2697312a646"},
+    {file = "MarkupSafe-2.0.1-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:4dc8f9fb58f7364b63fd9f85013b780ef83c11857ae79f2feda41e270468dd9b"},
+    {file = "MarkupSafe-2.0.1-cp310-cp310-musllinux_1_1_i686.whl", hash = "sha256:20dca64a3ef2d6e4d5d615a3fd418ad3bde77a47ec8a23d984a12b5b4c74491a"},
+    {file = "MarkupSafe-2.0.1-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:cdfba22ea2f0029c9261a4bd07e830a8da012291fbe44dc794e488b6c9bb353a"},
+    {file = "MarkupSafe-2.0.1-cp310-cp310-win32.whl", hash = "sha256:99df47edb6bda1249d3e80fdabb1dab8c08ef3975f69aed437cb69d0a5de1e28"},
+    {file = "MarkupSafe-2.0.1-cp310-cp310-win_amd64.whl", hash = "sha256:e0f138900af21926a02425cf736db95be9f4af72ba1bb21453432a07f6082134"},
     {file = "MarkupSafe-2.0.1-cp36-cp36m-macosx_10_9_x86_64.whl", hash = "sha256:f9081981fe268bd86831e5c75f7de206ef275defcb82bc70740ae6dc507aee51"},
     {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux1_i686.whl", hash = "sha256:0955295dd5eec6cb6cc2fe1698f4c6d84af2e92de33fbcac4111913cd100a6ff"},
     {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux1_x86_64.whl", hash = "sha256:0446679737af14f45767963a1a9ef7620189912317d095f2d9ffa183a4d25d2b"},
     {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux2010_i686.whl", hash = "sha256:f826e31d18b516f653fe296d967d700fddad5901ae07c622bb3705955e1faa94"},
     {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux2010_x86_64.whl", hash = "sha256:fa130dd50c57d53368c9d59395cb5526eda596d3ffe36666cd81a44d56e48872"},
     {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux2014_aarch64.whl", hash = "sha256:905fec760bd2fa1388bb5b489ee8ee5f7291d692638ea5f67982d968366bef9f"},
+    {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:bf5d821ffabf0ef3533c39c518f3357b171a1651c1ff6827325e4489b0e46c3c"},
+    {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux_2_5_i686.manylinux1_i686.manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:0d4b31cc67ab36e3392bbf3862cfbadac3db12bdd8b02a2731f509ed5b829724"},
+    {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl", hash = "sha256:baa1a4e8f868845af802979fcdbf0bb11f94f1cb7ced4c4b8a351bb60d108145"},
+    {file = "MarkupSafe-2.0.1-cp36-cp36m-musllinux_1_1_aarch64.whl", hash = "sha256:deb993cacb280823246a026e3b2d81c493c53de6acfd5e6bfe31ab3402bb37dd"},
+    {file = "MarkupSafe-2.0.1-cp36-cp36m-musllinux_1_1_i686.whl", hash = "sha256:63f3268ba69ace99cab4e3e3b5840b03340efed0948ab8f78d2fd87ee5442a4f"},
+    {file = "MarkupSafe-2.0.1-cp36-cp36m-musllinux_1_1_x86_64.whl", hash = "sha256:8d206346619592c6200148b01a2142798c989edcb9c896f9ac9722a99d4e77e6"},
     {file = "MarkupSafe-2.0.1-cp36-cp36m-win32.whl", hash = "sha256:6c4ca60fa24e85fe25b912b01e62cb969d69a23a5d5867682dd3e80b5b02581d"},
     {file = "MarkupSafe-2.0.1-cp36-cp36m-win_amd64.whl", hash = "sha256:b2f4bf27480f5e5e8ce285a8c8fd176c0b03e93dcc6646477d4630e83440c6a9"},
     {file = "MarkupSafe-2.0.1-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:0717a7390a68be14b8c793ba258e075c6f4ca819f15edfc2a3a027c823718567"},
@@ -1596,14 +1598,27 @@ markupsafe = [
     {file = "MarkupSafe-2.0.1-cp37-cp37m-manylinux2010_i686.whl", hash = "sha256:d7f9850398e85aba693bb640262d3611788b1f29a79f0c93c565694658f4071f"},
     {file = "MarkupSafe-2.0.1-cp37-cp37m-manylinux2010_x86_64.whl", hash = "sha256:6a7fae0dd14cf60ad5ff42baa2e95727c3d81ded453457771d02b7d2b3f9c0c2"},
     {file = "MarkupSafe-2.0.1-cp37-cp37m-manylinux2014_aarch64.whl", hash = "sha256:b7f2d075102dc8c794cbde1947378051c4e5180d52d276987b8d28a3bd58c17d"},
+    {file = "MarkupSafe-2.0.1-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e9936f0b261d4df76ad22f8fee3ae83b60d7c3e871292cd42f40b81b70afae85"},
+    {file = "MarkupSafe-2.0.1-cp37-cp37m-manylinux_2_5_i686.manylinux1_i686.manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:2a7d351cbd8cfeb19ca00de495e224dea7e7d919659c2841bbb7f420ad03e2d6"},
+    {file = "MarkupSafe-2.0.1-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl", hash = "sha256:60bf42e36abfaf9aff1f50f52644b336d4f0a3fd6d8a60ca0d054ac9f713a864"},
+    {file = "MarkupSafe-2.0.1-cp37-cp37m-musllinux_1_1_aarch64.whl", hash = "sha256:d6c7ebd4e944c85e2c3421e612a7057a2f48d478d79e61800d81468a8d842207"},
+    {file = "MarkupSafe-2.0.1-cp37-cp37m-musllinux_1_1_i686.whl", hash = "sha256:f0567c4dc99f264f49fe27da5f735f414c4e7e7dd850cfd8e69f0862d7c74ea9"},
+    {file = "MarkupSafe-2.0.1-cp37-cp37m-musllinux_1_1_x86_64.whl", hash = "sha256:89c687013cb1cd489a0f0ac24febe8c7a666e6e221b783e53ac50ebf68e45d86"},
     {file = "MarkupSafe-2.0.1-cp37-cp37m-win32.whl", hash = "sha256:a30e67a65b53ea0a5e62fe23682cfe22712e01f453b95233b25502f7c61cb415"},
     {file = "MarkupSafe-2.0.1-cp37-cp37m-win_amd64.whl", hash = "sha256:611d1ad9a4288cf3e3c16014564df047fe08410e628f89805e475368bd304914"},
+    {file = "MarkupSafe-2.0.1-cp38-cp38-macosx_10_9_universal2.whl", hash = "sha256:5bb28c636d87e840583ee3adeb78172efc47c8b26127267f54a9c0ec251d41a9"},
     {file = "MarkupSafe-2.0.1-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:be98f628055368795d818ebf93da628541e10b75b41c559fdf36d104c5787066"},
     {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux1_i686.whl", hash = "sha256:1d609f577dc6e1aa17d746f8bd3c31aa4d258f4070d61b2aa5c4166c1539de35"},
     {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux1_x86_64.whl", hash = "sha256:7d91275b0245b1da4d4cfa07e0faedd5b0812efc15b702576d103293e252af1b"},
     {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux2010_i686.whl", hash = "sha256:01a9b8ea66f1658938f65b93a85ebe8bc016e6769611be228d797c9d998dd298"},
     {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux2010_x86_64.whl", hash = "sha256:47ab1e7b91c098ab893b828deafa1203de86d0bc6ab587b160f78fe6c4011f75"},
     {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux2014_aarch64.whl", hash = "sha256:97383d78eb34da7e1fa37dd273c20ad4320929af65d156e35a5e2d89566d9dfb"},
+    {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:6fcf051089389abe060c9cd7caa212c707e58153afa2c649f00346ce6d260f1b"},
+    {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:5855f8438a7d1d458206a2466bf82b0f104a3724bf96a1c781ab731e4201731a"},
+    {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl", hash = "sha256:3dd007d54ee88b46be476e293f48c85048603f5f516008bee124ddd891398ed6"},
+    {file = "MarkupSafe-2.0.1-cp38-cp38-musllinux_1_1_aarch64.whl", hash = "sha256:aca6377c0cb8a8253e493c6b451565ac77e98c2951c45f913e0b52facdcff83f"},
+    {file = "MarkupSafe-2.0.1-cp38-cp38-musllinux_1_1_i686.whl", hash = "sha256:04635854b943835a6ea959e948d19dcd311762c5c0c6e1f0e16ee57022669194"},
+    {file = "MarkupSafe-2.0.1-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:6300b8454aa6930a24b9618fbb54b5a68135092bc666f7b06901f897fa5c2fee"},
     {file = "MarkupSafe-2.0.1-cp38-cp38-win32.whl", hash = "sha256:023cb26ec21ece8dc3907c0e8320058b2e0cb3c55cf9564da612bc325bed5e64"},
     {file = "MarkupSafe-2.0.1-cp38-cp38-win_amd64.whl", hash = "sha256:984d76483eb32f1bcb536dc27e4ad56bba4baa70be32fa87152832cdd9db0833"},
     {file = "MarkupSafe-2.0.1-cp39-cp39-macosx_10_9_universal2.whl", hash = "sha256:2ef54abee730b502252bcdf31b10dacb0a416229b72c18b19e24a4509f273d26"},
@@ -1613,6 +1628,12 @@ markupsafe = [
     {file = "MarkupSafe-2.0.1-cp39-cp39-manylinux2010_i686.whl", hash = "sha256:4efca8f86c54b22348a5467704e3fec767b2db12fc39c6d963168ab1d3fc9135"},
     {file = "MarkupSafe-2.0.1-cp39-cp39-manylinux2010_x86_64.whl", hash = "sha256:ab3ef638ace319fa26553db0624c4699e31a28bb2a835c5faca8f8acf6a5a902"},
     {file = "MarkupSafe-2.0.1-cp39-cp39-manylinux2014_aarch64.whl", hash = "sha256:f8ba0e8349a38d3001fae7eadded3f6606f0da5d748ee53cc1dab1d6527b9509"},
+    {file = "MarkupSafe-2.0.1-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:c47adbc92fc1bb2b3274c4b3a43ae0e4573d9fbff4f54cd484555edbf030baf1"},
+    {file = "MarkupSafe-2.0.1-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_12_i686.manylinux2010_i686.whl", hash = "sha256:37205cac2a79194e3750b0af2a5720d95f786a55ce7df90c3af697bfa100eaac"},
+    {file = "MarkupSafe-2.0.1-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl", hash = "sha256:1f2ade76b9903f39aa442b4aadd2177decb66525062db244b35d71d0ee8599b6"},
+    {file = "MarkupSafe-2.0.1-cp39-cp39-musllinux_1_1_aarch64.whl", hash = "sha256:4296f2b1ce8c86a6aea78613c34bb1a672ea0e3de9c6ba08a960efe0b0a09047"},
+    {file = "MarkupSafe-2.0.1-cp39-cp39-musllinux_1_1_i686.whl", hash = "sha256:9f02365d4e99430a12647f09b6cc8bab61a6564363f313126f775eb4f6ef798e"},
+    {file = "MarkupSafe-2.0.1-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:5b6d930f030f8ed98e3e6c98ffa0652bdb82601e7a016ec2ab5d7ff23baa78d1"},
     {file = "MarkupSafe-2.0.1-cp39-cp39-win32.whl", hash = "sha256:10f82115e21dc0dfec9ab5c0223652f7197feb168c940f3ef61563fc2d6beb74"},
     {file = "MarkupSafe-2.0.1-cp39-cp39-win_amd64.whl", hash = "sha256:693ce3f9e70a6cf7d2fb9e6c9d8b204b6b39897a2c4a1aa65728d5ac97dcc1d8"},
     {file = "MarkupSafe-2.0.1.tar.gz", hash = "sha256:594c67807fb16238b30c44bdf74f36c02cdf22d1c8cda91ef8a0ed8dabf5620a"},
@@ -1714,6 +1735,7 @@ pbr = [
     {file = "pbr-5.8.0.tar.gz", hash = "sha256:672d8ebee84921862110f23fcec2acea191ef58543d34dfe9ef3d9f13c31cddf"},
 ]
 pdoc3 = [
+    {file = "pdoc3-0.10.0-py3-none-any.whl", hash = "sha256:ba45d1ada1bd987427d2bf5cdec30b2631a3ff5fb01f6d0e77648a572ce6028b"},
     {file = "pdoc3-0.10.0.tar.gz", hash = "sha256:5f22e7bcb969006738e1aa4219c75a32f34c2d62d46dc9d2fb2d3e0b0287e4b7"},
 ]
 platformdirs = [
@@ -1918,10 +1940,6 @@ stevedore = [
     {file = "stevedore-3.5.0-py3-none-any.whl", hash = "sha256:a547de73308fd7e90075bb4d301405bebf705292fa90a90fc3bcf9133f58616c"},
     {file = "stevedore-3.5.0.tar.gz", hash = "sha256:f40253887d8712eaa2bb0ea3830374416736dc8ec0e22f5a65092c1174c44335"},
 ]
-testfixtures = [
-    {file = "testfixtures-6.18.3-py2.py3-none-any.whl", hash = "sha256:6ddb7f56a123e1a9339f130a200359092bd0a6455e31838d6c477e8729bb7763"},
-    {file = "testfixtures-6.18.3.tar.gz", hash = "sha256:2600100ae96ffd082334b378e355550fef8b4a529a6fa4c34f47130905c7426d"},
-]
 toml = [
     {file = "toml-0.10.2-py2.py3-none-any.whl", hash = "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b"},
     {file = "toml-0.10.2.tar.gz", hash = "sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"},
diff --git a/pyproject.toml b/pyproject.toml
index a07ce065857..e617d91cb21 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -39,7 +39,7 @@ flake8-builtins = "^1.5.3"
 flake8-comprehensions = "^3.7.0"
 flake8-debugger = "^4.0.0"
 flake8-fixme = "^1.1.1"
-flake8-isort = "^4.1.1"
+flake8-isort = "^4.1.2"
 flake8-variables-names = "^0.0.4"
 isort = "^5.10.1"
 pytest-cov = "^3.0.0"

From 39c4a5942875af6df20969f67a8efa7403a3021c Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Thu, 28 Jul 2022 14:09:27 +0200
Subject: [PATCH 4/6] chore(deps): bump constructs from 10.1.1 to 10.1.59
 (#1396)

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 layer/requirements.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/layer/requirements.txt b/layer/requirements.txt
index 4e42439d2b3..ea37d383dd7 100644
--- a/layer/requirements.txt
+++ b/layer/requirements.txt
@@ -27,9 +27,9 @@ cdk-lambda-powertools-python-layer==2.0.49 \
     --hash=sha256:8055fc691539f16e22a40e3d3df9c3f59fb28012437b08c47c639aefb001f1b2 \
     --hash=sha256:9b0a7b7344f9ccb486564af728cefeac743687bfb131631e6d9171a55800dbac
     # via -r requirements.txt
-constructs==10.1.52 \
-    --hash=sha256:a1887a0ee28336d38cc61830eae9dd774b4b3628c33498645f93bcfa4b54ed99 \
-    --hash=sha256:beabd1895cbe52a8b44dafe8b822e69585179e5e421ceb7e262a7ab327604fc8
+constructs==10.1.59 \
+    --hash=sha256:1f3c8a87f3d78df0502b6966cfa534c50fe10e6e4ad9a53e9bf8f28f85b895db \
+    --hash=sha256:2d73f3c00eb72d9229d848e757b07f745483fcf7959ec0dad731ff55fe5fa02e
     # via
     #   -r requirements.txt
     #   aws-cdk-lib

From 02e8b600531d2a25f0f721bea8b26c47930474aa Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Thu, 28 Jul 2022 14:09:47 +0200
Subject: [PATCH 5/6] chore(deps): bump jsii from 1.57.0 to 1.63.1 (#1390)

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
---
 layer/requirements.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/layer/requirements.txt b/layer/requirements.txt
index ea37d383dd7..642cf5d9096 100644
--- a/layer/requirements.txt
+++ b/layer/requirements.txt
@@ -40,9 +40,9 @@ exceptiongroup==1.0.0rc8 \
     # via
     #   -r requirements.txt
     #   cattrs
-jsii==1.62.0 \
-    --hash=sha256:c22ac7373260fbabdb012faba717a8a4dbd933120cee373905030fd66956a65a \
-    --hash=sha256:d124b0f350fd206e0488d3bb83dc58832f11e64fc728fd3a10096872d8a3a938
+jsii==1.63.1 \
+    --hash=sha256:1921cd0e84c180e160711c5c5caabc5ab17ab65a1640acd3f5e71e753e161501 \
+    --hash=sha256:e67d8887d8012e8e98b46ed120bffd062165765ced44eeb202fbb5c1b162bf40
     # via
     #   -r requirements.txt
     #   aws-cdk-lib

From 160feae22e24708bc5bb4cf979a0c05c99db87a4 Mon Sep 17 00:00:00 2001
From: Ruben Fonseca <fonseka@gmail.com>
Date: Fri, 29 Jul 2022 15:50:36 +0200
Subject: [PATCH 6/6] feat(idempotency): handle lambda timeout scenarios for
 INPROGRESS records (#1387)

Co-authored-by: heitorlessa <lessa@amazon.co.uk>
---
 .../utilities/idempotency/base.py             |  32 ++-
 .../utilities/idempotency/config.py           |  10 +
 .../utilities/idempotency/idempotency.py      |   2 +
 .../utilities/idempotency/persistence/base.py |  20 +-
 .../idempotency/persistence/dynamodb.py       |  59 ++++-
 docs/media/idempotent_sequence.png            | Bin 74622 -> 0 bytes
 docs/media/idempotent_sequence_exception.png  | Bin 46647 -> 0 bytes
 docs/utilities/idempotency.md                 | 209 +++++++++++----
 .../event_handler/test_api_gateway.py         |   2 +-
 tests/functional/idempotency/conftest.py      |  78 ++++--
 .../idempotency/test_idempotency.py           | 239 +++++++++++++++---
 tests/functional/idempotency/utils.py         |  31 ++-
 12 files changed, 561 insertions(+), 121 deletions(-)
 delete mode 100644 docs/media/idempotent_sequence.png
 delete mode 100644 docs/media/idempotent_sequence_exception.png

diff --git a/aws_lambda_powertools/utilities/idempotency/base.py b/aws_lambda_powertools/utilities/idempotency/base.py
index 41fbd232ad3..ddd054daa14 100644
--- a/aws_lambda_powertools/utilities/idempotency/base.py
+++ b/aws_lambda_powertools/utilities/idempotency/base.py
@@ -1,3 +1,4 @@
+import datetime
 import logging
 from copy import deepcopy
 from typing import Any, Callable, Dict, Optional, Tuple
@@ -73,6 +74,7 @@ def __init__(
         self.data = deepcopy(_prepare_data(function_payload))
         self.fn_args = function_args
         self.fn_kwargs = function_kwargs
+        self.config = config
 
         persistence_store.configure(config, self.function.__name__)
         self.persistence_store = persistence_store
@@ -101,7 +103,9 @@ def _process_idempotency(self):
         try:
             # We call save_inprogress first as an optimization for the most common case where no idempotent record
             # already exists. If it succeeds, there's no need to call get_record.
-            self.persistence_store.save_inprogress(data=self.data)
+            self.persistence_store.save_inprogress(
+                data=self.data, remaining_time_in_millis=self._get_remaining_time_in_millis()
+            )
         except IdempotencyKeyError:
             raise
         except IdempotencyItemAlreadyExistsError:
@@ -113,6 +117,25 @@ def _process_idempotency(self):
 
         return self._get_function_response()
 
+    def _get_remaining_time_in_millis(self) -> Optional[int]:
+        """
+        Tries to determine the remaining time available for the current lambda invocation.
+
+        This only works if the idempotent handler decorator is used, since we need to access the lambda context.
+        However, this could be improved if we start storing the lambda context globally during the invocation. One
+        way to do this is to register the lambda context when configuring the IdempotencyConfig object.
+
+        Returns
+        -------
+        Optional[int]
+            Remaining time in millis, or None if the remaining time cannot be determined.
+        """
+
+        if self.config.lambda_context is not None:
+            return self.config.lambda_context.get_remaining_time_in_millis()
+
+        return None
+
     def _get_idempotency_record(self) -> DataRecord:
         """
         Retrieve the idempotency record from the persistence layer.
@@ -167,6 +190,13 @@ def _handle_for_status(self, data_record: DataRecord) -> Optional[Dict[Any, Any]
             raise IdempotencyInconsistentStateError("save_inprogress and get_record return inconsistent results.")
 
         if data_record.status == STATUS_CONSTANTS["INPROGRESS"]:
+            if data_record.in_progress_expiry_timestamp is not None and data_record.in_progress_expiry_timestamp < int(
+                datetime.datetime.now().timestamp() * 1000
+            ):
+                raise IdempotencyInconsistentStateError(
+                    "item should have been expired in-progress because it already time-outed."
+                )
+
             raise IdempotencyAlreadyInProgressError(
                 f"Execution already in progress with idempotency key: "
                 f"{self.persistence_store.event_key_jmespath}={data_record.idempotency_key}"
diff --git a/aws_lambda_powertools/utilities/idempotency/config.py b/aws_lambda_powertools/utilities/idempotency/config.py
index 06468cc74a7..e78f339fdc9 100644
--- a/aws_lambda_powertools/utilities/idempotency/config.py
+++ b/aws_lambda_powertools/utilities/idempotency/config.py
@@ -1,5 +1,7 @@
 from typing import Dict, Optional
 
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
 
 class IdempotencyConfig:
     def __init__(
@@ -12,6 +14,7 @@ def __init__(
         use_local_cache: bool = False,
         local_cache_max_items: int = 256,
         hash_function: str = "md5",
+        lambda_context: Optional[LambdaContext] = None,
     ):
         """
         Initialize the base persistence layer
@@ -32,6 +35,8 @@ def __init__(
             Max number of items to store in local cache, by default 1024
         hash_function: str, optional
             Function to use for calculating hashes, by default md5.
+        lambda_context: LambdaContext, optional
+            Lambda Context containing information about the invocation, function and execution environment.
         """
         self.event_key_jmespath = event_key_jmespath
         self.payload_validation_jmespath = payload_validation_jmespath
@@ -41,3 +46,8 @@ def __init__(
         self.use_local_cache = use_local_cache
         self.local_cache_max_items = local_cache_max_items
         self.hash_function = hash_function
+        self.lambda_context: Optional[LambdaContext] = lambda_context
+
+    def register_lambda_context(self, lambda_context: LambdaContext):
+        """Captures the Lambda context, to calculate the remaining time before the invocation times out"""
+        self.lambda_context = lambda_context
diff --git a/aws_lambda_powertools/utilities/idempotency/idempotency.py b/aws_lambda_powertools/utilities/idempotency/idempotency.py
index 4a7d8e71e1d..646fd68558f 100644
--- a/aws_lambda_powertools/utilities/idempotency/idempotency.py
+++ b/aws_lambda_powertools/utilities/idempotency/idempotency.py
@@ -62,6 +62,8 @@ def idempotent(
         return handler(event, context)
 
     config = config or IdempotencyConfig()
+    config.register_lambda_context(context)
+
     args = event, context
     idempotency_handler = IdempotencyHandler(
         function=handler,
diff --git a/aws_lambda_powertools/utilities/idempotency/persistence/base.py b/aws_lambda_powertools/utilities/idempotency/persistence/base.py
index e6ffea10de8..a87980d7fe0 100644
--- a/aws_lambda_powertools/utilities/idempotency/persistence/base.py
+++ b/aws_lambda_powertools/utilities/idempotency/persistence/base.py
@@ -40,6 +40,7 @@ def __init__(
         idempotency_key,
         status: str = "",
         expiry_timestamp: Optional[int] = None,
+        in_progress_expiry_timestamp: Optional[int] = None,
         response_data: Optional[str] = "",
         payload_hash: Optional[str] = None,
     ) -> None:
@@ -53,6 +54,8 @@ def __init__(
             status of the idempotent record
         expiry_timestamp: int, optional
             time before the record should expire, in seconds
+        in_progress_expiry_timestamp: int, optional
+            time before the record should expire while in the INPROGRESS state, in seconds
         payload_hash: str, optional
             hashed representation of payload
         response_data: str, optional
@@ -61,6 +64,7 @@ def __init__(
         self.idempotency_key = idempotency_key
         self.payload_hash = payload_hash
         self.expiry_timestamp = expiry_timestamp
+        self.in_progress_expiry_timestamp = in_progress_expiry_timestamp
         self._status = status
         self.response_data = response_data
 
@@ -328,7 +332,7 @@ def save_success(self, data: Dict[str, Any], result: dict) -> None:
 
         self._save_to_cache(data_record=data_record)
 
-    def save_inprogress(self, data: Dict[str, Any]) -> None:
+    def save_inprogress(self, data: Dict[str, Any], remaining_time_in_millis: Optional[int] = None) -> None:
         """
         Save record of function's execution being in progress
 
@@ -336,6 +340,8 @@ def save_inprogress(self, data: Dict[str, Any]) -> None:
         ----------
         data: Dict[str, Any]
             Payload
+        remaining_time_in_millis: Optional[int]
+            If expiry of in-progress invocations is enabled, this will contain the remaining time available in millis
         """
         data_record = DataRecord(
             idempotency_key=self._get_hashed_idempotency_key(data=data),
@@ -344,6 +350,18 @@ def save_inprogress(self, data: Dict[str, Any]) -> None:
             payload_hash=self._get_hashed_payload(data=data),
         )
 
+        if remaining_time_in_millis:
+            now = datetime.datetime.now()
+            period = datetime.timedelta(milliseconds=remaining_time_in_millis)
+            timestamp = (now + period).timestamp()
+
+            data_record.in_progress_expiry_timestamp = int(timestamp * 1000)
+        else:
+            warnings.warn(
+                "Couldn't determine the remaining time left. "
+                "Did you call register_lambda_context on IdempotencyConfig?"
+            )
+
         logger.debug(f"Saving in progress record for idempotency key: {data_record.idempotency_key}")
 
         if self._retrieve_from_cache(idempotency_key=data_record.idempotency_key):
diff --git a/aws_lambda_powertools/utilities/idempotency/persistence/dynamodb.py b/aws_lambda_powertools/utilities/idempotency/persistence/dynamodb.py
index 88955738ecc..90cbd853e8a 100644
--- a/aws_lambda_powertools/utilities/idempotency/persistence/dynamodb.py
+++ b/aws_lambda_powertools/utilities/idempotency/persistence/dynamodb.py
@@ -12,7 +12,7 @@
     IdempotencyItemAlreadyExistsError,
     IdempotencyItemNotFoundError,
 )
-from aws_lambda_powertools.utilities.idempotency.persistence.base import DataRecord
+from aws_lambda_powertools.utilities.idempotency.persistence.base import STATUS_CONSTANTS, DataRecord
 
 logger = logging.getLogger(__name__)
 
@@ -25,6 +25,7 @@ def __init__(
         static_pk_value: Optional[str] = None,
         sort_key_attr: Optional[str] = None,
         expiry_attr: str = "expiration",
+        in_progress_expiry_attr: str = "in_progress_expiration",
         status_attr: str = "status",
         data_attr: str = "data",
         validation_key_attr: str = "validation",
@@ -47,6 +48,8 @@ def __init__(
             DynamoDB attribute name for the sort key
         expiry_attr: str, optional
             DynamoDB attribute name for expiry timestamp, by default "expiration"
+        in_progress_expiry_attr: str, optional
+            DynamoDB attribute name for in-progress expiry timestamp, by default "in_progress_expiration"
         status_attr: str, optional
             DynamoDB attribute name for status, by default "status"
         data_attr: str, optional
@@ -85,6 +88,7 @@ def __init__(
         self.static_pk_value = static_pk_value
         self.sort_key_attr = sort_key_attr
         self.expiry_attr = expiry_attr
+        self.in_progress_expiry_attr = in_progress_expiry_attr
         self.status_attr = status_attr
         self.data_attr = data_attr
         self.validation_key_attr = validation_key_attr
@@ -133,6 +137,7 @@ def _item_to_data_record(self, item: Dict[str, Any]) -> DataRecord:
             idempotency_key=item[self.key_attr],
             status=item[self.status_attr],
             expiry_timestamp=item[self.expiry_attr],
+            in_progress_expiry_timestamp=item.get(self.in_progress_expiry_attr),
             response_data=item.get(self.data_attr),
             payload_hash=item.get(self.validation_key_attr),
         )
@@ -153,17 +158,59 @@ def _put_record(self, data_record: DataRecord) -> None:
             self.status_attr: data_record.status,
         }
 
+        if data_record.in_progress_expiry_timestamp is not None:
+            item[self.in_progress_expiry_attr] = data_record.in_progress_expiry_timestamp
+
         if self.payload_validation_enabled:
             item[self.validation_key_attr] = data_record.payload_hash
 
         now = datetime.datetime.now()
         try:
             logger.debug(f"Putting record for idempotency key: {data_record.idempotency_key}")
+
+            # |     LOCKED     |         RETRY if status = "INPROGRESS"                |     RETRY
+            # |----------------|-------------------------------------------------------|-------------> .... (time)
+            # |             Lambda                                              Idempotency Record
+            # |             Timeout                                                 Timeout
+            # |       (in_progress_expiry)                                          (expiry)
+
+            # Conditions to successfully save a record:
+
+            # The idempotency key does not exist:
+            #    - first time that this invocation key is used
+            #    - previous invocation with the same key was deleted due to TTL
+            idempotency_key_not_exist = "attribute_not_exists(#id)"
+
+            # The idempotency record exists but it's expired:
+            idempotency_expiry_expired = "#expiry < :now"
+
+            # The status of the record is "INPROGRESS", there is an in-progress expiry timestamp, but it's expired
+            inprogress_expiry_expired = " AND ".join(
+                [
+                    "#status = :inprogress",
+                    "attribute_exists(#in_progress_expiry)",
+                    "#in_progress_expiry < :now_in_millis",
+                ]
+            )
+
+            condition_expression = (
+                f"{idempotency_key_not_exist} OR {idempotency_expiry_expired} OR ({inprogress_expiry_expired})"
+            )
+
             self.table.put_item(
                 Item=item,
-                ConditionExpression="attribute_not_exists(#id) OR #now < :now",
-                ExpressionAttributeNames={"#id": self.key_attr, "#now": self.expiry_attr},
-                ExpressionAttributeValues={":now": int(now.timestamp())},
+                ConditionExpression=condition_expression,
+                ExpressionAttributeNames={
+                    "#id": self.key_attr,
+                    "#expiry": self.expiry_attr,
+                    "#in_progress_expiry": self.in_progress_expiry_attr,
+                    "#status": self.status_attr,
+                },
+                ExpressionAttributeValues={
+                    ":now": int(now.timestamp()),
+                    ":now_in_millis": int(now.timestamp() * 1000),
+                    ":inprogress": STATUS_CONSTANTS["INPROGRESS"],
+                },
             )
         except self.table.meta.client.exceptions.ConditionalCheckFailedException:
             logger.debug(f"Failed to put record for already existing idempotency key: {data_record.idempotency_key}")
@@ -171,15 +218,15 @@ def _put_record(self, data_record: DataRecord) -> None:
 
     def _update_record(self, data_record: DataRecord):
         logger.debug(f"Updating record for idempotency key: {data_record.idempotency_key}")
-        update_expression = "SET #response_data = :response_data, #expiry = :expiry, #status = :status"
+        update_expression = "SET #response_data = :response_data, #expiry = :expiry, " "#status = :status"
         expression_attr_values = {
             ":expiry": data_record.expiry_timestamp,
             ":response_data": data_record.response_data,
             ":status": data_record.status,
         }
         expression_attr_names = {
-            "#response_data": self.data_attr,
             "#expiry": self.expiry_attr,
+            "#response_data": self.data_attr,
             "#status": self.status_attr,
         }
 
diff --git a/docs/media/idempotent_sequence.png b/docs/media/idempotent_sequence.png
deleted file mode 100644
index 92593184abbfb79cc673af07bfbb019bf6c06812..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 74622
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

diff --git a/docs/media/idempotent_sequence_exception.png b/docs/media/idempotent_sequence_exception.png
deleted file mode 100644
index 4cf065993dd0ca3818941e1e80af17f4f7ed56f7..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 46647
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
R89D|(igIeQ>Cz_8{|j#6Zn^*f

diff --git a/docs/utilities/idempotency.md b/docs/utilities/idempotency.md
index a5ed14b9150..7ba61fd3062 100644
--- a/docs/utilities/idempotency.md
+++ b/docs/utilities/idempotency.md
@@ -22,6 +22,7 @@ times with the same parameters**. This makes idempotent operations safe to retry
 * Ensure Lambda handler returns the same result when called with the same payload
 * Select a subset of the event as the idempotency key using JMESPath expressions
 * Set a time window in which records with the same payload should be considered duplicates
+* Expires in-progress executions if the Lambda function times out halfway through
 
 ## Getting started
 
@@ -35,10 +36,10 @@ As of now, Amazon DynamoDB is the only supported persistent storage layer, so yo
 
 If you're not [changing the default configuration for the DynamoDB persistence layer](#dynamodbpersistencelayer), this is the expected default configuration:
 
-Configuration | Value | Notes
-------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------
-Partition key | `id` |
-TTL attribute name | `expiration` | This can only be configured after your table is created if you're using AWS Console
+| Configuration      | Value        | Notes                                                                               |
+| ------------------ | ------------ | ----------------------------------------------------------------------------------- |
+| Partition key      | `id`         |
+| TTL attribute name | `expiration` | This can only be configured after your table is created if you're using AWS Console |
 
 ???+ tip "Tip: You can share a single state table for all functions"
     You can reuse the same DynamoDB table to store idempotency state. We add your `function_name` in addition to the idempotency key as a hash key.
@@ -161,6 +162,7 @@ When using `idempotent_function`, you must tell us which keyword parameter in yo
     def lambda_handler(event, context):
         # `data` parameter must be called as a keyword argument to work
         dummy("hello", "universe", data="test")
+		config.register_lambda_context(context) # see Lambda timeouts section
         return processor.response()
     ```
 
@@ -197,7 +199,7 @@ When using `idempotent_function`, you must tell us which keyword parameter in yo
 
 === "dataclass_sample.py"
 
-    ```python hl_lines="3-4 23 32"
+    ```python hl_lines="3-4 23 33"
     from dataclasses import dataclass
 
     from aws_lambda_powertools.utilities.idempotency import (
@@ -224,17 +226,18 @@ When using `idempotent_function`, you must tell us which keyword parameter in yo
     def process_order(order: Order):
         return f"processed order {order.order_id}"
 
+	def lambda_handler(event, context):
+		config.register_lambda_context(context) # see Lambda timeouts section
+		order_item = OrderItem(sku="fake", description="sample")
+		order = Order(item=order_item, order_id="fake-id")
 
-    order_item = OrderItem(sku="fake", description="sample")
-    order = Order(item=order_item, order_id="fake-id")
-
-    # `order` parameter must be called as a keyword argument to work
-    process_order(order=order)
+		# `order` parameter must be called as a keyword argument to work
+		process_order(order=order)
     ```
 
 === "parser_pydantic_sample.py"
 
-    ```python hl_lines="1-2 22 31"
+    ```python hl_lines="1-2 22 32"
     from aws_lambda_powertools.utilities.idempotency import (
         DynamoDBPersistenceLayer, IdempotencyConfig, idempotent_function)
     from aws_lambda_powertools.utilities.parser import BaseModel
@@ -260,12 +263,13 @@ When using `idempotent_function`, you must tell us which keyword parameter in yo
     def process_order(order: Order):
         return f"processed order {order.order_id}"
 
+	def lambda_handler(event, context):
+		config.register_lambda_context(context) # see Lambda timeouts section
+		order_item = OrderItem(sku="fake", description="sample")
+		order = Order(item=order_item, order_id="fake-id")
 
-    order_item = OrderItem(sku="fake", description="sample")
-    order = Order(item=order_item, order_id="fake-id")
-
-    # `order` parameter must be called as a keyword argument to work
-    process_order(order=order)
+		# `order` parameter must be called as a keyword argument to work
+		process_order(order=order)
     ```
 
 ### Choosing a payload subset for idempotency
@@ -354,19 +358,136 @@ Imagine the function executes successfully, but the client never receives the re
 
 This sequence diagram shows an example flow of what happens in the payment scenario:
 
-![Idempotent sequence](../media/idempotent_sequence.png)
+<center>
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Lambda
+    participant Persistence Layer
+    alt initial request
+        Client->>Lambda: Invoke (event)
+        Lambda->>Persistence Layer: Get or set (id=event.search(payload))
+        activate Persistence Layer
+        Note right of Persistence Layer: Locked to prevent concurrent<br/>invocations with <br/> the same payload.
+        Lambda-->>Lambda: Call handler (event)
+        Lambda->>Persistence Layer: Update record with result
+        deactivate Persistence Layer
+        Persistence Layer-->>Persistence Layer: Update record with result
+        Lambda-->>Client: Response sent to client
+    else retried request
+        Client->>Lambda: Invoke (event)
+        Lambda->>Persistence Layer: Get or set (id=event.search(payload))
+        Persistence Layer-->>Lambda: Already exists in persistence layer. Return result
+        Lambda-->>Client: Response sent to client
+    end
+```
+<i>Idempotent sequence</i>
+</center>
 
 The client was successful in receiving the result after the retry. Since the Lambda handler was only executed once, our customer hasn't been charged twice.
 
 ???+ note
     Bear in mind that the entire Lambda handler is treated as a single idempotent operation. If your Lambda handler can cause multiple side effects, consider splitting it into separate functions.
 
+#### Lambda timeouts
+
+???+ note
+    This is automatically done when you decorate your Lambda handler with [@idempotent decorator](#idempotent-decorator).
+
+To prevent against extended failed retries when a [Lambda function times out](https://aws.amazon.com/premiumsupport/knowledge-center/lambda-verify-invocation-timeouts/), Powertools calculates and includes the remaining invocation available time as part of the idempotency record.
+
+???+ example
+    If a second invocation happens **after** this timestamp, and the record is marked as `INPROGRESS`, we will execute the invocation again as if it was in the `EXPIRED` state (e.g, `expire_seconds` field elapsed).
+
+    This means that if an invocation expired during execution, it will be quickly executed again on the next retry.
+
+???+ important
+    If you are only using the [@idempotent_function decorator](#idempotentfunction-decorator) to guard isolated parts of your code, you must use `register_lambda_context` available in the [idempotency config object](#customizing-the-default-behavior) to benefit from this protection.
+
+Here is an example on how you register the Lambda context in your handler:
+
+```python hl_lines="8 16" title="Registering the Lambda context"
+from aws_lambda_powertools.utilities.data_classes.sqs_event import SQSRecord
+from aws_lambda_powertools.utilities.idempotency import (
+    IdempotencyConfig, idempotent_function
+)
+
+persistence_layer = DynamoDBPersistenceLayer(table_name="...")
+
+config = IdempotencyConfig()
+
+@idempotent_function(data_keyword_argument="record", persistence_store=persistence_layer, config=config)
+def record_handler(record: SQSRecord):
+    return {"message": record["body"]}
+
+
+def lambda_handler(event, context):
+    config.register_lambda_context(context)
+
+    return record_handler(event)
+```
+
+#### Lambda timeout sequence diagram
+
+This sequence diagram shows an example flow of what happens if a Lambda function times out:
+
+<center>
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Lambda
+    participant Persistence Layer
+    alt initial request
+        Client->>Lambda: Invoke (event)
+        Lambda->>Persistence Layer: Get or set (id=event.search(payload))
+        activate Persistence Layer
+        Note right of Persistence Layer: Locked to prevent concurrent<br/>invocations with <br/> the same payload.
+        Note over Lambda: Time out
+        Lambda--xLambda: Call handler (event)
+        Lambda-->>Client: Return error response
+        deactivate Persistence Layer
+    else concurrent request before timeout
+        Client->>Lambda: Invoke (event)
+        Lambda->>Persistence Layer: Get or set (id=event.search(payload))
+        Persistence Layer-->>Lambda: Request already INPROGRESS
+        Lambda--xClient: Return IdempotencyAlreadyInProgressError
+    else retry after Lambda timeout
+        Client->>Lambda: Invoke (event)
+        Lambda->>Persistence Layer: Get or set (id=event.search(payload))
+        activate Persistence Layer
+        Note right of Persistence Layer: Locked to prevent concurrent<br/>invocations with <br/> the same payload.
+        Lambda-->>Lambda: Call handler (event)
+        Lambda->>Persistence Layer: Update record with result
+        deactivate Persistence Layer
+        Persistence Layer-->>Persistence Layer: Update record with result
+        Lambda-->>Client: Response sent to client
+    end
+```
+<i>Idempotent sequence for Lambda timeouts</i>
+</center>
+
 ### Handling exceptions
 
 If you are using the `idempotent` decorator on your Lambda handler, any unhandled exceptions that are raised during the code execution will cause **the record in the persistence layer to be deleted**.
 This means that new invocations will execute your code again despite having the same payload. If you don't want the record to be deleted, you need to catch exceptions within the idempotent function and return a successful response.
 
-![Idempotent sequence exception](../media/idempotent_sequence_exception.png)
+<center>
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Lambda
+    participant Persistence Layer
+    Client->>Lambda: Invoke (event)
+    Lambda->>Persistence Layer: Get or set (id=event.search(payload))
+    activate Persistence Layer
+    Note right of Persistence Layer: Locked during this time. Prevents multiple<br/>Lambda invocations with the same<br/>payload running concurrently.
+    Lambda--xLambda: Call handler (event).<br/>Raises exception
+    Lambda->>Persistence Layer: Delete record (id=event.search(payload))
+    deactivate Persistence Layer
+    Lambda-->>Client: Return error response
+```
+<i>Idempotent sequence exception</i>
+</center>
 
 If you are using `idempotent_function`, any unhandled exceptions that are raised _inside_ the decorated function will cause the record in the persistence layer to be deleted, and allow the function to be executed again if retried.
 
@@ -402,13 +523,14 @@ def call_external_service(data: dict, **kwargs):
 
 This persistence layer is built-in, and you can either use an existing DynamoDB table or create a new one dedicated for idempotency state (recommended).
 
-```python hl_lines="5-9" title="Customizing DynamoDBPersistenceLayer to suit your table structure"
+```python hl_lines="5-10" title="Customizing DynamoDBPersistenceLayer to suit your table structure"
 from aws_lambda_powertools.utilities.idempotency import DynamoDBPersistenceLayer
 
 persistence_layer = DynamoDBPersistenceLayer(
 	table_name="IdempotencyTable",
 	key_attr="idempotency_key",
 	expiry_attr="expires_at",
+	in_progress_expiry_attr="in_progress_expires_at",
 	status_attr="current_status",
 	data_attr="result_data",
 	validation_key_attr="validation_key",
@@ -417,16 +539,17 @@ persistence_layer = DynamoDBPersistenceLayer(
 
 When using DynamoDB as a persistence layer, you can alter the attribute names by passing these parameters when initializing the persistence layer:
 
-Parameter | Required | Default | Description
-------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------
-**table_name** | :heavy_check_mark: | | Table name to store state
-**key_attr** |  | `id` | Partition key of the table. Hashed representation of the payload (unless **sort_key_attr** is specified)
-**expiry_attr** |  | `expiration` | Unix timestamp of when record expires
-**status_attr** |  | `status` | Stores status of the lambda execution during and after invocation
-**data_attr** |  | `data`  | Stores results of successfully executed Lambda handlers
-**validation_key_attr** |  | `validation` | Hashed representation of the parts of the event used for validation
-**sort_key_attr** | | | Sort key of the table (if table is configured with a sort key).
-**static_pk_value** | | `idempotency#{LAMBDA_FUNCTION_NAME}` | Static value to use as the partition key. Only used when **sort_key_attr** is set.
+| Parameter                   | Required           | Default                              | Description                                                                                              |
+| --------------------------- | ------------------ | ------------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| **table_name**              | :heavy_check_mark: |                                      | Table name to store state                                                                                |
+| **key_attr**                |                    | `id`                                 | Partition key of the table. Hashed representation of the payload (unless **sort_key_attr** is specified) |
+| **expiry_attr**             |                    | `expiration`                         | Unix timestamp of when record expires                                                                    |
+| **in_progress_expiry_attr** |                    | `in_progress_expiration`             | Unix timestamp of when record expires while in progress (in case of the invocation times out)            |
+| **status_attr**             |                    | `status`                             | Stores status of the lambda execution during and after invocation                                        |
+| **data_attr**               |                    | `data`                               | Stores results of successfully executed Lambda handlers                                                  |
+| **validation_key_attr**     |                    | `validation`                         | Hashed representation of the parts of the event used for validation                                      |
+| **sort_key_attr**           |                    |                                      | Sort key of the table (if table is configured with a sort key).                                          |
+| **static_pk_value**         |                    | `idempotency#{LAMBDA_FUNCTION_NAME}` | Static value to use as the partition key. Only used when **sort_key_attr** is set.                       |
 
 ## Advanced
 
@@ -434,15 +557,15 @@ Parameter | Required | Default | Description
 
 Idempotent decorator can be further configured with **`IdempotencyConfig`** as seen in the previous example. These are the available options for further configuration
 
-Parameter | Default | Description
-------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------
-**event_key_jmespath** | `""` | JMESPath expression to extract the idempotency key from the event record using [built-in functions](/utilities/jmespath_functions)
-**payload_validation_jmespath** | `""` | JMESPath expression to validate whether certain parameters have changed in the event while the event payload
-**raise_on_no_idempotency_key** | `False` | Raise exception if no idempotency key was found in the request
-**expires_after_seconds** | 3600 | The number of seconds to wait before a record is expired
-**use_local_cache** | `False` | Whether to locally cache idempotency results
-**local_cache_max_items** | 256 | Max number of items to store in local cache
-**hash_function** | `md5` | Function to use for calculating hashes, as provided by [hashlib](https://docs.python.org/3/library/hashlib.html) in the standard library.
+| Parameter                       | Default | Description                                                                                                                               |
+| ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| **event_key_jmespath**          | `""`    | JMESPath expression to extract the idempotency key from the event record using [built-in functions](/utilities/jmespath_functions)        |
+| **payload_validation_jmespath** | `""`    | JMESPath expression to validate whether certain parameters have changed in the event while the event payload                              |
+| **raise_on_no_idempotency_key** | `False` | Raise exception if no idempotency key was found in the request                                                                            |
+| **expires_after_seconds**       | 3600    | The number of seconds to wait before a record is expired                                                                                  |
+| **use_local_cache**             | `False` | Whether to locally cache idempotency results                                                                                              |
+| **local_cache_max_items**       | 256     | Max number of items to store in local cache                                                                                               |
+| **hash_function**               | `md5`   | Function to use for calculating hashes, as provided by [hashlib](https://docs.python.org/3/library/hashlib.html) in the standard library. |
 
 ### Handling concurrent executions with the same payload
 
@@ -706,11 +829,11 @@ def handler(event, context):
 
 The example function above would cause data to be stored in DynamoDB like this:
 
-| id                           | sort_key                         | expiration | status      | data                                |
-|------------------------------|----------------------------------|------------|-------------|-------------------------------------|
-| idempotency#MyLambdaFunction | 1e956ef7da78d0cb890be999aecc0c9e | 1636549553 | COMPLETED   | {"id": 12391, "message": "success"} |
-| idempotency#MyLambdaFunction | 2b2cdb5f86361e97b4383087c1ffdf27 | 1636549571 | COMPLETED   | {"id": 527212, "message": "success"}|
-| idempotency#MyLambdaFunction | f091d2527ad1c78f05d54cc3f363be80 | 1636549585 | IN_PROGRESS |                                     |
+| id                           | sort_key                         | expiration | status      | data                                 |
+| ---------------------------- | -------------------------------- | ---------- | ----------- | ------------------------------------ |
+| idempotency#MyLambdaFunction | 1e956ef7da78d0cb890be999aecc0c9e | 1636549553 | COMPLETED   | {"id": 12391, "message": "success"}  |
+| idempotency#MyLambdaFunction | 2b2cdb5f86361e97b4383087c1ffdf27 | 1636549571 | COMPLETED   | {"id": 527212, "message": "success"} |
+| idempotency#MyLambdaFunction | f091d2527ad1c78f05d54cc3f363be80 | 1636549585 | IN_PROGRESS |                                      |
 
 ### Bring your own persistent store
 
diff --git a/tests/functional/event_handler/test_api_gateway.py b/tests/functional/event_handler/test_api_gateway.py
index f1fb6a1f942..4b1d7c1ee32 100644
--- a/tests/functional/event_handler/test_api_gateway.py
+++ b/tests/functional/event_handler/test_api_gateway.py
@@ -283,7 +283,7 @@ def test_base64_encode():
 
     @app.get("/my/path", compress=True)
     def read_image() -> Response:
-        return Response(200, "image/png", read_media("idempotent_sequence_exception.png"))
+        return Response(200, "image/png", read_media("tracer_utility_showcase.png"))
 
     # WHEN calling the event handler
     result = app(mock_event, None)
diff --git a/tests/functional/idempotency/conftest.py b/tests/functional/idempotency/conftest.py
index 74deecef123..b5cf79727b1 100644
--- a/tests/functional/idempotency/conftest.py
+++ b/tests/functional/idempotency/conftest.py
@@ -1,6 +1,5 @@
 import datetime
 import json
-from collections import namedtuple
 from decimal import Decimal
 from unittest import mock
 
@@ -32,14 +31,17 @@ def lambda_apigw_event():
 
 @pytest.fixture
 def lambda_context():
-    lambda_context = {
-        "function_name": "test-func",
-        "memory_limit_in_mb": 128,
-        "invoked_function_arn": "arn:aws:lambda:eu-west-1:809313241234:function:test-func",
-        "aws_request_id": "52fdfc07-2182-154f-163f-5f0f9a621d72",
-    }
+    class LambdaContext:
+        def __init__(self):
+            self.function_name = "test-func"
+            self.memory_limit_in_mb = 128
+            self.invoked_function_arn = "arn:aws:lambda:eu-west-1:809313241234:function:test-func"
+            self.aws_request_id = "52fdfc07-2182-154f-163f-5f0f9a621d72"
+
+        def get_remaining_time_in_millis(self) -> int:
+            return 1000
 
-    return namedtuple("LambdaContext", lambda_context.keys())(*lambda_context.values())
+    return LambdaContext()
 
 
 @pytest.fixture
@@ -77,7 +79,11 @@ def default_jmespath():
 @pytest.fixture
 def expected_params_update_item(serialized_lambda_response, hashed_idempotency_key):
     return {
-        "ExpressionAttributeNames": {"#expiry": "expiration", "#response_data": "data", "#status": "status"},
+        "ExpressionAttributeNames": {
+            "#expiry": "expiration",
+            "#response_data": "data",
+            "#status": "status",
+        },
         "ExpressionAttributeValues": {
             ":expiry": stub.ANY,
             ":response_data": serialized_lambda_response,
@@ -108,19 +114,34 @@ def expected_params_update_item_with_validation(
         },
         "Key": {"id": hashed_idempotency_key},
         "TableName": "TEST_TABLE",
-        "UpdateExpression": "SET #response_data = :response_data, "
-        "#expiry = :expiry, #status = :status, "
-        "#validation_key = :validation_key",
+        "UpdateExpression": (
+            "SET #response_data = :response_data, "
+            "#expiry = :expiry, #status = :status, "
+            "#validation_key = :validation_key"
+        ),
     }
 
 
 @pytest.fixture
 def expected_params_put_item(hashed_idempotency_key):
     return {
-        "ConditionExpression": "attribute_not_exists(#id) OR #now < :now",
-        "ExpressionAttributeNames": {"#id": "id", "#now": "expiration"},
-        "ExpressionAttributeValues": {":now": stub.ANY},
-        "Item": {"expiration": stub.ANY, "id": hashed_idempotency_key, "status": "INPROGRESS"},
+        "ConditionExpression": (
+            "attribute_not_exists(#id) OR #expiry < :now OR "
+            "(#status = :inprogress AND attribute_exists(#in_progress_expiry) AND #in_progress_expiry < :now_in_millis)"
+        ),
+        "ExpressionAttributeNames": {
+            "#id": "id",
+            "#expiry": "expiration",
+            "#status": "status",
+            "#in_progress_expiry": "in_progress_expiration",
+        },
+        "ExpressionAttributeValues": {":now": stub.ANY, ":now_in_millis": stub.ANY, ":inprogress": "INPROGRESS"},
+        "Item": {
+            "expiration": stub.ANY,
+            "id": hashed_idempotency_key,
+            "status": "INPROGRESS",
+            "in_progress_expiration": stub.ANY,
+        },
         "TableName": "TEST_TABLE",
     }
 
@@ -128,11 +149,20 @@ def expected_params_put_item(hashed_idempotency_key):
 @pytest.fixture
 def expected_params_put_item_with_validation(hashed_idempotency_key, hashed_validation_key):
     return {
-        "ConditionExpression": "attribute_not_exists(#id) OR #now < :now",
-        "ExpressionAttributeNames": {"#id": "id", "#now": "expiration"},
-        "ExpressionAttributeValues": {":now": stub.ANY},
+        "ConditionExpression": (
+            "attribute_not_exists(#id) OR #expiry < :now OR "
+            "(#status = :inprogress AND attribute_exists(#in_progress_expiry) AND #in_progress_expiry < :now_in_millis)"
+        ),
+        "ExpressionAttributeNames": {
+            "#id": "id",
+            "#expiry": "expiration",
+            "#status": "status",
+            "#in_progress_expiry": "in_progress_expiration",
+        },
+        "ExpressionAttributeValues": {":now": stub.ANY, ":now_in_millis": stub.ANY, ":inprogress": "INPROGRESS"},
         "Item": {
             "expiration": stub.ANY,
+            "in_progress_expiration": stub.ANY,
             "id": hashed_idempotency_key,
             "status": "INPROGRESS",
             "validation": hashed_validation_key,
@@ -176,6 +206,7 @@ def idempotency_config(config, request, default_jmespath):
     return IdempotencyConfig(
         event_key_jmespath=request.param.get("event_key_jmespath") or default_jmespath,
         use_local_cache=request.param["use_local_cache"],
+        payload_validation_jmespath=request.param.get("payload_validation_jmespath") or "",
     )
 
 
@@ -184,15 +215,6 @@ def config_without_jmespath(config, request):
     return IdempotencyConfig(use_local_cache=request.param["use_local_cache"])
 
 
-@pytest.fixture
-def config_with_validation(config, request, default_jmespath):
-    return IdempotencyConfig(
-        event_key_jmespath=default_jmespath,
-        use_local_cache=request.param,
-        payload_validation_jmespath="requestContext",
-    )
-
-
 @pytest.fixture
 def config_with_jmespath_options(config, request):
     class CustomFunctions(functions.Functions):
diff --git a/tests/functional/idempotency/test_idempotency.py b/tests/functional/idempotency/test_idempotency.py
index 40cee10e4f7..97a9166efa0 100644
--- a/tests/functional/idempotency/test_idempotency.py
+++ b/tests/functional/idempotency/test_idempotency.py
@@ -1,5 +1,7 @@
 import copy
+import datetime
 import sys
+import warnings
 from hashlib import md5
 from unittest.mock import MagicMock
 
@@ -10,7 +12,7 @@
 
 from aws_lambda_powertools.utilities.data_classes import APIGatewayProxyEventV2, event_source
 from aws_lambda_powertools.utilities.idempotency import DynamoDBPersistenceLayer, IdempotencyConfig
-from aws_lambda_powertools.utilities.idempotency.base import _prepare_data
+from aws_lambda_powertools.utilities.idempotency.base import MAX_RETRIES, IdempotencyHandler, _prepare_data
 from aws_lambda_powertools.utilities.idempotency.exceptions import (
     IdempotencyAlreadyInProgressError,
     IdempotencyInconsistentStateError,
@@ -208,9 +210,6 @@ def test_idempotent_lambda_first_execution(
     expected_params_update_item,
     expected_params_put_item,
     lambda_response,
-    serialized_lambda_response,
-    deserialized_lambda_response,
-    hashed_idempotency_key,
     lambda_context,
 ):
     """
@@ -295,7 +294,11 @@ def test_idempotent_lambda_first_execution_event_mutation(
     event = copy.deepcopy(lambda_apigw_event)
     stubber = stub.Stubber(persistence_store.table.meta.client)
     ddb_response = {}
-    stubber.add_response("put_item", ddb_response, build_idempotency_put_item_stub(data=event["body"]))
+    stubber.add_response(
+        "put_item",
+        ddb_response,
+        build_idempotency_put_item_stub(data=event["body"]),
+    )
     stubber.add_response(
         "update_item",
         ddb_response,
@@ -319,15 +322,13 @@ def test_idempotent_lambda_expired(
     idempotency_config: IdempotencyConfig,
     persistence_store: DynamoDBPersistenceLayer,
     lambda_apigw_event,
-    timestamp_expired,
     lambda_response,
     expected_params_update_item,
     expected_params_put_item,
-    hashed_idempotency_key,
     lambda_context,
 ):
     """
-    Test idempotent decorator when lambda is called with an event it succesfully handled already, but outside of the
+    Test idempotent decorator when lambda is called with an event it successfully handled already, but outside of the
     expiry window
     """
 
@@ -354,8 +355,6 @@ def test_idempotent_lambda_exception(
     idempotency_config: IdempotencyConfig,
     persistence_store: DynamoDBPersistenceLayer,
     lambda_apigw_event,
-    timestamp_future,
-    lambda_response,
     hashed_idempotency_key,
     expected_params_put_item,
     lambda_context,
@@ -389,10 +388,15 @@ def lambda_handler(event, context):
 
 
 @pytest.mark.parametrize(
-    "config_with_validation", [{"use_local_cache": False}, {"use_local_cache": True}], indirect=True
+    "idempotency_config",
+    [
+        {"use_local_cache": False, "payload_validation_jmespath": "requestContext"},
+        {"use_local_cache": True, "payload_validation_jmespath": "requestContext"},
+    ],
+    indirect=True,
 )
 def test_idempotent_lambda_already_completed_with_validation_bad_payload(
-    config_with_validation: IdempotencyConfig,
+    idempotency_config: IdempotencyConfig,
     persistence_store: DynamoDBPersistenceLayer,
     lambda_apigw_event,
     timestamp_future,
@@ -422,7 +426,7 @@ def test_idempotent_lambda_already_completed_with_validation_bad_payload(
     stubber.add_response("get_item", ddb_response, expected_params)
     stubber.activate()
 
-    @idempotent(config=config_with_validation, persistence_store=persistence_store)
+    @idempotent(config=idempotency_config, persistence_store=persistence_store)
     def lambda_handler(event, context):
         return lambda_response
 
@@ -445,7 +449,7 @@ def test_idempotent_lambda_expired_during_request(
     lambda_context,
 ):
     """
-    Test idempotent decorator when lambda is called with an event it succesfully handled already. Persistence store
+    Test idempotent decorator when lambda is called with an event it successfully handled already. Persistence store
     returns inconsistent/rapidly changing result between put_item and get_item calls.
     """
 
@@ -495,9 +499,6 @@ def test_idempotent_persistence_exception_deleting(
     idempotency_config: IdempotencyConfig,
     persistence_store: DynamoDBPersistenceLayer,
     lambda_apigw_event,
-    timestamp_future,
-    lambda_response,
-    hashed_idempotency_key,
     expected_params_put_item,
     lambda_context,
 ):
@@ -530,9 +531,6 @@ def test_idempotent_persistence_exception_updating(
     idempotency_config: IdempotencyConfig,
     persistence_store: DynamoDBPersistenceLayer,
     lambda_apigw_event,
-    timestamp_future,
-    lambda_response,
-    hashed_idempotency_key,
     expected_params_put_item,
     lambda_context,
 ):
@@ -565,10 +563,6 @@ def test_idempotent_persistence_exception_getting(
     idempotency_config: IdempotencyConfig,
     persistence_store: DynamoDBPersistenceLayer,
     lambda_apigw_event,
-    timestamp_future,
-    lambda_response,
-    hashed_idempotency_key,
-    expected_params_put_item,
     lambda_context,
 ):
     """
@@ -594,17 +588,20 @@ def lambda_handler(event, context):
 
 
 @pytest.mark.parametrize(
-    "config_with_validation", [{"use_local_cache": False}, {"use_local_cache": True}], indirect=True
+    "idempotency_config",
+    [
+        {"use_local_cache": False, "payload_validation_jmespath": "requestContext"},
+        {"use_local_cache": True, "payload_validation_jmespath": "requestContext"},
+    ],
+    indirect=True,
 )
 def test_idempotent_lambda_first_execution_with_validation(
-    config_with_validation: IdempotencyConfig,
+    idempotency_config: IdempotencyConfig,
     persistence_store: DynamoDBPersistenceLayer,
     lambda_apigw_event,
     expected_params_update_item_with_validation,
     expected_params_put_item_with_validation,
     lambda_response,
-    hashed_idempotency_key,
-    hashed_validation_key,
     lambda_context,
 ):
     """
@@ -617,7 +614,7 @@ def test_idempotent_lambda_first_execution_with_validation(
     stubber.add_response("update_item", ddb_response, expected_params_update_item_with_validation)
     stubber.activate()
 
-    @idempotent(config=config_with_validation, persistence_store=persistence_store)
+    @idempotent(config=idempotency_config, persistence_store=persistence_store)
     def lambda_handler(event, context):
         return lambda_response
 
@@ -679,6 +676,118 @@ def lambda_handler(event, context):
     stubber.deactivate()
 
 
+@pytest.mark.parametrize("idempotency_config", [{"use_local_cache": False}, {"use_local_cache": True}], indirect=True)
+def test_idempotent_lambda_expires_in_progress_before_expire(
+    idempotency_config: IdempotencyConfig,
+    persistence_store: DynamoDBPersistenceLayer,
+    lambda_apigw_event,
+    timestamp_future,
+    lambda_response,
+    hashed_idempotency_key,
+    lambda_context,
+):
+    stubber = stub.Stubber(persistence_store.table.meta.client)
+
+    stubber.add_client_error("put_item", "ConditionalCheckFailedException")
+
+    now = datetime.datetime.now()
+    period = datetime.timedelta(seconds=5)
+    timestamp_expires_in_progress = int((now + period).timestamp() * 1000)
+
+    expected_params_get_item = {
+        "TableName": TABLE_NAME,
+        "Key": {"id": hashed_idempotency_key},
+        "ConsistentRead": True,
+    }
+    ddb_response_get_item = {
+        "Item": {
+            "id": {"S": hashed_idempotency_key},
+            "expiration": {"N": timestamp_future},
+            "in_progress_expiration": {"N": str(timestamp_expires_in_progress)},
+            "data": {"S": '{"message": "test", "statusCode": 200'},
+            "status": {"S": "INPROGRESS"},
+        }
+    }
+    stubber.add_response("get_item", ddb_response_get_item, expected_params_get_item)
+
+    stubber.activate()
+
+    @idempotent(config=idempotency_config, persistence_store=persistence_store)
+    def lambda_handler(event, context):
+        return lambda_response
+
+    with pytest.raises(IdempotencyAlreadyInProgressError):
+        lambda_handler(lambda_apigw_event, lambda_context)
+
+    stubber.assert_no_pending_responses()
+    stubber.deactivate()
+
+
+@pytest.mark.parametrize("idempotency_config", [{"use_local_cache": False}, {"use_local_cache": True}], indirect=True)
+def test_idempotent_lambda_expires_in_progress_after_expire(
+    idempotency_config: IdempotencyConfig,
+    persistence_store: DynamoDBPersistenceLayer,
+    lambda_apigw_event,
+    timestamp_future,
+    lambda_response,
+    hashed_idempotency_key,
+    lambda_context,
+):
+    stubber = stub.Stubber(persistence_store.table.meta.client)
+
+    for _ in range(MAX_RETRIES + 1):
+        stubber.add_client_error("put_item", "ConditionalCheckFailedException")
+
+        one_second_ago = datetime.datetime.now() - datetime.timedelta(seconds=1)
+        expected_params_get_item = {
+            "TableName": TABLE_NAME,
+            "Key": {"id": hashed_idempotency_key},
+            "ConsistentRead": True,
+        }
+        ddb_response_get_item = {
+            "Item": {
+                "id": {"S": hashed_idempotency_key},
+                "expiration": {"N": timestamp_future},
+                "in_progress_expiration": {"N": str(int(one_second_ago.timestamp() * 1000))},
+                "data": {"S": '{"message": "test", "statusCode": 200'},
+                "status": {"S": "INPROGRESS"},
+            }
+        }
+        stubber.add_response("get_item", ddb_response_get_item, expected_params_get_item)
+
+    stubber.activate()
+
+    @idempotent(config=idempotency_config, persistence_store=persistence_store)
+    def lambda_handler(event, context):
+        return lambda_response
+
+    with pytest.raises(IdempotencyInconsistentStateError):
+        lambda_handler(lambda_apigw_event, lambda_context)
+
+    stubber.assert_no_pending_responses()
+    stubber.deactivate()
+
+
+def test_idempotent_lambda_expires_in_progress_unavailable_remaining_time():
+    mock_event = {"data": "value"}
+    idempotency_key = "test-func.function#" + hash_idempotency_key(mock_event)
+    persistence_layer = MockPersistenceLayer(expected_idempotency_key=idempotency_key)
+    expected_result = {"message": "Foo"}
+
+    @idempotent_function(persistence_store=persistence_layer, data_keyword_argument="record")
+    def function(record):
+        return expected_result
+
+    with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter("default")
+        function(record=mock_event)
+        assert len(w) == 1
+        assert (
+            str(w[-1].message)
+            == "Couldn't determine the remaining time left. Did you call register_lambda_context on IdempotencyConfig?"
+        )
+
+
 def test_data_record_invalid_status_value():
     data_record = DataRecord("key", status="UNSUPPORTED_STATUS")
     with pytest.raises(IdempotencyInvalidStatusError) as e:
@@ -710,6 +819,62 @@ def test_data_record_json_to_dict_mapping_when_response_data_none():
     assert response_data is None
 
 
+@pytest.mark.parametrize("idempotency_config", [{"use_local_cache": True}], indirect=True)
+def test_handler_for_status_expired_data_record(
+    idempotency_config: IdempotencyConfig, persistence_store: DynamoDBPersistenceLayer
+):
+    idempotency_handler = IdempotencyHandler(
+        function=lambda a: a,
+        function_payload={},
+        config=idempotency_config,
+        persistence_store=persistence_store,
+    )
+    data_record = DataRecord("key", status="EXPIRED", response_data=None)
+
+    with pytest.raises(IdempotencyInconsistentStateError):
+        idempotency_handler._handle_for_status(data_record)
+
+
+@pytest.mark.parametrize("idempotency_config", [{"use_local_cache": True}], indirect=True)
+def test_handler_for_status_inprogress_data_record_inconsistent(
+    idempotency_config: IdempotencyConfig, persistence_store: DynamoDBPersistenceLayer
+):
+    idempotency_handler = IdempotencyHandler(
+        function=lambda a: a,
+        function_payload={},
+        config=idempotency_config,
+        persistence_store=persistence_store,
+    )
+
+    now = datetime.datetime.now()
+    period = datetime.timedelta(milliseconds=100)
+    timestamp = int((now - period).timestamp() * 1000)
+    data_record = DataRecord("key", in_progress_expiry_timestamp=timestamp, status="INPROGRESS", response_data=None)
+
+    with pytest.raises(IdempotencyInconsistentStateError):
+        idempotency_handler._handle_for_status(data_record)
+
+
+@pytest.mark.parametrize("idempotency_config", [{"use_local_cache": True}], indirect=True)
+def test_handler_for_status_inprogress_data_record_consistent(
+    idempotency_config: IdempotencyConfig, persistence_store: DynamoDBPersistenceLayer
+):
+    idempotency_handler = IdempotencyHandler(
+        function=lambda a: a,
+        function_payload={},
+        config=idempotency_config,
+        persistence_store=persistence_store,
+    )
+
+    now = datetime.datetime.now()
+    period = datetime.timedelta(milliseconds=100)
+    timestamp = int((now + period).timestamp() * 1000)
+    data_record = DataRecord("key", in_progress_expiry_timestamp=timestamp, status="INPROGRESS", response_data=None)
+
+    with pytest.raises(IdempotencyAlreadyInProgressError):
+        idempotency_handler._handle_for_status(data_record)
+
+
 @pytest.mark.parametrize("idempotency_config", [{"use_local_cache": True}], indirect=True)
 def test_in_progress_never_saved_to_cache(
     idempotency_config: IdempotencyConfig, persistence_store: DynamoDBPersistenceLayer
@@ -800,7 +965,7 @@ def test_is_missing_idempotency_key():
     "idempotency_config", [{"use_local_cache": False, "event_key_jmespath": "body"}], indirect=True
 )
 def test_default_no_raise_on_missing_idempotency_key(
-    idempotency_config: IdempotencyConfig, persistence_store: DynamoDBPersistenceLayer, lambda_context
+    idempotency_config: IdempotencyConfig, persistence_store: DynamoDBPersistenceLayer
 ):
     # GIVEN a persistence_store with use_local_cache = False and event_key_jmespath = "body"
     function_name = "foo"
@@ -817,10 +982,14 @@ def test_default_no_raise_on_missing_idempotency_key(
 
 
 @pytest.mark.parametrize(
-    "idempotency_config", [{"use_local_cache": False, "event_key_jmespath": "[body, x]"}], indirect=True
+    "idempotency_config",
+    [
+        {"use_local_cache": False, "event_key_jmespath": "[body, x]"},
+    ],
+    indirect=True,
 )
 def test_raise_on_no_idempotency_key(
-    idempotency_config: IdempotencyConfig, persistence_store: DynamoDBPersistenceLayer, lambda_context
+    idempotency_config: IdempotencyConfig, persistence_store: DynamoDBPersistenceLayer
 ):
     # GIVEN a persistence_store with raise_on_no_idempotency_key and no idempotency key in the request
     persistence_store.configure(idempotency_config)
@@ -842,12 +1011,12 @@ def test_raise_on_no_idempotency_key(
         {
             "use_local_cache": False,
             "event_key_jmespath": "[requestContext.authorizer.claims.sub, powertools_json(body).id]",
-        }
+        },
     ],
     indirect=True,
 )
 def test_jmespath_with_powertools_json(
-    idempotency_config: IdempotencyConfig, persistence_store: DynamoDBPersistenceLayer, lambda_context
+    idempotency_config: IdempotencyConfig, persistence_store: DynamoDBPersistenceLayer
 ):
     # GIVEN an event_key_jmespath with powertools_json custom function
     persistence_store.configure(idempotency_config, "handler")
@@ -868,7 +1037,7 @@ def test_jmespath_with_powertools_json(
 
 @pytest.mark.parametrize("config_with_jmespath_options", ["powertools_json(data).payload"], indirect=True)
 def test_custom_jmespath_function_overrides_builtin_functions(
-    config_with_jmespath_options: IdempotencyConfig, persistence_store: DynamoDBPersistenceLayer, lambda_context
+    config_with_jmespath_options: IdempotencyConfig, persistence_store: DynamoDBPersistenceLayer
 ):
     # GIVEN a persistence store with a custom jmespath_options
     # AND use a builtin powertools custom function
diff --git a/tests/functional/idempotency/utils.py b/tests/functional/idempotency/utils.py
index ca3862a2d8c..797b696aba4 100644
--- a/tests/functional/idempotency/utils.py
+++ b/tests/functional/idempotency/utils.py
@@ -12,14 +12,29 @@ def hash_idempotency_key(data: Any):
 
 
 def build_idempotency_put_item_stub(
-    data: Dict, function_name: str = "test-func", handler_name: str = "lambda_handler"
+    data: Dict,
+    function_name: str = "test-func",
+    handler_name: str = "lambda_handler",
 ) -> Dict:
     idempotency_key_hash = f"{function_name}.{handler_name}#{hash_idempotency_key(data)}"
     return {
-        "ConditionExpression": "attribute_not_exists(#id) OR #now < :now",
-        "ExpressionAttributeNames": {"#id": "id", "#now": "expiration"},
-        "ExpressionAttributeValues": {":now": stub.ANY},
-        "Item": {"expiration": stub.ANY, "id": idempotency_key_hash, "status": "INPROGRESS"},
+        "ConditionExpression": (
+            "attribute_not_exists(#id) OR #expiry < :now OR "
+            "(#status = :inprogress AND attribute_exists(#in_progress_expiry) AND #in_progress_expiry < :now_in_millis)"
+        ),
+        "ExpressionAttributeNames": {
+            "#id": "id",
+            "#expiry": "expiration",
+            "#status": "status",
+            "#in_progress_expiry": "in_progress_expiration",
+        },
+        "ExpressionAttributeValues": {":now": stub.ANY, ":now_in_millis": stub.ANY, ":inprogress": "INPROGRESS"},
+        "Item": {
+            "expiration": stub.ANY,
+            "id": idempotency_key_hash,
+            "status": "INPROGRESS",
+            "in_progress_expiration": stub.ANY,
+        },
         "TableName": "TEST_TABLE",
     }
 
@@ -33,7 +48,11 @@ def build_idempotency_update_item_stub(
     idempotency_key_hash = f"{function_name}.{handler_name}#{hash_idempotency_key(data)}"
     serialized_lambda_response = json_serialize(handler_response)
     return {
-        "ExpressionAttributeNames": {"#expiry": "expiration", "#response_data": "data", "#status": "status"},
+        "ExpressionAttributeNames": {
+            "#expiry": "expiration",
+            "#response_data": "data",
+            "#status": "status",
+        },
         "ExpressionAttributeValues": {
             ":expiry": stub.ANY,
             ":response_data": serialized_lambda_response,