AWS Lambda Builders

Warnings

• deprecated The `npm --production` flag for Node.js workflows has been deprecated. It has been replaced with `npm --omit=dev` for better exclusion of development dependencies.
  Fix: Ensure your build environment for Node.js projects uses `npm --omit=dev` instead of `npm --production`. The `aws-lambda-builders` library itself should handle this for integrated workflows, but custom Node.js build steps might need updating.
• deprecated The `bundler --without` option for Ruby workflows has been removed. This was used to exclude groups of gems.
  Fix: For Ruby projects, remove any usage of `bundler --without` in custom build scripts. The library's internal Ruby workflows should adapt to current Bundler best practices.
• gotcha The Python UV workflow, introduced in v1.62.0, is currently in beta. While it offers performance improvements, it may not be fully stable or recommended for critical production workloads without thorough testing.
  Fix: If encountering issues with Python builds, consider falling back to the default `pip` workflow by not specifying `uv` as the package manager or build tool in your configurations until the `uv` workflow is marked stable.
• breaking Python 3.12 and later runtimes return Unicode characters as part of their JSON response, unlike earlier versions which returned escaped sequences. If callers expect escaped Unicode, this is a breaking change in behavior.
  Fix: Adjust calling code to handle direct Unicode characters in JSON responses for Lambda functions deployed with Python 3.12+. If escaped Unicode is strictly required by the caller, manually escape the characters in the Lambda function's response.

Install

• pip install aws-lambda-builders Install with pip

Imports

• LambdaBuilder

  from aws_lambda_builders.builder import LambdaBuilder

  This is the primary class for programmatically initiating a Lambda build process.
• PythonPipWorkflow

  from aws_lambda_builders.workflows.python_pip.workflow import PythonPipWorkflow

  Import a specific workflow class if you're directly invoking a workflow, though LambdaBuilder typically abstracts this.
• BuildError

  from aws_lambda_builders.exceptions import BuildError

  Common exception for handling build failures.

Quickstart

This example demonstrates how to programmatically use `aws-lambda-builders` to package a simple Python Lambda function with a dependency. It creates a dummy source directory, defines build parameters like runtime and output directories, then invokes the `LambdaBuilder` to create the deployment package. The output will be a zip-ready artifact in the specified `artifacts_dir`.

import os
from aws_lambda_builders.builder import LambdaBuilder
from aws_lambda_builders.exceptions import BuildError

# Create a dummy source directory with a requirements.txt and app.py
# In a real scenario, this would be your Lambda function's source code.
source_dir = './my_lambda_app_source'
artifacts_dir = './my_lambda_app_build'

os.makedirs(source_dir, exist_ok=True)
os.makedirs(artifacts_dir, exist_ok=True)

with open(os.path.join(source_dir, 'requirements.txt'), 'w') as f:
    f.write('requests==2.28.1\n')

with open(os.path.join(source_dir, 'app.py'), 'w') as f:
    f.write('import requests\n\ndef handler(event, context):\n    response = requests.get("https://api.github.com")\n    return {\n        "statusCode": 200,\n        "body": f"Hello from Lambda! GitHub status: {response.status_code}"\n    }\n')

# Define build parameters
# runtime: The target AWS Lambda runtime (e.g., 'python3.9', 'nodejs18.x')
# build_options: Specific options for the workflow (e.g., 'uv' for Python)
build_parameters = {
    "source_dir": source_dir,
    "artifacts_dir": artifacts_dir,
    "scratch_dir": './.aws-lambda-builders-scratch',
    "runtime": 'python3.9',
    "architecture": 'x86_64',
    "optimizations": {},
    "options": {
        "artifact_executable_name": "app.py", # Entry point for Python
        "handler": "app.handler"
    }
}

try:
    print("Starting Lambda build...")
    # Initialize the LambdaBuilder
    builder = LambdaBuilder(
        lambda_builders_version='1.0.0', # Placeholder for internal tracking
        **build_parameters
    )

    # Execute the build
    builder.build()

    print(f"Lambda function successfully built to: {artifacts_dir}")
    print(f"Contents: {os.listdir(artifacts_dir)}")
    # Clean up dummy files
    os.remove(os.path.join(source_dir, 'requirements.txt'))
    os.remove(os.path.join(source_dir, 'app.py'))
    os.rmdir(source_dir)
    os.rmdir(build_parameters['scratch_dir'])
    os.rmdir(artifacts_dir)
except BuildError as e:
    print(f"Build failed: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")