Merge branch 'develop' into dependabot/docker/docs/squidfunk/mkdocs-material-405aeb6dbf1fcddd1082993eacf288a46648ea56b846323f001aee619015a23b

Author: leandrodamascena

aws_lambda_powertools/shared/version.py

@@ -1,3 +1,3 @@
 """Exposes version constant to avoid circular dependencies."""
 
-VERSION = "3.19.1a1"
+VERSION = "3.19.1a2"

aws_lambda_powertools/utilities/parser/models/dynamodb.py

@@ -2,53 +2,111 @@
 from datetime import datetime
 from typing import Any, Dict, List, Literal, Optional, Type, Union
 
-from pydantic import BaseModel, field_validator
+from pydantic import BaseModel, Field, field_validator
 
 from aws_lambda_powertools.shared.dynamodb_deserializer import TypeDeserializer
 
 _DESERIALIZER = TypeDeserializer()
 
 
 class DynamoDBStreamChangedRecordModel(BaseModel):
-    ApproximateCreationDateTime: Optional[datetime] = None
-    Keys: Dict[str, Any]
-    NewImage: Optional[Union[Dict[str, Any], Type[BaseModel], BaseModel]] = None
-    OldImage: Optional[Union[Dict[str, Any], Type[BaseModel], BaseModel]] = None
-    SequenceNumber: str
-    SizeBytes: int
-    StreamViewType: Literal["NEW_AND_OLD_IMAGES", "KEYS_ONLY", "NEW_IMAGE", "OLD_IMAGE"]
-
-    # context on why it's commented: https://github.com/aws-powertools/powertools-lambda-python/pull/118
-    # since both images are optional, they can both be None. However, at least one must
-    # exist in a legal model of NEW_AND_OLD_IMAGES type
-    # @root_validator
-    # def check_one_image_exists(cls, values): # noqa: ERA001
-    #     new_img, old_img = values.get("NewImage"), values.get("OldImage") # noqa: ERA001
-    #     stream_type = values.get("StreamViewType") # noqa: ERA001
-    #     if stream_type == "NEW_AND_OLD_IMAGES" and not new_img and not old_img: # noqa: ERA001
-    #         raise TypeError("DynamoDB streams model failed validation, missing both new & old stream images") # noqa: ERA001,E501
-    #     return values # noqa: ERA001
+    ApproximateCreationDateTime: Optional[datetime] = Field(  # AWS sends this as Unix epoch float
+        default=None,
+        description="The approximate date and time when the stream record was created (Unix epoch time).",
+        examples=[1693997155.0],
+    )
+    Keys: Dict[str, Any] = Field(description="Primary key attributes for the item.", examples=[{"Id": {"N": "101"}}])
+    NewImage: Optional[Union[Dict[str, Any], Type[BaseModel], BaseModel]] = Field(
+        default=None,
+        description="The item after modifications, in DynamoDB attribute-value format.",
+        examples=[{"Message": {"S": "New item!"}, "Id": {"N": "101"}}],
+    )
+    OldImage: Optional[Union[Dict[str, Any], Type[BaseModel], BaseModel]] = Field(
+        default=None,
+        description="The item before modifications, in DynamoDB attribute-value format.",
+        examples=[{"Message": {"S": "Old item!"}, "Id": {"N": "100"}}],
+    )
+    SequenceNumber: str = Field(description="A unique identifier for the stream record.", examples=["222"])
+    SizeBytes: int = Field(description="The size of the stream record, in bytes.", examples=[26])
+    StreamViewType: Literal["NEW_AND_OLD_IMAGES", "KEYS_ONLY", "NEW_IMAGE", "OLD_IMAGE"] = Field(
+        description="The type of data included in the stream record.",
+        examples=["NEW_AND_OLD_IMAGES"],
+    )
 
     @field_validator("Keys", "NewImage", "OldImage", mode="before")
     def deserialize_field(cls, value):
         return {k: _DESERIALIZER.deserialize(v) for k, v in value.items()}
 
 
 class UserIdentity(BaseModel):
