Skip to content

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
75
76
77
78
79
80
81
82
83
84
85
86
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
75
76
77
78
79
80
81
82
83
84
85
86
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
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
@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
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
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
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
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
75
76
77
78
79
80
81
82
83
84
85
86
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
75
76
77
78
79
80
81
82
83
84
85
86
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
32
33
34
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
75
76
77
78
79
80
81
82
83
84
85
86
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
75
76
77
78
79
80
81
82
83
84
85
86
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
75
76
77
78
79
80
81
82
83
84
85
86
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.