Define Lambda function handler in Python (original) (raw)

The Lambda function handler is the method in your function code that processes events. When your function is invoked, Lambda runs the handler method. Your function runs until the handler returns a response, exits, or times out.

This page describes how to work with Lambda function handlers in Python, including naming conventions, valid handler signatures, and code best practices. This page also includes an example of a Python Lambda function that takes in information about an order, produces a text file receipt, and puts this file in an Amazon Simple Storage Service (Amazon S3) bucket.

Topics

Example Python Lambda function code

The following example Python Lambda function code takes in information about an order, produces a text file receipt, and puts this file in an Amazon S3 bucket:

Example Python Lambda function
import json
import os
import logging
import boto3

# Initialize the S3 client outside of the handler
s3_client = boto3.client('s3')

# Initialize the logger
logger = logging.getLogger()
logger.setLevel("INFO")

def upload_receipt_to_s3(bucket_name, key, receipt_content):
    """Helper function to upload receipt to S3"""
    
    try:
        s3_client.put_object(
            Bucket=bucket_name,
            Key=key,
            Body=receipt_content
        )
    except Exception as e:
        logger.error(f"Failed to upload receipt to S3: {str(e)}")
        raise

def lambda_handler(event, context):
    """
    Main Lambda handler function
    Parameters:
        event: Dict containing the Lambda function event data
        context: Lambda runtime context
    Returns:
        Dict containing status message
    """
    try:
        # Parse the input event
        order_id = event['Order_id']
        amount = event['Amount']
        item = event['Item']
        
        # Access environment variables
        bucket_name = os.environ.get('RECEIPT_BUCKET')
        if not bucket_name:
            raise ValueError("Missing required environment variable RECEIPT_BUCKET")

        # Create the receipt content and key destination
        receipt_content = (
            f"OrderID: {order_id}\n"
            f"Amount: ${amount}\n"
            f"Item: {item}"
        )
        key = f"receipts/{order_id}.txt"

        # Upload the receipt to S3
        upload_receipt_to_s3(bucket_name, key, receipt_content)

        logger.info(f"Successfully processed order {order_id} and stored receipt in S3 bucket {bucket_name}")
        
        return {
            "statusCode": 200,
            "message": "Receipt processed successfully"
        }

    except Exception as e:
        logger.error(f"Error processing order: {str(e)}")
        raise

This file contains the following sections of code:

Handler naming conventions

The function handler name defined at the time that you create a Lambda function is derived from:

In the example above, if the file is named lambda_function.py, the handler would be specified as lambda_function.lambda_handler. This is the default handler name given to functions you create using the Lambda console.

If you create a function in the console using a different file name or function handler name, you must edit the default handler name.

To change the function handler name (console)
  1. Open the Functions page of the Lambda console and choose your function.
  2. Choose the Code tab.
  3. Scroll down to the Runtime settings pane and choose Edit.
  4. In Handler, enter the new name for your function handler.
  5. Choose Save.

Using the Lambda event object

When Lambda invokes your function, it passes an event object argument to the function handler. JSON objects are the most common event format for Lambda functions. In the code example in the previous section, the function expects an input in the following format:

{
    "Order_id": "12345",
    "Amount": 199.99,
    "Item": "Wireless Headphones"
}

If your function is invoked by another AWS service, the input event is also a JSON object. The exact format of the event object depends on the service that's invoking your function. To see the event format for a particular service, refer to the appropriate page in the Invoking Lambda with events from other AWS services chapter.

If the input event is in the form of a JSON object, the Lambda runtime converts the object to a Python dictionary. To assign values in the input JSON to variables in your code, use the standard Python dictionary methods as illustrated in the example code.

You can also pass data into your function as a JSON array, or as any of the other valid JSON data types. The following table defines how the Python runtime converts these JSON types.

JSON data type Python data type
object dictionary (dict)
array list (list)
number integer (int) or floating point number (float)
string string (str)
Boolean Boolean (bool)
null NoneType (NoneType)

Accessing and using the Lambda context object

