Merge branch 'develop' into custom_mask

Author: leandrodamascena

.github/workflows/quality_check.yml

@@ -61,6 +61,8 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
         run: make dev-quality-code
+      - name: Checking third-party library licenses
+        run: make check-licenses
       - name: Formatting and Linting
         run: make lint
       - name: Static type checking

.github/workflows/reusable_publish_docs.yml

@@ -84,9 +84,6 @@ jobs:
           aws-region: us-east-1
           role-to-assume: ${{ secrets.AWS_DOCS_ROLE_ARN }}
           mask-aws-account-id: true
-      - name: Copy API Docs
-        run: |
-          cp -r api site/
       - name: Deploy Docs (Version)
         env:
           VERSION: ${{ inputs.version }}

.gitignore

@@ -314,4 +314,7 @@ examples/**/sam/.aws-sam
 
 cdk.out
 # NOTE: different accounts will be used for E2E thus creating unnecessary git clutter
-cdk.context.json
+cdk.context.json
+
+# vim
+*.swp

CHANGELOG.md

@@ -9,37 +9,60 @@
 * **docs:** typo in a service name in Event Handler ([#5944](https://github.com/aws-powertools/powertools-lambda-python/issues/5944))
 * **logger:** child logger must respect log level ([#5950](https://github.com/aws-powertools/powertools-lambda-python/issues/5950))
 
+## Code Refactoring
+
+* **metrics:** Improve type annotations for metrics decorator ([#6000](https://github.com/aws-powertools/powertools-lambda-python/issues/6000))
+
 ## Documentation
 
+* **api:** migrating the tracer utility to mkdocstrings ([#6017](https://github.com/aws-powertools/powertools-lambda-python/issues/6017))
+* **api:** migrating the batch utility to mkdocstrings ([#6016](https://github.com/aws-powertools/powertools-lambda-python/issues/6016))
+* **api:** migrating the event source data classes utility to mkdocstrings ([#6015](https://github.com/aws-powertools/powertools-lambda-python/issues/6015))
+* **api:** migrating the data masking utility to mkdocstrings ([#6013](https://github.com/aws-powertools/powertools-lambda-python/issues/6013))
+* **api:** migrating the AppConfig utility to mkdocstrings ([#6008](https://github.com/aws-powertools/powertools-lambda-python/issues/6008))
+* **api:** migrating the idempotency utility to mkdocstrings ([#6007](https://github.com/aws-powertools/powertools-lambda-python/issues/6007))
+* **api:** migrating the jmespath utility to mkdocstrings ([#6006](https://github.com/aws-powertools/powertools-lambda-python/issues/6006))
+* **api:** migrating the parameters utility to mkdocstrings ([#6005](https://github.com/aws-powertools/powertools-lambda-python/issues/6005))
+* **api:** migrating the parser utility to mkdocstrings ([#6004](https://github.com/aws-powertools/powertools-lambda-python/issues/6004))
+* **api:** migrating the streaming utility to mkdocstrings ([#6003](https://github.com/aws-powertools/powertools-lambda-python/issues/6003))
+* **api:** migrating the typing utility to mkdocstrings ([#5996](https://github.com/aws-powertools/powertools-lambda-python/issues/5996))
 * **api:** migrating the validation utility to mkdocstrings ([#5972](https://github.com/aws-powertools/powertools-lambda-python/issues/5972))
 * **layer:** update layer version number - v3.5.0 ([#5952](https://github.com/aws-powertools/powertools-lambda-python/issues/5952))
 
 ## Features
 
 * **logger:** add clear_state method ([#5956](https://github.com/aws-powertools/powertools-lambda-python/issues/5956))
+* **openapi:** enhance support for tuple return type validation ([#5997](https://github.com/aws-powertools/powertools-lambda-python/issues/5997))
 
 ## Maintenance
 
+* **ci:** new pre-release 3.5.1a4 ([#6018](https://github.com/aws-powertools/powertools-lambda-python/issues/6018))
 * **ci:** new pre-release 3.5.1a0 ([#5945](https://github.com/aws-powertools/powertools-lambda-python/issues/5945))
 * **ci:** new pre-release 3.5.1a1 ([#5954](https://github.com/aws-powertools/powertools-lambda-python/issues/5954))
 * **ci:** install & configure mkdocstrings plugin ([#5959](https://github.com/aws-powertools/powertools-lambda-python/issues/5959))
+* **ci:** new pre-release 3.5.1a3 ([#5998](https://github.com/aws-powertools/powertools-lambda-python/issues/5998))
 * **ci:** new pre-release 3.5.1a2 ([#5970](https://github.com/aws-powertools/powertools-lambda-python/issues/5970))
-* **deps:** bump zgosalvez/github-actions-ensure-sha-pinned-actions from 3.0.18 to 3.0.20 ([#5977](https://github.com/aws-powertools/powertools-lambda-python/issues/5977))
-* **deps:** bump squidfunk/mkdocs-material from `41942f7` to `471695f` in /docs ([#5979](https://github.com/aws-powertools/powertools-lambda-python/issues/5979))
-* **deps:** bump actions/setup-go from 5.2.0 to 5.3.0 ([#5978](https://github.com/aws-powertools/powertools-lambda-python/issues/5978))
-* **deps:** bump aws-actions/configure-aws-credentials from 4.0.2 to 4.0.3 ([#5975](https://github.com/aws-powertools/powertools-lambda-python/issues/5975))
-* **deps:** bump actions/upload-artifact from 4.5.0 to 4.6.0 ([#5962](https://github.com/aws-powertools/powertools-lambda-python/issues/5962))
-* **deps:** bump actions/setup-node from 4.1.0 to 4.2.0 ([#5963](https://github.com/aws-powertools/powertools-lambda-python/issues/5963))
-* **deps:** bump pypa/gh-action-pypi-publish from 1.12.3 to 1.12.4 ([#5980](https://github.com/aws-powertools/powertools-lambda-python/issues/5980))
 * **deps:** bump codecov/codecov-action from 5.1.2 to 5.3.1 ([#5964](https://github.com/aws-powertools/powertools-lambda-python/issues/5964))
-* **deps:** bump docker/setup-qemu-action from 3.2.0 to 3.3.0 ([#5961](https://github.com/aws-powertools/powertools-lambda-python/issues/5961))
 * **deps:** bump release-drafter/release-drafter from 6.0.0 to 6.1.0 ([#5976](https://github.com/aws-powertools/powertools-lambda-python/issues/5976))
+* **deps:** bump aws-actions/configure-aws-credentials from 4.0.2 to 4.0.3 ([#5975](https://github.com/aws-powertools/powertools-lambda-python/issues/5975))
 * **deps:** bump actions/setup-python from 5.3.0 to 5.4.0 ([#5960](https://github.com/aws-powertools/powertools-lambda-python/issues/5960))
-* **deps-dev:** bump ruff from 0.9.3 to 0.9.4 ([#5969](https://github.com/aws-powertools/powertools-lambda-python/issues/5969))
+* **deps:** bump pypa/gh-action-pypi-publish from 1.12.3 to 1.12.4 ([#5980](https://github.com/aws-powertools/powertools-lambda-python/issues/5980))
+* **deps:** bump actions/setup-go from 5.2.0 to 5.3.0 ([#5978](https://github.com/aws-powertools/powertools-lambda-python/issues/5978))
+* **deps:** bump squidfunk/mkdocs-material from `471695f` to `7e841df` in /docs ([#6012](https://github.com/aws-powertools/powertools-lambda-python/issues/6012))
+* **deps:** bump squidfunk/mkdocs-material from `41942f7` to `471695f` in /docs ([#5979](https://github.com/aws-powertools/powertools-lambda-python/issues/5979))
+* **deps:** bump docker/setup-qemu-action from 3.2.0 to 3.3.0 ([#5961](https://github.com/aws-powertools/powertools-lambda-python/issues/5961))
+* **deps:** bump actions/upload-artifact from 4.5.0 to 4.6.0 ([#5962](https://github.com/aws-powertools/powertools-lambda-python/issues/5962))
+* **deps:** bump actions/setup-node from 4.1.0 to 4.2.0 ([#5963](https://github.com/aws-powertools/powertools-lambda-python/issues/5963))
+* **deps:** bump zgosalvez/github-actions-ensure-sha-pinned-actions from 3.0.18 to 3.0.20 ([#5977](https://github.com/aws-powertools/powertools-lambda-python/issues/5977))
 * **deps-dev:** bump mkdocs-material from 9.5.50 to 9.6.1 ([#5966](https://github.com/aws-powertools/powertools-lambda-python/issues/5966))
-* **deps-dev:** bump black from 24.10.0 to 25.1.0 ([#5968](https://github.com/aws-powertools/powertools-lambda-python/issues/5968))
-* **deps-dev:** bump cfn-lint from 1.22.7 to 1.23.1 ([#5967](https://github.com/aws-powertools/powertools-lambda-python/issues/5967))
 * **deps-dev:** bump isort from 5.13.2 to 6.0.0 ([#5965](https://github.com/aws-powertools/powertools-lambda-python/issues/5965))
+* **deps-dev:** bump cfn-lint from 1.22.7 to 1.23.1 ([#5967](https://github.com/aws-powertools/powertools-lambda-python/issues/5967))
+* **deps-dev:** bump black from 24.10.0 to 25.1.0 ([#5968](https://github.com/aws-powertools/powertools-lambda-python/issues/5968))
+* **deps-dev:** bump mkdocstrings-python from 1.13.0 to 1.14.2 ([#6011](https://github.com/aws-powertools/powertools-lambda-python/issues/6011))
+* **deps-dev:** bump mkdocs-material from 9.6.1 to 9.6.2 ([#6009](https://github.com/aws-powertools/powertools-lambda-python/issues/6009))
+* **deps-dev:** bump boto3-stubs from 1.36.10 to 1.36.11 ([#6010](https://github.com/aws-powertools/powertools-lambda-python/issues/6010))
+* **deps-dev:** bump boto3-stubs from 1.36.10 to 1.36.12 ([#6014](https://github.com/aws-powertools/powertools-lambda-python/issues/6014))
+* **deps-dev:** bump ruff from 0.9.3 to 0.9.4 ([#5969](https://github.com/aws-powertools/powertools-lambda-python/issues/5969))
 
 
 <a name="v3.5.0"></a>

Makefile

@@ -1,5 +1,5 @@
-.PHONY: target dev format lint test coverage-html pr  build build-docs build-docs-api build-docs-website
-.PHONY: docs-local docs-api-local security-baseline complexity-baseline release-prod release-test release
+.PHONY: target dev format lint test coverage-html pr  build build-docs build-docs-website check-licenses
+.PHONY: docs-local security-baseline complexity-baseline release-prod release-test release
 
 target:
 	@$(MAKE) pr
@@ -21,6 +21,10 @@ dev-gitpod:
 	poetry install --extras "all redis datamasking"
 	pre-commit install
 
+# Running licensecheck with zero to break the pipeline if there is an invalid license
+check-licenses:
+	poetry run licensecheck -u poetry:dev --zero
+
 format:
 	poetry run black aws_lambda_powertools tests examples
 
@@ -55,7 +59,7 @@ coverage-html:
 pre-commit:
 	pre-commit run --show-diff-on-failure
 
-pr: lint lint-docs mypy pre-commit test security-baseline complexity-baseline
+pr: lint lint-docs mypy pre-commit check-licenses test security-baseline complexity-baseline
 
 build: pr
 	poetry build
@@ -65,14 +69,6 @@ release-docs:
 	rm -rf site api
 	@echo "Updating website docs"
 	poetry run mike deploy --push --update-aliases ${VERSION} ${ALIAS}
-	@echo "Building API docs"
-	@$(MAKE) build-docs-api VERSION=${VERSION}
-
-build-docs-api:
-	poetry run pdoc --html --output-dir ./api/ ./aws_lambda_powertools --force
-	mv -f ./api/aws_lambda_powertools/* ./api/
-	rm -rf ./api/aws_lambda_powertools
-	mkdir ${VERSION} && cp -R api ${VERSION}
 
 docs-local:
 	poetry run mkdocs serve
@@ -81,9 +77,6 @@ docs-local-docker:
 	docker build -t squidfunk/mkdocs-material ./docs/
 	docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
 
-docs-api-local:
-	poetry run pdoc --http : aws_lambda_powertools
-
 security-baseline:
 	poetry run bandit --baseline bandit.baseline -r aws_lambda_powertools
 

aws_lambda_powertools/event_handler/api_gateway.py

@@ -313,10 +313,10 @@ def __init__(
         middlewares: list[Callable[..., Response]] | None = None,
     ):
         """
+        Internally used Route Configuration
 
         Parameters
         ----------
-
         method: str
             The HTTP method, example "GET"
         path: str
@@ -908,6 +908,8 @@ def build(self, event: ResponseEventT, cors: CORSConfig | None = None) -> dict[s
 
 
 class BaseRouter(ABC):
+    """Base class for Routing"""
+
     current_event: BaseProxyEvent
     lambda_context: LambdaContext
     context: dict
@@ -1459,7 +1461,7 @@ def _registered_api_adapter(app: ApiGatewayResolver, next_middleware: Callable[.
 
 
 class ApiGatewayResolver(BaseRouter):
-    """API Gateway and ALB proxy resolver
+    """API Gateway, VPC Laticce, Bedrock and ALB proxy resolver
 
     Examples
     --------
@@ -2570,6 +2572,8 @@ def register_exception_handler(func: Callable):
 
 
 class APIGatewayRestResolver(ApiGatewayResolver):
+    """Amazon API Gateway REST and HTTP API v1 payload resolver"""
+
     current_event: APIGatewayProxyEvent
 
     def __init__(
@@ -2650,6 +2654,8 @@ def _compile_regex(rule: str, base_regex: str = _ROUTE_REGEX):
 
 
 class APIGatewayHttpResolver(ApiGatewayResolver):
+    """Amazon API Gateway HTTP API v2 payload resolver"""
+
     current_event: APIGatewayProxyEventV2
 
     def __init__(
@@ -2685,6 +2691,8 @@ def _get_base_path(self) -> str:
 
 
 class ALBResolver(ApiGatewayResolver):
+    """Amazon Application Load Balancer (ALB) resolver"""
+
     current_event: ALBEvent
 
     def __init__(

aws_lambda_powertools/event_handler/middlewares/base.py

@@ -26,7 +26,7 @@ class BaseMiddlewareHandler(Generic[EventHandlerInstance], ABC):
     This is the middleware handler function where middleware logic is implemented.
     The next middleware handler is represented by `next_middleware`, returning a Response object.
 
-    Examples
+    Example
     --------
 
     **Correlation ID Middleware**

aws_lambda_powertools/event_handler/middlewares/openapi_validation.py

@@ -37,7 +37,7 @@ class OpenAPIValidationMiddleware(BaseMiddlewareHandler):
     Lambda handler. It also validates the response against the OpenAPI schema defined by the Lambda handler. It
     should not be used directly, but rather through the `enable_validation` parameter of the `ApiGatewayResolver`.
 
-    Examples
+    Example
     --------
 
     ```python

aws_lambda_powertools/event_handler/middlewares/schema_validation.py

@@ -18,7 +18,7 @@
 class SchemaValidationMiddleware(BaseMiddlewareHandler):
     """Middleware to validate API request and response against JSON Schema using the [Validation utility](https://docs.powertools.aws.dev/lambda/python/latest/utilities/validation/).
 
-    Examples
+    Example
     --------
     **Validating incoming event**
 

aws_lambda_powertools/event_handler/openapi/params.py

@@ -879,8 +879,6 @@ def get_flat_dependant(
     ----------
     dependant: Dependant
         The dependant model to flatten
-    skip_repeats: bool
-        If True, child Dependents already visited will be skipped to avoid duplicates
     visited: list[CacheKey], optional
         Keeps track of visited Dependents to avoid infinite recursion. Defaults to empty list.
 
@@ -932,7 +930,12 @@ def analyze_param(
     ModelField | None
         The type annotation and the Pydantic field representing the parameter
     """
-    field_info, type_annotation = get_field_info_and_type_annotation(annotation, value, is_path_param)
+    field_info, type_annotation = get_field_info_and_type_annotation(
+        annotation,
+        value,
+        is_path_param,
+        is_response_param,
+    )
 
     # If the value is a FieldInfo, we use it as the FieldInfo for the parameter
     if isinstance(value, FieldInfo):
@@ -962,7 +965,12 @@ def analyze_param(
     return field
 
 
-def get_field_info_and_type_annotation(annotation, value, is_path_param: bool) -> tuple[FieldInfo | None, Any]:
+def get_field_info_and_type_annotation(
+    annotation,
+    value,
+    is_path_param: bool,
+    is_response_param: bool,
+) -> tuple[FieldInfo | None, Any]:
     """
     Get the FieldInfo and type annotation from an annotation and value.
     """
@@ -976,19 +984,33 @@ def get_field_info_and_type_annotation(annotation, value, is_path_param: bool) -
         # If the annotation is a Response type, we recursively call this function with the inner type
         elif get_origin(annotation) is Response:
             field_info, type_annotation = get_field_info_response_type(annotation, value)
+        # If the response param is a tuple with two elements, we use the first element as the type annotation,
+        # just like we did in the APIGateway._to_response
+        elif is_response_param and get_origin(annotation) is tuple and len(get_args(annotation)) == 2:
+            field_info, type_annotation = get_field_info_tuple_type(annotation, value)
         # If the annotation is not an Annotated type, we use it as the type annotation
         else:
             type_annotation = annotation
 
     return field_info, type_annotation
 
 
+def get_field_info_tuple_type(annotation, value) -> tuple[FieldInfo | None, Any]:
+    (inner_type, _) = get_args(annotation)
+
+    # If the inner type is an Annotated type, we need to extract the type annotation and the FieldInfo
+    if get_origin(inner_type) is Annotated:
+        return get_field_info_annotated_type(inner_type, value, False)
+
+    return None, inner_type
+
+
 def get_field_info_response_type(annotation, value) -> tuple[FieldInfo | None, Any]:
     # Example: get_args(Response[inner_type]) == (inner_type,)  # noqa: ERA001
     (inner_type,) = get_args(annotation)
 
     # Recursively resolve the inner type
-    return get_field_info_and_type_annotation(inner_type, value, False)
+    return get_field_info_and_type_annotation(inner_type, value, False, True)
 
 
 def get_field_info_annotated_type(annotation, value, is_path_param: bool) -> tuple[FieldInfo | None, Any]:

aws_lambda_powertools/event_handler/openapi/swagger_ui/html.py

@@ -22,7 +22,7 @@ def generate_swagger_html(
     spec: str
         The OpenAPI spec
     swagger_js: str
-       Swagger UI JavaScript source code or URL
+        Swagger UI JavaScript source code or URL
     swagger_css: str
         Swagger UI CSS source code or URL
     swagger_base_url: str

aws_lambda_powertools/logging/__init__.py

@@ -1,5 +1,4 @@
-"""Logging utility
-"""
+"""Logging utility"""
 
 from .logger import Logger
 

aws_lambda_powertools/logging/exceptions.py

@@ -1,2 +1,6 @@
 class InvalidLoggerSamplingRateError(Exception):
+    """
+    Logger configured with Invalid Sampling value
+    """
+
     pass

aws_lambda_powertools/logging/formatter.py

@@ -273,17 +273,17 @@ def append_context_keys(self, **additional_keys: Any) -> Generator[None, None, N
         """
         Context manager to temporarily add logging keys.
 
-        Parameters:
+        Parameters
         -----------
-        **keys: Any
+        **additional_keys: Any
             Key-value pairs to include in the log context during the lifespan of the context manager.
 
-        Example:
+        Example
         --------
-        >>> logger = Logger(service="example_service")
-        >>> with logger.append_context_keys(user_id="123", operation="process"):
-        >>>     logger.info("Log with context")
-        >>> logger.info("Log without context")
+            logger = Logger(service="example_service")
+            with logger.append_context_keys(user_id="123", operation="process"):
+                logger.info("Log with context")
+            logger.info("Log without context")
         """
         # Add keys to the context
         self.append_keys(**additional_keys)