foundation

Common infrastructure for Lambda layer builders using the Command Pattern.

This module provides the foundational classes and utilities that support multiple build strategies (pip, poetry, uv) through a consistent command pattern architecture. The design separates public API functions from internal command classes to balance ease of use with code maintainability.

Architecture Overview:

• Public Functions: Simple API for end users

  (e.g., build_layer_artifacts_using_pip_in_local, build_layer_artifacts_using_pip_in_container)

• Command Classes: Internal implementation for better code organization and testability

• Local Builders: Direct dependency installation on the host machine

• Container Builders: Dockerized builds for AWS Lambda runtime compatibility

class aws_lambda_artifact_builder.layer.foundation.Credentials(index_name: str, index_url: str, username: str, password: str)

Private repository credentials for accessing authenticated package indexes.

Used to configure pip, poetry, and uv to authenticate with private PyPI servers or corporate package repositories during layer builds.

property normalized_index_url: str

Normalize index URL by stripping scheme and trailing slashes.

property uppercase_index_name: str

This is used for environment variable keys for poetry / uv authentication.

property pip_extra_index_url: str

Generate pip-compatible URL with embedded authentication.

Returns:

URL in format https://username:password@hostname/simple/

dump(path: Path)

Save credentials to a JSON file.

Parameters:

path – Path to the output JSON file

property additional_pip_install_args_index_url

Override default PyPI with authenticated URL with embedded credentials.

See also

https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-i

property additional_pip_install_args_extra_index_url

Override default PyPI with authenticated URL with embedded credentials.

See also

https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-extra-index-url

poetry_login() → tuple[str, str]

Configure Poetry authentication via environment variables.

Poetry uses POETRY_HTTP_BASIC_{SOURCE}_USERNAME/PASSWORD environment variables for private repository authentication, following Poetry’s documented credential configuration pattern.

See also

https://python-poetry.org/docs/repositories/#configuring-credentials

uv_login() → tuple[str, str]

Configure UV authentication via environment variables.

See also

https://docs.astral.sh/uv/reference/environment/#uv_index_url

class aws_lambda_artifact_builder.layer.foundation.LayerPathLayout(path_pyproject_toml: Path = REQ)

Local directory layout manager for Lambda layer build artifacts.

Assuming your Git repository is located at ${dir_project_root}/, we use ${dir_project_root} to represent this path. The Lambda layer-related paths are as follows:

• ${dir_project_root}

  dir_project_root(), Git repository root directory.

• ${dir_project_root}/pyproject.toml

  path_pyproject_toml, pyproject.toml file path.

• ${dir_project_root}/build/lambda/layer

  dir_build_lambda_layer(), temporary directory for building Lambda layer, cleared before each build.

• ${dir_project_root}/build/lambda/layer/layer.zip

  path_build_lambda_layer_zip(), final Lambda layer zip file path for deployment.

• ${dir_project_root}/build/lambda/layer/repo

  dir_repo(), to avoid affecting original files in the repository, we create a temporary directory here with a structure similar to dir_project_root, copying important files like pyproject.toml. If temporary virtual environments need to be built, they will also be created here.

• ${dir_project_root}/build/lambda/layer/artifacts

  dir_artifacts(), directory for storing all files to be packaged into layer.zip

• ${dir_project_root}/build/lambda/layer/artifacts/python

  dir_python(), AWS Lambda required python subdirectory.

property dir_project_root: Path

Project root directory, usually the Git repository root.

property dir_build_lambda_layer_repo_venv_site_packages: Path

The site-packages directory of the virtual environment that stores all Lambda layer dependencies. Created by poetry or uv.

get_path_in_container(path_in_local: Path) → str

Convert local filesystem path to corresponding Docker container path.

Docker containers mount the project root to /var/task, so this method translates local paths to their container equivalents for script execution.

Parameters:

path_in_local – Local filesystem path relative to project root

Returns:

Corresponding path inside Docker container

property dir_build_lambda: Path

The build directory for Lambda-related artifacts.

property dir_build_lambda_layer: Path

The build directory for Lambda layer build.

Important

This directory is cleared before each build to ensure a clean environment.

property path_build_lambda_layer_zip: Path

The output zip file path for the built Lambda layer.

property dir_repo: Path

A temporary copy of the project repository for building the layer.

property path_tmp_pyproject_toml: Path

A temporary copy of pyproject.toml for building the layer.

property path_build_lambda_layer_in_container_script_in_local: Path

Local path where the containerized build script is copied.

This script contains the build logic that will be executed inside the Docker container to install dependencies.

Important

This path has to be outside the dir_build_lambda_layer() folder, because the dir_build_lambda_layer() folder is cleared before each build_lambda_layer_***_in_local(...) function call, but this script must persist before that.

property path_build_lambda_layer_in_container_script_in_container: str

