awslambda.PythonFunction

Hook Path: runway.cfngin.hooks.awslambda.PythonFunction

This hook creates deployment packages for Python Lambda Functions, uploads them to S3, and returns data about the deployment package.

The return value can be retrieved using the hook_data or by interacting with the CfnginContext object passed to the Blueprint.

To use this hook to install dependencies, it must be able to find project metadata files. This can include Pipefile & Pipfile.lock files (pipenv), a pyproject.toml & poetry.lock files (poetry), or a requirements.txt file (pip). The project metadata files can exist either in the source code directory (value of source_code arg) or in the same directory as the CFNgin configuration file. If metadata files are not found, dependencies will not be included in the deployment package.

This hook will always use Docker to install/compile dependencies unless explicitly configured not to. It is recommended to always use Docker to ensure a clean and consistent build. It also ensures that binary files built during the install process are compatible with AWS Lambda.

New in version 2.5.0.

Table of Contents

Args
Return Value
Example

Args 

Arguments that can be passed to the hook in the args field.

Note

Documentation for each field is automatically generated from class attributes in the source code. When specifying the field, exclude the class name.

PythonHookArgs.bucket_name: str: Name of the S3 Bucket where deployment package is/will be stored. The Bucket must be in the same region the Lambda Function is being deployed in.

PythonHookArgs.cache_dir: Optional[pathlib.Path]

Explicitly define the directory location. Must be an absolute path or it will be relative to the CFNgin module directory.

If not provided, the cache directory is .runway/awslambda/pip_cache within the current working directory.

PythonHookArgs.docker: runway.cfngin.hooks.awslambda.models.args.DockerOptions

Docker options.

DockerOptions.disabled: bool

Explicitly disable the use of docker (default False).

If not disabled and Docker is unreachable, the hook will result in an error.

Example

args:
  docker:
    disabled: true

DockerOptions.extra_files: List[str]

List of absolute file paths within the Docker container to copy into the deployment package.

Some Python packages require extra OS libraries (*.so) files at runtime. These files need to be included in the deployment package for the Lambda Function to run. List the files here and the hook will handle copying them into the deployment package.

The file name may end in a wildcard (*) to accommodate .so files that end in an variable number (see example below).

If the file does not exist, it will result in an error.

Example

args:
  docker:
    extra_files:
      - /usr/lib64/mysql/libmysqlclient.so.*
      - /usr/lib64/libxmlsec1-openssl.so

DockerOptions.file: Optional[pathlib.Path]

Dockerfile to use to build an image for use in this process.

This, image , or runtime must be provided. If not provided, image will be used.

Example

args:
  docker:
    file: Dockerfile

DockerOptions.image: Optional[str]

Docker image to use. If the image does not exist locally, it will be pulled.

This, file (takes precedence), or runtime must be provided. If only runtime is provided, it will be used to determine the appropriate image to use.

Example

args:
  docker:
    image: public.ecr.aws/sam/build-python3.9:latest

DockerOptions.name: Optional[str]

When providing a Dockerfile, this will be the name applied to the resulting image. It is the equivalent to name in the name:tag syntax of the docker build [--tag, -t] command option.

If not provided, a default image name is used.

This field is ignore unless file is provided.

Example

args:
  docker:
    file: Dockerfile
    name: ${namespace}.runway.awslambda

DockerOptions.pull: bool

Always download updates to the specified image before use. When building an image, the FROM image will be updated during the build process (default True).

Example

args:
  docker:
    pull: false

PythonHookArgs.extend_gitignore: List[str]

gitignore rules that should be added to the rules already defined in a .gitignore file in the source code directory. This can be used with or without an existing file. Files that match a gitignore rule will not be included in the deployment package.

.git/ & .gitignore will always be added.

Important

This only applies to files in the source_code directory.

Example

args:
  extend_gitignore:
    - cfngin.yml
    - poetry.lock
    - poetry.toml
    - pyproject.toml

PythonHookArgs.extend_pip_args: Optional[List[str]]

Additional arguments that should be passed to pip install.

Important

When providing this field, be careful not to duplicate any of the arguments passed by this hook (e.g. --requirements, --target, --no-input). Providing duplicate arguments will result in an error.

Example

args:
  extend_pip_args:
    - '--proxy'
    - '[user:passwd@]proxy.server:port'

PythonHookArgs.object_prefix: Optional[str]

Prefix to add to the S3 Object key.

The object will always be prefixed with awslambda/functions. If provided, the value will be added to the end of the static prefix (e.g. awslambda/<functions|layers>/<object_prefix>/<file name>).

PythonHookArgs.runtime: Optional[str]

Runtime of the Lambda Function (https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html).

This, docker.file, or docker.image must be provided. If docker.disabled, this field is required.

When provided, the runtime available on the build system (Docker container or localhost) will be checked against this value. If they do not match, an error will be raised.

If the defined or detected runtime ever changes so that it no longer matches the deployment package in S3, the deployment package in S3 will be deleted and a new one will be built and uploaded.