-    type: Literal["Service"]  # noqa: VNE003, A003
-    principalId: Literal["dynamodb.amazonaws.com"]
+    type: Literal["Service"] = Field(
+        description="The type of identity that made the request, which is always 'Service' for DynamoDB streams.",
+        examples=["Service"],
+    )
+    principalId: Literal["dynamodb.amazonaws.com"] = Field(
+        description="The unique identifier for the principal that made the request.",
+        examples=["dynamodb.amazonaws.com"],
+    )
 
 
 class DynamoDBStreamRecordModel(BaseModel):
-    eventID: str
-    eventName: Literal["INSERT", "MODIFY", "REMOVE"]
-    eventVersion: float
-    eventSource: Literal["aws:dynamodb"]
-    awsRegion: str
-    eventSourceARN: str
-    dynamodb: DynamoDBStreamChangedRecordModel
-    userIdentity: Optional[UserIdentity] = None
+    eventID: str = Field(description="A unique identifier for the event.", examples=["1"])
+    eventName: Literal["INSERT", "MODIFY", "REMOVE"] = Field(
+        description="The type of operation that was performed on the item.",
+        examples=["INSERT"],
+    )
+    eventVersion: float = Field(description="The version of the stream record format.", examples=["1.0"])
+    eventSource: Literal["aws:dynamodb"] = Field(
+        description="The source of the event, which is always 'aws:dynamodb' for DynamoDB streams.",
+        examples=["aws:dynamodb"],
+    )
+    awsRegion: str = Field(description="The AWS region where the stream record was generated.", examples=["us-west-2"])
+    eventSourceARN: str = Field(
+        description="The Amazon Resource Name (ARN) of the DynamoDB stream.",
+        examples=["arn:aws:dynamodb:us-west-2:123456789012:table/ExampleTable/stream/2021-01-01T00:00:00.000"],
+    )
+    dynamodb: DynamoDBStreamChangedRecordModel = Field(
+        description="Contains the details of the DynamoDB stream record.",
+        examples=[
+            {
+                "ApproximateCreationDateTime": 1693997155.0,
+                "Keys": {"Id": {"N": "101"}},
+                "NewImage": {"Message": {"S": "New item!"}, "Id": {"N": "101"}},
+                "OldImage": {"Message": {"S": "Old item!"}, "Id": {"N": "100"}},
+                "SequenceNumber": "222",
+                "SizeBytes": 26,
+                "StreamViewType": "NEW_AND_OLD_IMAGES",
+            },
+        ],
+    )
+    userIdentity: Optional[UserIdentity] = Field(
+        default=None,
+        description="Information about the identity that made the request.",
+        examples=[{"type": "Service", "principalId": "dynamodb.amazonaws.com"}],
+    )
 
 
 class DynamoDBStreamModel(BaseModel):
-    Records: List[DynamoDBStreamRecordModel]
+    Records: List[DynamoDBStreamRecordModel] = Field(
+        description="A list of records that contain the details of the DynamoDB stream events.",
+        examples=[
+            {
+                "eventID": "1",
+                "eventName": "INSERT",
+                "eventVersion": "1.0",
+                "eventSource": "aws:dynamodb",
+                "awsRegion": "us-west-2",
+                "eventSourceARN": "arn:aws:dynamodb:us-west-2:123456789012:table/ExampleTable/stream/2021-01-01T00:00:00.000",  # noqa E501
+                "dynamodb": {
+                    "ApproximateCreationDateTime": 1693997155.0,
+                    "Keys": {"Id": {"N": "101"}},
+                    "NewImage": {"Message": {"S": "New item!"}, "Id": {"N": "101"}},
+                    "OldImage": {"Message": {"S": "Old item!"}, "Id": {"N": "100"}},
+                    "SequenceNumber": "222",
+                    "SizeBytes": 26,
+                    "StreamViewType": "NEW_AND_OLD_IMAGES",
+                },
+                "userIdentity": {"type": "Service", "principalId": "dynamodb.amazonaws.com"},
+            },
+        ],
+    )

