Event Source Data Classes

Base class for Event Source Data Classes

Usage Documentation

Data classes

CLASS	DESCRIPTION
`APIGatewayEventIdentity`
`BaseProxyEvent`
`BaseRequestContext`
`BaseRequestContextV2`
`CaseInsensitiveDict`	Case insensitive dict implementation. Assumes string keys only.
`DictWrapper`	Provides a single read only access to a wrapper dict
`RequestContextClientCert`
`RequestContextV2Http`

APIGatewayEventIdentity ¶

APIGatewayEventIdentity(data: dict[str, Any], json_deserializer: Callable | None = None)

Bases: DictWrapper

ATTRIBUTE	DESCRIPTION
`account_id`	The AWS account ID associated with the request. TYPE: `str \| None`
`api_key`	For API methods that require an API key, this variable is the API key associated with the method request. TYPE: `str \| None`
`api_key_id`	The API key ID associated with an API request that requires an API key. TYPE: `str \| None`
`caller`	The principal identifier of the caller making the request. TYPE: `str \| None`
`cognito_authentication_provider`	A comma-separated list of the Amazon Cognito authentication providers used by the caller TYPE: `str \| None`
`cognito_authentication_type`	The Amazon Cognito authentication type of the caller making the request. TYPE: `str \| None`
`cognito_identity_id`	The Amazon Cognito identity ID of the caller making the request. TYPE: `str \| None`
`cognito_identity_pool_id`	The Amazon Cognito identity pool ID of the caller making the request. TYPE: `str \| None`
`principal_org_id`	The AWS organization ID. TYPE: `str \| None`
`source_ip`	The source IP address of the TCP connection making the request to API Gateway. TYPE: `str`
`user`	The principal identifier of the user making the request. TYPE: `str \| None`
`user_agent`	The User Agent of the API caller. TYPE: `str \| None`
`user_arn`	The Amazon Resource Name (ARN) of the effective user identified after authentication. TYPE: `str \| None`

Source code in aws_lambda_powertools/utilities/data_classes/common.py

def __init__(self, data: dict[str, Any], json_deserializer: Callable | None = None):
    """
    Parameters
    ----------
    data : dict[str, Any]
        Lambda Event Source Event payload
    json_deserializer : Callable, optional
        function to deserialize `str`, `bytes`, `bytearray` containing a JSON document to a Python `obj`,
        by default json.loads
    """
    self._data = data
    self._json_deserializer = json_deserializer or json.loads

account_id `property` ¶

account_id: str | None

The AWS account ID associated with the request.

api_key `property` ¶

api_key: str | None

For API methods that require an API key, this variable is the API key associated with the method request. For methods that don't require an API key, this variable is null.

api_key_id `property` ¶

api_key_id: str | None

The API key ID associated with an API request that requires an API key.

caller `property` ¶

caller: str | None

The principal identifier of the caller making the request.

cognito_authentication_provider `property` ¶

cognito_authentication_provider: str | None

A comma-separated list of the Amazon Cognito authentication providers used by the caller making the request. Available only if the request was signed with Amazon Cognito credentials.

cognito_authentication_type `property` ¶

cognito_authentication_type: str | None

The Amazon Cognito authentication type of the caller making the request. Available only if the request was signed with Amazon Cognito credentials.

cognito_identity_id `property` ¶

cognito_identity_id: str | None

The Amazon Cognito identity ID of the caller making the request. Available only if the request was signed with Amazon Cognito credentials.

cognito_identity_pool_id `property` ¶

cognito_identity_pool_id: str | None

The Amazon Cognito identity pool ID of the caller making the request. Available only if the request was signed with Amazon Cognito credentials.

principal_org_id `property` ¶

principal_org_id: str | None

The AWS organization ID.

source_ip `property` ¶

source_ip: str

The source IP address of the TCP connection making the request to API Gateway.

user `property` ¶

user: str | None

The principal identifier of the user making the request.

user_agent `property` ¶

user_agent: str | None

The User Agent of the API caller.

user_arn `property` ¶

user_arn: str | None

The Amazon Resource Name (ARN) of the effective user identified after authentication.

BaseProxyEvent ¶

BaseProxyEvent(data: dict[str, Any], json_deserializer: Callable | None = None)

Bases: DictWrapper

METHOD	DESCRIPTION
`get_header_value`	Get header value by name
`get_multi_value_query_string_values`	Get multi-value query string parameter values by name
`get_query_string_value`	Get query string value by name