PythonHookArgs.slim: bool

Automatically remove information and caches from dependencies (default True). This is done by applying the following gitignore rules to the dependencies:

**/*.dist-info*
**/*.py[c|d|i|o]
**/*.so
**/__pycache__*

PythonHookArgs.source_code: pathlib.Path

Path to the Lambda Function source code.

Example

args:
  source_code: ./my/package

PythonHookArgs.strip: bool

Whether or not to strip binary files from the dependencies (default True). This only takes effect if slim: true.

If false, the gitignore rule **/*.so is not used.

PythonHookArgs.use_cache: bool: Whether to use a cache directory with pip that will persist builds (default True).

PythonHookArgs.use_pipenv: bool: Whether pipenv should be used if determined appropriate.

PythonHookArgs.use_poetry: bool: Whether poetry should be used if determined appropriate.

Return Value 

class runway.cfngin.hooks.awslambda.models.responses.AwsLambdaHookDeployResponse[source]

Data model for AwsLambdaHook deploy response.

When returned by the hook as hook_data, this model is dumped to a standard Dict using the field’s aliases as the key in place of the attribute names. This is done so that the key is a direct match to a CloudFormation Property where the value should be used.

bucket_name: str: Name of the S3 Bucket where the deployment package is located. (alias S3Bucket)

code_sha256: str: SHA256 of the deployment package. This can be used by CloudFormation as the value of AWS::Lambda::Version.CodeSha256. (alias CodeSha256)

compatible_architectures: Optional[List[str]]: A list of compatible instruction set architectures. (https://docs.aws.amazon.com/lambda/latest/dg/foundation-arch.html) (alias CompatibleArchitectures)

compatible_runtimes: Optional[List[str]]: A list of compatible function runtimes. Used for filtering with ListLayers and ListLayerVersions. (alias CompatibleRuntimes)

license: Optional[str]

The layer’s software license (alias License). Can be any of the following:

A SPDX license identifier (e.g. MIT).
The URL of a license hosted on the internet (e.g. https://opensource.org/licenses/MIT).
The full text of the license.

object_key: str: Key (file path) of the deployment package S3 Object. (alias S3Key)

object_version_id: Optional[str]: The version ID of the deployment package S3 Object. This will only have a value if the S3 Bucket has versioning enabled. (alias S3ObjectVersion)

runtime: str: Runtime of the Lambda Function. (alias Runtime)

Example 

Dockerfile

FROM public.ecr.aws/sam/build-python3.9:latest

RUN yum install libxml2-devel xmlsec1-devel xmlsec1-openssl-devel libtool-ltdl-devel -y

cfngin.yml

namespace: ${namespace}
cfngin_bucket: ${cfngin_bucket}
src_path: ./

pre_deploy:
  - path: runway.cfngin.hooks.awslambda.PythonFunction
    data_key: awslambda.example-function-no-docker
    args:
      bucket_name: ${bucket_name}
      docker:
        disabled: true
      extend_gitignore:
        - "*.lock"
        - '*.md'
        - '*.toml'
        - tests/
      extend_pip_args:
        - '--proxy'
        - '[user:passwd@]proxy.server:port'
      runtime: python3.9
      slim: false
      source_code: ./src/example-function
  - path: runway.cfngin.hooks.awslambda.PythonFunction
    data_key: awslambda.example-function
    args:
      bucket_name: ${bucket_name}
      # docker:  # example of default & inferred values
      #   disabled: false  # default value
      #   image: public.ecr.aws/sam/build-python3.9:latest  # inferred from runtime
      #   pull: true  # default value
      extend_gitignore:
        - "*.lock"
        - '*.md'
        - '*.toml'
        - tests/
      extend_pip_args:
        - '--proxy'
        - '[user:passwd@]proxy.server:port'
      runtime: python3.9
      source_code: ./src/example-function
  - path: runway.cfngin.hooks.awslambda.PythonFunction
    data_key: awslambda.xmlsec
    args:
      bucket_name: ${bucket_name}
      docker:
        extra_files:
          - /usr/lib64/libltdl.so.*
          - /usr/lib64/libxml2.so.*
          - /usr/lib64/libxmlsec1-openssl.so
          - /usr/lib64/libxmlsec1.so.*
          - /usr/lib64/libxslt.so.*
        file: ./Dockerfile
        pull: false
      extend_gitignore:
        - "*.lock"
        - '*.md'
        - '*.toml'
        - tests/
      source_code: ./src/xmlsec-function
      strip: false

stacks:
  - name: example-stack
    class_path: blueprints.ExampleBlueprint
    parameters:
      XmlCodeSha256: ${awslambda.CodeSha256 awslambda.xmlsec}
      XmlRuntime: ${awslambda.Runtime awslambda.xmlsec}
      XmlS3Bucket: ${awslambda.S3Bucket awslambda.xmlsec}
      XmlS3Key: ${awslambda.S3Key awslambda.xmlsec}
  ...

awslambda.PythonFunction

Args

Return Value

Example

Args 

Return Value 

Example 