aws-powertools/powertools-lambda-python

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

Closed this issue · 5 comments

xkortex commented

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 
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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ev-events.html). It might even be able to be autogenerated from botocore, not sure about that rabbit hole.

See also
#5476

Solution/User Experience

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

Alternative solutions

No response

Acknowledgment

boring-cyborg commented

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

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.

leandrodamascena commented

Hi @xkortex! I've started changing the models to include those fields.

leandrodamascena commented

Hi @xkortex, we've completed all the tasks and our models now contain descriptions and examples. Thanks for opening this issue.

powertools-for-aws-oss-automation commented

Warning

This issue is now closed. Please be mindful that future comments are hard for our team to see.
If you need more assistance, please either reopen the issue, or open a new issue referencing this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.