ATTRIBUTE	DESCRIPTION
`body`	Submitted body of the request as a string TYPE: `str \| None`
`decoded_body`	Decode the body from base64 if encoded, otherwise return it as is. TYPE: `str \| None`
`http_method`	The HTTP method used. Valid values include: DELETE, GET, HEAD, OPTIONS, PATCH, POST, and PUT. TYPE: `str`
`json_body`	Parses the submitted body as json TYPE: `Any`
`resolved_cookies_field`	This property extracts cookies from the request as a dict of name-value pairs. TYPE: `dict[str, str]`
`resolved_headers_field`	This property determines the appropriate header to be used TYPE: `dict[str, str]`
`resolved_query_string_parameters`	This property determines the appropriate query string parameter to be used TYPE: `dict[str, list[str]]`

Source code in aws_lambda_powertools/utilities/data_classes/common.py

def __init__(self, data: dict[str, Any], json_deserializer: Callable | None = None):
    """
    Parameters
    ----------
    data : dict[str, Any]
        Lambda Event Source Event payload
    json_deserializer : Callable, optional
        function to deserialize `str`, `bytes`, `bytearray` containing a JSON document to a Python `obj`,
        by default json.loads
    """
    self._data = data
    self._json_deserializer = json_deserializer or json.loads

body `property` ¶

body: str | None

Submitted body of the request as a string

decoded_body `cached` `property` ¶

decoded_body: str | None

Decode the body from base64 if encoded, otherwise return it as is.

http_method `property` ¶

http_method: str

The HTTP method used. Valid values include: DELETE, GET, HEAD, OPTIONS, PATCH, POST, and PUT.

json_body `cached` `property` ¶

json_body: Any

Parses the submitted body as json

resolved_cookies_field `property` ¶

resolved_cookies_field: dict[str, str]

This property extracts cookies from the request as a dict of name-value pairs.

By default, cookies are parsed from the Cookie header. Uses self.headers (CaseInsensitiveDict) first for reliable case-insensitive lookup, then falls back to resolved_headers_field for proxies that only populate multi-value headers (e.g., ALB without single-value headers). Subclasses may override this for event formats that provide cookies in a dedicated field (e.g., API Gateway HTTP API v2).

resolved_headers_field `property` ¶

resolved_headers_field: dict[str, str]

This property determines the appropriate header to be used as a trusted source for validating OpenAPI.

This is necessary because different resolvers use different formats to encode headers parameters.

Headers are case-insensitive according to RFC 7540 (HTTP/2), so we lower the header name This ensures that customers can access headers with any casing, as per the RFC guidelines. Reference: https://www.rfc-editor.org/rfc/rfc7540#section-8.1.2

resolved_query_string_parameters `property` ¶

resolved_query_string_parameters: dict[str, list[str]]

This property determines the appropriate query string parameter to be used as a trusted source for validating OpenAPI.

This is necessary because different resolvers use different formats to encode multi query string parameters.

get_header_value ¶

get_header_value(name: str, default_value: str, case_sensitive: bool = False) -> str

get_header_value(name: str, default_value: str | None = None, case_sensitive: bool = False) -> str | None

get_header_value(name: str, default_value: str | None = None, case_sensitive: bool = False) -> str | None

Get header value by name

PARAMETER	DESCRIPTION
`name`	Header name TYPE: `str`
`default_value`	Default value if no value was found by name TYPE: `str \| None` DEFAULT: `None`
`case_sensitive`	Whether to use a case-sensitive look up. By default we make a case-insensitive lookup. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`(str, optional)`	Header value

Source code in aws_lambda_powertools/utilities/data_classes/common.py

@deprecated(
    "`get_header_value` function is deprecated; Access headers directly using event.headers.get('HeaderName')",
    category=None,
)
def get_header_value(
    self,
    name: str,
    default_value: str | None = None,
    case_sensitive: bool = False,
) -> str | None:
    """Get header value by name
    Parameters
    ----------
    name: str
        Header name
    default_value: str, optional
        Default value if no value was found by name
    case_sensitive: bool
        Whether to use a case-sensitive look up. By default we make a case-insensitive lookup.
    Returns
    -------
    str, optional
        Header value
    """
    warnings.warn(
        "The `get_header_value` function is deprecated in V3 and the `case_sensitive` parameter "
        "no longer has any effect. This function will be removed in the next major version. "
        "Instead, access headers directly using event.headers.get('HeaderName'), which is case insensitive.",
        category=PowertoolsDeprecationWarning,
        stacklevel=2,
    )
    return get_header_value(  # ty: ignore[deprecated]
        headers=self.headers,
        name=name,
        default_value=default_value,
        case_sensitive=case_sensitive,
    )

get_multi_value_query_string_values ¶

get_multi_value_query_string_values(name: str, default_values: list[str] | None = None) -> list[str]

