Skip to content

Commit a1bdb09

Browse files
ivica-kivica-k
committed
refactor(parser): improves S3 models with examples and descriptions
1 parent 4c24ee7 commit a1bdb09

File tree

2 files changed

+269
-34
lines changed

2 files changed

+269
-34
lines changed

‎.gitleaksignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
11
examples/batch_processing/src/context_manager_access_output_pydantic.txt:aws-access-token:10
22
examples/batch_processing/src/context_manager_access_output_pydantic.txt:aws-access-token:15
33
examples/batch_processing/src/context_manager_access_output.txt:aws-access-token:10
4+
aws_lambda_powertools/utilities/parser/models/s3.py:aws-access-token:32
5+
aws_lambda_powertools/utilities/parser/models/s3.py:aws-access-token:34
6+
aws_lambda_powertools/utilities/parser/models/s3.py:aws-access-token:70

‎aws_lambda_powertools/utilities/parser/models/s3.py

Lines changed: 266 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -11,88 +11,320 @@
1111

1212
class S3EventRecordGlacierRestoreEventData(BaseModel):
1313
lifecycleRestorationExpiryTime: datetime
14-
lifecycleRestoreStorageClass: str
14+
lifecycleRestoreStorageClass: str = Field(
15+
description="Source storage class for restore.",
16+
examples=[
17+
"standard",
18+
"standard_ia",
19+
"glacier",
20+
],
21+
)
1522

1623

1724
class S3EventRecordGlacierEventData(BaseModel):
1825
restoreEventData: S3EventRecordGlacierRestoreEventData
1926

2027

2128
class S3Identity(BaseModel):
22-
principalId: str
29+
principalId: str = Field(
30+
description="Amazon customer ID of the user who caused the event.",
31+
examples=[
32+
"AIDAJDPLRKLG7UEXAMPLE",
33+
"A1YQ72UWCM96UF",
34+
"AWS:AIDAINPONIXQXHT3IKHL2",
35+
],
36+
)
2337

2438

2539
class S3RequestParameters(BaseModel):
2640
sourceIPAddress: Union[IPvAnyNetwork, Literal["s3.amazonaws.com"]]
2741

2842

2943
class S3ResponseElements(BaseModel):
30-
x_amz_request_id: str = Field(..., alias="x-amz-request-id")
31-
x_amz_id_2: str = Field(..., alias="x-amz-id-2")
44+
x_amz_request_id: str = Field(
45+
...,
46+
alias="x-amz-request-id",
47+
description="Amazon S3 generated request ID.",
48+
examples=[
49+
"C3D13FE58DE4C810",
50+
"D82B88E5F771F645",
51+
],
52+
)
53+
x_amz_id_2: str = Field(
54+
...,
55+
alias="x-amz-id-2",
56+
description="ID of the Amazon S3 host that processed the request.",
57+
examples=[
58+
"FMyUVURIY8/IgAtTv8xRjskZQpcIZ9KG4V5Wp6S7S/JRWeUWerMUE5JgHvANOjpD",
59+
"vlR7PnpV2Ce81l0PRw6jlUpck7Jo5ZsQjryTjKlc5aLWGVHPZLj5NeC6qMa0emYBDXOo6QBU0Wo=",
60+
],
61+
)
3262

3363

3464
class S3OwnerIdentify(BaseModel):
35-
principalId: str
65+
principalId: str = Field(
66+
description="Amazon customer ID of the bucket owner.",
67+
examples=[
68+
"A3I5XTEXAMAI3E",
69+
"A1YQ72UWCM96UF",
70+
"AWS:AIDAINPONIXQXHT3IKHL2",
71+
],
72+
)
3673

3774

3875
class S3Bucket(BaseModel):
39-
name: str
76+
name: str = Field(
77+
description="Name of the Amazon S3 bucket.",
78+
examples=[
79+
"lambda-artifacts-deafc19498e3f2df",
80+
"example-bucket",
81+
"sourcebucket",
82+
],
83+
)
4084
ownerIdentity: S3OwnerIdentify
41-
arn: str
85+
arn: str = Field(
86+
description="The ARN of the Amazon S3 bucket.",
87+
examples=[
88+
"arn:aws:s3:::lambda-artifacts-deafc19498e3f2df",
89+
"arn:aws:s3:::example-bucketarn:aws:s3:::sourcebucket",
90+
],
91+
)
4292

4393