The Lambda context object contains information about the function invocation and execution environment. Lambda passes the context object to your function automatically when it's invoked. You can use the context object to output information about your function's invocation for monitoring purposes.

The context object is a Python class that's defined in the Lambda runtime interface client. To return the value of any of the context object properties, use the corresponding method on the context object. For example, the following code snippet assigns the value of the aws_request_id property (the identifier for the invocation request) to a variable named request. 

request = context.aws_request_id

To learn more about using the Lambda context object, and to see a complete list of the available methods and properties, see Using the Lambda context object to retrieve Python function information.

Valid handler signatures for Python handlers

When defining your handler function in Python, the function must take two arguments. The first of these arguments is the Lambda event object and the second one is the Lambda context object. By convention, these input arguments are usually named event and context, but you can give them any names you wish. If you declare your handler function with a single input argument, Lambda will raise an error when it attempts to run your function. The most common way to declare a handler function in Python is as follows:

def lambda_handler(event, context):

You can also use Python type hints in your function declaration, as shown in the following example:

from typing import Dict, Any
      
def lambda_handler(event: Dict[str, Any], context: Any) -> Dict[str, Any]:

To use specific AWS typing for events generated by other AWS services and for the context object, add the aws-lambda-typing package to your function's deployment package. You can install this library in your development environment by running `pip install aws-lambda-typing`. The following code snippet shows how to use AWS-specific type hints. In this example, the expected event is an Amazon S3 event.

from aws_lambda_typing.events import S3Event
from aws_lambda_typing.context import Context
from typing import Dict, Any

def lambda_handler(event: S3Event, context: Context) -> Dict[str, Any]:

You can't use the Python async function type for your handler function.

Returning a value

Optionally, a handler can return a value, which must be JSON serializable. Common return types include dict, list, str, int, float, and bool.

What happens to the returned value depends on the invocation type and the service that invoked the function. For example:

In the example code, the handler returns the following Python dictionary:

{
  "statusCode": 200,
  "message": "Receipt processed successfully"
}

The Lambda runtime serializes this dictionary and returns it to the client that invoked the function as a JSON string.

Note

In Python 3.9 and later releases, Lambda includes the requestId of the invocation in the error response.

Using the AWS SDK for Python (Boto3) in your handler

Often, you'll use Lambda functions to interact with other AWS services and resources. The simplest way to interface with these resources is to use the AWS SDK for Python (Boto3). All supported Lambda Python runtimes include a version of the SDK for Python. However, we strongly recommend that you include the SDK in your function's deployment package if your code needs to use it. Including the SDK in your deployment package gives you full control over your dependencies and reduces the risk of version misalignment issues with other libraries. See Runtime dependencies in Python and Backward compatibility to learn more.

To use the SDK for Python in your Lambda function, add the following statement to the import block at the beginning of your function code:

import boto3

Use the pip install command to add the boto3 library to your function's deployment package. For detailed instructions on how to add dependencies to a .zip deployment package, see Creating a .zip deployment package with dependencies. To learn more about adding dependencies to Lambda functions deployed as container images, see Creating an image from a base image or Creating an image from an alternative base image.

When using boto3 in your code, you don't need to provide any credentials to initialize a client. For example, in the example code, we use the following line of code to initialize an Amazon S3 client:

# Initialize the S3 client outside of the handler
s3_client = boto3.client('s3')

With Python, Lambda automatically creates environment variables with credentials. The boto3 SDK checks your function's environment variables for these credentials during initialization.

Accessing environment variables

In your handler code, you can reference environment variables by using the os.environ.get method. In the example code, we reference the defined RECEIPT_BUCKET environment variable using the following line of code:

# Access environment variables
bucket_name = os.environ.get('RECEIPT_BUCKET')

Don't forget to include an import os statement in the import block at the beginning of your code.

Code best practices for Python Lambda functions

Adhere to the guidelines in the following list to use best coding practices when building your Lambda functions:

def lambda_handler(event, context):  
    foo = event['foo']  
    bar = event['bar']  
    result = my_lambda_function(foo, bar)  
def my_lambda_function(foo, bar):  
    // MyLambdaFunction logic here