Skip to content

Commit 5f8078a

Browse files
committed
docs(parser): fix headings before adding install
1 parent cd49db3 commit 5f8078a

File tree

1 file changed

+20
-14
lines changed

1 file changed

+20
-14
lines changed

docs/utilities/parser.md

Lines changed: 20 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Parser
2+
title: Parser (Pydantic)
33
description: Utility
44
---
55
<!-- markdownlint-disable MD043 -->
@@ -25,7 +25,11 @@ This utility provides data parsing and deep validation using [Pydantic](https://
2525

2626
Install parser's extra dependencies using **`pip install aws-lambda-powertools[pydantic]`**.
2727

28-
## Defining models
28+
## Getting started
29+
30+
### Install
31+
32+
### Defining models
2933

3034
You can define models to parse incoming events by inheriting from `BaseModel`.
3135

@@ -47,11 +51,11 @@ class Order(BaseModel):
4751

4852
These are simply Python classes that inherit from BaseModel. **Parser** enforces type hints declared in your model at runtime.
4953

50-
## Parsing events
54+
### Parsing events
5155

5256
You can parse inbound events using **event_parser** decorator, or the standalone `parse` function. Both are also able to parse either dictionary or JSON string as an input.
5357

54-
### event_parser decorator
58+
#### event_parser decorator
5559

5660
Use the decorator for fail fast scenarios where you want your Lambda function to raise an exception in the event of a malformed payload.
5761

@@ -104,7 +108,7 @@ handler(event=payload, context=LambdaContext())
104108
handler(event=json.dumps(payload), context=LambdaContext()) # also works if event is a JSON string
105109
```
106110

107-
### parse function
111+
#### parse function
108112

109113
Use this standalone function when you want more control over the data validation process, for example returning a 400 error for malformed payloads.
110114

@@ -149,7 +153,7 @@ def my_function():
149153
}
150154
```
151155

152-
## Built-in models
156+
### Built-in models
153157

154158
Parser comes with the following built-in models:
155159

@@ -171,7 +175,7 @@ Parser comes with the following built-in models:
171175
| **KafkaSelfManagedEventModel** | Lambda Event Source payload for self managed Kafka payload |
172176
| **KafkaMskEventModel** | Lambda Event Source payload for AWS MSK payload |
173177

174-
### extending built-in models
178+
#### extending built-in models
175179

176180
You can extend them to include your own models, and yet have all other known fields parsed along the way.
177181

@@ -236,7 +240,9 @@ for order_item in ret.detail.items:
236240
3. Defined how part of our EventBridge event should look like by overriding `detail` key within our `OrderEventModel`
237241
4. Parser parsed the original event against `OrderEventModel`
238242

239-
## Envelopes
243+
## Advanced
244+
245+
### Envelopes
240246

241247
When trying to parse your payloads wrapped in a known structure, you might encounter the following situations:
242248

@@ -294,7 +300,7 @@ def handler(event: UserModel, context: LambdaContext):
294300
3. Parser parsed the original event against the EventBridge model
295301
4. Parser then parsed the `detail` key using `UserModel`
296302

297-
### Built-in envelopes
303+
#### Built-in envelopes
298304

299305
Parser comes with the following built-in envelopes, where `Model` in the return section is your given model.
300306

@@ -312,7 +318,7 @@ Parser comes with the following built-in envelopes, where `Model` in the return
312318
| **LambdaFunctionUrlEnvelope** | 1. Parses data using `LambdaFunctionUrlModel`. <br/> 2. Parses `body` key using your model and returns it. | `Model` |
313319
| **KafkaEnvelope** | 1. Parses data using `KafkaRecordModel`. <br/> 2. Parses `value` key using your model and returns it. | `Model` |
314320

315-
### Bringing your own envelope
321+
#### Bringing your own envelope
316322

317323
You can create your own Envelope model and logic by inheriting from `BaseEnvelope`, and implementing the `parse` method.
318324

@@ -377,7 +383,7 @@ Here's a snippet of how the EventBridge envelope we demonstrated previously is i
377383
3. Then, we parsed the incoming data with our envelope to confirm it matches EventBridge's structure defined in `EventBridgeModel`
378384
4. Lastly, we call `_parse` from `BaseEnvelope` to parse the data in our envelope (.detail) using the customer model
379385

380-
## Data model validation
386+
### Data model validation
381387

382388
???+ warning
383389
This is radically different from the **Validator utility** which validates events against JSON Schema.
@@ -394,7 +400,7 @@ Keep the following in mind regardless of which decorator you end up using it:
394400
* You must raise either `ValueError`, `TypeError`, or `AssertionError` when value is not compliant
395401
* You must return the value(s) itself if compliant
396402

397-
### validating fields
403+
#### validating fields
398404

399405
Quick validation to verify whether the field `message` has the value of `hello world`.
400406

@@ -439,7 +445,7 @@ class HelloWorldModel(BaseModel):
439445
parse(model=HelloWorldModel, event={"message": "hello universe", "sender": "universe"})
440446
```
441447

442-
### validating entire model
448+
#### validating entire model
443449

444450
`root_validator` can help when you have a complex validation mechanism. For example finding whether data has been omitted, comparing field values, etc.
445451

@@ -470,7 +476,7 @@ parse(model=UserModel, event=payload)
470476
???+ info
471477
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>.
472478

473-
## Advanced use cases
479+
### Advanced use cases
474480

475481
???+ tip "Tip: Looking to auto-generate models from JSON, YAML, JSON Schemas, OpenApi, etc?"
476482
Use Koudai Aono's [data model code generation tool for Pydantic](https://github.com/koxudaxi/datamodel-code-generator)

0 commit comments

Comments
 (0)