4494
class S3Object(BaseModel):
45-
key: str
46-
size: Optional[NonNegativeFloat] = None
47-
eTag: Optional[str] = None
48-
sequencer: Optional[str] = None
49-
versionId: Optional[str] = None
95+
key: str = Field(
96+
description="The object key (file name) of the S3 object.",
97+
examples=[
98+
"my-image.jpg",
99+
"documents/report.pdf",
100+
"logs/2023/01/15/app.log",
101+
],
102+
)
103+
size: Optional[NonNegativeFloat] = Field(
104+
default=None,
105+
description="The size of the object in bytes.",
106+
examples=[1024, 2048576, 0],
107+
)
108+
etag: str = Field(
109+
default="",
110+
description="The entity tag (ETag) of the object.",
111+
examples=[
112+
"d41d8cd98f00b204e9800998ecf8427e",
113+
"098f6bcd4621d373cade4e832627b4f6",
114+
],
115+
)
116+
sequencer: Optional[str] = Field(
117+
default=None,
118+
description="A string representation of a hexadecimal value used to determine event sequence.",
119+
examples=[
120+
"0A1B2C3D4E5F678901",
121+
"005B21C13A6F24045E",
122+
],
123+
)
124+
version_id: Optional[str] = Field(
125+
default=None,
126+
alias="version-id",
127+
description="The version ID of the object (if versioning is enabled).",
128+
examples=[
129+
"096fKKXTRTtl3on89fVO.nfljtsv6qko",
130+
"null",
131+
],
132+
)
50133

51134

52135
class S3Message(BaseModel):
53-
s3SchemaVersion: str
54-
configurationId: str
136+
s3SchemaVersion: str = Field(
137+
description="S3 schema version.",
138+
examples=[
139+
"1.0",
140+
],
141+
)
142+
configurationId: str = Field(
143+
description="ID of the bucket notification configuration.",
144+
examples=[
145+
"828aa6fc-f7b5-4305-8584-487c791949c1",
146+
"f99fa751-7860-4d65-86cb-10ff34448555",
147+
"b1d3a482-96eb-4d3a-abd7-763662a6ba94",
148+
],
149+
)
55150
bucket: S3Bucket
56151
object: S3Object # noqa: A003
57152

58153

59154
class S3EventNotificationObjectModel(BaseModel):
60-
key: str
61-
size: Optional[NonNegativeFloat] = None
62-
etag: str = Field(default="")
63-
version_id: Optional[str] = Field(None, alias="version-id")
64-
sequencer: Optional[str] = None
155+
key: str = Field(
156+
description="The object key (file name) of the S3 object.",
157+
examples=[
158+
"my-image.jpg",
159+
"documents/report.pdf",
160+
"logs/2023/01/15/app.log",
161+
],
162+
)
163+
size: Optional[NonNegativeFloat] = Field(
164+
default=None,
165+
description="The size of the object in bytes.",
166+
examples=[1024, 2048576, 0],
167+
)
168+
etag: str = Field(
169+
default="",
170+
description="The entity tag (ETag) of the object.",
171+
examples=[
172+
"d41d8cd98f00b204e9800998ecf8427e",
173+
"098f6bcd4621d373cade4e832627b4f6",
174+
],
175+
)
176+
version_id: Optional[str] = Field(
177+
default=None,
178+
alias="version-id",
179+
description="The version ID of the object (if versioning is enabled).",
180+
examples=[
181+
"096fKKXTRTtl3on89fVO.nfljtsv6qko",
182+
"null",
183+
],
184+
)
185+
sequencer: Optional[str] = Field(
186+
default=None,
187+
description="A string representation of a hexadecimal value used to determine event sequence.",
188+
examples=[
189+
"0A1B2C3D4E5F678901",
190+
"005B21C13A6F24045E",
191+
],
192+
)
65193

66194

67195
class S3EventNotificationEventBridgeBucketModel(BaseModel):
68-
name: str
196+
name: str = Field(
197+
description="Name of the Amazon S3 bucket.",
198+
examples=[
199+
"lambda-artifacts-deafc19498e3f2df",
200+
"example-bucket",
201+
"sourcebucket",
202+
],
203+
)
69204

70205

