foundation

Common infrastructure for Lambda layer builders.

This module provides the foundational classes and utilities that support multiple build strategies (pip, poetry, uv) through a consistent architecture. The design separates tool-agnostic infrastructure (this module) from tool-specific logic (downstream packages like aws_lbd_art_builder_uv).

Key classes:

• Credentials - Private repository authentication

• LayerPathLayout - Local directory layout manager

• LayerS3Layout - S3 directory layout manager

• BaseLogger - Logging mixin

• LayerManifestManager - Dependency manifest management

class aws_lbd_art_builder_core.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.

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_lbd_art_builder_core.layer.foundation.LayerPathLayout(path_pyproject_toml: Path = REQ)

Local directory layout manager for Lambda layer build artifacts.

This class manages tool-agnostic directory conventions. Tool-specific paths (e.g., poetry.lock, uv.lock) are handled by downstream packages.

Assuming your Git repository is located at ${dir_project_root}/, 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.

• ${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.

Example: ${dir_project_root}

property dir_venv: Path

Example: ${dir_project_root}/.venv

property path_venv_bin_python: Path

Example: ${dir_project_root}/.venv/bin/python

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.

Example: ${dir_project_root}/build/lambda/layer/repo/.venv/lib/python3.12/site-packages

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.

Example: ${dir_project_root}/build/lambda

property dir_build_lambda_layer: Path

The build directory for Lambda layer build.

Example: ${dir_project_root}/build/lambda/layer

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.

Example: ${dir_project_root}/build/lambda/layer/layer.zip

property dir_repo: Path

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

Example: ${dir_project_root}/build/lambda/layer/repo

property path_tmp_pyproject_toml: Path

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

Example: ${dir_project_root}/build/lambda/layer/repo/pyproject.toml

property path_build_lambda_layer_in_container_script_in_local: Path

Local path where the containerized build script is copied.

Example: ${dir_project_root}/build/lambda/layer/build_lambda_layer_in_container.py

property path_build_lambda_layer_in_container_script_in_container: str

Container path where the build script can be executed.

Example: /var/task/build_lambda_layer_in_container.py

Returns:

Path string for use in Docker run commands

property path_private_repository_credentials_in_local: Path

The private repository credentials file path.

Example: ${dir_project_root}/build/lambda/layer/private-repository-credentials.json

property path_private_repository_credentials_in_container: str

The private repository credentials file path inside the container.

Example: /var/task/private-repository-credentials.json

property dir_artifacts: Path

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

Example: ${dir_project_root}/build/lambda/layer/artifacts

property dir_python: Path

The AWS Lambda required python subdirectory.

Example: ${dir_project_root}/build/lambda/layer/artifacts/python

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.

Parameters:

skip_prompt – If True, skip user confirmation for directory removal

mkdirs()

Create all necessary directories for the build process.

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.

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.

Parameters:

printer – Function to handle log messages

class aws_lbd_art_builder_core.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 manifest 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/{manifest_filename}

  get_s3path_layer_manifest(), Versioned manifest file for layer version 1.

property s3path_temp_layer_zip: S3Path

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

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’s artifacts.

Parameters:

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

Returns:

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

get_s3path_layer_manifest(layer_version: int, manifest_filename: str) → S3Path

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

This is a generic method that works with any manifest type (requirements.txt, poetry.lock, uv.lock, etc.).

Parameters:

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

• manifest_filename – The manifest filename (e.g., “requirements.txt”, “uv.lock”)

Returns:

S3Path object pointing to the versioned manifest file

class aws_lbd_art_builder_core.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.

log_header(title: str)

Log a prominent section header with a box.

log_sub_header(title: str)

Log a sub-section header with a line.

log_detail(msg: str)

Log a detail line indented under a sub-section.

class aws_lbd_art_builder_core.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, path_manifest: ~pathlib.Path = REQ, s3_client: S3Client = REQ)

Manages dependency manifest files for Lambda layers.

This is a tool-agnostic manager that accepts a direct path to the manifest file. Downstream packages pass in their tool-specific manifest path (e.g., requirements.txt for pip, uv.lock for uv, poetry.lock for poetry).

property path_layout: LayerPathLayout

LayerPathLayout object for managing build paths.

property s3_layout: LayerS3Layout

LayerS3Layout object for managing build paths.

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.

Parameters:

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

Returns:

S3Path pointing to the stored manifest file for the specified version