Feature request: Return empty Dict or List in Event Source Data Classes instead of None

[ericbn]

Use case

Arguably, it might be easier for users if an empty Dict is returned instead of None for path_parameters in APIGatewayProxyEventV2, for example.

Instead of:

@event_source(data_class=APIGatewayProxyEventV2)
def lambda_handler(event: APIGatewayProxyEventV2, context) -> None:
    parameters = event.path_parameters or {}
    handle(parameters["id"])

it would become:

@event_source(data_class=APIGatewayProxyEventV2)
def lambda_handler(event: APIGatewayProxyEventV2, context) -> None:
    handle(event.path_parameters["id"])

Ultimately this approach could be followed for any return value that is either an Optional[Dict] or an Optional[List], returning an empty Dict or List instead of None in all cases:

• utilities/data_classes/api_gateway_proxy_event.py
  • APIGatewayEventAuthorizer
    • def claims(self) -> Dict[str, Any]
    • def scopes(self) -> List[str]
  • APIGatewayProxyEvent
    • def multi_value_query_string_parameters(self) -> Dict[str, List[str]]
    • def path_parameters(self) -> Dict[str, str]
    • def stage_variables(self) -> Dict[str, str]
  • RequestContextV2AuthorizerIam
    • def cognito_amr(self) -> List[str]
  • RequestContextV2Authorizer
    • def jwt_claim(self) -> Dict[str, Any]
    • def jwt_scopes(self) -> List[str]
    • def get_lambda(self) -> Dict[str, Any]
  • APIGatewayProxyEventV2
    • def cookies(self) -> List[str]
    • def path_parameters(self) -> Dict[str, str]
    • def stage_variables(self) -> Dict[str, str]

and so on...

The bottom line is: Does it matter for users to differentiate between None and an empty Dict or List for any Event Source Data Classe property? If it does for a particular one, it an exception to a rule or the rule?

This change would be backwards compatible with the previous code.

This approach was already implemented in only one place so far, as far as I could check:

• utilities/data_classes/common.py
  • BaseProxyEvent
    • def headers(self) -> Dict[str, str]

Solution/User Experience

Solution can be the same as for the headers in the BaseProxyEvent:

powertools-lambda-python/aws_lambda_powertools/utilities/data_classes/common.py

Lines 98 to 100 in 1905e4c

	@property
	def headers(self) -> Dict[str, str]:
	return self.get("headers") or {}

Alternative solutions

No response

Acknowledgment

• This feature request meets Powertools for AWS Lambda (Python) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Java, TypeScript, and .NET

[rubenfonseca]

Hi @ericbn thank you for sending this proposal! Two notes:

1. Do you agree that code that backwards compatibility can be ensured since existing code that relies on None as a valid value will still function correctly?
2. Providing specific use cases and examples where this feature significantly improves the developer experience would strengthen the proposal.

It seems to be this would be a big breaking change anyways. So we might have to open an RFC to discuss this with the larger community and consider the breaking change for v3.

[ericbn]

Hi. Totally agree this is a breaking change for existing code that relies on None as a valid value. Good point. I see the change in the headers method in BaseProxyEvent was done exactly to keep backward compatibility.

I propose this change is favor of an API with multiple methods like get_query_string_value and get_header_value in BaseProxyEvent.

powertools-lambda-python/aws_lambda_powertools/utilities/data_classes/common.py

Lines 139 to 157 in 2c44207

	def get_query_string_value(self, name: str, default_value: Optional[str] = None) -> Optional[str]:
	"""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,
	)

powertools-lambda-python/aws_lambda_powertools/utilities/data_classes/common.py

Lines 159 to 186 in 2c44207

	# Maintenance: missing @overload to ensure return type is a str when default_value is set
	def get_header_value(
	self,
	name: str,
	default_value: Optional[str] = None,
	case_sensitive: Optional[bool] = False,
	) -> Optional[str]:
	"""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
	Returns
	-------
	str, optional
	Header value
	"""
	return get_header_value(
	headers=self.headers,
	name=name,
	default_value=default_value,
	case_sensitive=case_sensitive,
	)

Pros:

• No need to create extra methods in the data classes.
• User can use the List and Dict API directly, for example to choose between event.query_string_parameters["foo"] or event.query_string_parameters.get("foo") or event.query_string_parameters.get("foo", "default_foo") in case the key is required or not, or to use other functions like first(event.cookies).

Cons(?):

• As the List and Dict APIs are used directly, a parameter like case_sensitive in get_header_value would have to be replaced by returning a custom CaseInsensitiveDict.

[leandrodamascena]

Hello @ericbn! We've updated our roadmap and included this feature request. We are planning to release this feature in Powertools v3.

Roadmap for v3: https://docs.powertools.aws.dev/lambda/python/latest/roadmap/#v3