Container path where the build script can be executed.

Returns:

Path string for use in Docker run commands

property path_requirements_txt: Path

The generated requirements.txt file path.

property path_poetry_lock: Path

The original poetry.lock file path.

property path_tmp_poetry_lock: Path

A temporary copy of poetry.lock for building the layer.

property path_uv_lock: Path

The original uv.lock file path.

property path_tmp_uv_lock: Path

A temporary copy of uv.lock for building the layer.

property path_private_repository_credentials_in_local: Path

The private repository credentials file path.

Important

This path has to be outside the dir_build_lambda_layer() folder, because the dir_build_lambda_layer() folder is cleared before each build_lambda_layer_***_in_local(...) function call, but this script must persist before that.

property path_private_repository_credentials_in_container: str

The private repository credentials file path inside the container.

property dir_artifacts: Path

The directory to store all files to be included in the layer.zip.

property dir_python: Path

The AWS Lambda required python subdirectory.

Ref:

• https://docs.aws.amazon.com/lambda/latest/dg/python-layers.html

clean(skip_prompt: bool = False)

Clean existing build directory to ensure fresh installation.

Removes all artifacts from previous builds to prevent conflicts and ensure reproducible layer creation.

Parameters:

skip_prompt – If True, skip user confirmation for directory removal

mkdirs()

Create all necessary directories for the build process.

Ensures the directory structure is ready for dependency installation and layer artifact creation.

copy_file(p_src: ~pathlib.Path, p_dst: ~pathlib.Path, printer: ~typing.Callable[[str], None] = <built-in function print>)

Copy a file with logging support.

Parameters:

• p_src – Source file path

• p_dst – Destination file path

• printer – Function to handle log messages

copy_build_script(p_src: ~pathlib.Path, printer: ~typing.Callable[[str], None] = <built-in function print>)

Copy containerized build script to the project directory.

The build script contains tool-specific logic (pip/poetry/uv) that will be executed inside the Docker container.

Parameters:

• p_src – Path to the tool-specific build script

• printer – Function to handle log messages

copy_pyproject_toml(printer: ~typing.Callable[[str], None] = <built-in function print>)

Copy pyproject.toml to the isolated build directory.

Creates a clean copy for dependency resolution without affecting the original project configuration.

Parameters:

printer – Function to handle log messages

copy_poetry_lock(printer: ~typing.Callable[[str], None] = <built-in function print>)

Copy poetry.lock to the isolated build directory.

Ensures dependency versions remain consistent by using the locked dependency resolution from the original project.

Parameters:

printer – Function to handle log messages

copy_uv_lock(printer: ~typing.Callable[[str], None] = <built-in function print>)

Copy uv.lock to the isolated build directory.

Maintains reproducible builds by preserving the exact dependency versions resolved by uv.

Parameters:

printer – Function to handle log messages

get_path_manifest(tool: LayerBuildToolEnum) → Path

Get the dependency manifest file path for the specified build tool.

A dependency manifest is the “source of truth” file that contains the exact specification of all dependencies and their versions. With this manifest file, the Python layer can be rebuilt identically, ensuring reproducible builds across different environments.

Manifest Types by Tool:

• pip: requirements.txt - Lists exact package versions and hashes

• poetry: poetry.lock - Lock file with resolved dependency tree

• uv: uv.lock - Lock file with ultra-fast resolved dependencies

Parameters:

tool – The build tool enum specifying which manifest to return

Returns:

Path to the appropriate dependency manifest file

Raises:

ValueError – If an unsupported build tool is specified

class aws_lambda_artifact_builder.layer.foundation.LayerS3Layout(s3dir_lambda: S3Path)

S3 directory layout manager for Lambda layer artifacts and versioning.

This class provides a structured approach to organizing Lambda layer artifacts in S3 with proper versioning support. It manages both temporary upload locations and permanent versioned storage for requirements tracking and layer management.

Assuming s3dir_lambda is s3://bucket/path/lambda, the relevant paths are:

• ${s3dir_lambda}/layer/layer.zip

  s3path_temp_layer_zip(), Temporary upload location for layer zip file.

• ${s3dir_lambda}/layer/000001/requirements.txt

  get_s3path_layer_requirements_txt(), Versioned requirements file for layer version 1.

• ${s3dir_lambda}/layer/000002/requirements.txt

  get_s3path_layer_requirements_txt(), Versioned requirements file for layer version 2.

• ${s3dir_lambda}/layer/last-requirements.txt

  s3path_last_requirements_txt(), Requirements file from the most recently published layer version.

property s3path_temp_layer_zip: S3Path

Temporary S3 location for layer zip uploads before AWS Lambda layer publishing.

This is a staging location used during the layer publishing process. AWS Lambda reads the zip from this location and stores it internally, so we don’t need to maintain historical versions in S3.

