Namespace Amazon.CDK.AWS.Lambda.Python
Amazon Lambda Python Library
---AWS CDK v1 has reached End-of-Support on 2023-06-01.
This package is no longer being updated, and users should migrate to AWS CDK v2.
For more information on how to migrate, see the Migrating to AWS CDK v2 guide.
This library provides constructs for Python Lambda functions.
To use this module, you will need to have Docker installed.
Python Function
Define a PythonFunction
:
new PythonFunction(this, "MyFunction", new PythonFunctionProps {
Entry = "/path/to/my/function", // required
Runtime = Runtime.PYTHON_3_8, // required
Index = "my_index.py", // optional, defaults to 'index.py'
Handler = "my_exported_func"
});
All other properties of lambda.Function
are supported, see also the AWS Lambda construct library.
Python Layer
You may create a python-based lambda layer with PythonLayerVersion
. If PythonLayerVersion
detects a requirements.txt
or Pipfile
or poetry.lock
with the associated pyproject.toml
at the entry path, then PythonLayerVersion
will include the dependencies inline with your code in the
layer.
Define a PythonLayerVersion
:
new PythonLayerVersion(this, "MyLayer", new PythonLayerVersionProps {
Entry = "/path/to/my/layer"
});
A layer can also be used as a part of a PythonFunction
:
new PythonFunction(this, "MyFunction", new PythonFunctionProps {
Entry = "/path/to/my/function",
Runtime = Runtime.PYTHON_3_8,
Layers = new [] {
new PythonLayerVersion(this, "MyLayer", new PythonLayerVersionProps {
Entry = "/path/to/my/layer"
}) }
});
Packaging
If requirements.txt
, Pipfile
or poetry.lock
exists at the entry path, the construct will handle installing all required modules in a Lambda compatible Docker container according to the runtime
and with the Docker platform based on the target architecture of the Lambda function.
Python bundles are only recreated and published when a file in a source directory has changed. Therefore (and as a general best-practice), it is highly recommended to commit a lockfile with a list of all transitive dependencies and their exact versions. This will ensure that when any dependency version is updated, the bundle asset is recreated and uploaded.
To that end, we recommend using [pipenv
] or [poetry
] which have lockfile support.
Packaging is executed using the Packaging
class, which:
Lambda with a requirements.txt
.
├── lambda_function.py # exports a function named 'handler'
├── requirements.txt # has to be present at the entry path
Lambda with a Pipfile
.
├── lambda_function.py # exports a function named 'handler'
├── Pipfile # has to be present at the entry path
├── Pipfile.lock # your lock file
Lambda with a poetry.lock
.
├── lambda_function.py # exports a function named 'handler'
├── pyproject.toml # your poetry project definition
├── poetry.lock # your poetry lock file has to be present at the entry path
Custom Bundling
Custom bundling can be performed by passing in additional build arguments that point to index URLs to private repos, or by using an entirely custom Docker images for bundling dependencies. The build args currently supported are:
Additional build args for bundling that refer to PyPI indexes can be specified as:
var entry = "/path/to/function";
var image = DockerImage.FromBuild(entry);
new PythonFunction(this, "function", new PythonFunctionProps {
Entry = entry,
Runtime = Runtime.PYTHON_3_8,
Bundling = new BundlingOptions {
BuildArgs = new Dictionary<string, string> { { "PIP_INDEX_URL", "https://your.index.url/simple/" }, { "PIP_EXTRA_INDEX_URL", "https://your.extra-index.url/simple/" } }
}
});
If using a custom Docker image for bundling, the dependencies are installed with pip
, pipenv
or poetry
by using the Packaging
class. A different bundling Docker image that is in the same directory as the function can be specified as:
var entry = "/path/to/function";
var image = DockerImage.FromBuild(entry);
new PythonFunction(this, "function", new PythonFunctionProps {
Entry = entry,
Runtime = Runtime.PYTHON_3_8,
Bundling = new BundlingOptions { Image = image }
});
Custom Bundling with Code Artifact
To use a Code Artifact PyPI repo, the PIP_INDEX_URL
for bundling the function can be customized (requires AWS CLI in the build environment):
using Child.Process;
var entry = "/path/to/function";
var image = DockerImage.FromBuild(entry);
var domain = "my-domain";
var domainOwner = "111122223333";
var repoName = "my_repo";
var region = "us-east-1";
var codeArtifactAuthToken = ExecSync($"aws codeartifact get-authorization-token --domain {domain} --domain-owner {domainOwner} --query authorizationToken --output text").ToString().Trim();
var indexUrl = $"https://aws:{codeArtifactAuthToken}@{domain}-{domainOwner}.d.codeartifact.{region}.amazonaws.com/pypi/{repoName}/simple/";
new PythonFunction(this, "function", new PythonFunctionProps {
Entry = entry,
Runtime = Runtime.PYTHON_3_8,
Bundling = new BundlingOptions {
Environment = new Dictionary<string, string> { { "PIP_INDEX_URL", indexUrl } }
}
});
The index URL or the token are only used during bundling and thus not included in the final asset. Setting only environment variable for PIP_INDEX_URL
or PIP_EXTRA_INDEX_URL
should work for accesing private Python repositories with pip
, pipenv
and poetry
based dependencies.
If you also want to use the Code Artifact repo for building the base Docker image for bundling, use buildArgs
. However, note that setting custom build args for bundling will force the base bundling image to be rebuilt every time (i.e. skip the Docker cache). Build args can be customized as:
using Child.Process;
var entry = "/path/to/function";
var image = DockerImage.FromBuild(entry);
var domain = "my-domain";
var domainOwner = "111122223333";
var repoName = "my_repo";
var region = "us-east-1";
var codeArtifactAuthToken = ExecSync($"aws codeartifact get-authorization-token --domain {domain} --domain-owner {domainOwner} --query authorizationToken --output text").ToString().Trim();
var indexUrl = $"https://aws:{codeArtifactAuthToken}@{domain}-{domainOwner}.d.codeartifact.{region}.amazonaws.com/pypi/{repoName}/simple/";
new PythonFunction(this, "function", new PythonFunctionProps {
Entry = entry,
Runtime = Runtime.PYTHON_3_8,
Bundling = new BundlingOptions {
BuildArgs = new Dictionary<string, string> { { "PIP_INDEX_URL", indexUrl } }
}
});
Classes
BundlingOptions | (experimental) Options for bundling. |
PythonFunction | (experimental) A Python Lambda function. |
PythonFunctionProps | (experimental) Properties for a PythonFunction. |
PythonLayerVersion | (experimental) A lambda layer version. |
PythonLayerVersionProps | (experimental) Properties for PythonLayerVersion. |
Interfaces
IBundlingOptions | (experimental) Options for bundling. |
IPythonFunctionProps | (experimental) Properties for a PythonFunction. |
IPythonLayerVersionProps | (experimental) Properties for PythonLayerVersion. |