Skip to content

Commit c8dbd4f

Browse files
ivica-kivica-k
committed
refactor(parser): improves S3 models with examples and descriptions
1 parent 218184f commit c8dbd4f

File tree

2 files changed

+268
-34
lines changed

2 files changed

+268
-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: 265 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -11,88 +11,319 @@
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: Optional[str] = Field(
109+
default=None,
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+
versionId: Optional[str] = Field(
125+
default=None,
126+
description="The version ID of the object (if versioning is enabled).",
127+
examples=[
128+
"096fKKXTRTtl3on89fVO.nfljtsv6qko",
129+
"null",
130+
],
131+
)
50132

51133

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

58152

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

66193

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

70204

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

85290

86291
class S3EventNotificationEventBridgeModel(EventBridgeModel): # type: ignore[override]
87292
detail: S3EventNotificationEventBridgeDetailModel
88293

89294

90295
class S3RecordModel(BaseModel):
91-
eventVersion: str
296+
eventVersion: str = Field(
297+
description="Version of the event message, with a major and minor version in the form <major>.<minor>.",
298+
examples=[
299+
"2.2",
300+
"1.9",
301+
],
302+
)
92303
eventSource: Literal["aws:s3"]
93-
awsRegion: str
94-
eventTime: datetime
95-
eventName: str
304+
awsRegion: str = Field(
305+
description="The AWS region where the event occurred.",
306+
examples=[
307+
"us-east-1",
308+
"eu-central-1",
309+
"ap-northeast-2",
310+
],
311+
)
312+
eventTime: datetime = Field(
313+
description="The time, in ISO-8601 format, for example, 1970-01-01T00:00:00.000Z, when Amazon S3 finished "
314+
"processing the request.",
315+
examples=[
316+
"1970-01-01T00:00:00.000Z",
317+
],
318+
)
319+
eventName: str = Field(
320+
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.",
321+
examples=[
322+
"ObjectCreated",
323+
"ObjectCreated:Put",
324+
"LifecycleExpiration:Delete",
325+
],
326+
)
96327
userIdentity: S3Identity
97328
requestParameters: S3RequestParameters
98329
responseElements: S3ResponseElements

0 commit comments

Comments
 (0)