docs: add missing docs

Author: Michael Brewer

aws_lambda_powertools/utilities/data_classes/api_gateway_authorizer_event.py

@@ -61,63 +61,78 @@ def parse_api_gateway_arn(arn: str) -> APIGatewayRouteArn:
     )
 
 
-class APIGatewayAuthorizerV2Event(DictWrapper):
-    """API Gateway Authorizer Event Format 2.0
+class APIGatewayAuthorizerTokenEvent(DictWrapper):
+    """API Gateway Authorizer Token Event Format 1.0
+
+    Documentation:
+    -------------
+    - https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html
+    """
+
+    @property
+    def get_type(self) -> str:
+        return self["type"]
+
+    @property
+    def authorization_token(self) -> str:
+        return self["authorizationToken"]
+
+    @property
+    def method_arn(self) -> str:
+        """ARN of the incoming method request and is populated by API Gateway in accordance with the Lambda authorizer
+        configuration"""
+        return self["methodArn"]
+
+    @property
+    def parsed_arn(self) -> APIGatewayRouteArn:
+        """Convenient property to return a parsed api gateway method arn"""
+        return parse_api_gateway_arn(self.method_arn)
+
+
+class APIGatewayAuthorizerRequestEvent(DictWrapper):
+    """API Gateway Authorizer Request Event Format 1.0
 
     Documentation:
     -------------
+    - https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html
     - https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-lambda-authorizer.html
     """
 
     @property
     def version(self) -> str:
-        """Event payload version should always be 2.0"""
         return self["version"]
 
     @property
     def get_type(self) -> str:
-        """Event type should always be request"""
         return self["type"]
 
     @property
-    def route_arn(self) -> str:
-        """ARN of the route being called
-
-        eg: arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request"""
-        return self["routeArn"]
+    def method_arn(self) -> str:
+        return self["methodArn"]
 
     @property
     def parsed_arn(self) -> APIGatewayRouteArn:
-        """Convenient property to return a parsed api gateway route arn"""
-        return parse_api_gateway_arn(self.route_arn)
+        return parse_api_gateway_arn(self.method_arn)
 
     @property
-    def identity_source(self) -> Optional[List[str]]:
-        """The identity source for which authorization is requested.
-
-        For a REQUEST authorizer, this is optional. The value is a set of one or more mapping expressions of the
-        specified request parameters. The identity source can be headers, query string parameters, stage variables,
-        and context parameters.
-        """
-        return self.get("identitySource")
+    def identity_source(self) -> str:
+        return self["identitySource"]
 
     @property
-    def route_key(self) -> str:
-        """The route key for the route. For HTTP APIs, the route key can be either $default,
-        or a combination of an HTTP method and resource path, for example, GET /pets."""
-        return self["routeKey"]
+    def authorization_token(self) -> str:
+        return self["authorizationToken"]
 
     @property
-    def raw_path(self) -> str:
-        return self["rawPath"]
+    def resource(self) -> str:
+        return self["resource"]
 
     @property
-    def raw_query_string(self) -> str:
-        return self["rawQueryString"]
+    def path(self) -> str:
+        return self["path"]
 
     @property
-    def cookies(self) -> List[str]:
-        return self["cookies"]
+    def http_method(self) -> str:
+        return self["httpMethod"]
 
     @property
     def headers(self) -> Dict[str, str]:
@@ -128,16 +143,16 @@ def query_string_parameters(self) -> Dict[str, str]:
         return self["queryStringParameters"]
 
     @property
-    def request_context(self) -> BaseRequestContextV2:
-        return BaseRequestContextV2(self._data)
+    def path_parameters(self) -> Dict[str, str]:
+        return self["pathParameters"]
 
     @property
-    def path_parameters(self) -> Optional[Dict[str, str]]:
-        return self.get("pathParameters")
+    def stage_variables(self) -> Dict[str, str]:
+        return self["stageVariables"]
 
     @property
-    def stage_variables(self) -> Optional[Dict[str, str]]:
-        return self.get("stageVariables")
+    def request_context(self) -> BaseRequestContext:
+        return BaseRequestContext(self._data)
 
     def get_header_value(
         self, name: str, default_value: Optional[str] = None, case_sensitive: Optional[bool] = False
@@ -160,78 +175,64 @@ def get_header_value(
         return get_header_value(self.headers, name, default_value, case_sensitive)
 
 
-class APIGatewayAuthorizerTokenEvent(DictWrapper):
-    """API Gateway Authorizer Token Event Format 1.0
-
-    Documentation:
-    -------------
-    - https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html
-    """
-
-    @property
-    def get_type(self) -> str:
-        return self["type"]
-
-    @property
-    def authorization_token(self) -> str:
-        return self["authorizationToken"]
-
-    @property
-    def method_arn(self) -> str:
-        """ARN of the incoming method request and is populated by API Gateway in accordance with the Lambda authorizer
-        configuration"""
-        return self["methodArn"]
-
-    @property
-    def parsed_arn(self) -> APIGatewayRouteArn:
-        """Convenient property to return a parsed api gateway method arn"""
-        return parse_api_gateway_arn(self.method_arn)
-
-
-class APIGatewayAuthorizerRequestEvent(DictWrapper):
-    """API Gateway Authorizer Request Event Format 1.0
+class APIGatewayAuthorizerEventV2(DictWrapper):
+    """API Gateway Authorizer Event Format 2.0
 
     Documentation:
     -------------
-    - https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html
     - https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-lambda-authorizer.html
+    - https://aws.amazon.com/blogs/compute/introducing-iam-and-lambda-authorizers-for-amazon-api-gateway-http-apis/
     """
 
     @property
     def version(self) -> str:
+        """Event payload version should always be 2.0"""
         return self["version"]
 
     @property
     def get_type(self) -> str:
+        """Event type should always be request"""
         return self["type"]
 
     @property
-    def method_arn(self) -> str:
-        return self["methodArn"]
+    def route_arn(self) -> str:
+        """ARN of the route being called
+
+        eg: arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request"""
+        return self["routeArn"]
 
     @property
     def parsed_arn(self) -> APIGatewayRouteArn:
-        return parse_api_gateway_arn(self.method_arn)
+        """Convenient property to return a parsed api gateway route arn"""
+        return parse_api_gateway_arn(self.route_arn)
 
     @property
-    def identity_source(self) -> str:
-        return self["identitySource"]
+    def identity_source(self) -> Optional[List[str]]:
+        """The identity source for which authorization is requested.
+
+        For a REQUEST authorizer, this is optional. The value is a set of one or more mapping expressions of the
+        specified request parameters. The identity source can be headers, query string parameters, stage variables,
+        and context parameters.
+        """
+        return self.get("identitySource")
 
     @property
-    def authorization_token(self) -> str:
-        return self["authorizationToken"]
+    def route_key(self) -> str:
+        """The route key for the route. For HTTP APIs, the route key can be either $default,
+        or a combination of an HTTP method and resource path, for example, GET /pets."""
+        return self["routeKey"]
 
     @property
-    def resource(self) -> str:
-        return self["resource"]
+    def raw_path(self) -> str:
+        return self["rawPath"]
 
     @property
-    def path(self) -> str:
-        return self["path"]
+    def raw_query_string(self) -> str:
+        return self["rawQueryString"]
 
     @property
-    def http_method(self) -> str:
-        return self["httpMethod"]
+    def cookies(self) -> List[str]:
+        return self["cookies"]
 
     @property
     def headers(self) -> Dict[str, str]:
@@ -242,16 +243,16 @@ def query_string_parameters(self) -> Dict[str, str]:
         return self["queryStringParameters"]
 
     @property
-    def path_parameters(self) -> Dict[str, str]:
-        return self["pathParameters"]
+    def request_context(self) -> BaseRequestContextV2:
+        return BaseRequestContextV2(self._data)
 
     @property
-    def stage_variables(self) -> Dict[str, str]:
-        return self["stageVariables"]
+    def path_parameters(self) -> Optional[Dict[str, str]]:
+        return self.get("pathParameters")
 
     @property
