Add documentation for additional events.

[jonathan343]

Overview

Our boto3 documentation website currently has a n Extensibility Guide which provides users an introduction and explanation of our event system in botocore/boto3. Despite botocore emitting various types of events, we currently only document 3 of them including creating-client-class, creating-resource-class, and provide-client-params. This PR adds the following:

• Additional documentation for the following events:
  • before-call
  • request-created
  • before-send
  • needs-retry
  • after-call
  • after-call-error
• A table providing the order in which all events are emitted along with a link to the location where they're emitted in code.

Testing

I ran make clean html to generate the html version of events.rstand inspected to ensure it was generated correctly.

Screenshot

[dlm6693]

Some initial comments/thoughts. I'll need to take another pass at it, but I did notice some inconsistent language to describe the same objects like AWSResponse. I think the wording should be exact and identical everywhere we write it.

[dlm6693]

Do we want to be advertising the injection of parameters that are not validated?

[jonemo]

It's also just not correct. I used the sample script from below in this section:

    import boto3

    s3 = boto3.client('s3')

    # Access the event system on the S3 client
    event_system = s3.meta.events

    # Create a function
    def add_my_bucket(params, **kwargs):
        # Add the name of the bucket you want to default to.
        if 'Bucket' not in params:
            params['Bucket'] = 'mybucket'

    # Register the function to an event
    event_system.register('before-parameter-build.s3.ListObjectsV2', add_my_bucket)

    response = s3.list_objects_v2()

... and then modified the S3 service model such that the bucket name has a minimum length of 20 characters. If this were correct, there would be no validation error with mybucket. Instead:

botocore.exceptions.ParamValidationError: Parameter validation failed:
Invalid length for parameter Bucket, value: 8, valid min length: 20

[dlm6693]

Yeah Jonas is right. Input parameter validation happens during serialization, which is called in BaseClient._convert_to_request_dict. before-parameter-build is fired in BaseClient._emit_api_params, which is called earlier.

Could be worth mentioning this event is fired just before endpoint resolution, but not necessary.

[dlm6693]

Suggested change

	:param params: A dictionary where the keys are the names of the
	parameters passed through the client method and the values are the values
	of those parameters.
	:param params: A dictionary containing key value pairs consisting of the parameters passed through to the client method.

[jonemo]

Couple of comments on phrasing and such, but most importantly:

1. All statements about whether events occur before or after parameter validation need fact checking.
2. Usage of "request parameters" throughout the doc needs to be cleaned up to avoid confusion between operation params and the request dict.

[jonemo]

It's also just not correct. I used the sample script from below in this section:

    import boto3

    s3 = boto3.client('s3')

    # Access the event system on the S3 client
    event_system = s3.meta.events

    # Create a function
    def add_my_bucket(params, **kwargs):
        # Add the name of the bucket you want to default to.
        if 'Bucket' not in params:
            params['Bucket'] = 'mybucket'

    # Register the function to an event
    event_system.register('before-parameter-build.s3.ListObjectsV2', add_my_bucket)

    response = s3.list_objects_v2()

... and then modified the S3 service model such that the bucket name has a minimum length of 20 characters. If this were correct, there would be no validation error with mybucket. Instead:

botocore.exceptions.ParamValidationError: Parameter validation failed:
Invalid length for parameter Bucket, value: 8, valid min length: 20

[Frederik-Baetens]

There's also a before-sign. Is there any point in documenting that?

[dlm6693]

Just a couple of minor things to address. Once fixed I think this will be good to merge.

[dlm6693]

📦