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_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_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 cached 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(
        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.