docs(middleware-factory): Fix and improve typing (#3569)

* Fix typing in middleware examples

* Update highlighted lines

* Reduce highlighting to improve readability

---------

Co-authored-by: Leandro Damascena <lcdama@amazon.pt>

Author: kamilturek

docs/utilities/middleware_factory.md

@@ -30,7 +30,7 @@ You can create your own middleware using `lambda_handler_decorator`. The decorat
 ### Middleware with before logic
 
 === "getting_started_middleware_before_logic_function.py"
-    ```python hl_lines="5 26 27 32 33 35 40 41"
+    ```python hl_lines="5 26 27 36 37 39 44 45"
     --8<-- "examples/middleware_factory/src/getting_started_middleware_before_logic_function.py"
     ```
 
@@ -43,7 +43,7 @@ You can create your own middleware using `lambda_handler_decorator`. The decorat
 ### Middleware with after logic
 
 === "getting_started_middleware_after_logic_function.py"
-    ```python hl_lines="7 14 15 21-23 37"
+    ```python hl_lines="8 14 15 24-26 40 41"
     --8<-- "examples/middleware_factory/src/getting_started_middleware_after_logic_function.py"
     ```
 
@@ -58,7 +58,7 @@ You can create your own middleware using `lambda_handler_decorator`. The decorat
 You can also have your own keyword arguments after the mandatory arguments.
 
 === "getting_started_middleware_with_params_function.py"
-    ```python hl_lines="6 30 31 32 36 52"
+    ```python hl_lines="6 30 31 41 56 57"
     --8<-- "examples/middleware_factory/src/getting_started_middleware_with_params_function.py"
     ```
 
@@ -83,7 +83,7 @@ You can also use [`POWERTOOLS_TRACE_MIDDLEWARES`](#tracing-middleware-execution)
 For advanced use cases, you can instantiate [Tracer](../core/tracer.md){target="_blank"} inside your middleware, and add annotations as well as metadata for additional operational insights.
 
 === "advanced_middleware_tracer_function.py"
-    ```python hl_lines="7 9 12 16 17 19 25 42"
+    ```python hl_lines="7 9 12 16 17 22 28 45 46"
     --8<-- "examples/middleware_factory/src/advanced_middleware_tracer_function.py"
     ```
 
@@ -105,7 +105,7 @@ This makes use of an existing Tracer instance that you may have initialized anyw
     You must [enable Active Tracing](../core/tracer.md#permissions){target="_blank"} in your Lambda function when using this feature, otherwise Lambda cannot send traces to XRay.
 
 === "getting_started_middleware_tracer_function.py"
-    ```python hl_lines="8 14 15 36"
+    ```python hl_lines="8 14 15 39 40"
     --8<-- "examples/middleware_factory/src/getting_started_middleware_tracer_function.py"
     ```
 
@@ -134,7 +134,7 @@ In the example below, we create a Middleware with the following features:
 * Save execution history to a DynamoDB table
 
 === "combining_powertools_utilities_function.py"
-    ```python hl_lines="11 28 29 119 52 61 73"
+    ```python hl_lines="11 28 29 56 64 77 123"
     --8<-- "examples/middleware_factory/src/combining_powertools_utilities_function.py"
     ```
 

examples/middleware_factory/src/advanced_middleware_tracer_function.py

@@ -14,8 +14,11 @@
 
 
 @lambda_handler_decorator(trace_execution=True)
-def middleware_with_advanced_tracing(handler, event, context) -> Callable:
-
+def middleware_with_advanced_tracing(
+    handler: Callable[[dict, LambdaContext], dict],
+    event: dict,
+    context: LambdaContext,
+) -> dict:
     tracer.put_metadata(key="resource", value=event.get("resource"))
 
     start_time = time.time()

examples/middleware_factory/src/combining_powertools_utilities_function.py

@@ -26,7 +26,11 @@
 
 
 @lambda_handler_decorator(trace_execution=True)
-def middleware_custom(handler: Callable, event: dict, context: LambdaContext):
+def middleware_custom(
+    handler: Callable[[dict, LambdaContext], dict],
+    event: dict,
+    context: LambdaContext,
+) -> dict:
     # validating the INPUT with the given schema
     # X-Customer-Id header must be informed in all requests
     try:

examples/middleware_factory/src/getting_started_middleware_after_logic_function.py

@@ -12,8 +12,11 @@
 
 
 @lambda_handler_decorator
-def middleware_after(handler, event, context) -> Callable:
-
+def middleware_after(
+    handler: Callable[[dict, LambdaContext], dict],
+    event: dict,
+    context: LambdaContext,
+) -> dict:
     start_time = time.time()
     response = handler(event, context)
     execution_time = time.time() - start_time

examples/middleware_factory/src/getting_started_middleware_before_logic_function.py

@@ -24,7 +24,11 @@ class PaymentError(Exception):
 
 
 @lambda_handler_decorator
-def middleware_before(handler, event, context) -> Callable:
+def middleware_before(
+    handler: Callable[[dict, LambdaContext], dict],
+    event: dict,
+    context: LambdaContext,
+) -> dict:
     # extract payload from a EventBridge event
     detail: dict = extract_data_from_envelope(data=event, envelope=envelopes.EVENTBRIDGE)
 
@@ -38,7 +42,7 @@ def middleware_before(handler, event, context) -> Callable:
 
 
 @middleware_before
-def lambda_handler(event, context: LambdaContext) -> dict:
+def lambda_handler(event: dict, context: LambdaContext) -> dict:
     try:
         payment_payload: dict = extract_data_from_envelope(data=event, envelope=envelopes.EVENTBRIDGE)
         return {

examples/middleware_factory/src/getting_started_middleware_tracer_function.py

@@ -12,8 +12,11 @@
 
 
 @lambda_handler_decorator(trace_execution=True)
-def middleware_with_tracing(handler, event, context) -> Callable:
-
+def middleware_with_tracing(
+    handler: Callable[[dict, LambdaContext], dict],
+    event: dict,
+    context: LambdaContext,
+) -> dict:
     start_time = time.time()
     response = handler(event, context)
     execution_time = time.time() - start_time

examples/middleware_factory/src/getting_started_middleware_with_params_function.py

@@ -28,7 +28,12 @@ class BookingError(Exception):
 
 
 @lambda_handler_decorator
-def obfuscate_sensitive_data(handler, event, context, fields: List) -> Callable:
+def obfuscate_sensitive_data(
+    handler: Callable[[dict, LambdaContext], dict],
+    event: dict,
+    context: LambdaContext,
+    fields: List,
+) -> dict:
     # extracting payload from a EventBridge event
     detail: dict = extract_data_from_envelope(data=event, envelope=envelopes.EVENTBRIDGE)
     guest_data: Any = detail.get("guest")
@@ -49,7 +54,7 @@ def obfuscate_data(value: str) -> bytes:
 
 
 @obfuscate_sensitive_data(fields=["email", "passport", "vat"])
-def lambda_handler(event, context: LambdaContext) -> dict:
+def lambda_handler(event: dict, context: LambdaContext) -> dict:
     try:
         booking_payload: dict = extract_data_from_envelope(data=event, envelope=envelopes.EVENTBRIDGE)
         return {