Relative Python imports in a Dockerized lambda function

Relative Python imports can be tricky for lambda functions. I wrote a blog on this 3 years ago. But recently, I ran into the same issue with Dockerized lambda functions. So, I figured it was time for a new blog!

You can follow along with the steps or look at the result directly on GitHub.

Project setup

Make sure you installed the AWS CDK cli.

brew install aws-cdk

Initialize the project:

cdk init app --language=typescript

Lambda setup

First we will need to create the file and folder structure:

mkdir -p lib/functions/hello-world/hello_world
touch lib/functions/hello-world/hello_world/__init__.py
touch lib/functions/hello-world/requirements.txt
touch lib/functions/hello-world/Dockerfile

Now you will need to fill the Dockerfile, like this:

FROM public.ecr.aws/lambda/python:3.12
COPY requirements.txt .
COPY hello_world ${LAMBDA_TASK_ROOT}/hello_world
RUN pip install --no-cache-dir -r requirements.txt
CMD ["hello_world.handler"]

We are using a Python base image that is based on Python 3.12. Next, we will copy in the requirements.txt file and the source code. We will install all dependencies listed in the requirements.txt file and make sure that the handler method is set as the CMD.

Next, we will need to fill our Python files with some code. In the __init__.py file, you can place the following content:

from typing import Dict, Any


def handler(event: Dict[str, Any], context: Any) -> Dict[str, str]:
    name = event.get("name", "World")

    return {
        "Name": name,
        "Message": f"Hello {name}!",
    }


__all__ = [
    "handler"
]

NOTE: The code used here could use relative imports. This is possible because it is in a separate package. This example only shows the code in the __init__.py file. However, you can use multiple files here to improve the maintainability of your project.

For this example, I don't need any dependencies, so we can keep the requirements.txt file empty. I included it in this example to illustrate how you can include dependencies as well.

Create the Lambda function using IaC

Our folders and files are in place, so it is time to add the Lambda function to the CDK construct. You can simply add it like this:

    new lambda.Function(this, 'Function', {
      functionName: "hello-world",
      code: lambda.Code.fromAssetImage("lib/functions/hello-world", {
        platform: ecr_assets.Platform.LINUX_ARM64,
      }),
      runtime: lambda.Runtime.FROM_IMAGE,
      handler: lambda.Handler.FROM_IMAGE,
      architecture: lambda.Architecture.ARM_64,
      timeout: cdk.Duration.seconds(15),
      memorySize: 128,
    });

For this to work, you also need the following imports:

import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as ecr_assets from 'aws-cdk-lib/aws-ecr-assets';

Note that we make sure that the code directory points to the directory that contains the Dockerfile and that we select the ARM platform for both the code and the function itself.

Testing the lambda function locally

Fast feedback is important, so there might be cases where you need to run the container locally. For this, you first need to build the container:

docker build --platform linux/arm64 \
  -t hello-world:latest \
  -f ./lib/functions/hello-world/Dockerfile \
  ./lib/functions/hello-world

Note that this command can be executed from the project's root. Next, we need to make sure it's running before we can invoke it:

docker run --platform linux/arm64 -p 9000:8080 hello-world:latest

Afterwards, you can invoke the function as follows:

curl http://localhost:9000/2015-03-31/functions/function/invocations -d '{"name": "Joris"}'

Conclusion

Relative imports can be tricky! You need to place your code in a package. This allows you to do relative imports within your own package. This will enable cleaner code, as you can split responsibilities into multiple files, making it easier to manage and maintain.

Photo by Kaique Rocha