docs/build_recipes/cicd-integration.md

@@ -0,0 +1,68 @@
+---
+title: CI/CD Integration
+description: Automate Lambda function builds and deployments
+---
+
+<!-- markdownlint-disable MD043 -->
+
+Automate your Lambda function builds and deployments using popular CI/CD platforms. These examples show how to build and deploy Lambda functions with Powertools for AWS with proper cross-platform compatibility and deploy them reliably.
+
+## GitHub Actions
+
+**GitHub Actions** provides a powerful, integrated CI/CD platform that runs directly in your GitHub repository. It offers excellent integration with AWS services, supports matrix builds for testing multiple configurations, and provides a rich ecosystem of pre-built actions.
+
+=== "Modern AWS Lambda deploy action"
+
+    ```yaml
+    --8<-- "examples/build_recipes/cicd/github-actions/deploy-modern.yml"
+    ```
+
+=== "Multi-environment deployment"
+
+    ```yaml
+    --8<-- "examples/build_recipes/cicd/github-actions/deploy-multi-env.yml"
+    ```
+
+=== "Simple source code deployment"
+
+    ```yaml
+    --8<-- "examples/build_recipes/cicd/github-actions/deploy-simple.yml"
+    ```
+
+=== "S3 deployment method"
+
+    ```yaml
+    --8<-- "examples/build_recipes/cicd/github-actions/deploy-s3.yml"
+    ```
+
+=== "Build tool integration"
+
+    ```yaml
+    --8<-- "examples/build_recipes/cicd/github-actions/deploy-build-tools.yml"
+    ```
+
+## AWS CodeBuild
+
+**AWS CodeBuild** is a fully managed build service that compiles source code, runs tests, and produces deployment packages. It integrates seamlessly with other AWS services and provides consistent build environments with automatic scaling.
+
+=== "Basic CodeBuild Configuration"
+
+    ```yaml
+    --8<-- "examples/build_recipes/cicd/codebuild/buildspec.yml"
+    ```
+
+## Best Practices for CI/CD
+
+1. **Use Linux runners** (ubuntu-latest) to ensure Lambda compatibility
+2. **Cache dependencies** to speed up builds (uv, poetry cache, pip cache)
+3. **Run tests first** before building deployment packages
+4. **Use matrix builds** to test multiple Python versions or configurations
+5. **Implement proper secrets management** with GitHub Secrets or AWS Parameter Store
+6. **Add deployment gates** for production environments
+7. **Monitor deployment success** with CloudWatch metrics and alarms
+
+???+ tip "Performance Optimization"
+    - Use **uv** for fastest dependency installation in CI/CD
+    - **Cache virtual environments** between builds when possible
+    - **Parallelize builds** for multiple environments
+    - **Use container images** for complex dependencies or large packages

examples/build_recipes/cicd/codebuild/buildspec-advanced.yml

