From f8390c3dc8d7e5fe414ef8eccf77fe6b2685b682 Mon Sep 17 00:00:00 2001 From: jonathan343 Date: Thu, 27 Apr 2023 23:00:43 -0700 Subject: [PATCH 1/4] Add documentation for additional events. --- docs/source/guide/events.rst | 513 ++++++++++++++++++++++++++++++++--- 1 file changed, 475 insertions(+), 38 deletions(-) diff --git a/docs/source/guide/events.rst b/docs/source/guide/events.rst index d97261c861..14b9a24ab5 100644 --- a/docs/source/guide/events.rst +++ b/docs/source/guide/events.rst @@ -40,15 +40,15 @@ Here is an example of how the event system works:: params['Bucket'] = 'mybucket' # Register the function to an event - event_system.register('provide-client-params.s3.ListObjects', add_my_bucket) + event_system.register('provide-client-params.s3.ListObjectsV2', add_my_bucket) - response = s3.list_objects() + response = s3.list_objects_v2() In this example, the handler ``add_my_bucket`` is registered such that the handler will inject the value ``'mybucket`` for the ``Bucket`` parameter whenever the -``list_objects`` client call is made without the ``Bucket`` parameter. Note -that if the same ``list_objects`` call is made without the ``Bucket`` +``list_objects_v2`` client call is made without the ``Bucket`` parameter. Note +that if the same ``list_objects_v2`` call is made without the ``Bucket`` parameter and the registered handler, it will result in a validation error. Here are the takeaways from this example: @@ -68,7 +68,7 @@ Here are the takeaways from this example: function to and the function handle. Note that if you register the event after the event is emitted, the function will not be called unless the event is emitted again. In the example, the ``add_my_bucket`` handler - was registered to the ``'provide-client-params.s3.ListObjects'`` event, + was registered to the ``'provide-client-params.s3.ListObjectsV2'`` event, which is an event that can be used to inject and modify parameters passed in by the client method. To read more about the event refer to `provide-client-params`_ @@ -110,15 +110,15 @@ its hierarchical structure:: params['Bucket'] = 'myspecificbucket' event_system.register('provide-client-params.s3', add_my_general_bucket) - event_system.register('provide-client-params.s3.ListObjects', add_my_specific_bucket) + event_system.register('provide-client-params.s3.ListObjectsV2', add_my_specific_bucket) - list_obj_response = s3.list_objects() + list_obj_response = s3.list_objects_v2() put_obj_response = s3.put_object(Key='mykey', Body=b'my body') -In this example, the ``list_objects`` method call will use the +In this example, the ``list_objects_v2`` method call will use the ``'myspecificbucket'`` for the bucket instead of ``'mybucket'`` because the ``add_my_specific_bucket`` method was registered to the -``'provide-client-params.s3.ListObjects'`` event which is more specific than +``'provide-client-params.s3.ListObjectsV2'`` event which is more specific than the ``'provide-client-params.s3'`` event. Thus, the ``add_my_specific_bucket`` function is called before the ``add_my_general_bucket`` function is called when the event is emitted. @@ -127,7 +127,7 @@ However for the ``put_object`` call, the bucket used is ``'mybucket'``. This is because the event emitted for the ``put_object`` client call is ``'provide-client-params.s3.PutObject'`` and the ``add_my_general_bucket`` method is called via its registration to ``'provide-client-params.s3'``. The -``'provide-client-params.s3.ListObjects'`` event is never emitted so the +``'provide-client-params.s3.ListObjectsV2'`` event is never emitted so the registered ``add_my_specific_bucket`` function is never called. @@ -150,7 +150,7 @@ of using wildcards in the event system:: params['Bucket'] = 'mybucket' event_system.register('provide-client-params.s3.*', add_my_wildcard_bucket) - response = s3.list_objects() + response = s3.list_objects_v2() The ``'*'`` allows you to register to a group of events without having to @@ -191,17 +191,17 @@ to another client's event system:: params['Bucket'] = 'myotherbucket' client1.meta.events.register( - 'provide-client-params.s3.ListObjects', add_my_bucket) + 'provide-client-params.s3.ListObjectsV2', add_my_bucket) client2.meta.events.register( - 'provide-client-params.s3.ListObjects', add_my_other_bucket) + 'provide-client-params.s3.ListObjectsV2', add_my_other_bucket) - client1_response = client1.list_objects() - client2_response = client2.list_objects() + client1_response = client1.list_objects_v2() + client2_response = client2.list_objects_v2() Thanks to the isolation of clients' event systems, ``client1`` will inject -``'mybucket'`` for its ``list_objects`` method call while ``client2`` will -inject ``'myotherbucket'`` for its ``list_objects`` method call because +``'mybucket'`` for its ``list_objects_v2`` method call while ``client2`` will +inject ``'myotherbucket'`` for its ``list_objects_v2`` method call because ``add_my_bucket`` was registered to ``client1`` while ``add_my_other_bucket`` was registered to ``client2``. @@ -212,11 +212,43 @@ Boto3 specific events Boto3 emits a set of events that users can register to customize clients or resources and modify the behavior of method calls. -Here is the list of events that users of Boto3 can register handlers to: - -* ``'creating-client-class'`` -* ``'creating-resource-class'`` -* ``'provide-client-params'`` +Below is a table of events that users of Boto3 can register handlers to. More information +about each event can be found in the corresponding sections below: + ++-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ +| Event Name | Order | Emit Location | ++=============================+=======+======================================================================================================================================+ +| ``creating-client-class`` | 1 | `Location `_ | ++-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ +| ``creating-resource-class`` | 2 * | `Location `_ | ++-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ +| ``provide-client-params`` | 2 * | `Location `_ | ++-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ +| ``before-parameter-build`` | 3 | `Location `_ | ++-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ +| ``before-call`` | 4 | `Location `_ | ++-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ +| ``request-created`` | 5 | `Location `_ | ++-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ +| ``before-send`` | 6 | `Location `_ | ++-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ +| ``needs-retry`` | 7 | `Location `_ | ++-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ +| ``after-call`` | 8 * | `Location `_ | ++-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ +| ``after-call-error`` | 8 * | `Location `_ | ++-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ + +.. note:: + + Events with a \* in their order number are conditionally emitted while all others are always emitted. + An explination of all 4 conditional events is provided below. + + ``2 *`` - ``creating-resource-class`` is emitted when using a service resource and + ``provide-client-params`` is emitted when using a service client. + + ``8 *`` - ``after-call`` is emitted when a successful API response is received + and ``after-call-error`` is emitted when an error is received. `creating-client-class` @@ -225,8 +257,10 @@ Here is the list of events that users of Boto3 can register handlers to: :Full Event Name: ``'creating-client-class.service-name'`` - Note: ``service-name`` refers to the value used to instantiate a client i.e. - ``boto3.client('service-name')`` + .. note:: + + ``service-name`` refers to the value used to instantiate a client i.e. + ``boto3.client('service-name')`` :Description: This event is emitted upon creation of the client class for a service. The @@ -245,7 +279,7 @@ Here is the list of events that users of Boto3 can register handlers to: :param base_classes: A list of classes that the client class will inherit from where the order of inheritance is the same as the order of the list. -:Expected Return Value: Do not return anything. +:Expected Return Value: ``None`` :Example: Here is an example of how to add a method to the client class:: @@ -298,9 +332,12 @@ Here is the list of events that users of Boto3 can register handlers to: :Full Event Name: ``'creating-resource-class.service-name.resource-name'`` - Note: ``service-name`` refers to the value used to instantiate a service - resource i.e. ``boto3.resource('service-name')`` and ``resource-name`` - refers to the name of the resource class. + .. note:: + + ``service-name`` refers to the value used to instantiate a service + resource i.e. ``boto3.resource('service-name')`` and ``resource-name`` + refers to the name of the resource class. + :Description: This event is emitted upon creation of the resource class. The @@ -319,7 +356,7 @@ Here is the list of events that users of Boto3 can register handlers to: :param base_classes: A list of classes that the resource class will inherit from where the order of inheritance is the same as the order of the list. -:Expected Return Value: Do not return anything. +:Expected Return Value: ``None`` :Example: Here is an example of how to add a method to a resource class:: @@ -374,12 +411,12 @@ Here is the list of events that users of Boto3 can register handlers to: :Full Event Name: ``'provide-client-params.service-name.operation-name'`` - Note: ``service-name`` refers to the value used to instantiate a client i.e. - ``boto3.client('service-name')``. ``operation-name`` refers to the - underlying API operation of the corresponding client method. To access - the operation API name, retrieve the value from the - ``client.meta.method_to_api_mapping`` dictionary using the name of the - desired client method as the key. + .. note:: + + ``service-name`` refers to the value used to instantiate a client i.e. + ``boto3.client('service-name')``. ``operation-name`` refers to the + underlying API operation name of the corresponding client method. + :Description: This event is emitted before validation of the parameters passed to @@ -398,7 +435,7 @@ Here is the list of events that users of Boto3 can register handlers to: :param model: A model representing the underlying API operation of the client method. -:Expected Return Value: Do not return anything or return a new dictionary of +:Expected Return Value: ``None`` or return a new dictionary of parameters to use when making the request. :Example: @@ -418,7 +455,407 @@ Here is the list of events that users of Boto3 can register handlers to: params['Bucket'] = 'mybucket' # Register the function to an event - event_system.register('provide-client-params.s3.ListObjects', add_my_bucket) + event_system.register('provide-client-params.s3.ListObjectsV2', add_my_bucket) + + response = s3.list_objects_v2() + + +`before-parameter-build` +~~~~~~~~~~~~~~~~~~~~~ + +:Full Event Name: + ``'before-parameter-build.service-name.operation-name'`` + + .. note:: + + ``service-name`` refers to the value used to instantiate a client i.e. + ``boto3.client('service-name')``. ``operation-name`` refers to the + underlying API operation name of the corresponding client method. + + +:Description: + This event is emitted before the API request parameters are built. + Use this event to inject or modify parameters after they're validated + and built into a request that is sent over the wire. + +:Keyword Arguments Emitted: + + :type params: dict + :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. + + :type model: ``botocore.model.OperationModel`` + :param model: A model representing the underlying API operation of the + client method. + +:Expected Return Value: ``None`` + +:Example: + Here is an example of how to inject a parameter using the event:: + + 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() + + +`before-call` +~~~~~~~~~~~~~~~~~~~~~ + +:Full Event Name: + ``'before-call.service-name.operation-name'`` + + .. note:: + + ``service-name`` refers to the value used to instantiate a client i.e. + ``boto3.client('service-name')``. ``operation-name`` refers to the + underlying API operation name of the corresponding client method. + + + +:Description: + This event is emitted just before creating the HTTP request and allows you to + modify request parameters prior to the request being created. + +:Keyword Arguments Emitted: + + :type model: ``botocore.model.OperationModel`` + :param model: A model representing the underlying API operation of the + client method. + + :type params: dict + :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. + + :type request_signer: ``botocore.signers.RequestSigner`` + :param request_signer: An object to sign requests before they go out over + the wire using one of the authentication mechanisms defined in ``auth.py``. + +:Expected Return Value: ``None`` + +:Example: + Here is an example of how to add an additional header before making an API call:: + + from boto3.session import Session + + def add_fake_header_before_call(model, params, request_signer, **kwargs): + params['headers']['fake-header'] = 'fake-info' + headers = params['headers'] + print(f'param headers: {headers}') + + + session = Session() + session.events.register('before-call.s3.ListBuckets', add_fake_header_before_call) + + client = session.client('s3') + client.list_buckets() + + This should output:: + + param headers: {..., 'fake-header': 'fake-info'} + + +`request-created` +~~~~~~~~~~~~~~~~~~~~~ + +:Full Event Name: + ``'request-created.service-name.operation-name'`` + + .. note:: + + ``service-name`` refers to the value used to instantiate a client i.e. + ``boto3.client('service-name')``. ``operation-name`` refers to the + underlying API operation name of the corresponding client method. + + + +:Description: + This event is emitted just after the request is created and before seralization or + signing is done. + +:Keyword Arguments Emitted: + + :type request: ``botocore.awsrequest.AWSRequest`` + :param request: An AWSRequest object which represents the request that was + created given some params and an operation model. + + :type operation_name: str + :param operation_name: The name of the service operation model i.e. `ListObjectsV2`. + +:Expected Return Value: ``None`` + +:Example: + Here is an example of how to inspect the request once it's created:: + + from boto3.session import Session + + def inspect_request_created(request, operation_name, **kwargs): + print('Request Info:') + print(f'method: {request.method}') + print(f'url: {request.url}') + print(f'data: {request.data}') + print(f'params: {request.params}') + print(f'auth_path: {request.auth_path}') + print(f'stream_output: {request.stream_output}') + print(f'headers: {request.headers}') + print(f'operation_name: {operation_name}') + + + session = Session() + session.events.register('request-created.s3.ListObjectsV2', inspect_request_created) + + client = session.client('s3') + client.list_objects_v2(Bucket='my-bucket') + + This should output:: + + Request Info: + method: GET + url: https://my-bucket.s3... + data: b'...' + params: {...} + auth_path: ... + stream_output: ... + headers: ... + + Operation Info: + operation_name: ListObjectsV2 - response = s3.list_objects() +`before-send` +~~~~~~~~~~~~~~~~~~~~~ + +:Full Event Name: + ``'before-send.service-name.operation-name'`` + + .. note:: + + ``service-name`` refers to the value used to instantiate a client i.e. + ``boto3.client('service-name')``. ``operation-name`` refers to the + underlying API operation name of the corresponding client method. + + +:Description: + This event is emitted when the operation has been fully serialized, signed, + and is ready to be sent across the wire. This event allows the finalized + request to be inspected and allows a response to be returned that fufills + the request. If no response is returned botocore will fulfill the request + as normal. + +:Keyword Arguments Emitted: + + :type request: ``botocore.awsrequest.AWSPreparedRequest`` + :param request: An object representing the properties of an HTTP request. + +:Expected Return Value: ``None`` or an instance of :class:`.AWSResponse` + +:Example: + Here is an example of how to register a function that allows you to inspect + the prepared request before it's sent:: + + from boto3.session import Session + + def inspect_request_before_send(request, **kwargs): + print(f'request:\n{request}') + + + session = Session() + session.events.register('before-send.s3.ListBuckets', inspect_request_before_send) + + client = session.client('s3') + client.list_buckets() + + This should output:: + + request: + + + +`needs-retry` +~~~~~~~~~~~~~~~~~~~~~~~ + +:Full Event Name: + ``'needs-retry.service-name.operation-name'`` + + .. note:: + + ``service-name`` refers to the value used to instantiate a client i.e. + ``boto3.client('service-name')``. ``operation-name`` refers to the + underlying API operation name of the corresponding client method. + + +:Description: + This event is emitted before checking if the most recent request needs to be retried. + Catching this event allows developers to customize retry behavior according to the + specific requirements of their application, rather than relying solely on Boto3's + default settings for retries. + +:Keyword Arguments Emitted: + + :type response: tuple + :param response: A tuple that includes both the ``botocore.awsrequest.AWSResponse`` + and a dict that represents the parsed version of the response. + + :type endpoint: ``botocore.endpoint.Endpoint`` + :param endpoint: Represents an endpoint for a particular service in a specific + region. + + :type operation: ``botocore.model.OperationModel`` + :param operation: A model representing the underlying API operation of the + client method. + + :type attempts: int + :param attempts: A number representing the amount of retries that have been attempted. + + :type caught_exception: ``Exception`` + :param caught_exception: The exception raised after making an api call. If there was no + exception, this will be None. + + :type request_dict: dict + :param request_dict: A dictionary containing information related to the attempted API request. + +:Expected Return Value: Return ``None`` if no retry is needed, or return an ``int`` representing the retry delay. + +:Example: + Here is an example of how to add a method to a resource class:: + + from boto3.session import Session + + def needs_retry_handler(**kwargs): + # Implement custom retry logic + if some_condition: + return None + else: + return some_delay + + session = Session() + session.events.register('needs-retry', needs_retry_handler) + + client = session.client('s3') + client.list_buckets() + + +`after-call` +~~~~~~~~~~~~~~~~~~~~~ + +:Full Event Name: + ``'after-call.service-name.operation-name'`` + + .. note:: + + ``service-name`` refers to the value used to instantiate a client i.e. + ``boto3.client('service-name')``. ``operation-name`` refers to the + underlying API operation name of the corresponding client method. + + +:Description: + This event is emitted just after the service client makes an API call. + This event allows developers to post process or inspect the API response according to the + specific requirements of their application if needed. + +:Keyword Arguments Emitted: + + :type http_response: ``botocore.awsrequest.AWSResponse`` + :param http_response: A data class representing an HTTP response received from the server. + + :type parsed: dict + :param params: A parsed version of the AWSResponse in the form of + a python dictionary. + + :type model: ``botocore.model.OperationModel`` + :param model: A model representing the underlying API operation of the + client method. + +:Expected Return Value: ``None`` + +:Example: + Here is an example that inspects args emitted from the ``after-call`` event:: + + from boto3.session import Session + + def print_after_call_args(http_response, parsed, model, **kwargs): + print(f'http_response:\n{http_response.text}') + print(f'\nparsed:\n{parsed}') + print(f'\nmodel:\n{model.name}') + + session = Session() + session.events.register('after-call.s3.ListObjectsV2', print_after_call_args) + + client = session.client('s3') + client.list_objects_v2(Bucket='my-bucket') + + This should output:: + + http_response: + ... + + parsed: + ... + + model: + ListObjectsV2 + + +`after-call-error` +~~~~~~~~~~~~~~~~~~~~~ + +:Full Event Name: + ``'after-call-error.service-name.operation-name'`` + + .. note:: + + ``service-name`` refers to the value used to instantiate a client i.e. + ``boto3.client('service-name')``. ``operation-name`` refers to the + underlying API operation name of the corresponding client method. + + +:Description: + This event is emitted upon receiving an error after making an API call. + This event provides information about any errors encountered during the + operation and allows listeners to take corrective actions if necessary. + +:Keyword Arguments Emitted: + + :type exception: ``Exception`` + :param exception: The exception raised after making an api call. + +:Expected Return Value: ``None`` + +:Example: + Here is an example we use the ``before-send`` to mimic a bad response which + triggers the ``after-call-error`` event and prints the exception:: + + from boto3.session import Session + + def print_after_call_error_args(exception, **kwargs): + print(f'exception: {exception}') + + def list_objects_v2_bad_response(**kwargs): + raise Exception("This is a test exception.") + + session = Session() + session.events.register('before-send.s3.ListBuckets', list_objects_v2_bad_response) + session.events.register('after-call-error.s3.ListBuckets', print_after_call_error_args) + + client = session.client('s3') + client.list_buckets() + + This should output:: + + exception: This is a test exception. + # Stack Trace From 474838462a357b421ba42ba35bb09101d6c5dbf2 Mon Sep 17 00:00:00 2001 From: jonathan343 Date: Mon, 10 Jul 2023 11:10:24 -0700 Subject: [PATCH 2/4] Addressed all PR feedback. --- docs/source/guide/events.rst | 413 ++++++++++++++--------------------- 1 file changed, 165 insertions(+), 248 deletions(-) diff --git a/docs/source/guide/events.rst b/docs/source/guide/events.rst index 14b9a24ab5..14887eb1e3 100644 --- a/docs/source/guide/events.rst +++ b/docs/source/guide/events.rst @@ -46,7 +46,7 @@ Here is an example of how the event system works:: In this example, the handler ``add_my_bucket`` is registered such that the handler will inject the -value ``'mybucket`` for the ``Bucket`` parameter whenever the +value ``'mybucket'`` for the ``Bucket`` parameter whenever the ``list_objects_v2`` client call is made without the ``Bucket`` parameter. Note that if the same ``list_objects_v2`` call is made without the ``Bucket`` parameter and the registered handler, it will result in a validation error. @@ -212,44 +212,52 @@ Boto3 specific events Boto3 emits a set of events that users can register to customize clients or resources and modify the behavior of method calls. -Below is a table of events that users of Boto3 can register handlers to. More information +Here is a table of events that users of Boto3 can register handlers to. More information about each event can be found in the corresponding sections below: -+-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ -| Event Name | Order | Emit Location | -+=============================+=======+======================================================================================================================================+ -| ``creating-client-class`` | 1 | `Location `_ | -+-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ -| ``creating-resource-class`` | 2 * | `Location `_ | -+-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ -| ``provide-client-params`` | 2 * | `Location `_ | -+-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ -| ``before-parameter-build`` | 3 | `Location `_ | -+-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ -| ``before-call`` | 4 | `Location `_ | -+-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ -| ``request-created`` | 5 | `Location `_ | -+-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ -| ``before-send`` | 6 | `Location `_ | -+-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ -| ``needs-retry`` | 7 | `Location `_ | -+-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ -| ``after-call`` | 8 * | `Location `_ | -+-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ -| ``after-call-error`` | 8 * | `Location `_ | -+-----------------------------+-------+--------------------------------------------------------------------------------------------------------------------------------------+ - .. note:: - Events with a \* in their order number are conditionally emitted while all others are always emitted. - An explination of all 4 conditional events is provided below. + Events with a ``*`` in their order number are conditionally emitted while all others are always emitted. + An explanation of all 4 conditional events is provided below. - ``2 *`` - ``creating-resource-class`` is emitted when using a service resource and - ``provide-client-params`` is emitted when using a service client. + ``2 *`` - ``creating-resource-class`` is emitted ONLY when using a service resource. ``8 *`` - ``after-call`` is emitted when a successful API response is received and ``after-call-error`` is emitted when an error is received. ++-----------------------------+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+ +| Event Name | Order | Emit Location | ++=============================+=======+===============================================================================================================================================+ +| ``creating-client-class`` | 1 | `Location `_ | ++-----------------------------+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+ +| ``creating-resource-class`` | 2 * | `Location `_ | ++-----------------------------+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+ +| ``provide-client-params`` | 3 | `Location `_ | ++-----------------------------+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+ +| ``before-call`` | 4 | `Location `_ | ++-----------------------------+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+ +| ``request-created`` | 5 | `Location `_ | ++-----------------------------+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+ +| ``before-send`` | 6 | `Location `_ | ++-----------------------------+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+ +| ``needs-retry`` | 7 | `Location `_ | ++-----------------------------+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+ +| ``after-call`` | 8 * | `Location `_ | ++-----------------------------+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+ +| ``after-call-error`` | 8 * | `Location `_ | ++-----------------------------+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+ + +.. note:: + If any of the following keywords are included in an event's Full Event Name, you'll need + to replace it with the corresponding value: + + * ``service-name`` - The value used to instantiate a client as in ``boto3.client('service-name')``. + * ``operation-name`` - The underlying API operation name of the corresponding client method. To access + the operation API name, retrieve the value from the ``client.meta.method_to_api_mapping`` dictionary + using the name of the desired client method as the key. + * ``resource-name`` - The name of the resource class such as ``ServiceResource``. + + `creating-client-class` ~~~~~~~~~~~~~~~~~~~~~ @@ -257,11 +265,6 @@ about each event can be found in the corresponding sections below: :Full Event Name: ``'creating-client-class.service-name'`` - .. note:: - - ``service-name`` refers to the value used to instantiate a client i.e. - ``boto3.client('service-name')`` - :Description: This event is emitted upon creation of the client class for a service. The client class for a service is not created until the first instantiation of @@ -332,13 +335,6 @@ about each event can be found in the corresponding sections below: :Full Event Name: ``'creating-resource-class.service-name.resource-name'`` - .. note:: - - ``service-name`` refers to the value used to instantiate a service - resource i.e. ``boto3.resource('service-name')`` and ``resource-name`` - refers to the name of the resource class. - - :Description: This event is emitted upon creation of the resource class. The resource class is not created until the first instantiation of @@ -411,25 +407,16 @@ about each event can be found in the corresponding sections below: :Full Event Name: ``'provide-client-params.service-name.operation-name'`` - .. note:: - - ``service-name`` refers to the value used to instantiate a client i.e. - ``boto3.client('service-name')``. ``operation-name`` refers to the - underlying API operation name of the corresponding client method. - - :Description: - This event is emitted before validation of the parameters passed to - client method. Use this event to inject or modify parameters prior - to the parameters being validated and built into a request that is sent - over the wire. + This event is emitted before operation parameters are validated and built + into the HTTP request that will be sent over the wire. Use this event to + inject or modify parameters. :Keyword Arguments Emitted: :type params: dict - :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. :type model: ``botocore.model.OperationModel`` :param model: A model representing the underlying API operation of the @@ -460,76 +447,19 @@ about each event can be found in the corresponding sections below: response = s3.list_objects_v2() -`before-parameter-build` -~~~~~~~~~~~~~~~~~~~~~ - -:Full Event Name: - ``'before-parameter-build.service-name.operation-name'`` - - .. note:: - - ``service-name`` refers to the value used to instantiate a client i.e. - ``boto3.client('service-name')``. ``operation-name`` refers to the - underlying API operation name of the corresponding client method. - - -:Description: - This event is emitted before the API request parameters are built. - Use this event to inject or modify parameters after they're validated - and built into a request that is sent over the wire. - -:Keyword Arguments Emitted: - - :type params: dict - :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. - - :type model: ``botocore.model.OperationModel`` - :param model: A model representing the underlying API operation of the - client method. - -:Expected Return Value: ``None`` - -:Example: - Here is an example of how to inject a parameter using the event:: - - 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() - - `before-call` ~~~~~~~~~~~~~~~~~~~~~ :Full Event Name: ``'before-call.service-name.operation-name'`` - .. note:: - - ``service-name`` refers to the value used to instantiate a client i.e. - ``boto3.client('service-name')``. ``operation-name`` refers to the - underlying API operation name of the corresponding client method. - - - :Description: - This event is emitted just before creating the HTTP request and allows you to - modify request parameters prior to the request being created. + This event is emitted just before creating and sending the HTTP request. + Use this event for modifying various HTTP request components prior to the request + being created. A response tuple may optionally be returned to trigger a short-circuit + and prevent the request from being made. This is useful for testing and is how the + `botocore stubber `_ + mocks responses. :Keyword Arguments Emitted: @@ -538,36 +468,41 @@ about each event can be found in the corresponding sections below: client method. :type params: dict - :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 for various components of + an HTTP request such as ``url_path``, ``host_prefix``, ``query_string``, ``headers``, + ``body``, and ``method``. :type request_signer: ``botocore.signers.RequestSigner`` - :param request_signer: An object to sign requests before they go out over + :param request_signer: An object to sign requests before they are sent over the wire using one of the authentication mechanisms defined in ``auth.py``. -:Expected Return Value: ``None`` +:Expected Return Value: ``None`` or a ``tuple`` that includes both the ``botocore.awsrequest.AWSResponse`` + and a ``dict`` that represents the parsed response described by the model. :Example: - Here is an example of how to add an additional header before making an API call:: + Here is an example of how to add a custom header before making an API call:: - from boto3.session import Session + import boto3 + + s3 = boto3.client('s3') + + # Access the event system on the S3 client + event_system = s3.meta.events - def add_fake_header_before_call(model, params, request_signer, **kwargs): - params['headers']['fake-header'] = 'fake-info' + # Create a function that adds a custom header and prints all headers. + def add_custom_header_before_call(model, params, request_signer, **kwargs): + params['headers']['my-custom-header'] = 'header-info' headers = params['headers'] print(f'param headers: {headers}') + # Register the function to an event. + event_system.register('before-call.s3.ListBuckets', add_custom_header_before_call) - session = Session() - session.events.register('before-call.s3.ListBuckets', add_fake_header_before_call) - - client = session.client('s3') - client.list_buckets() + s3.list_buckets() This should output:: - param headers: {..., 'fake-header': 'fake-info'} + param headers: { ... , 'my-custom-header': 'header-info'} `request-created` @@ -576,17 +511,8 @@ about each event can be found in the corresponding sections below: :Full Event Name: ``'request-created.service-name.operation-name'`` - .. note:: - - ``service-name`` refers to the value used to instantiate a client i.e. - ``boto3.client('service-name')``. ``operation-name`` refers to the - underlying API operation name of the corresponding client method. - - - :Description: - This event is emitted just after the request is created and before seralization or - signing is done. + This event is emitted just after the request is created and triggers request signing. :Keyword Arguments Emitted: @@ -595,15 +521,21 @@ about each event can be found in the corresponding sections below: created given some params and an operation model. :type operation_name: str - :param operation_name: The name of the service operation model i.e. `ListObjectsV2`. + :param operation_name: The name of the service operation model i.e. ``ListObjectsV2``. :Expected Return Value: ``None`` :Example: Here is an example of how to inspect the request once it's created:: - from boto3.session import Session + import boto3 + + s3 = boto3.client('s3') + # Access the event system on the S3 client + event_system = s3.meta.events + + # Create a function that prints the request information. def inspect_request_created(request, operation_name, **kwargs): print('Request Info:') print(f'method: {request.method}') @@ -615,26 +547,22 @@ about each event can be found in the corresponding sections below: print(f'headers: {request.headers}') print(f'operation_name: {operation_name}') + # Register the function to an event + event_system.register('request-created.s3.ListObjectsV2', inspect_request_created) - session = Session() - session.events.register('request-created.s3.ListObjectsV2', inspect_request_created) - - client = session.client('s3') - client.list_objects_v2(Bucket='my-bucket') + response = s3.list_objects_v2(Bucket='my-bucket') This should output:: Request Info: - method: GET - url: https://my-bucket.s3... - data: b'...' - params: {...} - auth_path: ... - stream_output: ... - headers: ... - - Operation Info: - operation_name: ListObjectsV2 + method: GET + url: https://my-bucket.s3 ... + data: ... + params: { ... } + auth_path: ... + stream_output: ... + headers: ... + operation_name: ListObjectsV2 `before-send` @@ -643,47 +571,43 @@ about each event can be found in the corresponding sections below: :Full Event Name: ``'before-send.service-name.operation-name'`` - .. note:: - - ``service-name`` refers to the value used to instantiate a client i.e. - ``boto3.client('service-name')``. ``operation-name`` refers to the - underlying API operation name of the corresponding client method. - - :Description: This event is emitted when the operation has been fully serialized, signed, - and is ready to be sent across the wire. This event allows the finalized - request to be inspected and allows a response to be returned that fufills + and is ready to be sent over the wire. This event allows the finalized + request to be inspected and allows a response to be returned that fulfills the request. If no response is returned botocore will fulfill the request as normal. :Keyword Arguments Emitted: :type request: ``botocore.awsrequest.AWSPreparedRequest`` - :param request: An object representing the properties of an HTTP request. + :param request: A data class representing a finalized request to be sent over the wire. -:Expected Return Value: ``None`` or an instance of :class:`.AWSResponse` +:Expected Return Value: ``None`` or an instance of ``botocore.awsrequest.AWSResponse``. :Example: Here is an example of how to register a function that allows you to inspect the prepared request before it's sent:: - from boto3.session import Session + import boto3 - def inspect_request_before_send(request, **kwargs): - print(f'request:\n{request}') + s3 = boto3.client('s3') + # Access the event system on the S3 client + event_system = s3.meta.events - session = Session() - session.events.register('before-send.s3.ListBuckets', inspect_request_before_send) + # Create a function that inspects the prepared request. + def inspect_request_before_send(request, **kwargs): + print(f'request: {request}') - client = session.client('s3') - client.list_buckets() + # Register the function to an event + event_system.register('before-send.s3.ListBuckets', inspect_request_before_send) + + s3.list_buckets() This should output:: - request: - + request: `needs-retry` @@ -692,28 +616,20 @@ about each event can be found in the corresponding sections below: :Full Event Name: ``'needs-retry.service-name.operation-name'`` - .. note:: - - ``service-name`` refers to the value used to instantiate a client i.e. - ``boto3.client('service-name')``. ``operation-name`` refers to the - underlying API operation name of the corresponding client method. - - :Description: This event is emitted before checking if the most recent request needs to be retried. - Catching this event allows developers to customize retry behavior according to the - specific requirements of their application, rather than relying solely on Boto3's - default settings for retries. + Use this event to define custom retry behavior when the configurable + `retry modes `_ + are not sufficient. :Keyword Arguments Emitted: :type response: tuple :param response: A tuple that includes both the ``botocore.awsrequest.AWSResponse`` - and a dict that represents the parsed version of the response. + and a ``dict`` that represents the parsed response described by the model. :type endpoint: ``botocore.endpoint.Endpoint`` - :param endpoint: Represents an endpoint for a particular service in a specific - region. + :param endpoint: Represents an endpoint for a particular service. :type operation: ``botocore.model.OperationModel`` :param operation: A model representing the underlying API operation of the @@ -722,32 +638,40 @@ about each event can be found in the corresponding sections below: :type attempts: int :param attempts: A number representing the amount of retries that have been attempted. - :type caught_exception: ``Exception`` + :type caught_exception: ``Exception`` | ``None``` :param caught_exception: The exception raised after making an api call. If there was no exception, this will be None. :type request_dict: dict - :param request_dict: A dictionary containing information related to the attempted API request. + :param request_dict: A dictionary containing key value pairs for various components of + an HTTP request such as ``url_path``, ``host_prefix``, ``query_string``, ``headers``, + ``body``, and ``method``. -:Expected Return Value: Return ``None`` if no retry is needed, or return an ``int`` representing the retry delay. +:Expected Return Value: Return ``None`` if no retry is needed, or return an ``int`` representing the + retry delay in seconds. :Example: - Here is an example of how to add a method to a resource class:: + Here is an example of how to add custom retry behavior:: - from boto3.session import Session + import boto3 - def needs_retry_handler(**kwargs): - # Implement custom retry logic - if some_condition: - return None - else: - return some_delay + s3 = boto3.client('s3') - session = Session() - session.events.register('needs-retry', needs_retry_handler) + # Access the event system on the S3 client + event_system = s3.meta.events - client = session.client('s3') - client.list_buckets() + # Create a handler that determines retry behavior. + def needs_retry_handler(**kwargs): + # Implement custom retry logic + if some_condition: + return None + else: + return some_delay + + # Register the function to an event + event_system.register('needs-retry', needs_retry_handler) + + s3.list_buckets() `after-call` @@ -756,16 +680,9 @@ about each event can be found in the corresponding sections below: :Full Event Name: ``'after-call.service-name.operation-name'`` - .. note:: - - ``service-name`` refers to the value used to instantiate a client i.e. - ``boto3.client('service-name')``. ``operation-name`` refers to the - underlying API operation name of the corresponding client method. - - :Description: This event is emitted just after the service client makes an API call. - This event allows developers to post process or inspect the API response according to the + This event allows developers to postprocess or inspect the API response according to the specific requirements of their application if needed. :Keyword Arguments Emitted: @@ -786,29 +703,29 @@ about each event can be found in the corresponding sections below: :Example: Here is an example that inspects args emitted from the ``after-call`` event:: - from boto3.session import Session + import boto3 - def print_after_call_args(http_response, parsed, model, **kwargs): - print(f'http_response:\n{http_response.text}') - print(f'\nparsed:\n{parsed}') - print(f'\nmodel:\n{model.name}') + s3 = boto3.client('s3') - session = Session() - session.events.register('after-call.s3.ListObjectsV2', print_after_call_args) + # Access the event system on the S3 client + event_system = s3.meta.events - client = session.client('s3') - client.list_objects_v2(Bucket='my-bucket') + # Create a function that prints the after-call event args. + def print_after_call_args(http_response, parsed, model, **kwargs): + print(f'http_response: {http_response}') + print(f'parsed: {parsed}') + print(f'model: {model.name}') - This should output:: + # Register the function to an event + event_system.register('after-call.s3.ListObjectsV2', print_after_call_args) - http_response: - ... + s3.list_objects_v2(Bucket='my-bucket') - parsed: - ... + This should output:: - model: - ListObjectsV2 + http_response: + parsed: { ... } + model: ListObjectsV2 `after-call-error` @@ -817,13 +734,6 @@ about each event can be found in the corresponding sections below: :Full Event Name: ``'after-call-error.service-name.operation-name'`` - .. note:: - - ``service-name`` refers to the value used to instantiate a client i.e. - ``boto3.client('service-name')``. ``operation-name`` refers to the - underlying API operation name of the corresponding client method. - - :Description: This event is emitted upon receiving an error after making an API call. This event provides information about any errors encountered during the @@ -840,22 +750,29 @@ about each event can be found in the corresponding sections below: Here is an example we use the ``before-send`` to mimic a bad response which triggers the ``after-call-error`` event and prints the exception:: - from boto3.session import Session + import boto3 + + s3 = boto3.client('s3') + + # Access the event system on the S3 client + event_system = s3.meta.events + # Prints the detected exception. def print_after_call_error_args(exception, **kwargs): - print(f'exception: {exception}') + if exception is not None: + print(f'Exception Detected: {exception}') + # Mocks an exception raised when making an API call. def list_objects_v2_bad_response(**kwargs): raise Exception("This is a test exception.") - session = Session() - session.events.register('before-send.s3.ListBuckets', list_objects_v2_bad_response) - session.events.register('after-call-error.s3.ListBuckets', print_after_call_error_args) + event_system.register('before-send.s3.ListBuckets', list_objects_v2_bad_response) + event_system.register('after-call-error.s3.ListBuckets', print_after_call_error_args) - client = session.client('s3') - client.list_buckets() + s3.list_buckets() This should output:: - exception: This is a test exception. + Exception Detected: This is a test exception. # Stack Trace + Exception: This is a test exception. From b9335c13afe634201e78591d9c27c97cc785290a Mon Sep 17 00:00:00 2001 From: jonathan343 Date: Mon, 10 Jul 2023 11:32:32 -0700 Subject: [PATCH 3/4] Fixed indentation for needs-retry code example. --- docs/source/guide/events.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/source/guide/events.rst b/docs/source/guide/events.rst index 14887eb1e3..f5f64d2ca6 100644 --- a/docs/source/guide/events.rst +++ b/docs/source/guide/events.rst @@ -653,25 +653,25 @@ about each event can be found in the corresponding sections below: :Example: Here is an example of how to add custom retry behavior:: - import boto3 + import boto3 - s3 = boto3.client('s3') + s3 = boto3.client('s3') - # Access the event system on the S3 client - event_system = s3.meta.events + # Access the event system on the S3 client + event_system = s3.meta.events - # Create a handler that determines retry behavior. - def needs_retry_handler(**kwargs): - # Implement custom retry logic - if some_condition: - return None - else: - return some_delay + # Create a handler that determines retry behavior. + def needs_retry_handler(**kwargs): + # Implement custom retry logic + if some_condition: + return None + else: + return some_delay - # Register the function to an event - event_system.register('needs-retry', needs_retry_handler) + # Register the function to an event + event_system.register('needs-retry', needs_retry_handler) - s3.list_buckets() + s3.list_buckets() `after-call` From 5b2997fa1d45a5c0b848cbaf6991907be4570a6c Mon Sep 17 00:00:00 2001 From: jonathan343 Date: Mon, 2 Oct 2023 10:54:24 -0700 Subject: [PATCH 4/4] More PR Feedback. --- docs/source/guide/events.rst | 113 ++++++++++++++++++----------------- 1 file changed, 57 insertions(+), 56 deletions(-) diff --git a/docs/source/guide/events.rst b/docs/source/guide/events.rst index f5f64d2ca6..9788e66153 100644 --- a/docs/source/guide/events.rst +++ b/docs/source/guide/events.rst @@ -218,37 +218,38 @@ about each event can be found in the corresponding sections below: .. note:: Events with a ``*`` in their order number are conditionally emitted while all others are always emitted. - An explanation of all 4 conditional events is provided below. + An explanation of all 3 conditional events is provided below. ``2 *`` - ``creating-resource-class`` is emitted ONLY when using a service resource. - ``8 *`` - ``after-call`` is emitted when a successful API response is received - and ``after-call-error`` is emitted when an error is received. - -+-----------------------------+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -| Event Name | Order | Emit Location | -+=============================+=======+===============================================================================================================================================+ -| ``creating-client-class`` | 1 | `Location `_ | -+-----------------------------+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -| ``creating-resource-class`` | 2 * | `Location `_ | -+-----------------------------+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -| ``provide-client-params`` | 3 | `Location `_ | -+-----------------------------+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -| ``before-call`` | 4 | `Location `_ | -+-----------------------------+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -| ``request-created`` | 5 | `Location `_ | -+-----------------------------+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -| ``before-send`` | 6 | `Location `_ | -+-----------------------------+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -| ``needs-retry`` | 7 | `Location `_ | -+-----------------------------+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -| ``after-call`` | 8 * | `Location `_ | -+-----------------------------+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -| ``after-call-error`` | 8 * | `Location `_ | -+-----------------------------+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+ + ``8 *`` - ``after-call`` is emitted when a successful API response is received. + + ``9 *`` - ``after-call-error`` is emitted when an unsuccessful API response is received. + ++-----------------------------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Event Name | Order | Emit Location | ++=============================+=======+==========================================================================================================================================================+ +| ``creating-client-class`` | 1 | `Location `__ | ++-----------------------------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``creating-resource-class`` | 2 * | `Location `__ | ++-----------------------------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``provide-client-params`` | 3 | `Location `__ | ++-----------------------------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``before-call`` | 4 | `Location `__ | ++-----------------------------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``request-created`` | 5 | `Location `__ | ++-----------------------------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``before-send`` | 6 | `Location `__ | ++-----------------------------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``needs-retry`` | 7 | `Location `__ | ++-----------------------------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``after-call`` | 8 * | `Location `__ | ++-----------------------------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ``after-call-error`` | 9 * | `Location `__ | ++-----------------------------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------+ .. note:: - If any of the following keywords are included in an event's Full Event Name, you'll need + If any of the following keywords are included in an event's full name, you'll need to replace it with the corresponding value: * ``service-name`` - The value used to instantiate a client as in ``boto3.client('service-name')``. @@ -260,7 +261,7 @@ about each event can be found in the corresponding sections below: `creating-client-class` -~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~ :Full Event Name: ``'creating-client-class.service-name'`` @@ -273,14 +274,14 @@ about each event can be found in the corresponding sections below: :Keyword Arguments Emitted: - :type class_attributes: dict + :type class_attributes: ``dict`` :param class_attributes: A dictionary where the keys are the names of the - attributes of the class and the values are the actual attributes of - the class. + attributes of the class and the values are the actual attributes of + the class. - :type base_classes: list + :type base_classes: ``list`` :param base_classes: A list of classes that the client class will inherit - from where the order of inheritance is the same as the order of the list. + from where the order of inheritance is the same as the order of the list. :Expected Return Value: ``None`` @@ -330,7 +331,7 @@ about each event can be found in the corresponding sections below: `creating-resource-class` -~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~ :Full Event Name: ``'creating-resource-class.service-name.resource-name'`` @@ -343,14 +344,14 @@ about each event can be found in the corresponding sections below: :Keyword Arguments Emitted: - :type class_attributes: dict + :type class_attributes: ``dict`` :param class_attributes: A dictionary where the keys are the names of the - attributes of the class and the values are the actual attributes of - the class. + attributes of the class and the values are the actual attributes of + the class. - :type base_classes: list + :type base_classes: ``list`` :param base_classes: A list of classes that the resource class will inherit - from where the order of inheritance is the same as the order of the list. + from where the order of inheritance is the same as the order of the list. :Expected Return Value: ``None`` @@ -402,7 +403,7 @@ about each event can be found in the corresponding sections below: `provide-client-params` -~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~ :Full Event Name: ``'provide-client-params.service-name.operation-name'`` @@ -414,7 +415,7 @@ about each event can be found in the corresponding sections below: :Keyword Arguments Emitted: - :type params: dict + :type params: ``dict`` :param params: A dictionary containing key value pairs consisting of the parameters passed through to the client method. @@ -422,7 +423,7 @@ about each event can be found in the corresponding sections below: :param model: A model representing the underlying API operation of the client method. -:Expected Return Value: ``None`` or return a new dictionary of +:Expected Return Value: ``None`` or return a ``dict`` containing parameters to use when making the request. :Example: @@ -448,7 +449,7 @@ about each event can be found in the corresponding sections below: `before-call` -~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~ :Full Event Name: ``'before-call.service-name.operation-name'`` @@ -467,10 +468,10 @@ about each event can be found in the corresponding sections below: :param model: A model representing the underlying API operation of the client method. - :type params: dict + :type params: ``dict`` :param params: A dictionary containing key value pairs for various components of - an HTTP request such as ``url_path``, ``host_prefix``, ``query_string``, ``headers``, - ``body``, and ``method``. + an HTTP request such as ``url_path``, ``host_prefix``, ``query_string``, ``headers``, + ``body``, and ``method``. :type request_signer: ``botocore.signers.RequestSigner`` :param request_signer: An object to sign requests before they are sent over @@ -506,7 +507,7 @@ about each event can be found in the corresponding sections below: `request-created` -~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~ :Full Event Name: ``'request-created.service-name.operation-name'`` @@ -520,7 +521,7 @@ about each event can be found in the corresponding sections below: :param request: An AWSRequest object which represents the request that was created given some params and an operation model. - :type operation_name: str + :type operation_name: ``str`` :param operation_name: The name of the service operation model i.e. ``ListObjectsV2``. :Expected Return Value: ``None`` @@ -566,7 +567,7 @@ about each event can be found in the corresponding sections below: `before-send` -~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~ :Full Event Name: ``'before-send.service-name.operation-name'`` @@ -611,7 +612,7 @@ about each event can be found in the corresponding sections below: `needs-retry` -~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~ :Full Event Name: ``'needs-retry.service-name.operation-name'`` @@ -624,7 +625,7 @@ about each event can be found in the corresponding sections below: :Keyword Arguments Emitted: - :type response: tuple + :type response: ``tuple`` :param response: A tuple that includes both the ``botocore.awsrequest.AWSResponse`` and a ``dict`` that represents the parsed response described by the model. @@ -635,14 +636,14 @@ about each event can be found in the corresponding sections below: :param operation: A model representing the underlying API operation of the client method. - :type attempts: int + :type attempts: ``int`` :param attempts: A number representing the amount of retries that have been attempted. - :type caught_exception: ``Exception`` | ``None``` + :type caught_exception: ``Exception`` | ``None`` :param caught_exception: The exception raised after making an api call. If there was no exception, this will be None. - :type request_dict: dict + :type request_dict: ``dict`` :param request_dict: A dictionary containing key value pairs for various components of an HTTP request such as ``url_path``, ``host_prefix``, ``query_string``, ``headers``, ``body``, and ``method``. @@ -675,7 +676,7 @@ about each event can be found in the corresponding sections below: `after-call` -~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~ :Full Event Name: ``'after-call.service-name.operation-name'`` @@ -690,7 +691,7 @@ about each event can be found in the corresponding sections below: :type http_response: ``botocore.awsrequest.AWSResponse`` :param http_response: A data class representing an HTTP response received from the server. - :type parsed: dict + :type parsed: ``dict`` :param params: A parsed version of the AWSResponse in the form of a python dictionary. @@ -729,7 +730,7 @@ about each event can be found in the corresponding sections below: `after-call-error` -~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~ :Full Event Name: ``'after-call-error.service-name.operation-name'``