source

This module provides utilities for building, packaging, and uploading AWS Lambda source artifacts.

It handles the complete lifecycle of Lambda source deployment packages:

1. Building source artifacts using pip from setup.py or pyproject.toml

2. Creating compressed zip archives of the built source

3. Uploading artifacts to S3 with proper versioning and metadata

Key Assumptions:

1. Pip-based packaging: Uses pip install to build source artifacts, ensuring proper Python package installation and module discovery within the Lambda runtime environment.

2. Code folder structure: Assumes the Lambda entry point (lambda_function.py) is included within the installed package structure, not as a separate external file.

S3 Storage Structure:

s3://bucket/${s3dir_lambda}/source/0.1.1/source.zip
s3://bucket/${s3dir_lambda}/source/0.1.2/source.zip
s3://bucket/${s3dir_lambda}/source/0.1.3/source.zip

The pattern in this module is inspired by this blog post

class aws_lambda_artifact_builder.source.SourcePathLayout

aws_lambda_artifact_builder.source.build_source_artifacts_using_pip(path_bin_pip: ~pathlib.Path, path_setup_py_or_pyproject_toml: ~pathlib.Path, dir_lambda_source_build: ~pathlib.Path, skip_prompt: bool = False, verbose: bool = True, printer: ~typing.Callable[[str], None] = <built-in function print>)

Build Lambda source artifacts by installing the current package using pip.

Why pip install? Using pip ensures proper Python package installation with correct module paths, entry points, and metadata that Lambda runtime expects. This approach guarantees that all package modules are discoverable and importable within the Lambda execution environment, unlike simple file copying which may break import resolution.

This function installs the Python package (defined by setup.py or pyproject.toml) into a target directory without dependencies, suitable for Lambda deployment. The build directory is cleaned before installation to ensure a fresh build.

Parameters:

• path_bin_pip – Path to pip executable, e.g., /path/to/.venv/bin/pip

• path_setup_py_or_pyproject_toml – Path to package definition file, e.g., /path/to/setup.py or /path/to/pyproject.toml

• dir_lambda_source_build – Target directory for built artifacts, e.g., /path/to/build/lambda/source/build

• verbose – If True, display detailed build output; if False, suppress pip output

• skip_prompt – If True, automatically clean existing build directory without user confirmation

• printer – Function to handle output messages, defaults to built-in print

aws_lambda_artifact_builder.source.create_source_zip(dir_lambda_source_build: ~pathlib.Path, path_source_zip: ~pathlib.Path, verbose: bool = True, printer: ~typing.Callable[[str], None] = <built-in function print>) → str

Create a compressed zip archive from the Lambda source build directory.

Important assumption: This function expects that the Lambda entry point (typically lambda_function.py with a lambda_handler function) is included within the installed package structure in the build directory, not as a separate external file. The entry point should be part of your Python package as defined in setup.py or pyproject.toml.

This function creates a zip file containing all files from the build directory using maximum compression (level 9) and calculates the SHA256 hash of the source directory for integrity verification.

Parameters:

• dir_lambda_source_build – Directory containing built Lambda source files

• path_source_zip – Output path for the created zip file

• verbose – If True, display progress information; if False, run quietly

• printer – Function to handle output messages, defaults to built-in print

Returns:

SHA256 hash of the source build directory

class aws_lambda_artifact_builder.source.SourceS3Layout(s3dir_lambda: S3Path)

S3 directory layout manager for Lambda source artifacts.

This class provides a structured approach to organizing Lambda source artifacts in S3 with semantic versioning. Each version gets its own directory containing the source.zip file.

Parameters:

s3dir_lambda – Base S3 directory for Lambda artifacts, e.g., s3://bucket/path/to/lambda/

Generated Layout, see get_s3path_source_zip()

${s3dir_lambda}/source/0.1.1/{source_sha256}/source.zip
${s3dir_lambda}/source/0.1.2/{source_sha256}/source.zip
${s3dir_lambda}/source/0.1.3/{source_sha256}/source.zip
...

get_s3path_source_zip(source_version: str, source_sha256: str) → S3Path

Generate S3 path for a specific version of the Lambda source zip.

Parameters:

• source_version – Semantic version string, e.g., "0.1.1"

• source_sha256 – SHA256 hash of the source build directory (not used in path generation)

Returns:

S3Path object pointing to the versioned source.zip file, example: ${s3dir_lambda}/source/{source_version}/{source_sha256}/source.zip

Note

The SHA256 hash is essential for proper AWS Lambda deployments. When using CDK, CloudFormation, or AWS APIs, if the S3 path remains unchanged between deployments, AWS assumes the code hasn’t changed and skips the update. Including the source SHA256 in the path ensures that any code changes result in a new S3 location, forcing AWS to recognize and deploy the updated Lambda function code.

aws_lambda_artifact_builder.source.upload_source_artifacts(s3_client: S3Client, source_version: str, source_sha256: str, path_source_zip: ~pathlib.Path, s3dir_lambda: S3Path, metadata: dict[str, str] | None = OPT, tags: dict[str, str] | None = OPT, verbose: bool = True, printer: ~typing.Callable[[str], None] = <built-in function print>) → S3Path

Upload Lambda source artifact zip file to S3 with versioning and metadata.

This function uploads the built source zip to S3 following the structured layout, automatically adding SHA256 hash metadata for integrity verification and supporting custom metadata and tags.

Parameters:

• s3_client – Boto3 S3 client for upload operations

• source_version – Semantic version for the source code, e.g., "0.1.1"

• source_sha256 – SHA256 hash of the source build directory for integrity verification

• path_source_zip – Local path to the source zip file to upload

• s3dir_lambda – Base S3 directory for Lambda artifacts, e.g., s3://bucket/path/to/lambda/

• metadata – Optional custom S3 object metadata to attach

• tags – Optional S3 object tags to attach

• verbose – If True, display upload progress and URLs; if False, run quietly

• printer – Function to handle output messages, defaults to built-in print

Returns:

S3Path object pointing to the uploaded source.zip file

class aws_lambda_artifact_builder.source.BuildSourceArtifactsResult(source_sha256: str, s3path_source_zip: S3Path)

Result of building and uploading Lambda source artifacts.

aws_lambda_artifact_builder.source.build_package_upload_source_artifacts(s3_client: S3Client, dir_project_root: ~pathlib.Path, s3dir_lambda: S3Path, skip_prompt: bool = False, verbose: bool = True, printer: ~typing.Callable[[str], None] = <built-in function print>) → BuildSourceArtifactsResult

Build, package, and upload Lambda source artifacts to S3.

This is a all-in-one function that handles the complete lifecycle of Lambda source.

Parameters:

• s3_client – Boto3 S3 client for upload operations

• dir_project_root – Root directory of the Python project containing setup.py or pyproject.toml

• s3dir_lambda – Base S3 directory for Lambda artifacts, e.g., s3://bucket/path/to/lambda/

• skip_prompt – If True, automatically clean existing build directory without user confirmation

• verbose – If True, display detailed progress information; if False, run quietly

• printer – Function to handle output messages, defaults to built-in print

Returns:

BuildSourceArtifactsResult containing SHA256 hash and S3 path of the uploaded source.zip

See also

• build_source_artifacts_using_pip()

• create_source_zip()

• upload_source_artifacts()