AWS CDK Python Lambda Alpha Library

Warnings

• breaking This library is an 'alpha' package, meaning its APIs are experimental and under active development. Breaking changes may occur in any future version without following semantic versioning, requiring code updates when upgrading.
  Fix: Regularly check release notes for breaking changes before upgrading. Be prepared to refactor code when new versions are adopted.
• gotcha Bundling Python Lambda functions with this construct requires Docker to be installed and running on the machine where `cdk synth` or `cdk deploy` is executed. Without Docker, bundling will fail.
  Fix: Ensure Docker Desktop or a compatible Docker environment (e.g., Docker Engine) is installed and actively running on your development machine before synthesizing or deploying CDK stacks that use `PythonFunction` or `PythonLayerVersion`.
• gotcha For reproducible builds and explicit dependency management, always commit a lockfile (e.g., `requirements.txt`, `Pipfile.lock`, `uv.lock`, or `poetry.lock`) alongside your Lambda function's source code in the `entry` directory.
  Fix: Use tools like `pip`, `pipenv`, `uv`, or `poetry` to generate and commit a lockfile specifying all transitive dependencies and their exact versions within your Lambda function's source directory.
• breaking Mixing CDK v1 modules with CDK v2's `aws-cdk-lib` and experimental 'alpha' packages like this one is a common source of dependency resolution errors and unexpected behavior.
  Fix: Ensure your project exclusively uses CDK v2 (`aws-cdk-lib`) and its associated alpha constructs. If migrating from v1, follow the AWS CDK v2 migration guide.
• gotcha Users have reported issues with bundling when using `podman` instead of `docker`, specifically related to user mapping parameters passed to the container, leading to permission denied errors.
  Fix: If encountering issues with `podman`, consider using Docker, or investigate potential workarounds/configuration adjustments for `podman` that might resolve issues with user mapping or permissions during containerized bundling. Refer to GitHub issues for potential solutions.
• gotcha A `Runtime.ImportModuleError` can occur if the local file structure or dependencies of your Lambda code are not correctly resolved during bundling, or if the `index` and `handler` properties do not accurately point to your Python entry point.
  Fix: Verify that your `entry` path is correct and contains all necessary files. Ensure `index` and `handler` accurately reflect the file and function name. All Python modules imported by your Lambda should be discoverable within the bundled asset, either as part of your source or defined in a lockfile.

Install

• pip install aws-cdk.aws-lambda-python-alpha Install package

Imports

• PythonFunction

  from aws_cdk.aws_lambda_python_alpha import PythonFunction

  The `-alpha` suffix is crucial for importing experimental constructs in CDK v2. Omitting it typically leads to an ImportError or attempting to use a CDK v1 construct.
• PythonLayerVersion

  from aws_cdk.aws_lambda_python_alpha import PythonLayerVersion

Quickstart

This quickstart demonstrates how to define a Python Lambda function using `PythonFunction` from the `aws-cdk.aws-lambda-python-alpha` library. It dynamically creates a `lambda_code` directory with a simple `lambda_handler.py` file. The `PythonFunction` construct automatically bundles your code and its dependencies (if a `requirements.txt`, `Pipfile`, `uv.lock`, or `poetry.lock` is present in the `entry` directory) using Docker during `cdk synth`.

import os
from aws_cdk import (
    App,
    Stack,
    aws_lambda as _lambda,
)
from aws_cdk.aws_lambda_python_alpha import PythonFunction
from constructs import Construct

# Create a dummy lambda_code directory and handler file for the example
lambda_code_dir = os.path.join(os.path.dirname(__file__), "lambda_code")
os.makedirs(lambda_code_dir, exist_ok=True)
with open(os.path.join(lambda_code_dir, "lambda_handler.py"), "w") as f:
    f.write("""
import json

def handler(event, context):
    print("Lambda received event:", event)
    return {
        'statusCode': 200,
        'body': json.dumps('Hello from Python Lambda Alpha!')
    }
""")
# Add a dummy requirements.txt if you want to test dependency bundling
# with open(os.path.join(lambda_code_dir, "requirements.txt"), "w") as f:
#     f.write("requests\n")

class MyPythonLambdaStack(Stack):
    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        PythonFunction(
            self,
            "MyPythonLambda",
            entry=lambda_code_dir, # Path to the directory containing your handler and dependencies
            runtime=_lambda.Runtime.PYTHON_3_9, # Specify a supported Python runtime
            index="lambda_handler.py", # Optional, defaults to 'index.py'
            handler="handler", # Optional, defaults to 'handler'
            # Set an environment variable (optional)
            environment={
                "MY_ENV_VAR": os.environ.get('MY_ENV_VAR', 'default_value')
            }
        )

app = App()
MyPythonLambdaStack(app, "MyPythonLambdaStack")
app.synth()