Request handler for a function in Python
A request handler is a method used to process each Python function call. When creating a function version, you must set up an entry point for it, i.e., a path to the request handler in <file>.<function> format, where:
<file>: Name of the file with the function code (without.py), e.g.,index. The code file must reside in the root directory. The file name must not contain any dots.<function>: Name of the callable object in<file>, e.g.,handler. When initializing the function, the runtime imports<file>and finds the callable object named<function>which runs on every function invocation.
Example of an entry point for a Python function: index.handler.
Note
At any given time, a single function instance processes only one request. This allows you to use global variables without the need to ensure data integrity control.
When calling the handler, the runtime provides the following arguments:
-
Request body (the
eventparameter):- If the request body is a JSON document, it will be converted into
dictusing thejson.loadsmethod. - If the function was invoked with the
?integration=rawquery parameter, the HTTP request body is provided to the function as is, i.e., unprocessed.
- If the request body is a JSON document, it will be converted into
-
Invocation context (the
contextparameter).The context provides all required information about the function version. The structure of this object is described in Python function invocation context.
Handler types
A function supports both synchronous and asynchronous handlers.
Synchronous handler
To return the execution result, use the return statement or raise an exception using the raise statement. A synchronous function must return a result or raise an exception.
Asynchronous handler
A handler can be an async def asynchronous function. In this case, you can use the following statements:
return: Returns the function response.raise: Reports an error to the runtime.await: Tracks the execution of asynchronous function invocations.
Note
The asyncio library is the only supported runtime for asynchronous functions.
In Python 3.14 and higher, asyncio.get_event_loop() no longer automatically creates an event loop, but results in RuntimeError. Use asyncio.get_running_loop() to manage asynchronous handlers. See this example.
For more information about the development process using async/await, see this article.
Examples
HTTP request structure output
The following function outputs the request structure and invocation context to both the execution log and function response:
import json
def handler(event, context):
return {
'statusCode': 200,
'body': json.dumps(
{
'event': event,
'context': context,
},
default=vars,
),
}
Function invocation example:
curl \
--data '{"hello": "world"}' \
--header 'Content-Type: application/json' \
https://functions.yandexcloud.net/<function_ID>?param=one
Result:
{
"context": {
"aws_request_id": "6e8356f9-489b-4c7b-8ba6-c8cd********",
"deadline_ms": 1657713543198,
"function_name": "d4eo2faf62**********",
"function_version": "d4e3vrugh3**********",
"invoked_function_arn": "d4eo2faf62**********",
"log_group_name": "ckgjmanjlh**********",
"log_stream_name": "d4e3vrugh3**********",
"memory_limit_in_mb": 128,
"request_id": "6e8356f9-489b-4c7b-8ba6-c8cd********",
"token": {
"access_token": "<IAM_token>",
"expires_in": 42299,
"token_type": "Bearer"
}
},
"event": {
"body": "{\"hello\": \"world\"}",
"headers": {
"Accept": "*/*",
"Content-Length": "18",
"Content-Type": "application/json",
"Host": "functions.yandexcloud.net",
"User-Agent": "curl/7.64.1",
"X-Forwarded-For": "109.252.148.209",
"X-Real-Remote-Address": "[109.252.148.209]:2816",
"X-Request-Id": "6e8356f9-489b-4c7b-8ba6-c8cd********",
"X-Trace-Id": "e9fe9b05-c1aa-4fb8-94d8-a514********"
},
"httpMethod": "POST",
"isBase64Encoded": false,
"multiValueHeaders": {
"Accept": [
"*/*"
],
"Content-Length": [
"18"
],
"Content-Type": [
"application/json"
],
"Host": [
"functions.yandexcloud.net"
],
"User-Agent": [
"curl/7.64.1"
],
"X-Forwarded-For": [
"109.252.148.209"
],
"X-Real-Remote-Address": [
"[109.252.148.209]:2816"
],
"X-Request-Id": [
"6e8356f9-489b-4c7b-8ba6-c8cd********"
],
"X-Trace-Id": [
"e9fe9b05-c1aa-4fb8-94d8-a514********"
]
},
"multiValueParams": {},
"multiValueQueryStringParameters": {
"param": [
"one"
]
},
"params": {},
"pathParams": {},
"queryStringParameters": {
"param": "one"
},
"requestContext": {
"httpMethod": "POST",
"identity": {
"sourceIp": "109.252.148.209",
"userAgent": "curl/7.64.1"
},
"requestId": "6e8356f9-489b-4c7b-8ba6-c8cd********",
"requestTime": "13/Jul/2022:11:58:59 +0000",
"requestTimeEpoch": 1657713539
},
"url": ""
}
}
Using an asynchronous handler in Python 3.14
The following function demonstrates how to use an asynchronous handler in Python 3.14 and higher, where explicit event loop management is required:
import asyncio
import json
def handler(event, context):
loop = asyncio.new_event_loop()
asyncio.set_event_loop(loop)
async def async_handler():
current_loop = asyncio.get_running_loop()
current_time = current_loop.time()
return {
'statusCode': 200,
'body': json.dumps({
'message': 'Async handler with explicit loop creation',
'loop_time': current_time,
'python_version': '3.14',
})
}
return loop.run_until_complete(async_handler())
Function invocation example:
curl \
--data '{"test": "asyncio"}' \
--header 'Content-Type: application/json' \
https://functions.yandexcloud.net/<function_ID>
Result:
{"message": "Async handler with explicit loop creation", "loop_time": 3.522407882, "python_version": "3.14"}