Skip to content

Commit 6877dee

Browse files
heitorlessaheitorlessa
committed
improv: add docstrings
1 parent cd6c34f commit 6877dee

File tree

2 files changed

+212
-3
lines changed

2 files changed

+212
-3
lines changed

‎aws_lambda_powertools/utilities/validation/base.py

Lines changed: 34 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import logging
2-
from typing import Dict
2+
from typing import Any, Dict
33

44
import fastjsonschema
55
import jmespath
@@ -12,6 +12,22 @@
1212

1313

1414
def validate_data_against_schema(data: Dict, schema: Dict):
15+
"""Validate dict data against given JSON Schema
16+
17+
Parameters
18+
----------
19+
data : Dict
20+
Data set to be validated
21+
schema : Dict
22+
JSON Schema to validate against
23+
24+
Raises
25+
------
26+
SchemaValidationError
27+
When schema validation fails against data set
28+
InvalidSchemaFormatError
29+
When JSON schema provided is invalid
30+
"""
1531
try:
1632
fastjsonschema.validate(definition=schema, data=data)
1733
except fastjsonschema.JsonSchemaException as e:
@@ -21,7 +37,23 @@ def validate_data_against_schema(data: Dict, schema: Dict):
2137
raise InvalidSchemaFormatError(f"Schema received: {schema}. Error: {e}")
2238

2339

24-
def unwrap_event_from_envelope(data: Dict, envelope: str, jmespath_options: Dict):
40+
def unwrap_event_from_envelope(data: Dict, envelope: str, jmespath_options: Dict) -> Any:
41+
"""Searches data using JMESPath expression
42+
43+
Parameters
44+
----------
45+
data : Dict
46+
Data set to be filtered
47+
envelope : str
48+
JMESPath expression to filter data against
49+
jmespath_options : Dict
50+
Alternative JMESPath options to be included when filtering expr
51+
52+
Returns
53+
-------
54+
Any
55+
Data found using JMESPath expression given in envelope
56+
"""
2557
if not jmespath_options:
2658
jmespath_options = {"custom_functions": PowertoolsFunctions()}
2759

‎aws_lambda_powertools/utilities/validation/validator.py

Lines changed: 178 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,106 @@ def validator(
1616
outbound_schema: Dict = None,
1717
envelope: str = None,
1818
jmespath_options: Dict = None,
19-
):
19+
) -> Any:
20+
"""Lambda handler decorator to validate incoming/outbound data using a JSON Schema
21+
22+
Example
23+
-------
24+
25+
**Validate incoming event**
26+
27+
import json
28+
from aws_lambda_powertools.utilities.validation import validator
29+
30+
@validator(inbound_schema=json_schema_dict)
31+
def handler(event, context):
32+
return event
33+
34+
**Validate incoming and outgoing event**
35+
36+
import json
37+
from aws_lambda_powertools.utilities.validation import validator
38+
39+
@validator(inbound_schema=json_schema_dict, outbound_schema=response_json_schema_dict)
40+
def handler(event, context):
41+
return event
42+
43+
**Unwrap event before validating against actual payload - using built-in envelopes**
44+
45+
import json
46+
from aws_lambda_powertools.utilities.validation import validator, envelopes
47+
48+
@validator(inbound_schema=json_schema_dict, envelope=envelopes.API_GATEWAY_REST)
49+
def handler(event, context):
50+
return event
51+
52+
**Unwrap event before validating against actual payload - using custom JMESPath expression**
53+
54+
import json
55+
from aws_lambda_powertools.utilities.validation import validator
56+
57+
@validator(inbound_schema=json_schema_dict, envelope="payload[*].my_data")
58+
def handler(event, context):
59+
return event
60+
61+
**Unwrap and deserialize JSON string event before validating against actual payload - using built-in functions**
62+
63+
import json
64+
from aws_lambda_powertools.utilities.validation import validator
65+
66+
@validator(inbound_schema=json_schema_dict, envelope="Records[*].powertools_json(body)")
67+
def handler(event, context):
68+
return event
69+
70+
**Unwrap, decode base64 and deserialize JSON string event before validating against actual payload - using built-in functions** # noqa: E501
71+
72+
import json
73+
from aws_lambda_powertools.utilities.validation import validator
74+
75+
@validator(inbound_schema=json_schema_dict, envelope="Records[*].kinesis.powertools_json(powertools_base64(data))")
76+
def handler(event, context):
77+
return event
78+
79+
**Unwrap, decompress ZIP archive and deserialize JSON string event before validating against actual payload - using built-in functions** # noqa: E501
80+
81+
import json
82+
from aws_lambda_powertools.utilities.validation import validator
83+
84+
@validator(inbound_schema=json_schema_dict, envelope="awslogs.powertools_base64_gzip(data) | powertools_json(@).logEvents[*]")
85+
def handler(event, context):
86+
return event
87+
88+
Parameters
89+
----------
90+
handler : Callable
91+
Method to annotate on
92+
event : Dict
93+
Lambda event to be validated
94+
context : Any
95+
Lambda context object
96+
inbound_schema : Dict
97+
JSON Schema to validate incoming event
98+
outbound_schema : Dict
99+
JSON Schema to validate outbound event
100+
envelope : Dict
101+
JMESPath expression to filter data against
102+
jmespath_options : Dict
103+
Alternative JMESPath options to be included when filtering expr
104+
105+
Returns
106+
-------
107+
Any
108+
Lambda handler response
109+
110+
Raises
111+
------
112+
SchemaValidationError
113+
When schema validation fails against data set
114+
InvalidSchemaFormatError
115+
When JSON schema provided is invalid
116+
InvalidEnvelopeExpressionError
117+
When JMESPath expression to unwrap event is invalid
118+
"""
20119
if envelope:
21120
event = unwrap_event_from_envelope(data=event, envelope=envelope, jmespath_options=jmespath_options)
22121

