fix(parser): Improve types for parser.py

When attempting to use the parse function we noticed we were getting
error messages like:

    Value of type variable "Model" of "parse" cannot be "Type[UserModel]"

Further investigation (using the example shown at
https://awslabs.github.io/aws-lambda-powertools-python/latest/utilities/parser/#envelopes)
showed that the types were incorrect for the example. The function
signatures were expecting an instance of `Model`, however the example
(and code) seemeed to expect a `Type[Model]`.

Similarly the signatures were expecting an optional instance of an
Envelope, but the code allows for either an instance or a Type.

Also, added a `TypeVar` for the decorator, specifying that the
event_parser` decorator returns the same type as the handler used.

Finally updated documentation on use of parser.

Author: carlos-alberto

Diff for: aws_lambda_powertools/utilities/parser/parser.py

@@ -1,5 +1,5 @@
 import logging
-from typing import Any, Callable, Dict, Optional
+from typing import Any, Callable, Dict, Optional, Type, TypeVar, Union
 
 from ...middleware_factory import lambda_handler_decorator
 from ..typing import LambdaContext
@@ -10,14 +10,17 @@
 logger = logging.getLogger(__name__)
 
 
+EventParserReturnType = TypeVar("EventParserReturnType")
+
+
 @lambda_handler_decorator
 def event_parser(
-    handler: Callable[[Any, LambdaContext], Any],
+    handler: Callable[[Any, LambdaContext], EventParserReturnType],
     event: Dict[str, Any],
     context: LambdaContext,
-    model: Model,
-    envelope: Optional[Envelope] = None,
-) -> Any:
+    model: Type[Model],
+    envelope: Optional[Union[Envelope, Type[Envelope]]] = None,
+) -> EventParserReturnType:
     """Lambda handler decorator to parse & validate events using Pydantic models
 
     It requires a model that implements Pydantic BaseModel to parse & validate the event.
@@ -83,7 +86,9 @@ def handler(event: Order, context: LambdaContext):
     return handler(parsed_event, context)
 
 
-def parse(event: Dict[str, Any], model: Model, envelope: Optional[Envelope] = None) -> Model:
+def parse(
+    event: Dict[str, Any], model: Type[Model], envelope: Optional[Union[Envelope, Type[Envelope]]] = None
+) -> Model:
     """Standalone function to parse & validate events using Pydantic models
 
     Typically used when you need fine-grained control over error handling compared to event_parser decorator.

Diff for: docs/utilities/parser.md

@@ -272,21 +272,21 @@ Here's an example of parsing a model found in an event coming from EventBridge,
         }
     }
 
-    ret = parse(model=UserModel, envelope=envelopes.EventBridgeModel, event=payload)
+    ret = parse(model=UserModel, envelope=envelopes.EventBridgeEnvelope, event=payload)
 
     # Parsed model only contains our actual model, not the entire EventBridge + Payload parsed
     assert ret.password1 == ret.password2
 
     # Same behaviour but using our decorator
-    @event_parser(model=UserModel, envelope=envelopes.EventBridgeModel)
+    @event_parser(model=UserModel, envelope=envelopes.EventBridgeEnvelope)
     def handler(event: UserModel, context: LambdaContext):
         assert event.password1 == event.password2
     ```
 
 **What's going on here, you might ask**:
 
 1. We imported built-in `envelopes` from the parser utility
-2. Used `envelopes.EventBridgeModel` as the envelope for our `UserModel` model
+2. Used `envelopes.EventBridgeEnvelope` as the envelope for our `UserModel` model
 3. Parser parsed the original event against the EventBridge model
 4. Parser then parsed the `detail` key using `UserModel`