Debian Codegraph @

docs/source/guide/events.rst

raw
1 Extensibility guide
2 ===================
3
4 All of Boto3's resource and client classes are generated at runtime.
5 This means that you cannot directly inherit and then extend the
6 functionality of these classes because they do not exist until the
7 program actually starts running.
8
9
10 However it is still possible to extend the functionality of classes through
11 Boto3's event system.
12
13
14 An introduction to the event system
15 -----------------------------------
16
17 Boto3's event system allows users to register a function to a specific event.
18 Then once the running program reaches a line that emits that specific event,
19 Boto3 will call every function registered to the event in the order in which
20 they were registered.
21
22 When Boto3 calls each of these registered functions, it will call each of them
23 with a specific set of keyword arguments that are associated with that event.
24 Then once the registered function is called, the function may modify the
25 keyword arguments passed to that function or return a value. Here is an
26 example of how the event system works::
27
28 import boto3
29
30 s3 = boto3.client('s3')
31
32 # Access the event system on the S3 client
33 event_system = s3.meta.events
34
35 # Create a function
36 def add_my_bucket(params, **kwargs):
37 # Add the name of the bucket you want to default to.
38 if 'Bucket' not in params:
39 params['Bucket'] = 'amzn-s3-demo-bucket'
40
41 # Register the function to an event
42 event_system.register('provide-client-params.s3.ListObjectsV2', add_my_bucket)
43
44 response = s3.list_objects_v2()
45
46 In this example, the handler ``add_my_bucket`` is registered such that the
47 handler will inject the value ``'amzn-s3-demo-bucket'`` for the ``Bucket``
48 parameter whenever the ``list_objects_v2`` client call is made without the
49 ``Bucket`` parameter. Note that if the same ``list_objects_v2`` call is made
50 without the ``Bucket`` parameter and the registered handler, it will result in
51 a validation error.
52
53 Here are the takeaways from this example:
54
55 * All clients have their own event system that you can use to fire events
56 and register functions. You can access the event system through the
57 ``meta.events`` attribute on the client.
58 * All functions registered to the event system must have ``**kwargs`` in
59 the function signature. This is because emitting an event can have any
60 number of keyword arguments emitted alongside it, and so if your
61 function is called without ``**kwargs``, its signature will have to
62 match every keyword argument emitted by the event. This also allows for
63 more keyword arguments to be added to the emitted event in the future
64 without breaking existing handlers.
65 * To register a function to an event, call the ``register`` method on the
66 event system with the name of the event you want to register the
67 function to and the function handle. Note that if you register the event
68 after the event is emitted, the function will not be called unless the
69 event is emitted again. In the example, the ``add_my_bucket`` handler
70 was registered to the ``'provide-client-params.s3.ListObjectsV2'`` event,
71 which is an event that can be used to inject and modify parameters passed
72 in by the client method. To read more about the event refer to
73 `provide-client-params`_
74
75
76 A hierarchical structure
77 ------------------------
78
79 The event system also provides a hierarchy for registering events such that
80 you can register a function to a set of events depending on the event name
81 hierarchy.
82
83 An event name can have its own hierarchy by specifying ``.`` in its name. For
84 example, take the event name ``'general.specific.more_specific'``. When
85 this event is emitted, the registered functions will be called in the order
86 from most specific to least specific registration. So in this example, the
87 functions will be called in the following order:
88
89 1) Functions registered to ``'general.specific.more_specific'``
90 2) Functions registered to ``'general.specific'``
91 3) Functions registered to ``'general'``
92
93 Here is a deeper example of how the event system works with respect to
94 its hierarchical structure::
95
96 import boto3
97
98 s3 = boto3.client('s3')
99
100 # Access the event system on the S3 client
101 event_system = s3.meta.events
102
103 def add_my_general_bucket(params, **kwargs):
104 if 'Bucket' not in params:
105 params['Bucket'] = 'amzn-s3-demo-bucket1'
106
107 def add_my_specific_bucket(params, **kwargs):
108 if 'Bucket' not in params:
109 params['Bucket'] = 'amzn-s3-demo-bucket2'
110
111 event_system.register('provide-client-params.s3', add_my_general_bucket)
112 event_system.register('provide-client-params.s3.ListObjectsV2', add_my_specific_bucket)
113
114 list_obj_response = s3.list_objects_v2()
115 put_obj_response = s3.put_object(Key='mykey', Body=b'my body')
116
117 In this example, the ``list_objects_v2`` method call will use the
118 ``'amzn-s3-demo-bucket2'`` for the bucket instead of
119 ``'amzn-s3-demo-bucket1'`` because the ``add_my_specific_bucket`` method was
120 registered to the ``'provide-client-params.s3.ListObjectsV2'`` event which is
121 more specific than the ``'provide-client-params.s3'`` event. Thus, the
122 ``add_my_specific_bucket`` function is called before the
123 ``add_my_general_bucket`` function is called when the event is emitted.
124
125 However for the ``put_object`` call, the bucket used is
126 ``'amzn-s3-demo-bucket1'``. This is because the event emitted for the
127 ``put_object`` client call is ``'provide-client-params.s3.PutObject'`` and the
128 ``add_my_general_bucket`` method is called via its registration to
129 ``'provide-client-params.s3'``. The
130 ``'provide-client-params.s3.ListObjectsV2'`` event is never emitted so the
131 registered ``add_my_specific_bucket`` function is never called.
132
133
134 Wildcard matching
135 -----------------
136
137 Another aspect of Boto3's event system is that it has the capability
138 to do wildcard matching using the ``'*'`` notation. Here is an example
139 of using wildcards in the event system::
140
141 import boto3
142
143 s3 = boto3.client('s3')
144
145 # Access the event system on the S3 client
146 event_system = s3.meta.events
147
148 def add_my_wildcard_bucket(params, **kwargs):
149 if 'Bucket' not in params:
150 params['Bucket'] = 'amzn-s3-demo-bucket'
151
152 event_system.register('provide-client-params.s3.*', add_my_wildcard_bucket)
153 response = s3.list_objects_v2()
154
155
156 The ``'*'`` allows you to register to a group of events without having to
157 know the actual name of the event. This is useful when you have to apply
158 the same handler in multiple places. Also note that if the wildcard is used,
159 it must be isolated. It does not handle globbing with additional characters.
160 So in the previous example, if the ``my_wildcard_function`` was registered
161 to ``'provide-client-params.s3.*objects'``, the handler would not be
162 called because it will consider ``'provide-client-params.s3.*objects'`` to be
163 a specific event.
164
165 The wildcard also respects the hierarchical structure of the event system.
166 If another handler was registered to the ``'provide-client-params.s3'`` event,
167 the ``add_my_wildcard_bucket`` would be called first because it is registered
168 to ``'provide-client-params.s3.*'`` which is more specific than the event
169 ``'provide-client.s3'``.
170
171
172 Isolation of event systems
173 --------------------------
174
175 The event system in Boto3 has the notion of isolation:
176 all clients maintain their own set of registered handlers. For example if a
177 handler is registered to one client's event system, it will not be registered
178 to another client's event system::
179
180 import boto3
181
182 client1 = boto3.client('s3')
183 client2 = boto3.client('s3')
184
185 def add_my_bucket(params, **kwargs):
186 if 'Bucket' not in params:
187 params['Bucket'] = 'amzn-s3-demo-bucket1'
188
189 def add_my_other_bucket(params, **kwargs):
190 if 'Bucket' not in params:
191 params['Bucket'] = 'amzn-s3-demo-bucket2'
192
193 client1.meta.events.register(
194 'provide-client-params.s3.ListObjectsV2', add_my_bucket)
195 client2.meta.events.register(
196 'provide-client-params.s3.ListObjectsV2', add_my_other_bucket)
197
198 client1_response = client1.list_objects_v2()
199 client2_response = client2.list_objects_v2()
200
201
202 Thanks to the isolation of clients' event systems, ``client1`` will inject
203 ``'amzn-s3-demo-bucket1'`` for its ``list_objects_v2`` method call while
204 ``client2`` will inject ``'amzn-s3-demo-bucket2'`` for its ``list_objects_v2``
205 method call because ``add_my_bucket`` was registered to ``client1`` while
206 ``add_my_other_bucket`` was registered to ``client2``.
207
208
209 Boto3 specific events
210 ---------------------
211
212 Boto3 emits a set of events that users can register to
213 customize clients or resources and modify the behavior of method calls.
214
215 Here is a table of events that users of Boto3 can register handlers to. More
216 information about each event can be found in the corresponding sections below:
217
218 .. note::
219
220 Events with a ``*`` in their order number are conditionally emitted while
221 all others are always emitted. An explanation of all 3 conditional events is
222 provided below.
223
224 ``2 *`` - ``creating-resource-class`` is emitted ONLY when using a service resource.
225
226 ``8 *`` - ``after-call`` is emitted once the API response is received.
227
228 ``9 *`` - ``after-call-error`` is emitted when an unsuccessful API response is received.
229
230 +-----------------------------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
231 | Event Name | Order | Emit Location |
232 +=============================+=======+==========================================================================================================================================================+
233 | ``creating-client-class`` | 1 | `Location <https://github.com/search?q=repo%3Aboto%2Fbotocore+creating-client-class+path%3A%2F%5Ebotocore%5C%2Fclient%5C.py%2F&type=code>`__ |
234 +-----------------------------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
235 | ``creating-resource-class`` | 2 * | `Location <https://github.com/search?q=repo%3Aboto%2Fboto3+creating-resource-class+path%3A%2F%5Eboto3%5C%2Fresources%5C%2Ffactory%5C.py%2F&type=code>`__ |
236 +-----------------------------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
237 | ``provide-client-params`` | 3 | `Location <https://github.com/search?q=repo%3Aboto%2Fbotocore+provide-client-params+path%3A%2F%5Ebotocore%5C%2Fclient%5C.py%2F&type=code>`__ |
238 +-----------------------------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
239 | ``before-call`` | 4 | `Location <https://github.com/search?q=repo%3Aboto%2Fbotocore+before-call+path%3A%2F%5Ebotocore%5C%2Fclient%5C.py%2F&type=code>`__ |
240 +-----------------------------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
241 | ``request-created`` | 5 | `Location <https://github.com/search?q=repo%3Aboto%2Fbotocore+request-created+path%3A%2F%5Ebotocore%5C%2Fendpoint%5C.py%2F&type=code>`__ |
242 +-----------------------------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
243 | ``before-send`` | 6 | `Location <https://github.com/search?q=repo%3Aboto%2Fbotocore+before-send+path%3A%2F%5Ebotocore%5C%2Fendpoint%5C.py%2F&type=code>`__ |
244 +-----------------------------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
245 | ``needs-retry`` | 7 | `Location <https://github.com/search?q=repo%3Aboto%2Fbotocore+needs-retry+path%3A%2F%5Ebotocore%5C%2Fendpoint%5C.py%2F&type=code>`__ |
246 +-----------------------------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
247 | ``after-call`` | 8 * | `Location <https://github.com/search?q=repo%3Aboto%2Fbotocore+after-call.+path%3A%2F%5Ebotocore%5C%2Fclient%5C.py%2F&type=code>`__ |
248 +-----------------------------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
249 | ``after-call-error`` | 9 * | `Location <https://github.com/search?q=repo%3Aboto%2Fbotocore+after-call-error+path%3A%2F%5Ebotocore%5C%2Fclient%5C.py%2F&type=code>`__ |
250 +-----------------------------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------+
251
252 .. note::
253 If any of the following keywords are included in an event's full name, you'll need
254 to replace it with the corresponding value:
255
256 * ``service-name`` - The value used to instantiate a client as in ``boto3.client('service-name')``.
257 * ``operation-name`` - The underlying API operation name of the corresponding client method. To access
258 the operation API name, retrieve the value from the ``client.meta.method_to_api_mapping`` dictionary
259 using the name of the desired client method as the key.
260 * ``resource-name`` - The name of the resource class such as ``ServiceResource``.
261
262
263
264 `creating-client-class`
265 ~~~~~~~~~~~~~~~~~~~~~~~
266
267 :Full Event Name:
268 ``'creating-client-class.service-name'``
269
270 :Description:
271 This event is emitted upon creation of the client class for a service. The
272 client class for a service is not created until the first instantiation of
273 the client class. Use this event for adding methods to the client class
274 or adding classes for the client class to inherit from.
275
276 :Keyword Arguments Emitted:
277
278 :type class_attributes: ``dict``
279 :param class_attributes: A dictionary where the keys are the names of the
280 attributes of the class and the values are the actual attributes of
281 the class.
282
283 :type base_classes: ``list``
284 :param base_classes: A list of classes that the client class will inherit
285 from where the order of inheritance is the same as the order of the list.
286
287 :Expected Return Value: ``None``
288
289 :Example:
290 Here is an example of how to add a method to the client class::
291
292 from boto3.session import Session
293
294 def custom_method(self):
295 print('This is my custom method')
296
297 def add_custom_method(class_attributes, **kwargs):
298 class_attributes['my_method'] = custom_method
299
300 session = Session()
301 session.events.register('creating-client-class.s3', add_custom_method)
302
303 client = session.client('s3')
304 client.my_method()
305
306 This should output::
307
308 This is my custom method
309
310
311 Here is an example of how to add a new class for the client class to
312 inherit from::
313
314 from boto3.session import Session
315
316 class MyClass(object):
317 def __init__(self, *args, **kwargs):
318 super(MyClass, self).__init__(*args, **kwargs)
319 print('Client instantiated!')
320
321 def add_custom_class(base_classes, **kwargs):
322 base_classes.insert(0, MyClass)
323
324 session = Session()
325 session.events.register('creating-client-class.s3', add_custom_class)
326
327 client = session.client('s3')
328
329 This should output::
330
331 Client instantiated!
332
333
334 `creating-resource-class`
335 ~~~~~~~~~~~~~~~~~~~~~~~~~
336
337 :Full Event Name:
338 ``'creating-resource-class.service-name.resource-name'``
339
340 :Description:
341 This event is emitted upon creation of the resource class. The
342 resource class is not created until the first instantiation of
343 the resource class. Use this event for adding methods to the resource
344 class or adding classes for the resource class to inherit from.
345
346 :Keyword Arguments Emitted:
347
348 :type class_attributes: ``dict``
349 :param class_attributes: A dictionary where the keys are the names of the
350 attributes of the class and the values are the actual attributes of
351 the class.
352
353 :type base_classes: ``list``
354 :param base_classes: A list of classes that the resource class will inherit
355 from where the order of inheritance is the same as the order of the list.
356
357 :Expected Return Value: ``None``
358
359 :Example:
360 Here is an example of how to add a method to a resource class::
361
362 from boto3.session import Session
363
364 def custom_method(self):
365 print('This is my custom method')
366
367 def add_custom_method(class_attributes, **kwargs):
368 class_attributes['my_method'] = custom_method
369
370 session = Session()
371 session.events.register('creating-resource-class.s3.ServiceResource',
372 add_custom_method)
373
374 resource = session.resource('s3')
375 resource.my_method()
376
377 This should output::
378
379 This is my custom method
380
381
382 Here is an example of how to add a new class for a resource class to
383 inherit from::
384
385 from boto3.session import Session
386
387 class MyClass(object):
388 def __init__(self, *args, **kwargs):
389 super(MyClass, self).__init__(*args, **kwargs)
390 print('Resource instantiated!')
391
392 def add_custom_class(base_classes, **kwargs):
393 base_classes.insert(0, MyClass)
394
395 session = Session()
396 session.events.register('creating-resource-class.s3.ServiceResource',
397 add_custom_class)
398
399 resource = session.resource('s3')
400
401 This should output::
402
403 Resource instantiated!
404
405
406 `provide-client-params`
407 ~~~~~~~~~~~~~~~~~~~~~~~
408
409 :Full Event Name:
410 ``'provide-client-params.service-name.operation-name'``
411
412 :Description:
413 This event is emitted before operation parameters are validated and built
414 into the HTTP request that will be sent over the wire. Use this event to
415 inject or modify parameters.
416
417 :Keyword Arguments Emitted:
418
419 :type params: ``dict``
420 :param params: A dictionary containing key value pairs consisting of the parameters
421 passed through to the client method.
422
423 :type model: ``botocore.model.OperationModel``
424 :param model: A model representing the underlying API operation of the
425 client method.
426
427 :Expected Return Value: ``None`` or return a ``dict`` containing
428 parameters to use when making the request.
429
430 :Example:
431 Here is an example of how to inject a parameter using the event::
432
433 import boto3
434
435 s3 = boto3.client('s3')
436
437 # Access the event system on the S3 client
438 event_system = s3.meta.events
439
440 # Create a function
441 def add_my_bucket(params, **kwargs):
442 # Add the name of the bucket you want to default to.
443 if 'Bucket' not in params:
444 params['Bucket'] = 'amzn-s3-demo-bucket'
445
446 # Register the function to an event
447 event_system.register('provide-client-params.s3.ListObjectsV2', add_my_bucket)
448
449 response = s3.list_objects_v2()
450
451
452 `before-call`
453 ~~~~~~~~~~~~~
454
455 :Full Event Name:
456 ``'before-call.service-name.operation-name'``
457
458 :Description:
459 This event is emitted just before creating and sending the HTTP request.
460 Use this event for modifying various HTTP request components prior to the request
461 being created. A response tuple may optionally be returned to trigger a short-circuit
462 and prevent the request from being made. This is useful for testing and is how the
463 `botocore stubber <https://botocore.amazonaws.com/v1/documentation/api/latest/reference/stubber.html>`_
464 mocks responses.
465
466 :Keyword Arguments Emitted:
467
468 :type model: ``botocore.model.OperationModel``
469 :param model: A model representing the underlying API operation of the
470 client method.
471
472 :type params: ``dict``
473 :param params: A dictionary containing key value pairs for various components of
474 an HTTP request such as ``url_path``, ``host_prefix``, ``query_string``, ``headers``,
475 ``body``, and ``method``.
476
477 :type request_signer: ``botocore.signers.RequestSigner``
478 :param request_signer: An object to sign requests before they are sent over
479 the wire using one of the authentication mechanisms defined in ``auth.py``.
480
481 :Expected Return Value: ``None`` or a ``tuple`` that includes both the ``botocore.awsrequest.AWSResponse``
482 and a ``dict`` that represents the parsed response described by the model.
483
484 :Example:
485 Here is an example of how to add a custom header before making an API call::
486
487 import boto3
488
489 s3 = boto3.client('s3')
490
491 # Access the event system on the S3 client
492 event_system = s3.meta.events
493
494 # Create a function that adds a custom header and prints all headers.
495 def add_custom_header_before_call(model, params, request_signer, **kwargs):
496 params['headers']['my-custom-header'] = 'header-info'
497 headers = params['headers']
498 print(f'param headers: {headers}')
499
500 # Register the function to an event.
501 event_system.register('before-call.s3.ListBuckets', add_custom_header_before_call)
502
503 s3.list_buckets()
504
505 This should output::
506
507 param headers: { ... , 'my-custom-header': 'header-info'}
508
509
510 `request-created`
511 ~~~~~~~~~~~~~~~~~
512
513 :Full Event Name:
514 ``'request-created.service-name.operation-name'``
515
516 :Description:
517 This event is emitted just after the request is created and triggers request signing.
518
519 :Keyword Arguments Emitted:
520
521 :type request: ``botocore.awsrequest.AWSRequest``
522 :param request: An AWSRequest object which represents the request that was
523 created given some params and an operation model.
524
525 :type operation_name: ``str``
526 :param operation_name: The name of the service operation model i.e. ``ListObjectsV2``.
527
528 :Expected Return Value: ``None``
529
530 :Example:
531 Here is an example of how to inspect the request once it's created::
532
533 import boto3
534
535 s3 = boto3.client('s3')
536
537 # Access the event system on the S3 client
538 event_system = s3.meta.events
539
540 # Create a function that prints the request information.
541 def inspect_request_created(request, operation_name, **kwargs):
542 print('Request Info:')
543 print(f'method: {request.method}')
544 print(f'url: {request.url}')
545 print(f'data: {request.data}')
546 print(f'params: {request.params}')
547 print(f'auth_path: {request.auth_path}')
548 print(f'stream_output: {request.stream_output}')
549 print(f'headers: {request.headers}')
550 print(f'operation_name: {operation_name}')
551
552 # Register the function to an event
553 event_system.register('request-created.s3.ListObjectsV2', inspect_request_created)
554
555 response = s3.list_objects_v2(Bucket='amzn-s3-demo-bucket')
556
557 This should output::
558
559 Request Info:
560 method: GET
561 url: https://amzn-s3-demo-bucket.s3 ...
562 data: ...
563 params: { ... }
564 auth_path: ...
565 stream_output: ...
566 headers: ...
567 operation_name: ListObjectsV2
568
569
570 `before-send`
571 ~~~~~~~~~~~~~
572
573 :Full Event Name:
574 ``'before-send.service-name.operation-name'``
575
576 :Description:
577 This event is emitted when the operation has been fully serialized, signed,
578 and is ready to be sent over the wire. This event allows the finalized
579 request to be inspected and allows a response to be returned that fulfills
580 the request. If no response is returned botocore will fulfill the request
581 as normal.
582
583 :Keyword Arguments Emitted:
584
585 :type request: ``botocore.awsrequest.AWSPreparedRequest``
586 :param request: A data class representing a finalized request to be sent over the wire.
587
588 :Expected Return Value: ``None`` or an instance of ``botocore.awsrequest.AWSResponse``.
589
590 :Example:
591 Here is an example of how to register a function that allows you to inspect
592 the prepared request before it's sent::
593
594 import boto3
595
596 s3 = boto3.client('s3')
597
598 # Access the event system on the S3 client
599 event_system = s3.meta.events
600
601 # Create a function that inspects the prepared request.
602 def inspect_request_before_send(request, **kwargs):
603 print(f'request: {request}')
604
605 # Register the function to an event
606 event_system.register('before-send.s3.ListBuckets', inspect_request_before_send)
607
608 s3.list_buckets()
609
610 This should output::
611
612 request: <AWSPreparedRequest ... >
613
614
615 `needs-retry`
616 ~~~~~~~~~~~~~
617
618 :Full Event Name:
619 ``'needs-retry.service-name.operation-name'``
620
621 :Description:
622 This event is emitted before checking if the most recent request needs to be retried.
623 Use this event to define custom retry behavior when the configurable
624 `retry modes <https://boto3.amazonaws.com/v1/documentation/api/latest/guide/retries.html>`_
625 are not sufficient.
626
627 :Keyword Arguments Emitted:
628
629 :type response: ``tuple``
630 :param response: A tuple that includes both the ``botocore.awsrequest.AWSResponse``
631 and a ``dict`` that represents the parsed response described by the model.
632
633 :type endpoint: ``botocore.endpoint.Endpoint``
634 :param endpoint: Represents an endpoint for a particular service.
635
636 :type operation: ``botocore.model.OperationModel``
637 :param operation: A model representing the underlying API operation of the
638 client method.
639
640 :type attempts: ``int``
641 :param attempts: A number representing the amount of retries that have been attempted.
642
643 :type caught_exception: ``Exception`` | ``None``
644 :param caught_exception: The exception raised after making an api call. If there was no
645 exception, this will be None.
646
647 :type request_dict: ``dict``
648 :param request_dict: A dictionary containing key value pairs for various components of
649 an HTTP request such as ``url_path``, ``host_prefix``, ``query_string``, ``headers``,
650 ``body``, and ``method``.
651
652 :Expected Return Value: Return ``None`` if no retry is needed, or return an ``int`` representing the
653 retry delay in seconds.
654
655 :Example:
656 Here is an example of how to add custom retry behavior::
657
658 import boto3
659
660 s3 = boto3.client('s3')
661
662 # Access the event system on the S3 client
663 event_system = s3.meta.events
664
665 # Create a handler that determines retry behavior.
666 def needs_retry_handler(**kwargs):
667 # Implement custom retry logic
668 if some_condition:
669 return None
670 else:
671 return some_delay
672
673 # Register the function to an event
674 event_system.register('needs-retry', needs_retry_handler)
675
676 s3.list_buckets()
677
678
679 `after-call`
680 ~~~~~~~~~~~~
681
682 :Full Event Name:
683 ``'after-call.service-name.operation-name'``
684
685 :Description:
686 This event is emitted just after the service client makes an API call. This
687 event allows developers to postprocess or inspect the API response according
688 to the specific requirements of their application if needed.
689
690 :Keyword Arguments Emitted:
691
692 :type http_response: ``botocore.awsrequest.AWSResponse``
693 :param http_response: A data class representing an HTTP response received from the server.
694
695 :type parsed: ``dict``
696 :param params: A parsed version of the AWSResponse in the form of
697 a python dictionary.
698
699 :type model: ``botocore.model.OperationModel``
700 :param model: A model representing the underlying API operation of the
701 client method.
702
703 :Expected Return Value: ``None``
704
705 :Example:
706 Here is an example that inspects args emitted from the ``after-call`` event::
707
708 import boto3
709
710 s3 = boto3.client('s3')
711
712 # Access the event system on the S3 client
713 event_system = s3.meta.events
714
715 # Create a function that prints the after-call event args.
716 def print_after_call_args(http_response, parsed, model, **kwargs):
717 print(f'http_response: {http_response}')
718 print(f'parsed: {parsed}')
719 print(f'model: {model.name}')
720
721 # Register the function to an event
722 event_system.register('after-call.s3.ListObjectsV2', print_after_call_args)
723
724 s3.list_objects_v2(Bucket='amzn-s3-demo-bucket')
725
726 This should output::
727
728 http_response: <botocore.awsrequest.AWSResponse object at ...>
729 parsed: { ... }
730 model: ListObjectsV2
731
732
733 `after-call-error`
734 ~~~~~~~~~~~~~~~~~~
735
736 :Full Event Name:
737 ``'after-call-error.service-name.operation-name'``
738
739 :Description:
740 This event is emitted upon receiving an error after making an API call.
741 This event provides information about any errors encountered during the
742 operation and allows listeners to take corrective actions if necessary.
743
744 :Keyword Arguments Emitted:
745
746 :type exception: ``Exception``
747 :param exception: The exception raised after making an api call.
748
749 :Expected Return Value: ``None``
750
751 :Example:
752 Here is an example we use the ``before-send`` to mimic a bad response which
753 triggers the ``after-call-error`` event and prints the exception::
754
755 import boto3
756
757 s3 = boto3.client('s3')
758
759 # Access the event system on the S3 client
760 event_system = s3.meta.events
761
762 # Prints the detected exception.
763 def print_after_call_error_args(exception, **kwargs):
764 if exception is not None:
765 print(f'Exception Detected: {exception}')
766
767 # Mocks an exception raised when making an API call.
768 def list_objects_v2_bad_response(**kwargs):
769 raise Exception("This is a test exception.")
770
771 event_system.register('before-send.s3.ListBuckets', list_objects_v2_bad_response)
772 event_system.register('after-call-error.s3.ListBuckets', print_after_call_error_args)
773
774 s3.list_buckets()
775
776 This should output::
777
778 Exception Detected: This is a test exception.
779 # Stack Trace
780 Exception: This is a test exception.