@@ -0,0 +1,131 @@
+version: 0.2
+
+env:
+  variables:
+    PYTHON_VERSION: "3.13"
+    BUILD_STAGE: "build"
+  parameter-store:
+    POWERTOOLS_VERSION: "/build/powertools-version"
+
+batch:
+  fast-fail: false
+  build-list:
+    - identifier: test
+      env:
+        variables:
+          BUILD_STAGE: "test"
+    - identifier: build_dev
+      env:
+        variables:
+          BUILD_STAGE: "build"
+          ENVIRONMENT: "dev"
+      depend-on:
+        - test
+    - identifier: build_prod
+      env:
+        variables:
+          BUILD_STAGE: "build"
+          ENVIRONMENT: "prod"
+      depend-on:
+        - test
+
+phases:
+  install:
+    runtime-versions:
+      python: $PYTHON_VERSION
+    commands:
+      - echo "Build stage: $BUILD_STAGE, Environment: $ENVIRONMENT"
+      - pip install --upgrade pip uv
+
+  pre_build:
+    commands:
+      - |
+        if [ "$BUILD_STAGE" = "test" ]; then
+          echo "Installing test dependencies..."
+          uv venv test-env
+          source test-env/bin/activate
+          uv pip install aws-lambda-powertools[all]==$POWERTOOLS_VERSION pytest pytest-cov
+          cp -r src/ test-src/
+        else
+          echo "Installing build dependencies..."
+          uv venv build-env
+          source build-env/bin/activate
+          uv pip install aws-lambda-powertools[all]==$POWERTOOLS_VERSION
+          uv pip install pydantic requests
+        fi
+
+  build:
+    commands:
+      - |
+        if [ "$BUILD_STAGE" = "test" ]; then
+          echo "Running tests..."
+          source test-env/bin/activate
+          cd test-src
+          pytest tests/ --cov=. --cov-report=xml --cov-report=term
+          echo "Tests completed successfully"
+        else
+          echo "Building deployment package for $ENVIRONMENT..."
+          source build-env/bin/activate
+
+          # Create environment-specific package
+          mkdir -p package-$ENVIRONMENT/
+          cp -r build-env/lib/python*/site-packages/* package-$ENVIRONMENT/
+          cp -r src/* package-$ENVIRONMENT/
+
+          # Environment-specific optimizations
+          if [ "$ENVIRONMENT" = "prod" ]; then
+            echo "Applying production optimizations..."
+            find package-$ENVIRONMENT/ -name "*.pyc" -delete
+            find package-$ENVIRONMENT/ -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null || true
+            find package-$ENVIRONMENT/ -name "tests" -type d -exec rm -rf {} + 2>/dev/null || true
+            find package-$ENVIRONMENT/ -name "*.dist-info" -type d -exec rm -rf {} + 2>/dev/null || true
+          fi
+
+          # Create deployment ZIP
+          cd package-$ENVIRONMENT && zip -r ../lambda-$ENVIRONMENT.zip . && cd ..
+
+          echo "Package size for $ENVIRONMENT: $(du -sh lambda-$ENVIRONMENT.zip)"
+        fi
+
+  post_build:
+    commands:
+      - |
+        if [ "$BUILD_STAGE" = "build" ]; then
+          echo "Deploying to $ENVIRONMENT environment..."
+
+          # Deploy to environment-specific function
+          aws lambda update-function-code \
+            --function-name powertools-app-$ENVIRONMENT \
+            --zip-file fileb://lambda-$ENVIRONMENT.zip \
+            --region $AWS_DEFAULT_REGION
+
+          # Update environment-specific configuration
+          LOG_LEVEL="INFO"
+          if [ "$ENVIRONMENT" = "dev" ]; then
+            LOG_LEVEL="DEBUG"
+          fi
+
+          aws lambda update-function-configuration \
+            --function-name powertools-app-$ENVIRONMENT \
+            --environment Variables="{
+              ENVIRONMENT=$ENVIRONMENT,
+              POWERTOOLS_SERVICE_NAME=powertools-app-$ENVIRONMENT,
+              POWERTOOLS_METRICS_NAMESPACE=MyApp/$ENVIRONMENT,
+              POWERTOOLS_LOG_LEVEL=$LOG_LEVEL
+            }" \
+            --region $AWS_DEFAULT_REGION
+
+          echo "Deployment to $ENVIRONMENT completed successfully!"
+        fi
+
+artifacts:
+  files:
+    - lambda-*.zip
+    - coverage.xml
+  name: lambda-artifacts-$(date +%Y-%m-%d-%H-%M-%S)
+
+cache:
+  paths:
+    - 'build-env/**/*'
+    - 'test-env/**/*'
+