Note

Since AWS manages layer storage internally, there’s no need to maintain historical versions of the layer zip in S3.

Returns:

S3Path to the temporary layer.zip file

get_s3dir_layer_version(layer_version: int) → S3Path

Generate S3 dir for a specific layer version’ artifacts.

Each layer version gets its own directory with zero-padded numbering to maintain proper lexicographic ordering in S3.

Parameters:

layer_version – Layer version number (e.g., 1, 2, 3…)

Returns:

S3Path object pointing to the versioned requirements.txt file (e.g., s3://bucket/path/lambda/layer/000001/)

get_s3path_layer_requirements_txt(layer_version: int) → S3Path

Generate S3 path for a specific layer version’s requirements.txt file.

Each layer version gets its own directory with zero-padded numbering to maintain proper lexicographic ordering in S3.

Parameters:

layer_version – Layer version number (e.g., 1, 2, 3…)

Returns:

S3Path object pointing to the versioned requirements.txt file (e.g., s3://bucket/path/lambda/layer/000001/requirements.txt)

get_s3path_layer_poetry_lock(layer_version: int) → S3Path

Generate S3 path for a specific layer version’s poetry.lock file.

Each layer version gets its own directory with zero-padded numbering to maintain proper lexicographic ordering in S3.

Parameters:

layer_version – Layer version number (e.g., 1, 2, 3…)

Returns:

S3Path object pointing to the versioned poetry.lock file (e.g., s3://bucket/path/lambda/layer/000001/poetry.lock)

get_s3path_layer_uv_lock(layer_version: int) → S3Path

Generate S3 path for a specific layer version’s uv.lock file.

Each layer version gets its own directory with zero-padded numbering to maintain proper lexicographic ordering in S3.

Parameters:

layer_version – Layer version number (e.g., 1, 2, 3…)

Returns:

S3Path object pointing to the versioned uv.lock file (e.g., s3://bucket/path/lambda/layer/000001/uv.lock)

property s3path_last_requirements_txt: S3Path

S3 path to the most recently published layer’s requirements.txt file.

This file serves as a reference point for dependency change detection. The build system compares the local requirements.txt with this file to determine whether a new layer version needs to be published.

Change Detection Logic: If local requirements differ from this file, a new layer version is automatically created and published.

Returns:

S3Path to the last-requirements.txt file

property s3path_last_poetry_lock: S3Path

S3 path to the most recently published layer’s poetry.lock file.

This file serves as a reference point for dependency change detection. The build system compares the local poetry.lock with this file to determine whether a new layer version needs to be published.

Change Detection Logic: If local poetry.lock differs from this file, a new layer version is automatically created and published.

Returns:

S3Path to the last-requirements.txt file

property s3path_last_uv_lock: S3Path

S3 path to the most recently published layer’s uv.lock file.

This file serves as a reference point for dependency change detection. The build system compares the local uv.lock with this file to determine whether a new layer version needs to be published.

Change Detection Logic: If local uv.lock differs from this file, a new layer version is automatically created and published.

Returns:

S3Path to the last-requirements.txt file

class aws_lambda_artifact_builder.layer.foundation.BaseLogger(verbose: bool = True, printer: Callable[[str], NoneType] = <built-in function print>)

printer(*, sep=' ', end='\n', file=None, flush=False)

Prints the values to a stream, or to sys.stdout by default.

sep

string inserted between values, default a space.

end

string appended after the last value, default a newline.

file

a file-like object (stream); defaults to the current sys.stdout.

flush

whether to forcibly flush the stream.

log(msg: str)

Log a message if verbosity is enabled.

class aws_lambda_artifact_builder.layer.foundation.LayerManifestManager(verbose: bool = True, printer: ~typing.Callable[[str], None] = <built-in function print>, path_pyproject_toml: ~pathlib.Path = REQ, s3dir_lambda: S3Path = REQ, layer_build_tool: ~aws_lambda_artifact_builder.constants.LayerBuildToolEnum = REQ, s3_client: S3Client = REQ)

Manages dependency manifest files for Lambda layers.

property path_layout: LayerPathLayout

LayerPathLayout object for managing build paths.

property s3_layout: LayerS3Layout

LayerS3Layout object for managing build paths.

property path_manifest: Path

Get the dependency manifest file path.

property manifest_md5: str

Calculate the MD5 hash of the dependency manifest file.

get_versioned_manifest(version: int) → S3Path

Get the S3 path of the dependency manifest file for a specific layer version.

This method constructs the S3 path where the dependency manifest (source of truth) is stored for a given layer version. The manifest serves as a backup that enables future change detection and layer reproducibility.

Parameters:

version – The layer version number to get the manifest path for

Returns:

S3Path pointing to the stored manifest file for the specified version