Feature request: Improved documentation of Event model fields using description and examples

xkortex commented 1 month ago

Use case

It would be convenient if models for well-known types such as EventBridgeModel, which map to well-documented objects in the AWS API, to use Field(description=..., examples =...). This serves as a really useful refresher for acceptable values, and adds this metadata to .model_schema_json() (useful for swagger docs, model factories and the like). To show you what I mean, I whipped up this class really quick before realizing ALP had a EventBridgeModel class already.

BaseModel classes with description and examples

```python class AWSEvent(BaseModel): model_config = ConfigDict(extra='allow', alias_generator=snake_to_kebab) # version: str # Currently 0 (zero) for all events, there is no need to allocate it at this time. id: str = Field( description="A Version 4 UUID generated for every event.", examples=['17793124-05d4-b198-2fde-7ededc63b103'], ) account: str = Field( description="The 12-digit AWS account ID of the owner of the service emitting the event.", examples=['111122223333'], ) detail_type: str = Field( alias='detail-type', serialization_alias='detail-type', description="Identifies the type of event", examples=['Scheduled Event', 'Object Created'], ) source: str = Field( description="Identifies the service that generated the event", examples=['aws.s3', 'aws.events'], ) time: datetime = Field(description="The time the event occurred.", examples=['2006-01-02T15:04:05Z']) region: str = Field(description="Identifies the AWS Region the event originated.", examples=['us-east-1']) resources: list[str] = Field( description="A JSON array that contains the Amazon Resource Name (ARN) " "of service(s) that generated the event", examples=['arn:aws:s3:::amzn-s3-demo-bucket1', 'arn:aws:events:us-east-1:123456789012:rule/SampleRule'], ) detail: dict[str, Nested] = Field( description="A JSON object that contains information about the event. " "The service generating the event determines the content of this field." ) class S3ObjectEvent(AWSEvent): detail_type: str = Field( alias='detail-type', pattern='Object .+', examples=[ 'Object Created', 'Object Deleted', 'Object Restore Initiated', 'Object Restore Completed', 'Object Restore Expired', 'Object Tags Added', 'Object Tags Deleted', 'Object ACL Updated', 'Object Storage Class Changed', 'Object Access Tier Changed', ], ) source: Literal['aws.s3'] class ScheduledEvent(AWSEvent): detail_type: str = Field(alias='detail-type', pattern='Scheduled Event', examples=['Scheduled Event']) source: Literal['aws.events'] ```

I mostly pulled these right from AWS documentation pages like this. It might even be able to be autogenerated from botocore, not sure about that rabbit hole.

Solution/User Experience

Basically the example above but adapted for how you have EventBridgeModel and its children structured.

Alternative solutions

No response

Acknowledgment

[x] This feature request meets Powertools for AWS Lambda (Python) Tenets
[x] Should this be considered in other Powertools for AWS Lambda languages? i.e. Java, TypeScript, and .NET

boring-cyborg[bot] commented 1 month ago

Thanks for opening your first issue here! We'll come back to you as soon as we can. In the meantime, check out the #python channel on our Powertools for AWS Lambda Discord: Invite link

leandrodamascena commented 3 weeks ago

Hi @xkortex! This is a really good idea to improve our models with better documentation. We probably can't do this for all our models because some events are very generic, but EventBridge is definitely one of them. Let's start with EventBridge and evaluate others?

Just a note: we can change the models to use Fields, but we can't change the model name or the field name, ok?

If you are open to submitting a PR, please do so.

aws-powertools / powertools-lambda-python