Application setup

AWS Lambdas require a handler that receives the events that are sent to them. Events can (among other) come from Http requests, or SQS queues, or can be manually triggered by you.

What is important is for the handler to know how to process and responde to the specific event that it received.

Configure your application

In order to make you application compatible with PythonDeploy, you need to:

  • Add pd_aws_lambda as a dependency

    # If you se Poetry
    poetry add pd_aws_lambda

  • Specify the following environment variables in you PythonDeploy application's dashboard:


You only need to specify the ones that your application needs. For example, if you are not using SQS queues then PD_SQS_HANDLER is not needed, or if you are only dealing with SQS events, then PD_WSGI_APPLICATION is not needed.

Set up environment variables


    This should be the python path to you WSGI application. For Flask projects it usually is For Django projects it will look like your_project.wsgi.application.


    If you are implementing background jobs with SQS, then all your SQS events will be passed to the method that you specify here. It will receive the Lambda event and context just as AWS provides them (example message).


    If you want a catch-all handler you can specify it with PD_DEFAULT_HANDLER. This needs to be the python path to your handler.

Publishing your app

Once you have added the environment variables in you dashboard, and you have added pd_aws_lambda as a dependency to your app, all that is left is to push your applications code. Checkout our deployments and CI/CD workflows guides.

Handler selection

The order in which handlers are selected is the following:

  1. Handler specified by handler_path in the event data.
  2. pd_aws_lambda.handlers.wsgi.handler if PD_WSGI_APPLICATION is specified and it is an event triggered by an Http request.
  3. PD_SQS_HANDLER if specified and it is an event triggered by an SQS message.
  4. PD_DEFAULT_HANDLER if specified and not handled by the previous handlers.
  5. pd_aws_lambda.handlers.wsgi.logger_handler as a catch-all handler.

Example handlers

The following is an example of a handler for SQS triggered events. It prints a json encoded message.

# file:
# PD_SQS_HANDLER=sqs_handler.my_sqs_handler
import json

def my_sqs_handler(event, context):
    """Read, json decode, and print the body of each record."""
    for record in event['Records']:
        # Lets assume that you sent a json encoded message.
        body = json.loads(record["body"])

A more elaborated handler can read the message, and then delegate for processing to a different function/actor specified in it:

# file:
# PD_SQS_HANDLER=sqs_handler.my_sqs_dispatcher
import importlib
import json

def my_sqs_dispatcher(event, context):
    """Read, json decode, and pass the message to an actor."""
    for record in event['Records']:
        # Lets assume that you sent a json encoded message.
        body = json.loads(record["body"])

        # `actor` can be `my_project.actors.my_actor`,
        # where `my_actor` is a function.
        actor_path = body.pop("actor")
        module, function = actor_path.rsplit(".", 1)
        app_module = importlib.import_module(module)
        actor = getattr(app_module, function)

        # Pass the message to the actor for processing.

Something missing? → [email protected]