docs: reorder data validation; improve envelopes section

Signed-off-by: heitorlessa <[email protected]>

Author: heitorlessa

docs/content/utilities/parser.mdx

@@ -70,6 +70,7 @@ Use the decorator for fail fast scenarios where you want your Lambda function to
 ```python:title=event_parser_decorator.py
 from aws_lambda_powertools.utilities.parser import event_parser, BaseModel, ValidationError
 from aws_lambda_powertools.utilities.typing import LambdaContext
+
 import json
 
 class OrderItem(BaseModel):
@@ -152,101 +153,6 @@ def my_function():
         }
 ```
 
-### Data model validation
-
-<Note type="warning">
-    This is radically different from the <strong>Validator utility</strong> which validates events against JSON Schema.
-</Note><br/>
-
-You can use parser's validator for deep inspection of object values and complex relationships.
-
-There are two types of class method decorators you can use:
-
-* **`validator`** - Useful to quickly validate an individual field and its value
-* **`root_validator`** - Useful to validate the entire model's data
-
-Keep the following in mind regardless of which decorator you end up using it:
-
-* You must raise either `ValueError`, `TypeError`, or `AssertionError` when value is not compliant
-* You must return the value(s) itself if compliant
-
-#### Validating fields
-
-Quick validation to verify whether the field `message` has the value of `hello world`.
-
-```python:title=deep_data_validation.py
-from aws_lambda_powertools.utilities.parser import parse, BaseModel, validator
-
-class HelloWorldModel(BaseModel):
-    message: str
-
-    @validator('message') # highlight-line
-    def is_hello_world(cls, v):
-        if v != "hello world":
-            raise ValueError("Message must be hello world!")
-        return v
-
-parse(model=HelloWorldModel, event={"message": "hello universe"})
-```
-
-If you run as-is, you should expect the following error with the message we provided in our exception:
-
-```
-message
-  Message must be hello world! (type=value_error)
-```
-
-Alternatively, you can pass `'*'` as an argument for the decorator so that you can validate every value available.
-
-```python:title=validate_all_field_values.py
-from aws_lambda_powertools.utilities.parser import parse, BaseModel, validator
-
-class HelloWorldModel(BaseModel):
-    message: str
-    sender: str
-
-    @validator('*') # highlight-line
-    def has_whitespace(cls, v):
-        if ' ' not in v:
-            raise ValueError("Must have whitespace...")
-
-        return v
-
-parse(model=HelloWorldModel, event={"message": "hello universe", "sender": "universe"})
-```
-
-#### Validating entire model
-
-`root_validator` can help when you have a complex validation mechanism. For example finding whether data has been omitted, comparing field values, etc.
-
-```python:title=validate_all_field_values.py
-from aws_lambda_powertools.utilities.parser import parse, BaseModel, validator
-
-class UserModel(BaseModel):
-    username: str
-    password1: str
-    password2: str
-
-    @root_validator
-    def check_passwords_match(cls, values):
-        pw1, pw2 = values.get('password1'), values.get('password2')
-        if pw1 is not None and pw2 is not None and pw1 != pw2:
-            raise ValueError('passwords do not match')
-        return values
-
-payload = {
-    "username": "universe",
-    "password1": "myp@ssword",
-    "password2": "repeat password"
-}
-
-parse(model=UserModel, event=payload)
-```
-
-<Note type="info">
-    You can read more about validating list items, reusing validators, validating raw inputs, and a lot more in <a href="https://pydantic-docs.helpmanual.io/usage/validators/">Pydantic's documentation</a>.
-</Note><br/>
-
 ## Extending built-in models
 
 Parser comes with the following built-in models:
@@ -324,12 +230,22 @@ for order_item in ret.detail.items:
 
 ## Envelopes
 
-Envelope parameter is useful when your actual payload is wrapped around a known structure, for example Lambda Event Sources like EventBridge.
+When trying to parse your payloads wrapped in a known structure, you might encounter the following situations:
+
+* Your actual payload is wrapped around a known structure, for example Lambda Event Sources like EventBridge
+* You're only interested in a portion of the payload, for example parsing the `detail` of custom events in EventBridge, or `body` of SQS records
+
+You can either solve these situations by creating a model of these known structures, parsing them, then extracting and parsing a key where your payload is.
 
