Skip to content

Commit a4fdec0

Browse files
n-k1Neel Krishnaleandrodamascena
authored
refactor(jmespath_utils): deprecate extract_data_from_envelope in favor of query (#4907)
* refactor!(jmespath_utils): deprecate extract_data_from_envelope in jmespath_utils and replace with query issue: #4218 * Adding deprecation decorator * Adding test * Fix highlight --------- Co-authored-by: Neel Krishna <[email protected]> Co-authored-by: Leandro Damascena <[email protected]>
1 parent 1a8818d commit a4fdec0

16 files changed

+80
-51
lines changed

‎aws_lambda_powertools/logging/logger.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -440,7 +440,7 @@ def decorate(event, context, *args, **kwargs):
440440

441441
if correlation_id_path:
442442
self.set_correlation_id(
443-
jmespath_utils.extract_data_from_envelope(envelope=correlation_id_path, data=event),
443+
jmespath_utils.query(envelope=correlation_id_path, data=event),
444444
)
445445

446446
if log_event:

‎aws_lambda_powertools/utilities/feature_flags/appconfig.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ def get_configuration(self) -> Dict[str, Any]:
102102

103103
if self.envelope:
104104
self.logger.debug("Envelope enabled; extracting data from config", extra={"envelope": self.envelope})
105-
config = jmespath_utils.extract_data_from_envelope(
105+
config = jmespath_utils.query(
106106
data=config,
107107
envelope=self.envelope,
108108
jmespath_options=self.jmespath_options,

‎aws_lambda_powertools/utilities/jmespath_utils/__init__.py

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,16 @@
22
import gzip
33
import json
44
import logging
5+
import warnings
56
from typing import Any, Dict, Optional, Union
67

78
import jmespath
89
from jmespath.exceptions import LexerError
910
from jmespath.functions import Functions, signature
11+
from typing_extensions import deprecated
1012

1113
from aws_lambda_powertools.exceptions import InvalidEnvelopeExpressionError
14+
from aws_lambda_powertools.warnings import PowertoolsDeprecationWarning
1215

1316
logger = logging.getLogger(__name__)
1417

@@ -30,7 +33,7 @@ def _func_powertools_base64_gzip(self, value):
3033
return uncompressed.decode()
3134

3235

33-
def extract_data_from_envelope(data: Union[Dict, str], envelope: str, jmespath_options: Optional[Dict] = None) -> Any:
36+
def query(data: Union[Dict, str], envelope: str, jmespath_options: Optional[Dict] = None) -> Any:
3437
"""Searches and extracts data using JMESPath
3538
3639
Envelope being the JMESPath expression to extract the data you're after
@@ -42,13 +45,13 @@ def extract_data_from_envelope(data: Union[Dict, str], envelope: str, jmespath_o
4245
4346
**Deserialize JSON string and extracts data from body key**
4447
45-
from aws_lambda_powertools.utilities.jmespath_utils import extract_data_from_envelope
48+
from aws_lambda_powertools.utilities.jmespath_utils import query
4649
from aws_lambda_powertools.utilities.typing import LambdaContext
4750
4851
4952
def handler(event: dict, context: LambdaContext):
5053
# event = {"body": "{\"customerId\":\"dd4649e6-2484-4993-acb8-0f9123103394\"}"} # noqa: ERA001
51-
payload = extract_data_from_envelope(data=event, envelope="powertools_json(body)")
54+
payload = query(data=event, envelope="powertools_json(body)")
5255
customer = payload.get("customerId") # now deserialized
5356
...
5457
@@ -76,3 +79,19 @@ def handler(event: dict, context: LambdaContext):
7679
except (LexerError, TypeError, UnicodeError) as e:
7780
message = f"Failed to unwrap event from envelope using expression. Error: {e} Exp: {envelope}, Data: {data}" # noqa: B306, E501
7881
raise InvalidEnvelopeExpressionError(message)
82+
83+
84+
@deprecated("`extract_data_from_envelope` is deprecated; use `query` instead.", category=None)
85+
def extract_data_from_envelope(data: Union[Dict, str], envelope: str, jmespath_options: Optional[Dict] = None) -> Any:
86+
"""Searches and extracts data using JMESPath
87+
88+
*Deprecated*: Use query instead
89+
"""
90+
warnings.warn(
91+
"The extract_data_from_envelope method is deprecated in V3 "
92+
"and will be removed in the next major version. Use query instead.",
93+
category=PowertoolsDeprecationWarning,
94+
stacklevel=2,
95+
)
96+
97+
return query(data=data, envelope=envelope, jmespath_options=jmespath_options)

‎aws_lambda_powertools/utilities/validation/validator.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ def handler(event, context):
119119
When JMESPath expression to unwrap event is invalid
120120
""" # noqa: E501
121121
if envelope:
122-
event = jmespath_utils.extract_data_from_envelope(
122+
event = jmespath_utils.query(
123123
data=event,
124124
envelope=envelope,
125125
jmespath_options=jmespath_options,
@@ -223,7 +223,7 @@ def handler(event, context):
223223
When JMESPath expression to unwrap event is invalid
224224
""" # noqa: E501
225225
if envelope:
226-
event = jmespath_utils.extract_data_from_envelope(
226+
event = jmespath_utils.query(
227227
data=event,
228228
envelope=envelope,
229229
jmespath_options=jmespath_options,

‎docs/utilities/jmespath_functions.md

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -30,14 +30,14 @@ Powertools for AWS Lambda (Python) also have utilities like [validation](validat
3030

3131
### Extracting data
3232

33-
You can use the `extract_data_from_envelope` function with any [JMESPath expression](https://jmespath.org/tutorial.html){target="_blank" rel="nofollow"}.
33+
You can use the `query` function with any [JMESPath expression](https://jmespath.org/tutorial.html){target="_blank" rel="nofollow"}.
3434

3535
???+ tip
3636
Another common use case is to fetch deeply nested data, filter, flatten, and more.
3737

38-
=== "extract_data_from_envelope.py"
38+
=== "query.py"
3939
```python hl_lines="1 6 10"
40-
--8<-- "examples/jmespath_functions/src/extract_data_from_envelope.py"
40+
--8<-- "examples/jmespath_functions/src/query.py"
4141
```
4242

4343
=== "extract_data_from_envelope.json"
@@ -52,7 +52,7 @@ We provide built-in envelopes for popular AWS Lambda event sources to easily dec
5252

5353
=== "extract_data_from_builtin_envelope.py"
5454

55-
```python hl_lines="1-4 9"
55+
```python hl_lines="4-7 14"
5656
--8<-- "examples/jmespath_functions/src/extract_data_from_builtin_envelope.py"
5757
```
5858

@@ -64,21 +64,21 @@ We provide built-in envelopes for popular AWS Lambda event sources to easily dec
6464

6565
These are all built-in envelopes you can use along with their expression as a reference:
6666

67-
| Envelope | JMESPath expression |
68-
| --------------------------------- | ----------------------------------------------------------------------------------------- |
69-
| **`API_GATEWAY_HTTP`** | `powertools_json(body)` |
70-
| **`API_GATEWAY_REST`** | `powertools_json(body)` |
71-
| **`CLOUDWATCH_EVENTS_SCHEDULED`** | `detail` |
67+
| Envelope | JMESPath expression | |
68+
| --------------------------------- | ----------------------------------------------------------------------------------------- |-|
69+
| **`API_GATEWAY_HTTP`** | `powertools_json(body)` | |
70+
| **`API_GATEWAY_REST`** | `powertools_json(body)` | |
71+
| **`CLOUDWATCH_EVENTS_SCHEDULED`** | `detail` | |
7272
| **`CLOUDWATCH_LOGS`** | `awslogs.powertools_base64_gzip(data) | powertools_json(@).logEvents[*]` |
73-
| **`EVENTBRIDGE`** | `detail` |
74-
| **`KINESIS_DATA_STREAM`** | `Records[*].kinesis.powertools_json(powertools_base64(data))` |
75-
| **`S3_EVENTBRIDGE_SQS`** | `Records[*].powertools_json(body).detail` |
76-
| **`S3_KINESIS_FIREHOSE`** | `records[*].powertools_json(powertools_base64(data)).Records[0]` |
77-
| **`S3_SNS_KINESIS_FIREHOSE`** | `records[*].powertools_json(powertools_base64(data)).powertools_json(Message).Records[0]` |
78-
| **`S3_SNS_SQS`** | `Records[*].powertools_json(body).powertools_json(Message).Records[0]` |
79-
| **`S3_SQS`** | `Records[*].powertools_json(body).Records[0]` |
73+
| **`EVENTBRIDGE`** | `detail` | |
74+
| **`KINESIS_DATA_STREAM`** | `Records[*].kinesis.powertools_json(powertools_base64(data))` | |
75+
| **`S3_EVENTBRIDGE_SQS`** | `Records[*].powertools_json(body).detail` | |
76+
| **`S3_KINESIS_FIREHOSE`** | `records[*].powertools_json(powertools_base64(data)).Records[0]` | |
77+
| **`S3_SNS_KINESIS_FIREHOSE`** | `records[*].powertools_json(powertools_base64(data)).powertools_json(Message).Records[0]` | |
78+
| **`S3_SNS_SQS`** | `Records[*].powertools_json(body).powertools_json(Message).Records[0]` | |
79+
| **`S3_SQS`** | `Records[*].powertools_json(body).Records[0]` | |
8080
| **`SNS`** | `Records[0].Sns.Message | powertools_json(@)` |
81-
| **`SQS`** | `Records[*].powertools_json(body)` |
81+
| **`SQS`** | `Records[*].powertools_json(body)` | |
8282

8383
???+ tip "Using SNS?"
8484
If you don't require SNS metadata, enable [raw message delivery](https://docs.aws.amazon.com/sns/latest/dg/sns-large-payload-raw-message-delivery.html). It will reduce multiple payload layers and size, when using SNS in combination with other services (_e.g., SQS, S3, etc_).
@@ -102,7 +102,7 @@ This sample will deserialize the JSON string within the `data` key before valida
102102

103103
=== "powertools_json_jmespath_function.py"
104104

105-
```python hl_lines="5 8 34 45 48 51"
105+
```python hl_lines="5 6 34 45 48 51"
106106
--8<-- "examples/jmespath_functions/src/powertools_json_jmespath_function.py"
107107
```
108108

@@ -142,7 +142,7 @@ This sample will decode the base64 value within the `data` key, and deserialize
142142

143143
=== "powertools_base64_jmespath_function.py"
144144

145-
```python hl_lines="7 10 37 49 53 55 57"
145+
```python hl_lines="7 11 36 48 52 54 56"
146146
--8<-- "examples/jmespath_functions/src/powertools_base64_jmespath_function.py"
147147
```
148148

‎examples/jmespath_functions/src/extract_data_from_builtin_envelope.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,15 @@
33
from aws_lambda_powertools import Logger
44
from aws_lambda_powertools.utilities.jmespath_utils import (
55
envelopes,
6-
extract_data_from_envelope,
6+
query,
77
)
88
from aws_lambda_powertools.utilities.typing import LambdaContext
99

1010
logger = Logger()
1111

1212

1313
def handler(event: dict, context: LambdaContext) -> dict:
14-
records: list = extract_data_from_envelope(data=event, envelope=envelopes.SQS)
14+
records: list = query(data=event, envelope=envelopes.SQS)
1515
for record in records: # records is a list
1616
logger.info(record.get("customerId")) # now deserialized
1717

‎examples/jmespath_functions/src/powertools_base64_gzip_jmespath_function.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ def lambda_handler(event, context: LambdaContext) -> dict:
1414
try:
1515
validate(event=event, schema=schemas.INPUT, envelope="powertools_base64_gzip(payload) | powertools_json(@)")
1616

17-
# Alternatively, extract_data_from_envelope works here too
17+
# Alternatively, query works here too
1818
encoded_payload = base64.b64decode(event["payload"])
1919
uncompressed_payload = gzip.decompress(encoded_payload).decode()
2020
log: dict = json.loads(uncompressed_payload)

‎examples/jmespath_functions/src/powertools_base64_jmespath_function.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ def lambda_handler(event, context: LambdaContext) -> dict:
3535
try:
3636
validate(event=event, schema=schemas.INPUT, envelope="powertools_json(powertools_base64(payload))")
3737

38-
# alternatively, extract_data_from_envelope works here too
38+
# alternatively, query works here too
3939
payload_decoded = base64.b64decode(event["payload"]).decode()
4040

4141
order_payload: dict = json.loads(payload_decoded)

‎examples/jmespath_functions/src/powertools_custom_jmespath_function.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77

88
from aws_lambda_powertools.utilities.jmespath_utils import (
99
PowertoolsFunctions,
10-
extract_data_from_envelope,
10+
query,
1111
)
1212

1313

@@ -27,7 +27,7 @@ def lambda_handler(event, context) -> dict:
2727
try:
2828
logs = []
2929
logs.append(
30-
extract_data_from_envelope(
30+
query(
3131
data=event,
3232
# NOTE: Use the prefix `_func_` before the name of the function
3333
envelope="Records[*].decode_zlib_compression(log)",

‎examples/jmespath_functions/src/powertools_json_jmespath_function.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ def lambda_handler(event, context: LambdaContext) -> dict:
3434
validate(event=event, schema=schemas.INPUT, envelope="powertools_json(payload)")
3535

3636
# Deserialize JSON string order as dict
37-
# alternatively, extract_data_from_envelope works here too
37+
# alternatively, query works here too
3838
order_payload: dict = json.loads(event.get("payload"))
3939

4040
return {

0 commit comments

Comments
 (0)