@@ -34,6 +133,84 @@ def validator(
34133

35134

36135
def validate(event: Dict, schema: Dict = None, envelope: str = None, jmespath_options: Dict = None):
136+
"""Standalone function to validate event data using a JSON Schema
137+
138+
Typically used when you need more control over the validation process.
139+
140+
**Validate event**
141+
142+
import json
143+
from aws_lambda_powertools.utilities.validation import validate
144+
145+
def handler(event, context):
146+
validate(event=event, schema=json_schema_dict)
147+
return event
148+
149+
**Unwrap event before validating against actual payload - using built-in envelopes**
150+
151+
import json
152+
from aws_lambda_powertools.utilities.validation import validate, envelopes
153+
154+
def handler(event, context):
155+
validate(event=event, schema=json_schema_dict, envelope=envelopes.API_GATEWAY_REST)
156+
return event
157+
158+
**Unwrap event before validating against actual payload - using custom JMESPath expression**
159+
160+
import json
161+
from aws_lambda_powertools.utilities.validation import validate
162+
163+
def handler(event, context):
164+
validate(event=event, schema=json_schema_dict, envelope="payload[*].my_data")
165+
return event
166+
167+
**Unwrap and deserialize JSON string event before validating against actual payload - using built-in functions**
168+
169+
import json
170+
from aws_lambda_powertools.utilities.validation import validate
171+
172+
def handler(event, context):
173+
validate(event=event, schema=json_schema_dict, envelope="Records[*].powertools_json(body)")
174+
return event
175+
176+
**Unwrap, decode base64 and deserialize JSON string event before validating against actual payload - using built-in functions**
177+
178+
import json
179+
from aws_lambda_powertools.utilities.validation import validate
180+
181+
def handler(event, context):
182+
validate(event=event, schema=json_schema_dict, envelope="Records[*].kinesis.powertools_json(powertools_base64(data))")
183+
return event
184+
185+
**Unwrap, decompress ZIP archive and deserialize JSON string event before validating against actual payload - using built-in functions** # noqa: E501
186+
187+
import json
188+
from aws_lambda_powertools.utilities.validation import validate
189+
190+
def handler(event, context):
191+
validate(event=event, schema=json_schema_dict, envelope="awslogs.powertools_base64_gzip(data) | powertools_json(@).logEvents[*]")
192+
return event
193+
194+
Parameters
195+
----------
196+
event : Dict
197+
Lambda event to be validated
198+
schema : Dict
199+
JSON Schema to validate incoming event
200+
envelope : Dict
201+
JMESPath expression to filter data against
202+
jmespath_options : Dict
203+
Alternative JMESPath options to be included when filtering expr
204+
205+
Raises
206+
------
207+
SchemaValidationError
208+
When schema validation fails against data set
209+
InvalidSchemaFormatError
210+
When JSON schema provided is invalid
211+
InvalidEnvelopeExpressionError
212+
When JMESPath expression to unwrap event is invalid
213+
"""
37214
if envelope:
38215
event = unwrap_event_from_envelope(data=event, envelope=envelope, jmespath_options=jmespath_options)
39216

0 commit comments

Comments
 (0)