Get multi-value query string parameter values by name

PARAMETER	DESCRIPTION
`name`	Multi-Value query string parameter name TYPE: `str`
`default_values`	Default values is no values are found by name TYPE: `list[str] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`(List[str], optional)`	List of query string values

Source code in aws_lambda_powertools/utilities/data_classes/common.py

def get_multi_value_query_string_values(
    self,
    name: str,
    default_values: list[str] | None = None,
) -> list[str]:
    """Get multi-value query string parameter values by name
    Parameters
    ----------
    name: str
        Multi-Value query string parameter name
    default_values: List[str], optional
        Default values is no values are found by name
    Returns
    -------
    List[str], optional
        List of query string values
    """
    return get_multi_value_query_string_values(
        multi_value_query_string_parameters=self.multi_value_query_string_parameters,
        name=name,
        default_values=default_values,
    )

get_query_string_value ¶

get_query_string_value(name: str, default_value: str) -> str

get_query_string_value(name: str, default_value: str | None = None) -> str | None

get_query_string_value(name: str, default_value: str | None = None) -> str | None

Get query string value by name

PARAMETER	DESCRIPTION
`name`	Query string parameter name TYPE: `str`
`default_value`	Default value if no value was found by name TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`(str, optional)`	Query string parameter value

Source code in aws_lambda_powertools/utilities/data_classes/common.py

def get_query_string_value(self, name: str, default_value: str | None = None) -> str | None:
    """Get query string value by name
    Parameters
    ----------
    name: str
        Query string parameter name
    default_value: str, optional
        Default value if no value was found by name
    Returns
    -------
    str, optional
        Query string parameter value
    """
    return get_query_string_value(
        query_string_parameters=self.query_string_parameters,
        name=name,
        default_value=default_value,
    )

BaseRequestContext ¶

BaseRequestContext(data: dict[str, Any], json_deserializer: Callable | None = None)

Bases: DictWrapper

ATTRIBUTE	DESCRIPTION
`account_id`	The AWS account ID associated with the request. TYPE: `str`
`api_id`	The identifier API Gateway assigns to your API. TYPE: `str`
`domain_name`	A domain name TYPE: `str \| None`
`extended_request_id`	An automatically generated ID for the API call, which contains more useful information TYPE: `str \| None`
`http_method`	The HTTP method used. Valid values include: DELETE, GET, HEAD, OPTIONS, PATCH, POST, and PUT. TYPE: `str`
`protocol`	The request protocol, for example, HTTP/1.1. TYPE: `str`
`request_id`	The ID that API Gateway assigns to the API request. TYPE: `str`
`request_time`	The CLF-formatted request time (dd/MMM/yyyy:HH:mm:ss +-hhmm) TYPE: `str \| None`
`request_time_epoch`	The Epoch-formatted request time. TYPE: `int`
`stage`	The deployment stage of the API request TYPE: `str`

Source code in aws_lambda_powertools/utilities/data_classes/common.py

def __init__(self, data: dict[str, Any], json_deserializer: Callable | None = None):
    """
    Parameters
    ----------
    data : dict[str, Any]
        Lambda Event Source Event payload
    json_deserializer : Callable, optional
        function to deserialize `str`, `bytes`, `bytearray` containing a JSON document to a Python `obj`,
        by default json.loads
    """
    self._data = data
    self._json_deserializer = json_deserializer or json.loads

account_id `property` ¶

account_id: str

The AWS account ID associated with the request.

api_id `property` ¶

api_id: str

The identifier API Gateway assigns to your API.

domain_name `property` ¶

domain_name: str | None

A domain name

extended_request_id `property` ¶

extended_request_id: str | None

An automatically generated ID for the API call, which contains more useful information for debugging/troubleshooting.

http_method `property` ¶

http_method: str

The HTTP method used. Valid values include: DELETE, GET, HEAD, OPTIONS, PATCH, POST, and PUT.

protocol `property` ¶

protocol: str

The request protocol, for example, HTTP/1.1.

request_id `property` ¶

request_id: str

The ID that API Gateway assigns to the API request.

request_time `property` ¶

request_time: str | None

The CLF-formatted request time (dd/MMM/yyyy:HH:mm:ss +-hhmm)

request_time_epoch `property` ¶

request_time_epoch: int

The Epoch-formatted request time.

stage `property` ¶

stage: str

The deployment stage of the API request

BaseRequestContextV2 ¶

BaseRequestContextV2(data: dict[str, Any], json_deserializer: Callable | None = None)

Bases: DictWrapper

ATTRIBUTE	DESCRIPTION
`account_id`	The AWS account ID associated with the request. TYPE: `str`
`api_id`	The identifier API Gateway assigns to your API. TYPE: `str`
`authentication`	Optional when using mutual TLS authentication TYPE: `RequestContextClientCert \| None`
`domain_name`	A domain name TYPE: `str`
`request_id`	The ID that API Gateway assigns to the API request. TYPE: `str`
`route_key`	The selected route key. TYPE: `str`
`stage`	The deployment stage of the API request TYPE: `str`
`time`	The CLF-formatted request time (dd/MMM/yyyy:HH:mm:ss +-hhmm). TYPE: `str`
`time_epoch`	The Epoch-formatted request time. TYPE: `int`

Source code in aws_lambda_powertools/utilities/data_classes/common.py

def __init__(self, data: dict[str, Any], json_deserializer: Callable | None = None):
    """
    Parameters
    ----------
    data : dict[str, Any]
        Lambda Event Source Event payload
    json_deserializer : Callable, optional
        function to deserialize `str`, `bytes`, `bytearray` containing a JSON document to a Python `obj`,
        by default json.loads
    """
    self._data = data
    self._json_deserializer = json_deserializer or json.loads

account_id `property` ¶

account_id: str

The AWS account ID associated with the request.

api_id `property` ¶

api_id: str

The identifier API Gateway assigns to your API.

authentication `property` ¶

authentication: RequestContextClientCert | None

Optional when using mutual TLS authentication

domain_name `property` ¶

domain_name: str

A domain name

request_id `property` ¶

request_id: str

The ID that API Gateway assigns to the API request.

route_key `property` ¶

route_key: str

The selected route key.

stage `property` ¶

stage: str

The deployment stage of the API request

time `property` ¶

time: str

The CLF-formatted request time (dd/MMM/yyyy:HH:mm:ss +-hhmm).

time_epoch `property` ¶

time_epoch: int

The Epoch-formatted request time.

CaseInsensitiveDict ¶

CaseInsensitiveDict(data=None, **kwargs)

Bases: dict

Case insensitive dict implementation. Assumes string keys only.

Source code in aws_lambda_powertools/utilities/data_classes/common.py

def __init__(self, data=None, **kwargs):
    super().__init__()
    self.update(data, **kwargs)

DictWrapper ¶

DictWrapper(data: dict[str, Any], json_deserializer: Callable | None = None)

Bases: Mapping

Provides a single read only access to a wrapper dict

data : dict[str, Any] Lambda Event Source Event payload json_deserializer : Callable, optional function to deserialize str, bytes, bytearray containing a JSON document to a Python obj, by default json.loads

ATTRIBUTE	DESCRIPTION
`raw_event`	The original raw event dict TYPE: `dict[str, Any]`

Source code in aws_lambda_powertools/utilities/data_classes/common.py

def __init__(self, data: dict[str, Any], json_deserializer: Callable | None = None):
    """
    Parameters
    ----------
    data : dict[str, Any]
        Lambda Event Source Event payload
    json_deserializer : Callable, optional
        function to deserialize `str`, `bytes`, `bytearray` containing a JSON document to a Python `obj`,
        by default json.loads
    """
    self._data = data
    self._json_deserializer = json_deserializer or json.loads

raw_event `property` ¶

raw_event: dict[str, Any]

The original raw event dict

RequestContextClientCert ¶

RequestContextClientCert(data: dict[str, Any], json_deserializer: Callable | None = None)

Bases: DictWrapper

ATTRIBUTE	DESCRIPTION
`client_cert_pem`	Client certificate pem TYPE: `str`
`issuer_dn`	Issuer Distinguished Name TYPE: `str`
`serial_number`	Unique serial number for client cert TYPE: `str`
`subject_dn`	Subject Distinguished Name TYPE: `str`
`validity_not_after`	Date when the cert is no longer valid TYPE: `str`
`validity_not_before`	Cert is not valid before this date TYPE: `str`

Source code in aws_lambda_powertools/utilities/data_classes/common.py

def __init__(self, data: dict[str, Any], json_deserializer: Callable | None = None):
    """
    Parameters
    ----------
    data : dict[str, Any]
        Lambda Event Source Event payload
    json_deserializer : Callable, optional
        function to deserialize `str`, `bytes`, `bytearray` containing a JSON document to a Python `obj`,
        by default json.loads
    """
    self._data = data
    self._json_deserializer = json_deserializer or json.loads

client_cert_pem `property` ¶

client_cert_pem: str

Client certificate pem

issuer_dn `property` ¶

issuer_dn: str

Issuer Distinguished Name

serial_number `property` ¶

serial_number: str

Unique serial number for client cert

subject_dn `property` ¶

subject_dn: str

Subject Distinguished Name

validity_not_after `property` ¶

validity_not_after: str

Date when the cert is no longer valid

eg: Aug 5 00:28:21 2120 GMT

validity_not_before `property` ¶

validity_not_before: str

Cert is not valid before this date

eg: Aug 29 00:28:21 2020 GMT

RequestContextV2Http ¶

RequestContextV2Http(data: dict[str, Any], json_deserializer: Callable | None = None)

Bases: DictWrapper

ATTRIBUTE	DESCRIPTION
`protocol`	The request protocol, for example, HTTP/1.1. TYPE: `str`
`source_ip`	The source IP address of the TCP connection making the request to API Gateway. TYPE: `str`
`user_agent`	The User Agent of the API caller. TYPE: `str`

Source code in aws_lambda_powertools/utilities/data_classes/common.py

def __init__(self, data: dict[str, Any], json_deserializer: Callable | None = None):
    """
    Parameters
    ----------
    data : dict[str, Any]
        Lambda Event Source Event payload
    json_deserializer : Callable, optional
        function to deserialize `str`, `bytes`, `bytearray` containing a JSON document to a Python `obj`,
        by default json.loads
    """
    self._data = data
    self._json_deserializer = json_deserializer or json.loads

protocol `property` ¶

protocol: str

The request protocol, for example, HTTP/1.1.

source_ip `property` ¶

source_ip: str

The source IP address of the TCP connection making the request to API Gateway.

user_agent `property` ¶

user_agent: str

The User Agent of the API caller.

Event Source Data Classes

APIGatewayEventIdentity ¶

account_id property ¶

api_key property ¶

api_key_id property ¶

caller property ¶

cognito_authentication_provider property ¶

cognito_authentication_type property ¶

cognito_identity_id property ¶

cognito_identity_pool_id property ¶

principal_org_id property ¶

source_ip property ¶

user property ¶

user_agent property ¶

user_arn property ¶

BaseProxyEvent ¶

body property ¶

decoded_body cached property ¶

http_method property ¶

json_body cached property ¶

resolved_cookies_field property ¶

resolved_headers_field property ¶

resolved_query_string_parameters property ¶

get_header_value ¶

get_multi_value_query_string_values ¶

get_query_string_value ¶

BaseRequestContext ¶

account_id property ¶

api_id property ¶

domain_name property ¶

extended_request_id property ¶

http_method property ¶

protocol property ¶

request_id property ¶

request_time property ¶

request_time_epoch property ¶

stage property ¶

BaseRequestContextV2 ¶

account_id property ¶

api_id property ¶

authentication property ¶

domain_name property ¶

request_id property ¶

route_key property ¶

stage property ¶

time property ¶

time_epoch property ¶

CaseInsensitiveDict ¶

DictWrapper ¶

raw_event property ¶

RequestContextClientCert ¶

client_cert_pem property ¶

issuer_dn property ¶

serial_number property ¶

subject_dn property ¶

validity_not_after property ¶

validity_not_before property ¶

RequestContextV2Http ¶

protocol property ¶

source_ip property ¶

user_agent property ¶

account_id `property` ¶

api_key `property` ¶

api_key_id `property` ¶

caller `property` ¶

cognito_authentication_provider `property` ¶

cognito_authentication_type `property` ¶

cognito_identity_id `property` ¶

cognito_identity_pool_id `property` ¶

principal_org_id `property` ¶

source_ip `property` ¶

user `property` ¶

user_agent `property` ¶

user_arn `property` ¶

body `property` ¶

decoded_body `cached` `property` ¶

http_method `property` ¶

json_body `cached` `property` ¶

resolved_cookies_field `property` ¶

resolved_headers_field `property` ¶

resolved_query_string_parameters `property` ¶

account_id `property` ¶

api_id `property` ¶

domain_name `property` ¶

extended_request_id `property` ¶

http_method `property` ¶

protocol `property` ¶

request_id `property` ¶

request_time `property` ¶

request_time_epoch `property` ¶

stage `property` ¶

account_id `property` ¶

api_id `property` ¶

authentication `property` ¶

domain_name `property` ¶

request_id `property` ¶

route_key `property` ¶

stage `property` ¶

time `property` ¶

time_epoch `property` ¶

raw_event `property` ¶

client_cert_pem `property` ¶

issuer_dn `property` ¶

serial_number `property` ¶

subject_dn `property` ¶

validity_not_after `property` ¶

validity_not_before `property` ¶

protocol `property` ¶

source_ip `property` ¶

user_agent `property` ¶