-    def request_context(self) -> BaseRequestContext:
-        return BaseRequestContext(self._data)
+    def stage_variables(self) -> Optional[Dict[str, str]]:
+        return self.get("stageVariables")
 
     def get_header_value(
         self, name: str, default_value: Optional[str] = None, case_sensitive: Optional[bool] = False
@@ -274,7 +275,7 @@ def get_header_value(
         return get_header_value(self.headers, name, default_value, case_sensitive)
 
 
-class APIGatewayAuthorizerV2Response:
+class APIGatewayAuthorizerResponseV2:
     """Api Gateway HTTP API V2 payload authorizer simple response helper
 
     Parameters

docs/utilities/data_classes.md

@@ -59,11 +59,12 @@ Same example as above, but using the `event_source` decorator
 
 Event Source | Data_class
 ------------------------------------------------- | ---------------------------------------------------------------------------------
+[API Gateway Authorizer V2](#api-gateway-authorizer-v2) | `APIGatewayAuthorizerEventV2`
 [API Gateway Proxy](#api-gateway-proxy) | `APIGatewayProxyEvent`
 [API Gateway Proxy V2](#api-gateway-proxy-v2) | `APIGatewayProxyEventV2`
 [Application Load Balancer](#application-load-balancer) | `ALBEvent`
-[AppSync Resolver](#appsync-resolver) | `AppSyncResolverEvent`
 [AppSync Authorizer](#appsync-authorizer) | `AppSyncAuthorizerEvent`
+[AppSync Resolver](#appsync-resolver) | `AppSyncResolverEvent`
 [CloudWatch Logs](#cloudwatch-logs) | `CloudWatchLogsEvent`
 [CodePipeline Job Event](#codepipeline-job) | `CodePipelineJobEvent`
 [Cognito User Pool](#cognito-user-pool) | Multiple available under `cognito_user_pool_event`
@@ -81,6 +82,45 @@ Event Source | Data_class
     The examples provided below are far from exhaustive - the data classes themselves are designed to provide a form of
     documentation inherently (via autocompletion, types and docstrings).
 
+### API Gateway Authorizer V2
+
+> New in 1.20.0
+
+It is used for API Gateway HTTP API lambda authorizer payload version 2. See blog post
+[Introducing IAM and Lambda authorizers for Amazon API Gateway HTTP APIs](https://aws.amazon.com/blogs/compute/introducing-iam-and-lambda-authorizers-for-amazon-api-gateway-http-apis/){target="_blank"}
+or [Working with AWS Lambda authorizers for HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-lambda-authorizer.html){target="_blank"}
+for more details
+
+Below is a simple example of an HTTP API lambda authorizer looking up user details by `x-token` header and using
+`APIGatewayAuthorizerResponseV2` to return the declined response when user is not found or authorized and include
+the user details in the request context.
+
+=== "app.py"
+
+    ```python
+    from aws_lambda_powertools.utilities.data_classes import event_source
+    from aws_lambda_powertools.utilities.data_classes.api_gateway_authorizer_event import (
+        APIGatewayAuthorizerEventV2,
+        APIGatewayAuthorizerResponseV2,
+    )
+
+
+    def get_user_by_token(token):
+        ...
+
+
+    @event_source(data_class=APIGatewayAuthorizerEventV2)
+    def handler(event: APIGatewayAuthorizerEventV2, context):
+        user = get_user_by_token(event.get_header_value("x-token"))
+
+        if user is None:
+            # No user was found, so we return not authorized
+            return APIGatewayAuthorizerResponseV2().asdict()
+
+        # Found the user and setting the details in the context
+        return APIGatewayAuthorizerResponseV2(authorize=True, context=user).asdict()
+    ```
+
 ### API Gateway Proxy
 
 It is used for either API Gateway REST API or HTTP API using v1 proxy event.

tests/functional/test_data_classes.py

@@ -23,10 +23,10 @@
     SQSEvent,
 )
 from aws_lambda_powertools.utilities.data_classes.api_gateway_authorizer_event import (
+    APIGatewayAuthorizerEventV2,
     APIGatewayAuthorizerRequestEvent,
+    APIGatewayAuthorizerResponseV2,
     APIGatewayAuthorizerTokenEvent,
-    APIGatewayAuthorizerV2Event,
-    APIGatewayAuthorizerV2Response,
     parse_api_gateway_arn,
 )
 from aws_lambda_powertools.utilities.data_classes.appsync.scalar_types_utils import (
@@ -1469,7 +1469,7 @@ def test_appsync_authorizer_response():
 
 def test_api_gateway_authorizer_v2():
     """Check api gateway authorize event format v2.0"""
-    event = APIGatewayAuthorizerV2Event(load_event("apiGatewayAuthorizerV2Event.json"))
+    event = APIGatewayAuthorizerEventV2(load_event("apiGatewayAuthorizerV2Event.json"))
 
     assert event["version"] == event.version
     assert event["version"] == "2.0"
@@ -1513,7 +1513,7 @@ def test_api_gateway_authorizer_v2():
     assert event.get_header_value("missing") is None
 
     # Check for optionals
-    event_optionals = APIGatewayAuthorizerV2Event({"requestContext": {}})
+    event_optionals = APIGatewayAuthorizerEventV2({"requestContext": {}})
     assert event_optionals.identity_source is None
     assert event_optionals.request_context.authentication is None
     assert event_optionals.path_parameters is None
@@ -1588,9 +1588,9 @@ def test_api_gateway_authorizer_request_event():
 
 def test_api_gateway_authorizer_simple_response():
     """Check building API Gateway authorizer simple resource"""
-    assert {"isAuthorized": False} == APIGatewayAuthorizerV2Response().asdict()
+    assert {"isAuthorized": False} == APIGatewayAuthorizerResponseV2().asdict()
     expected_context = {"foo": "value"}
-    assert {"isAuthorized": True, "context": expected_context} == APIGatewayAuthorizerV2Response(
+    assert {"isAuthorized": True, "context": expected_context} == APIGatewayAuthorizerResponseV2(
         authorize=True,
         context=expected_context,
     ).asdict()