-Example of parsing a model found in an event coming from EventBridge, where all you want is what's inside the `detail` key.
+This can become difficult quite quickly. Parser makes this problem easier through a feature named `Envelope`.
+
+Envelopes can be used via `envelope` parameter available in both `parse` function and `event_parser` decorator.
+
+Here's an example of parsing a model found in an event coming from EventBridge, where all you want is what's inside the `detail` key.
 
 ```python:title=parse_eventbridge_payload.py
-from aws_lambda_powertools.utilities.parser import parse, BaseModel, envelopes
+from aws_lambda_powertools.utilities.parser import event_parser, parse, BaseModel, envelopes
+from aws_lambda_powertools.utilities.typing import LambdaContext
 
 class UserModel(BaseModel):
     username: str
@@ -358,6 +274,11 @@ ret = parse(model=UserModel, envelope=envelopes.EventBridgeModel, 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) # highlight-line
+def handler(event: UserModel, context: LambdaContext):
+    assert event.password1 == event.password2
 ```
 
 **What's going on here, you might ask**:
@@ -367,17 +288,18 @@ assert ret.password1 == ret.password2
 3. Parser parsed the original event against the EventBridge model
 4. Parser then parsed the `detail` key using `UserModel`
 
+
 ### Built-in envelopes
 
-Parser comes with the following built-in envelopes, where `BaseModel` in the return section is your given model.
+Parser comes with the following built-in envelopes, where `Model` in the return section is your given model.
 
 Envelope name | Behaviour | Return
 ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------
-**DynamoDBStreamEnvelope** | 1. Parses data using `DynamoDBStreamModel`. <br/> 2. Parses records in `NewImage` and `OldImage` keys using your model. <br/> 3. Returns a list with a dictionary containing `NewImage` and `OldImage` keys | `List[Dict[Literal["NewImage", "OldImage"], BaseModel]]`
-**EventBridgeEnvelope** | 1. Parses data using `EventBridgeModel`. <br/> 2. Parses `detail` key using your model and returns it. | `BaseModel`
-**SqsEnvelope** | 1. Parses data using `SqsModel`. <br/> 2. Parses records in `body` key using your model and return them in a list. | `List[BaseModel]`
+**DynamoDBStreamEnvelope** | 1. Parses data using `DynamoDBStreamModel`. <br/> 2. Parses records in `NewImage` and `OldImage` keys using your model. <br/> 3. Returns a list with a dictionary containing `NewImage` and `OldImage` keys | `List[Dict[str, Optional[Model]]]`
+**EventBridgeEnvelope** | 1. Parses data using `EventBridgeModel`. <br/> 2. Parses `detail` key using your model and returns it. | `Model`
+**SqsEnvelope** | 1. Parses data using `SqsModel`. <br/> 2. Parses records in `body` key using your model and return them in a list. | `List[Model]`
 
-### Bringing your own envelope model
+### Bringing your own envelope
 
 You can create your own Envelope model and logic by inheriting from `BaseEnvelope`, and implementing the `parse` method.
 
@@ -407,28 +329,31 @@ class EventBridgeModel(BaseModel):
 **EventBridge Envelope**
 
 ```python:title=eventbridge_envelope.py
-from aws_lambda_powertools.utilities.parser import BaseEnvelope, BaseModel
-from typing import Any, Dict
-from ..models import EventBridgeModel
+from aws_lambda_powertools.utilities.parser import BaseEnvelope, models
+from aws_lambda_powertools.utilities.parser.models import EventBridgeModel
+
+from typing import Any, Dict, Optional, TypeVar
+
+Model = TypeVar("Model", bound=BaseModel)
 
 class EventBridgeEnvelope(BaseEnvelope): # highlight-line
 
-    def parse(self, data: Dict[str, Any], model: BaseModel) -> BaseModel: # highlight-line
+    def parse(self, data: Optional[Union[Dict[str, Any], Any]], model: Model) -> Optional[Model]: # highlight-line
         """Parses data found with model provided
 
         Parameters
         ----------
         data : Dict
             Lambda event to be parsed
-        model : BaseModel
+        model : Model
             Data model provided to parse after extracting data using envelope
 
         Returns
         -------
         Any
             Parsed detail payload with model provided
         """
-        parsed_envelope = EventBridgeModel(**data) # highlight-line
+        parsed_envelope = EventBridgeModel.parse_obj(data) # highlight-line
         return self._parse(data=parsed_envelope.detail, model=model) # highlight-line
 ```
 
