Skip to content

Commit ec4204f

Browse files
leandrodamascenaheitorlessarubenfonseca
authored
docs(upgrade_guide): add latest changes and quick summary (#1623)
Co-authored-by: heitorlessa <[email protected]> Co-authored-by: Rúben Fonseca <[email protected]>
1 parent 11ae5a9 commit ec4204f

File tree

3 files changed

+77
-67
lines changed

3 files changed

+77
-67
lines changed

Diff for: ‎docs/media/upgrade_idempotency_after.png

78.2 KB
Loading

Diff for: ‎docs/media/upgrade_idempotency_before.png

75.9 KB
Loading

Diff for: ‎docs/upgrade.md

+77-67
Original file line numberDiff line numberDiff line change
@@ -7,70 +7,39 @@ description: Guide to update between major Powertools versions
77

88
## Migrate to v2 from v1
99

10-
The transition from Powertools for Python v1 to v2 is as painless as possible, as we aimed for minimal breaking changes.
11-
Changes at a glance:
10+
We've made minimal breaking changes to make your transition to v2 as smooth as possible.
1211

13-
* The API for **event handler's `Response`** has minor changes to support multi value headers and cookies.
14-
* The **legacy SQS batch processor** was removed.
15-
* The **Idempotency key** format changed slightly, invalidating all the existing cached results.
16-
* The **Feature Flags and AppConfig Parameter utility** API calls have changed and you must update your IAM permissions.
17-
* The **`DynamoDBStreamEvent`** replaced `AttributeValue` with native Python types.
12+
### Quick summary
1813

19-
???+ important
20-
Powertools for Python v2 drops suport for Python 3.6, following the Python 3.6 End-Of-Life (EOL) reached on December 23, 2021.
14+
| Area | Change | Code change required | IAM Permissions change required |
15+
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------------------------------- |
16+
| **Batch** | Removed legacy [SQS batch processor](#legacy-sqs-batch-processor) in favour of **`BatchProcessor`**. | Yes | - |
17+
| **Environment variables** | Removed legacy **`POWERTOOLS_EVENT_HANDLER_DEBUG`** in favour of [`POWERTOOLS_DEV`](index.md#optimizing-for-non-production-environments){target="_blank"}. | - | - |
18+
| **Event Handler** | Updated [headers response format](#event-handler-headers-response-format) due to [multi-value headers and cookie support](./core/event_handler/api_gateway.md#fine-grained-responses){target="_blank"}. | Tests only | - |
19+
| **Event Source Data Classes** | Replaced [DynamoDBStreamEvent](#dynamodbstreamevent-in-event-source-data-classes) `AttributeValue` with native Python types. | Yes | - |
20+
| **Feature Flags** / **Parameters** | Updated [AppConfig API calls](#feature-flags-and-appconfig-parameter-utility) due to **`GetConfiguration`** API deprecation. | - | Yes |
21+
| **Idempotency** | Updated [partition key](#idempotency-key-format) to include fully qualified function/method names. | - | - |
2122

22-
### Initial Steps
23+
### First Steps
2324

2425
Before you start, we suggest making a copy of your current working project or create a new branch with git.
2526

2627
1. **Upgrade** Python to at least v3.7
27-
28-
2. **Ensure** you have the latest `aws-lambda-powertools`
29-
30-
```bash
31-
pip install aws-lambda-powertools -U
32-
```
33-
28+
2. **Ensure** you have the latest version via [Lambda Layer or PyPi](index.md#install){target="_blank"}
3429
3. **Review** the following sections to confirm whether they affect your code
3530

36-
## Event Handler Response (headers and cookies)
37-
38-
The `Response` class of the event handler utility changed slightly:
39-
40-
1. The `headers` parameter now expects either a value or list of values per header (type `Union[str, Dict[str, List[str]]]`)
41-
2. We introduced a new `cookies` parameter (type `List[str]`)
42-
43-
???+ note
44-
Code that set headers as `Dict[str, str]` will still work unchanged.
45-
46-
```python hl_lines="6 12 13"
47-
@app.get("/todos")
48-
def get_todos():
49-
# Before
50-
return Response(
51-
# ...
52-
headers={"Content-Type": "text/plain"}
53-
)
54-
55-
# After
56-
return Response(
57-
# ...
58-
headers={"Content-Type": ["text/plain"]},
59-
cookies=[Cookie(name="session_id", value="12345", secure=True, http_only=True)],
60-
)
61-
```
62-
6331
## Legacy SQS Batch Processor
6432

65-
The deprecated `PartialSQSProcessor` and `sqs_batch_processor` were removed.
66-
You can migrate to the [native batch processing](https://aws.amazon.com/about-aws/whats-new/2021/11/aws-lambda-partial-batch-response-sqs-event-source/) capability by:
33+
We removed the deprecated `PartialSQSProcessor` class and `sqs_batch_processor` decorator.
6734

68-
1. If you use **`sqs_batch_decorator`** you can now use **`batch_processor`** decorator
69-
2. If you use **`PartialSQSProcessor`** you can now use **`BatchProcessor`**
70-
3. [Enable the functionality](../utilities/batch#required-resources) on SQS
35+
You can migrate to `BatchProcessor` with the following changes:
36+
37+
1. If you use **`sqs_batch_decorator`**, change to **`batch_processor`** decorator
38+
2. If you use **`PartialSQSProcessor`**, change to **`BatchProcessor`**
39+
3. [Enable **`ReportBatchItemFailures`** in your Lambda Event Source](../utilities/batch#required-resources){target="_blank"}
7140
4. Change your Lambda Handler to return the new response format
7241

73-
=== "Decorator: Before"
42+
=== "[Before] Decorator"
7443

7544
```python hl_lines="1 6"
7645
from aws_lambda_powertools.utilities.batch import sqs_batch_processor
@@ -83,9 +52,9 @@ You can migrate to the [native batch processing](https://aws.amazon.com/about-aw
8352
return {"statusCode": 200}
8453
```
8554

86-
=== "Decorator: After"
55+
=== "[After] Decorator"
8756

88-
```python hl_lines="3 5 11"
57+
```python hl_lines="3 5 11 13"
8958
import json
9059

9160
from aws_lambda_powertools.utilities.batch import BatchProcessor, EventType, batch_processor
@@ -101,7 +70,7 @@ You can migrate to the [native batch processing](https://aws.amazon.com/about-aw
10170
return processor.response()
10271
```
10372

104-
=== "Context manager: Before"
73+
=== "[Before] Context manager"
10574

10675
```python hl_lines="1-2 4 14 19"
10776
from aws_lambda_powertools.utilities.batch import PartialSQSProcessor
@@ -125,9 +94,9 @@ You can migrate to the [native batch processing](https://aws.amazon.com/about-aw
12594
return result
12695
```
12796

128-
=== "Context manager: After"
97+
=== "[After] Context manager"
12998

130-
```python hl_lines="1 11"
99+
```python hl_lines="1 11 16"
131100
from aws_lambda_powertools.utilities.batch import BatchProcessor, EventType, batch_processor
132101

133102

@@ -146,27 +115,35 @@ You can migrate to the [native batch processing](https://aws.amazon.com/about-aw
146115
return processor.response()
147116
```
148117

149-
## Idempotency key format
150-
151-
The format of the Idempotency key was changed. This is used store the invocation results on a persistent store like DynamoDB.
118+
## Event Handler headers response format
152119

153-
No changes are necessary in your code, but remember that existing Idempotency records will be ignored when you upgrade, as new executions generate keys with the new format.
120+
!!! note "No code changes required"
154121

155-
Prior to this change, the Idempotency key was generated using only the caller function name (e.g: `lambda_handler#282e83393862a613b612c00283fef4c8`).
156-
After this change, the key is generated using the `module name` + `qualified function name` + `idempotency key` (e.g: `app.classExample.function#app.handler#282e83393862a613b612c00283fef4c8`).
122+
This only applies if you're using `APIGatewayRestResolver` and asserting custom header values in your tests.
157123

158-
Using qualified names prevents distinct functions with the same name to contend for the same Idempotency key.
124+
Previously, custom headers were available under `headers` key in the Event Handler response.
159125

160-
## Feature Flags and AppConfig Parameter utility
126+
```python title="V1 response headers" hl_lines="2"
127+
{
128+
"headers": {
129+
"Content-Type": "application/json"
130+
}
131+
}
132+
```
161133

162-
AWS AppConfig deprecated the current API (GetConfiguration) - [more details here](https://github.com/awslabs/aws-lambda-powertools-python/issues/1506#issuecomment-1266645884).
134+
In V2, we add all headers under `multiValueHeaders` key. This enables seamless support for multi-value headers and cookies in [fine grained responses](./core/event_handler/api_gateway.md#fine-grained-responses){target="_blank"}.
163135

164-
You must update your IAM permissions to allow `appconfig:GetLatestConfiguration` and `appconfig:StartConfigurationSession`. There are no code changes required.
136+
```python title="V2 response headers" hl_lines="2"
137+
{
138+
"multiValueHeaders": {
139+
"Content-Type": "application/json"
140+
}
141+
}
142+
```
165143

166144
## DynamoDBStreamEvent in Event Source Data Classes
167145

168-
???+ info
169-
This also applies if you're using [**`BatchProcessor`**](https://awslabs.github.io/aws-lambda-powertools-python/latest/utilities/batch/#processing-messages-from-dynamodb){target="_blank"} to handle DynamoDB Stream events.
146+
!!! info "This also applies if you're using [**DynamoDB BatchProcessor**](https://awslabs.github.io/aws-lambda-powertools-python/latest/utilities/batch/#processing-messages-from-dynamodb){target="_blank"}."
170147

171148
You will now receive native Python types when accessing DynamoDB records via `keys`, `new_image`, and `old_image` attributes in `DynamoDBStreamEvent`.
172149

@@ -206,3 +183,36 @@ def lambda_handler(event: DynamoDBStreamEvent, context):
206183
send_to_sqs(new_image) # Here new_image is just a Python Dict type
207184

208185
```
186+
187+
## Feature Flags and AppConfig Parameter utility
188+
189+
!!! note "No code changes required"
190+
191+
We replaced `GetConfiguration` API ([now deprecated](https://github.com/awslabs/aws-lambda-powertools-python/issues/1506#issuecomment-1266645884){target="_blank"}) with `GetLatestConfiguration` and `StartConfigurationSession`.
192+
193+
As such, you must update your IAM Role permissions to allow the following IAM actions:
194+
195+
* `appconfig:GetLatestConfiguration`
196+
* `appconfig:StartConfigurationSession`
197+
198+
## Idempotency partition key format
199+
200+
!!! note "No code changes required"
201+
202+
We replaced the DynamoDB partition key format to include fully qualified function/method names. This means that recent non-expired idempotent transactions will be ignored.
203+
204+
Previously, we used the function/method name to generate the partition key value.
205+
206+
> e.g. `HelloWorldFunction.lambda_handler#99914b932bd37a50b983c5e7c90ae93b`
207+
208+
![Idempotency Before](./media/upgrade_idempotency_before.png)
209+
210+
In V2, we now distinguish between distinct classes or modules that may have the same function/method name.
211+
212+
[For example](https://github.com/awslabs/aws-lambda-powertools-python/issues/1330){target="_blank"}, an ABC or Protocol class may have multiple implementations of `process_payment` method and may have different results.
213+
214+
<!-- After this change, the key is generated using the `module name` + `qualified function name` + `idempotency key` -->
215+
216+
> e.g. `HelloWorldFunction.app.lambda_handler#99914b932bd37a50b983c5e7c90ae93b`
217+
218+
![Idempotency Before](./media/upgrade_idempotency_after.png)

0 commit comments

Comments
 (0)