Lambda function handler in Python

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.

You can use the following general syntax when creating a function handler in Python:

def handler_name(event, context): 
    ...
    return some_value

Naming

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

• The name of the file in which the Lambda handler function is located.

• The name of the Python handler function.

A function handler can be any name; however, the default name in the Lambda console is lambda_function.lambda_handler. This function handler name reflects the function name (lambda_handler) and the file where the handler code is stored (lambda_function.py).

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.

How it works

When Lambda invokes your function handler, the Lambda runtime passes two arguments to the function handler:

• The first argument is the event object. An event is a JSON-formatted document that contains data for a Lambda function to process. The Lambda runtime converts the event to an object and passes it to your function code. It is usually of the Python dict type. It can also be list, str, int, float, or the NoneType type.

  The event object contains information from the invoking service. When you invoke a function, you determine the structure and contents of the event. When an AWS service invokes your function, the service defines the event structure. For more information about events from AWS services, see Using AWS Lambda with other services.

• The second argument is the context object. A context object is passed to your function by Lambda at runtime. This object provides methods and properties that provide information about the invocation, function, and runtime environment.

Returning a value

Optionally, a handler can return a value. What happens to the returned value depends on the invocation type and the service that invoked the function. For example:

• If you use the RequestResponse invocation type, such as Synchronous invocation, AWS Lambda returns the result of the Python function call to the client invoking the Lambda function (in the HTTP response to the invocation request, serialized into JSON). For example, AWS Lambda console uses the RequestResponse invocation type, so when you invoke the function on the console, the console will display the returned value.

• If the handler returns objects that can't be serialized by json.dumps, the runtime returns an error.

• If the handler returns None, as Python functions without a return statement implicitly do, the runtime returns null.

• If you use the Event invocation type (an asynchronous invocation), the value is discarded.

Note

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

Examples

The following section shows examples of Python functions you can use with Lambda. If you use the Lambda console to author your function, you do not need to attach a .zip archive file to run the functions in this section. These functions use standard Python libraries which are included with the Lambda runtime you selected. For more information, see Lambda deployment packages.

Returning a message

The following example shows a function called lambda_handler. The function accepts user input of a first and last name, and returns a message that contains data from the event it received as input.

def lambda_handler(event, context):
    message = 'Hello {} {}!'.format(event['first_name'], event['last_name'])  
    return { 
        'message' : message
    }

You can use the following event data to invoke the function:

{
    "first_name": "John",
    "last_name": "Smith"
}

The response shows the event data passed as input:

{
    "message": "Hello John Smith!"
}

Parsing a response

The following example shows a function called lambda_handler. The function uses event data passed by Lambda at runtime. It parses the environment variable in AWS_REGION returned in the JSON response.

import os
import json
        
def lambda_handler(event, context):
    json_region = os.environ['AWS_REGION']
    return {
        "statusCode": 200,
        "headers": {
            "Content-Type": "application/json"
        },
        "body": json.dumps({
            "Region ": json_region
        })
    }

You can use any event data to invoke the function:

{
  "key1": "value1",
  "key2": "value2",
  "key3": "value3"
}

Lambda runtimes set several environment variables during initialization. For more information on the environment variables returned in the response at runtime, see Using Lambda environment variables.

The function in this example depends on a successful response (in 200) from the Invoke API. For more information on the Invoke API status, see the Invoke Response Syntax.

Returning a calculation

The following example shows a function called lambda_handler. The function accepts user input and returns a calculation to the user. For more information about this example, see the aws-doc-sdk-examples GitHub repository.

import logging

logger = logging.getLogger()
logger.setLevel(logging.INFO)

def lambda_handler(event, context):
    ...
    result = None
    action = event.get('action')
    if action == 'increment':
        result = event.get('number', 0) + 1
        logger.info('Calculated result of %s', result)
    else:
        logger.error("%s is not a valid action.", action)

    response = {'result': result}
    return response

You can use the following event data to invoke the function:

{
    "action": "increment",
    "number": 3
}