@@ -439,6 +364,102 @@ class EventBridgeEnvelope(BaseEnvelope): # highlight-line
 3. Then, we parsed the incoming data with our envelope to confirm it matches EventBridge's structure defined in `EventBridgeModel`
 4. Lastly, we call `_parse` from `BaseEnvelope` to parse the data in our envelope (.detail) using the customer model
 
+### Data model validation
+
+<Note type="warning">
+    This is radically different from the <strong>Validator utility</strong> which validates events against JSON Schema.
+</Note><br/>
+
+You can use parser's validator for deep inspection of object values and complex relationships.
+
+There are two types of class method decorators you can use:
+
+* **`validator`** - Useful to quickly validate an individual field and its value
+* **`root_validator`** - Useful to validate the entire model's data
+
+Keep the following in mind regardless of which decorator you end up using it:
+
+* You must raise either `ValueError`, `TypeError`, or `AssertionError` when value is not compliant
+* You must return the value(s) itself if compliant
+
+#### Validating fields
+
+Quick validation to verify whether the field `message` has the value of `hello world`.
+
+```python:title=deep_data_validation.py
+from aws_lambda_powertools.utilities.parser import parse, BaseModel, validator
+
+class HelloWorldModel(BaseModel):
+    message: str
+
+    @validator('message') # highlight-line
+    def is_hello_world(cls, v):
+        if v != "hello world":
+            raise ValueError("Message must be hello world!")
+        return v
+
+parse(model=HelloWorldModel, event={"message": "hello universe"})
+```
+
+If you run as-is, you should expect the following error with the message we provided in our exception:
+
+```
+message
+  Message must be hello world! (type=value_error)
+```
+
+Alternatively, you can pass `'*'` as an argument for the decorator so that you can validate every value available.
+
+```python:title=validate_all_field_values.py
+from aws_lambda_powertools.utilities.parser import parse, BaseModel, validator
+
+class HelloWorldModel(BaseModel):
+    message: str
+    sender: str
+
+    @validator('*') # highlight-line
+    def has_whitespace(cls, v):
+        if ' ' not in v:
+            raise ValueError("Must have whitespace...")
+
+        return v
+
+parse(model=HelloWorldModel, event={"message": "hello universe", "sender": "universe"})
+```
+
+#### Validating entire model
+
+`root_validator` can help when you have a complex validation mechanism. For example finding whether data has been omitted, comparing field values, etc.
+
+```python:title=validate_all_field_values.py
+from aws_lambda_powertools.utilities.parser import parse, BaseModel, validator
+
+class UserModel(BaseModel):
+    username: str
+    password1: str
+    password2: str
+
+    @root_validator
+    def check_passwords_match(cls, values):
+        pw1, pw2 = values.get('password1'), values.get('password2')
+        if pw1 is not None and pw2 is not None and pw1 != pw2:
+            raise ValueError('passwords do not match')
+        return values
+
+payload = {
+    "username": "universe",
+    "password1": "myp@ssword",
+    "password2": "repeat password"
+}
+
+parse(model=UserModel, event=payload)
+```
+
+<Note type="info">
+    You can read more about validating list items, reusing validators, validating raw inputs, and a lot more in <a href="https://pydantic-docs.helpmanual.io/usage/validators/">Pydantic's documentation</a>.
+</Note><br/>
+
+
 ## FAQ
 
 **When should I use parser vs data_classes utility?**