71206
class S3EventNotificationEventBridgeDetailModel(BaseModel):
72-
version: str
207+
version: str = Field(
208+
description="Version of the event message. Currently 0 (zero) for all events",
209+
examples=[
210+
"0",
211+
],
212+
)
73213
bucket: S3EventNotificationEventBridgeBucketModel
74214
object: S3EventNotificationObjectModel # noqa: A003
75-
request_id: str = Field(..., alias="request-id")
76-
requester: str
77-
source_ip_address: Optional[str] = Field(None, alias="source-ip-address")
78-
reason: Optional[str] = None
79-
deletion_type: Optional[str] = Field(None, alias="deletion-type")
80-
restore_expiry_time: Optional[str] = Field(None, alias="restore-expiry-time")
81-
source_storage_class: Optional[str] = Field(None, alias="source-storage-class")
82-
destination_storage_class: Optional[str] = Field(None, alias="destination-storage-class")
83-
destination_access_tier: Optional[str] = Field(None, alias="destination-access-tier")
215+
request_id: str = Field(
216+
...,
217+
alias="request-id",
218+
description="Amazon S3 generated request ID.",
219+
examples=[
220+
"C3D13FE58DE4C810",
221+
"D82B88E5F771F645",
222+
"N4N7GDK58NMKJ12R",
223+
],
224+
)
225+
requester: str = Field(
226+
description="AWS account ID or AWS service principal of requester, or 's3.amazonaws.com'.",
227+
examples=[
228+
"s3.amazonaws.com",
229+
"123456789012",
230+
],
231+
)
232+
source_ip_address: Optional[str] = Field(
233+
None,
234+
alias="source-ip-address",
235+
description="Source IP address of S3 request. Only present for events triggered by an S3 request.",
236+
examples=[
237+
"0.0.0.0",
238+
"255.255.255.255",
239+
],
240+
)
241+
reason: Optional[str] = Field(
242+
default=None,
243+
description="For 'Object Created' events, the S3 API used to create the object: PutObject, POST Object, "
244+
"CopyObject, or CompleteMultipartUpload. For 'Object Deleted' events, this is set to 'DeleteObject' "
245+
"when an object is deleted by an S3 API call, or 'Lifecycle Expiration' when an object is deleted by an "
246+
"S3 Lifecycle expiration rule. For more information, see https://docs.aws.amazon.com/AmazonS3/latest/userguide/lifecycle-expire-general-considerations.html",
247+
examples=[
248+
"Lifecycle Expiration",
249+
"PutObject",
250+
"DeleteObject",
251+
],
252+
)
253+
deletion_type: Optional[str] = Field(
254+
default=None,
255+
alias="deletion-type",
256+
description="For 'Object Deleted' events, when an unversioned object is deleted, or a versioned object is "
257+
"permanently deleted, this is set to 'Permanently Deleted'. When a delete marker is created for a "
258+
"versioned object, this is set to 'Delete Marker Created'. For more information, "
259+
"see https://docs.aws.amazon.com/AmazonS3/latest/userguide/DeletingObjectVersions.html",
260+
examples=["Delete Marker Created", "Permanently Deleted"],
261+
)
262+
restore_expiry_time: Optional[str] = Field(
263+
default=None,
264+
alias="restore-expiry-time",
265+
description="For 'Object Restore Completed' events, the time when the temporary copy of the object will be "
266+
"deleted from S3. For more information, see https://docs.aws.amazon.com/AmazonS3/latest/userguide/archived-objects.html.",
267+
examples=["2021-11-13T00:00:00Z"],
268+
)
269+
source_storage_class: Optional[str] = Field(
270+
default=None,
271+
alias="source-storage-class",
272+
description="For 'Object Restore Initiated' and 'Object Restore Completed' events, the storage class of the "
273+
"object being restored. For more information, see https://docs.aws.amazon.com/AmazonS3/latest/userguide/archived-objects.html.",
274+
examples=["GLACIER", "STANDARD", "STANDARD_IA"],
275+
)
276+
destination_storage_class: Optional[str] = Field(
277+
default=None,
278+
alias="destination-storage-class",
279+
description="For 'Object Storage Class Changed' events, the new storage class of the object. For more "
280+
"information, see https://docs.aws.amazon.com/AmazonS3/latest/userguide/lifecycle-transition-general-considerations.html.",
281+
examples=["INTELLIGENT_TIERING", "STANDARD", "STANDARD_IA"],
282+
)
283+
destination_access_tier: Optional[str] = Field(
284+
default=None,
285+
alias="destination-access-tier",
286+
description="For 'Object Access Tier Changed' events, the new access tier of the object. For more information, "
287+
"see https://docs.aws.amazon.com/AmazonS3/latest/userguide/intelligent-tiering.html.",
288+
examples=["DEEP_ARCHIVE_ACCESS", "ARCHIVE_ACCESS"],
289+
)
84290

85291

86292
class S3EventNotificationEventBridgeModel(EventBridgeModel): # type: ignore[override]
87293
detail: S3EventNotificationEventBridgeDetailModel
88294

89295

90296
class S3RecordModel(BaseModel):
91-
eventVersion: str
297+
eventVersion: str = Field(
298+
description="Version of the event message, with a major and minor version in the form <major>.<minor>.",
299+
examples=[
300+
"2.2",
301+
"1.9",
302+
],
303+
)
92304
eventSource: Literal["aws:s3"]
93-
awsRegion: str
94-
eventTime: datetime
95-
eventName: str
305+
awsRegion: str = Field(
306+
description="The AWS region where the event occurred.",
307+
examples=[
308+
"us-east-1",
309+
"eu-central-1",
310+
"ap-northeast-2",
311+
],
312+
)
313+
eventTime: datetime = Field(
314+
description="The time, in ISO-8601 format, for example, 1970-01-01T00:00:00.000Z, when Amazon S3 finished "
315+
"processing the request.",
316+
examples=[
317+
"1970-01-01T00:00:00.000Z",
318+
],
319+
)
320+
eventName: str = Field(
321+
description="Name of the event notification type, without the 's3:' prefix. See more https://docs.aws.amazon.com/AmazonS3/latest/userguide/notification-how-to-event-types-and-destinations.html.",
322+
examples=[
323+
"ObjectCreated",
324+
"ObjectCreated:Put",
325+
"LifecycleExpiration:Delete",
326+
],
327+
)
96328
userIdentity: S3Identity
97329
requestParameters: S3RequestParameters
98330
responseElements: S3ResponseElements

0 commit comments

Comments
 (0)