docs(validation): extract and fix code examples

Makefile

@@ -90,3 +90,13 @@ changelog:
 
 mypy:
 	poetry run mypy --pretty aws_lambda_powertools
+
+format-examples:
+	poetry run isort docs/shared
+	poetry run black docs/shared/*.py
+	poetry run isort docs/examples
+	poetry run black docs/examples/*/*/*.py
+
+lint-examples:
+	poetry run python3 -m py_compile docs/shared/*.py
+	poetry run python3 -m py_compile docs/examples/*/*/*.py

docs/examples/utilities/validation/unwrapping_events.py

@@ -0,0 +1,8 @@
+import schemas
+
+from aws_lambda_powertools.utilities.validation import validator
+
+
+@validator(inbound_schema=schemas.INPUT, envelope="detail")
+def handler(event, context):
+    return event

docs/examples/utilities/validation/unwrapping_popular_event_sources.py

@@ -0,0 +1,8 @@
+import schemas
+
+from aws_lambda_powertools.utilities.validation import envelopes, validator
+
+
+@validator(inbound_schema=schemas.INPUT, envelope=envelopes.EVENTBRIDGE)
+def handler(event, context):
+    return event

docs/examples/utilities/validation/validate_custom_format.py

@@ -0,0 +1,10 @@
+import schema
+
+from aws_lambda_powertools.utilities.validation import validate
+
+custom_format = {
+    "int64": True,  # simply ignore it,
+    "positive": lambda x: False if x < 0 else True,
+}
+
+validate(event=event, schema=schemas.INPUT, formats=custom_format)

docs/examples/utilities/validation/validate_jsonschema.py

@@ -0,0 +1,131 @@
+INPUT = {
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "definitions": {
+        "AWSAPICallViaCloudTrail": {
+            "properties": {
+                "additionalEventData": {"$ref": "#/definitions/AdditionalEventData"},
+                "awsRegion": {"type": "string"},
+                "errorCode": {"type": "string"},
+                "errorMessage": {"type": "string"},
+                "eventID": {"type": "string"},
+                "eventName": {"type": "string"},
+                "eventSource": {"type": "string"},
+                "eventTime": {"format": "date-time", "type": "string"},
+                "eventType": {"type": "string"},
+                "eventVersion": {"type": "string"},
+                "recipientAccountId": {"type": "string"},
+                "requestID": {"type": "string"},
+                "requestParameters": {"$ref": "#/definitions/RequestParameters"},
+                "resources": {"items": {"type": "object"}, "type": "array"},
+                "responseElements": {"type": ["object", "null"]},
+                "sourceIPAddress": {"type": "string"},
+                "userAgent": {"type": "string"},
+                "userIdentity": {"$ref": "#/definitions/UserIdentity"},
+                "vpcEndpointId": {"type": "string"},
+                "x-amazon-open-api-schema-readOnly": {"type": "boolean"},
+            },
+            "required": [
+                "eventID",
+                "awsRegion",
+                "eventVersion",
+                "responseElements",
+                "sourceIPAddress",
+                "eventSource",
+                "requestParameters",
+                "resources",
+                "userAgent",
+                "readOnly",
+                "userIdentity",
+                "eventType",
+                "additionalEventData",
+                "vpcEndpointId",
+                "requestID",
+                "eventTime",
+                "eventName",
+                "recipientAccountId",
+            ],
+            "type": "object",
+        },
+        "AdditionalEventData": {
+            "properties": {
+                "objectRetentionInfo": {"$ref": "#/definitions/ObjectRetentionInfo"},
+                "x-amz-id-2": {"type": "string"},
+            },
+            "required": ["x-amz-id-2"],
+            "type": "object",
+        },
+        "Attributes": {
+            "properties": {
+                "creationDate": {"format": "date-time", "type": "string"},
+                "mfaAuthenticated": {"type": "string"},
+            },
+            "required": ["mfaAuthenticated", "creationDate"],
+            "type": "object",
+        },
+        "LegalHoldInfo": {
+            "properties": {
+                "isUnderLegalHold": {"type": "boolean"},
+                "lastModifiedTime": {"format": "int64", "type": "integer"},
+            },
+            "type": "object",
+        },
+        "ObjectRetentionInfo": {
+            "properties": {
+                "legalHoldInfo": {"$ref": "#/definitions/LegalHoldInfo"},
+                "retentionInfo": {"$ref": "#/definitions/RetentionInfo"},
+            },
+            "type": "object",
+        },
+        "RequestParameters": {
+            "properties": {
+                "bucketName": {"type": "string"},
+                "key": {"type": "string"},
+                "legal-hold": {"type": "string"},
+                "retention": {"type": "string"},
+            },
+            "required": ["bucketName", "key"],
+            "type": "object",
+        },
+        "RetentionInfo": {
+            "properties": {
+                "lastModifiedTime": {"format": "int64", "type": "integer"},
+                "retainUntilMode": {"type": "string"},
+                "retainUntilTime": {"format": "int64", "type": "integer"},
+            },
+            "type": "object",
+        },
+        "SessionContext": {
+            "properties": {"attributes": {"$ref": "#/definitions/Attributes"}},
+            "required": ["attributes"],
+            "type": "object",
+        },
+        "UserIdentity": {
+            "properties": {
+                "accessKeyId": {"type": "string"},
+                "accountId": {"type": "string"},
+                "arn": {"type": "string"},
+                "principalId": {"type": "string"},
+                "sessionContext": {"$ref": "#/definitions/SessionContext"},
+                "type": {"type": "string"},
+            },
+            "required": ["accessKeyId", "sessionContext", "accountId", "principalId", "type", "arn"],
+            "type": "object",
+        },
+    },
+    "properties": {
+        "account": {"type": "string"},
+        "detail": {"$ref": "#/definitions/AWSAPICallViaCloudTrail"},
+        "detail-type": {"type": "string"},
+        "id": {"type": "string"},
+        "region": {"type": "string"},
+        "resources": {"items": {"type": "string"}, "type": "array"},
+        "source": {"type": "string"},
+        "time": {"format": "date-time", "type": "string"},
+        "version": {"type": "string"},
+    },
+    "required": ["detail-type", "resources", "id", "source", "time", "detail", "region", "version", "account"],
+    "title": "AWSAPICallViaCloudTrail",
+    "type": "object",
+    "x-amazon-events-detail-type": "AWS API Call via CloudTrail",
+    "x-amazon-events-source": "aws.s3",
+}

docs/examples/utilities/validation/validator_decorator.py

@@ -0,0 +1,8 @@
+import schemas
+
+from aws_lambda_powertools.utilities.validation import validator
+
+
+@validator(inbound_schema=schemas.INPUT, outbound_schema=schemas.OUTPUT)
+def handler(event, context):
+    return event

docs/examples/utilities/validation/validator_function.py

@@ -0,0 +1,14 @@
+import schemas
+
+from aws_lambda_powertools.utilities.validation import validate
+from aws_lambda_powertools.utilities.validation.exceptions import SchemaValidationError
+
+
+def handler(event, context):
+    try:
+        validate(event=event, schema=schemas.INPUT)
+    except SchemaValidationError as e:
+        # do something before re-raising
+        raise
+
+    return event

docs/shared/validation_basic_jsonschema.py

@@ -33,7 +33,15 @@
     "examples": [{"statusCode": 200, "body": "response"}],
     "required": ["statusCode", "body"],
     "properties": {
-        "statusCode": {"$id": "#/properties/statusCode", "type": "integer", "title": "The statusCode"},
-        "body": {"$id": "#/properties/body", "type": "string", "title": "The response"},
+        "statusCode": {
+            "$id": "#/properties/statusCode",
+            "type": "integer",
+            "title": "The statusCode",
+        },
+        "body": {
+            "$id": "#/properties/body",
+            "type": "string",
+            "title": "The response",
+        },
     },
 }