Skip to content

Commit 0f170c1

Browse files
heitorlessaheitorlessa
authored
Merge pull request #171 from awslabs/docs/data_classes
docs: Data Classes Utility
2 parents 7311c5d + 9034827 commit 0f170c1

File tree

5 files changed

+254
-14
lines changed

5 files changed

+254
-14
lines changed

‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
![Build](https://github.com/awslabs/aws-lambda-powertools/workflows/Powertools%20Python/badge.svg?branch=master)
44
![PythonSupport](https://img.shields.io/static/v1?label=python&message=3.6%20|%203.7|%203.8&color=blue?style=flat-square&logo=python) ![PyPI version](https://badge.fury.io/py/aws-lambda-powertools.svg) ![PyPi monthly downloads](https://img.shields.io/pypi/dm/aws-lambda-powertools)
55

6-
A suite of utilities for AWS Lambda functions that makes tracing with AWS X-Ray, structured logging and creating custom metrics asynchronously easier.
6+
A suite of utilities for AWS Lambda functions to ease adopting best practices such as tracing, structured logging, custom metrics, and more.
77

88
**[📜Documentation](https://awslabs.github.io/aws-lambda-powertools-python/)** | **[API Docs](https://awslabs.github.io/aws-lambda-powertools-python/api/)** | **[🐍PyPi](https://pypi.org/project/aws-lambda-powertools/)** | **[Feature request](https://github.com/awslabs/aws-lambda-powertools-python/issues/new?assignees=&labels=feature-request%2C+triage&template=feature_request.md&title=)** | **[🐛Bug Report](https://github.com/awslabs/aws-lambda-powertools-python/issues/new?assignees=&labels=bug%2C+triage&template=bug_report.md&title=)** | **[Kitchen sink example](https://github.com/awslabs/aws-lambda-powertools-python/tree/develop/example)** | **[Detailed blog post](https://aws.amazon.com/blogs/opensource/simplifying-serverless-best-practices-with-lambda-powertools/)**
99

‎docs/content/index.mdx

+11-12
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: AWS Lambda Powertools Python
55

66
import Note from "../src/components/Note"
77

8-
Powertools is a suite of utilities for AWS Lambda functions that makes tracing with AWS X-Ray, structured logging and creating custom metrics asynchronously easier.
8+
A suite of utilities for AWS Lambda functions to ease adopting best practices such as tracing, structured logging, custom metrics, and more.
99

1010
<Note type="info">
1111
<strong>Looking for a quick run through of the core utilities?</strong><br/><br/>
@@ -24,12 +24,6 @@ Powertools is available in PyPi. You can use your favourite dependency managemen
2424
```bash:title=hello_world.sh
2525
sam init --location https://github.com/aws-samples/cookiecutter-aws-sam-python
2626
```
27-
* [Tracing](./core/tracer) - Decorators and utilities to trace Lambda function handlers, and both synchronous and asynchronous functions
28-
* [Logging](./core/logger) - Structured logging made easier, and decorator to enrich structured logging with key Lambda context details
29-
* [Metrics](./core/metrics) - Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF)
30-
* [Bring your own middleware](./utilities/middleware_factory) - Decorator factory to create your own middleware to run logic before, and after each Lambda invocation
31-
* [Parameters utility](./utilities/parameters) - Retrieve parameter values from AWS Systems Manager Parameter Store, AWS Secrets Manager, or Amazon DynamoDB, and cache them for a specific amount of time
32-
* [Batch utility](./utilities/batch) - Batch processing for AWS SQS, handles partial failure.
3327

3428
### Lambda Layer
3529

@@ -59,9 +53,10 @@ This will add a nested app stack with an output parameter `LayerVersionArn`, tha
5953

6054
You can fetch the available versions via the API with:
6155

62-
```bash
63-
aws serverlessrepo list-application-versions --application-id arn:aws:serverlessrepo:eu-west-1:057560766410:applications/aws-lambda-powertools-python-layer
64-
```
56+
```bash
57+
aws serverlessrepo list-application-versions \
58+
--application-id arn:aws:serverlessrepo:eu-west-1:057560766410:applications/aws-lambda-powertools-python-layer
59+
```
6560

6661
## Features
6762

@@ -71,8 +66,12 @@ Utility | Description
7166
[Logging](./core/logger) | Structured logging made easier, and decorator to enrich structured logging with key Lambda context details
7267
[Metrics](./core/metrics) | Custom Metrics created asynchronously via CloudWatch Embedded Metric Format (EMF)
7368
[Bring your own middleware](.//utilities/middleware_factory) | Decorator factory to create your own middleware to run logic before, and after each Lambda invocation
74-
[Parameters utility](./utilities/parameters) | Retrieve parameter values from AWS Systems Manager Parameter Store, AWS Secrets Manager, or Amazon DynamoDB, and cache them for a specific amount of time
75-
[Typing utility](./utilities/typing) | Static typing classes to speedup development in your IDE
69+
[Parameters](./utilities/parameters) | Retrieve parameter values from AWS Systems Manager Parameter Store, AWS Secrets Manager, or Amazon DynamoDB, and cache them for a specific amount of time
70+
[Typing](./utilities/typing) | Static typing classes to speedup development in your IDE
71+
[Batch](./utilities/batch) | Handle partial failures for AWS SQS batch processing
72+
[Validation](./utilities/validation) | JSON Schema validator for inbound events and responses
73+
[Event source data classes](./utilities/data_classes) | Data classes describing the schema of common Lambda event triggers
74+
7675

7776
## Environment variables
7877

‎docs/content/media/utilities_data_classes.png

311 KB
Loading

‎docs/content/utilities/data_classes.mdx

+240
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
---
2+
title: Event Source Data Classes
3+
description: Utility
4+
---
5+
6+
import Note from "../../src/components/Note"
7+
8+
The event source data classes utility provides classes describing the schema of common Lambda events triggers.
9+
10+
**Key Features**
11+
12+
* Type hinting and code completion for common event types
13+
* Helper functions for decoding/deserializing nested fields
14+
* Docstrings for fields contained in event schemas
15+
16+
**Background**
17+
18+
When authoring Lambda functions, you often need to understand the schema of the event dictionary which is passed to the
19+
handler. There are several common event types which follow a specific schema, depending on the service triggering the
20+
Lambda function.
21+
22+
23+
## Utilizing the data classes
24+
25+
The classes are initialized by passing in the Lambda event object into the constructor of the appropriate data class.
26+
For example, if your Lambda function is being triggered by an API Gateway proxy integration, you can use the
27+
`APIGatewayProxyEvent` class.
28+
29+
![Utilities Data Classes](../media/utilities_data_classes.png)
30+
31+
32+
## Supported event sources
33+
34+
Event Source | Data_class
35+
------------------------------------------------- | ---------------------------------------------------------------------------------
36+
[API Gateway Proxy](#api-gateway-proxy) | `APIGatewayProxyEvent`
37+
[API Gateway Proxy event v2](#api-gateway-proxy-v2) | `APIGatewayProxyEventV2`
38+
[CloudWatch Logs](#cloudWatch-logs) | `CloudWatchLogsEvent`
39+
[Cognito User Pool](#cognito-user-pool-triggers) | Multiple available under `cognito_user_pool_event`
40+
[DynamoDB streams](#dynamoDB-streams) | `DynamoDBStreamEvent`, `DynamoDBRecordEventName`
41+
[EventBridge](#eventbridge) | `EventBridgeEvent`
42+
[Kinesis Data Stream](#kinesis-streams) | `KinesisStreamEvent`
43+
[S3](#S3) | `S3Event`
44+
[SES](#SES) | `SESEvent`
45+
[SNS](#SNS) | `SNSEvent`
46+
[SQS](#SQS) | `SQSEvent`
47+
48+
49+
<Note type="info">
50+
The examples provided below are far from exhaustive - the data classes themselves are designed to provide a form of
51+
documentation inherently (via autocompletion, types and docstrings).
52+
</Note>
53+
54+
55+
## API Gateway Proxy
56+
57+
Typically used for API Gateway REST API or HTTP API using v1 proxy event.
58+
59+
```python:title=lambda_app.py
60+
from aws_lambda_powertools.utilities.data_classes import APIGatewayProxyEvent
61+
62+
def lambda_handler(event, context):
63+
event: APIGatewayProxyEvent = APIGatewayProxyEvent(event)
64+
request_context = event.request_context
65+
identity = request_context.identity
66+
67+
if 'helloworld' in event.path && event.http_method == 'GET':
68+
user = identity.user
69+
do_something_with(event.body, user)
70+
```
71+
72+
## API Gateway Proxy v2
73+
74+
```python:title=lambda_app.py
75+
from aws_lambda_powertools.utilities.data_classes import APIGatewayProxyEventV2
76+
77+
def lambda_handler(event, context):
78+
event: APIGatewayProxyEventV2 = APIGatewayProxyEventV2(event)
79+
request_context = event.request_context
80+
query_string_parameters = event.query_string_parameters
81+
82+
if 'helloworld' in event.raw_path && request_context.http.method == 'POST':
83+
do_something_with(event.body, query_string_parameters)
84+
```
85+
86+
## CloudWatch Logs
87+
88+
CloudWatch Logs events by default are compressed and base64 encoded. You can use the helper function provided to decode,
89+
decompress and parse json data from the event.
90+
91+
```python:title=lambda_app.py
92+
from aws_lambda_powertools.utilities.data_classes import CloudWatchLogsEvent
93+
94+
def lambda_handler(event, context):
95+
event: CloudWatchLogsEvent = CloudWatchLogsEvent(event)
96+
97+
decompressed_log = event.parse_logs_data
98+
log_events = decompressed_log.log_events
99+
for event in log_events:
100+
do_something_with(event.timestamp, event.message)
101+
```
102+
103+
## Cognito User Pool
104+
105+
Cognito User Pools have several [different Lambda trigger sources](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools-working-with-aws-lambda-triggers.html#cognito-user-identity-pools-working-with-aws-lambda-trigger-sources), all of which map to a different data class, which
106+
can be imported from `aws_lambda_powertools.data_classes.cognito_user_pool_event`:
107+
108+
Trigger/Event Source | Data Class
109+
------------------------------------------------- | -------------------------------------------------
110+
Custom message event | `data_classes.cognito_user_pool_event.CustomMessageTriggerEvent`
111+
Post authentication | `data_classes.cognito_user_pool_event.PostAuthenticationTriggerEvent`
112+
Post confirmation | `data_classes.cognito_user_pool_event.PostConfirmationTriggerEvent`
113+
Pre authentication | `data_classes.cognito_user_pool_event.PreAuthenticationTriggerEvent`
114+
Pre sign-up | `data_classes.cognito_user_pool_event.PreSignUpTriggerEvent`
115+
Pre token generation | `data_classes.cognito_user_pool_event.PreTokenGenerationTriggerEvent`
116+
User migration | `data_classes.cognito_user_pool_event.UserMigrationTriggerEvent`
117+
118+
```python:title=lambda_app.py
119+
from aws_lambda_powertools.utilities.cognito_user_pool_event import PostConfirmationTriggerEvent
120+
121+
def lambda_handler(event, context):
122+
event: PostConfirmationTriggerEvent = PostConfirmationTriggerEvent(event)
123+
124+
user_attributes = user_attributes = event.request.user_attributes
125+
do_something_with(user_attributes)
126+
```
127+
128+
## DynamoDB Streams
129+
130+
The DynamoDB data class utility provides the base class for `DynamoDBStreamEvent`, a typed class for
131+
attributes values (`AttributeValue`), as well as enums for stream view type (`StreamViewType`) and event type
132+
(`DynamoDBRecordEventName`).
133+
134+
```python:title=lambda_app.py
135+
from aws_lambda_powertools.utilities.data_classes import DynamoDBStreamEvent, DynamoDBRecordEventName
136+
137+
def lambda_handler(event, context):
138+
event: DynamoDBStreamEvent = DynamoDBStreamEvent(event)
139+
140+
# Multiple records can be delivered in a single event
141+
for record in event.records:
142+
if record.event_name == DynamoDBRecordEventName.MODIFY:
143+
do_something_with(record.dynamodb.new_image)
144+
do_something_with(record.dynamodb.old_image)
145+
```
146+
147+
## EventBridge
148+
149+
```python:title=lambda_app.py
150+
from aws_lambda_powertools.utilities.data_classes import EventBridgeEvent
151+
152+
def lambda_handler(event, context):
153+
event: EventBridgeEvent = EventBridgeEvent(event)
154+
do_something_with(event.detail)
155+
156+
```
157+
158+
## Kinesis streams
159+
160+
Kinesis events by default contain base64 encoded data. You can use the helper function to access the data either as json
161+
or plain text, depending on the original payload.
162+
163+
```python:title=lambda_app.py
164+
from aws_lambda_powertools.utilities.data_classes import KinesisStreamEvent
165+
166+
def lambda_handler(event, context):
167+
event: KinesisStreamEvent = KinesisStreamEvent(event)
168+
169+
# if data was delivered as json
170+
data = event.data_as_text()
171+
172+
# if data was delivered as text
173+
data = event.data_as_json()
174+
175+
do_something_with(data)
176+
177+
```
178+
179+
## S3
180+
181+
```python:title=lambda_app.py
182+
from aws_lambda_powertools.utilities.data_classes import S3Event
183+
184+
def lambda_handler(event, context):
185+
event: S3Event = S3Event(event)
186+
bucket_name = event.bucket_name
187+
188+
# Multiple records can be delivered in a single event
189+
for record in event.records:
190+
object_key = record.s3.get_object.key
191+
192+
do_something_with(f'{bucket_name}/{object_key}')
193+
194+
```
195+
196+
## SES
197+
198+
```python:title=lambda_app.py
199+
from aws_lambda_powertools.utilities.data_classes import SESEvent
200+
201+
def lambda_handler(event, context):
202+
event: SESEvent = SESEvent(event)
203+
204+
# Multiple records can be delivered in a single event
205+
for record in event.records:
206+
mail = record.ses.mail
207+
common_headers = list(mail.common_headers)
208+
209+
do_something_with(common_headers.to, common_headers.subject)
210+
211+
```
212+
213+
## SNS
214+
215+
```python:title=lambda_app.py
216+
from aws_lambda_powertools.utilities.data_classes import SNSEvent
217+
218+
def lambda_handler(event, context):
219+
event: SNSEvent = SNSEvent(event)
220+
221+
# Multiple records can be delivered in a single event
222+
for record in event.records:
223+
message = record.sns.message
224+
subject = record.sns.subject
225+
226+
do_something_with(subject, message)
227+
```
228+
229+
## SQS
230+
231+
```python:title=lambda_app.py
232+
from aws_lambda_powertools.utilities.data_classes import SQSEvent
233+
234+
def lambda_handler(event, context):
235+
event: SQSEvent = SQSEvent(event)
236+
237+
# Multiple records can be delivered in a single event
238+
for record in event.records:
239+
do_something_with(record.body)
240+
```

‎docs/gatsby-config.js

+2-1
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,8 @@ module.exports = {
3434
'utilities/parameters',
3535
'utilities/batch',
3636
'utilities/typing',
37-
'utilities/validation'
37+
'utilities/validation',
38+
'utilities/data_classes'
3839
],
3940
},
4041
navConfig: {

0 commit comments

Comments
 (0)