| 1 |
=============== |
| 2 |
Upgrading notes |
| 3 |
=============== |
| 4 |
|
| 5 |
Notes to refer to when upgrading ``boto3`` versions. |
| 6 |
|
| 7 |
1.9.0 |
| 8 |
----- |
| 9 |
|
| 10 |
What changed |
| 11 |
~~~~~~~~~~~~ |
| 12 |
|
| 13 |
The boto3 event system was changed to emit events based on the service id |
| 14 |
rather than the endpoint prefix or service name. |
| 15 |
|
| 16 |
Why was the change made |
| 17 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 18 |
|
| 19 |
This was done to handle several issues that were becoming increasingly |
| 20 |
problematic: |
| 21 |
|
| 22 |
* Services changing their endpoint prefix would cause some registered events to |
| 23 |
no longer fire (but not all). |
| 24 |
* New services that launch using an endpoint that another service is using |
| 25 |
won't be able to be uniquely selected. There are a number of cases of this |
| 26 |
already. |
| 27 |
* Services whose client name and endpoint prefix differed would require two |
| 28 |
different strings if you want to register against all events. |
| 29 |
|
| 30 |
How do I know if I'm impacted |
| 31 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 32 |
|
| 33 |
Any users relying on registering an event against one service impacting other |
| 34 |
services are impacted. You can consult the following table to see if you are |
| 35 |
impacted. If you are registering an event using one of the event parts in the |
| 36 |
leftmost column with the intention of impacting an unintended target service |
| 37 |
in the rightmost column, then you are impacted and will need to update. |
| 38 |
|
| 39 |
+----------------------+-------------------------+---------------------------------------------------+ |
| 40 |
| Event Part | Intended Target Service | Unintended Target Services | |
| 41 |
+----------------------+-------------------------+---------------------------------------------------+ |
| 42 |
| rds | rds | neptune | |
| 43 |
+----------------------+-------------------------+---------------------------------------------------+ |
| 44 |
| autoscaling | autoscaling | application-autoscaling, autoscaling-plans | |
| 45 |
+----------------------+-------------------------+---------------------------------------------------+ |
| 46 |
| kinesisvideo | kinesisvideo | kinesis-video-media, kinesis-video-archived-media | |
| 47 |
+----------------------+-------------------------+---------------------------------------------------+ |
| 48 |
| elasticloadbalancing | elb | elbv2 | |
| 49 |
+----------------------+-------------------------+---------------------------------------------------+ |
| 50 |
|
| 51 |
For example, if you are registering an event against |
| 52 |
``before-call.elasticloadbalancing`` expecting it to run when making calls with |
| 53 |
an ``elbv2`` client, you will be impacted. |
| 54 |
|
| 55 |
If you are registering an event against one of the services in the Unintended |
| 56 |
Targets column, you may be impacted if you were relying on those events not |
| 57 |
firing. |
| 58 |
|
| 59 |
If you are registering events using ``*`` in the service place, or are |
| 60 |
registering against any service not in this table, you will not need a code |
| 61 |
change. In many cases the actual event name will have changed, but for services |
| 62 |
without shared endpoints we do the work of translating the event name at |
| 63 |
registration and emission time. In future versions of boto3 we will remove |
| 64 |
this translation, so you may wish to update your code anyway. |
| 65 |
|
| 66 |
How do I update my code |
| 67 |
~~~~~~~~~~~~~~~~~~~~~~~ |
| 68 |
|
| 69 |
You will need to look at the events you are registering against and determine |
| 70 |
which services you wish to impact with your handler. If you only wish to |
| 71 |
impact the intended target service (as defined in the above table), then you |
| 72 |
don't need to change the event. If you wish to impact another service in |
| 73 |
addition to the intended target service, you will need to register a new event |
| 74 |
using that service's event name. Similarly, if you wish to impact another |
| 75 |
service instead you will simply need to change the event you are registered |
| 76 |
against. |
| 77 |
|
| 78 |
To get the new event name, consult this table: |
| 79 |
|
| 80 |
+------------------------------+----------------------+------------------------------+ |
| 81 |
| Service | Old Event Name | New Event Name | |
| 82 |
+------------------------------+----------------------+------------------------------+ |
| 83 |
| application-autoscaling | autoscaling | application-auto-scaling | |
| 84 |
+------------------------------+----------------------+------------------------------+ |
| 85 |
| autoscaling-plans | autoscaling | auto-scaling-plans | |
| 86 |
+------------------------------+----------------------+------------------------------+ |
| 87 |
| elbv2 | elasticloadbalancing | elastic-load-balancing | |
| 88 |
+------------------------------+----------------------+------------------------------+ |
| 89 |
| kinesis-video-archived-media | kinesisvideo | kinesis-video-archived-media | |
| 90 |
+------------------------------+----------------------+------------------------------+ |
| 91 |
| kinesis-video-media | kinesisvideo | kinesis-video-media | |
| 92 |
+------------------------------+----------------------+------------------------------+ |
| 93 |
| neptune | rds | neptune | |
| 94 |
+------------------------------+----------------------+------------------------------+ |
| 95 |
|
| 96 |
Additionally, you can get the new event name in code like so:: |
| 97 |
|
| 98 |
import boto3 |
| 99 |
|
| 100 |
client = boto3.client('elbv2') |
| 101 |
service_event_name = client.meta.service_model.service_id.hyphenize() |
| 102 |
|
| 103 |
Armed with the service event name, simply replace the old service name in the |
| 104 |
handler with the new service event name. If you were registering an event |
| 105 |
against ``before-call.autoscaling`` intending to impact ``autoscaling-plans`` |
| 106 |
for example, you would instead register against |
| 107 |
``before-call.auto-scaling-plans``. |
| 108 |
|
| 109 |
If you are registering an event against one of the services in the Unintended |
| 110 |
Targets column, you will now see those events getting fired where previously |
| 111 |
they were not. While this is enabling that expected behavior, this still |
| 112 |
represents a change in actual behavior. You should not need to update your |
| 113 |
code, but you should test to ensure that you are seeing the behavior you want. |
| 114 |
|
| 115 |
|
| 116 |
1.4.2 |
| 117 |
----- |
| 118 |
|
| 119 |
* The ``use_threads`` option was added to |
| 120 |
:py:class:`boto3.s3.transfer.TransferConfig`. |
| 121 |
Starting in version ``1.4.0``, all managed S3 transfer methods became |
| 122 |
threaded instead of possibly being threaded. If it is not desired to use |
| 123 |
threads for managed S3 transfers, set ``use_threads`` to ``False``. |
| 124 |
|
| 125 |
|
| 126 |
1.4.0 |
| 127 |
----- |
| 128 |
|
| 129 |
* Logic from the `s3transfer <https://github.com/boto/s3transfer>`_ package |
| 130 |
was ported into the ``boto3.s3.transfer`` module. In upgrading to this |
| 131 |
new version of ``boto3``, code that relies on the public classes and |
| 132 |
interfaces of ``boto3.s3.transfer``, such as |
| 133 |
:py:class:`boto3.s3.transfer.S3Transfer` and |
| 134 |
:py:class:`boto3.s3.transfer.TransferConfig`, should not be affected. |
| 135 |
However, code that relies on the internal classes and functionality of the |
| 136 |
``boto3.s3.transfer`` module may be affected in upgrading: |
| 137 |
|
| 138 |
* Removed internal classes such as ``MultipartUploader``, |
| 139 |
``MultipartDownloader``, ``ReadFileChunk``, etc. All of the managed |
| 140 |
transfer logic now lives inside of ``s3transfer`` and as a result these |
| 141 |
internal classes are no longer used and is essentially dead code. |
| 142 |
|
| 143 |
* Custom implementations of ``OSUtils`` may see the |
| 144 |
``open_file_chunk_reader`` method no longer being called when uploads |
| 145 |
occur. If this was for the purpose of being able to provide file-like |
| 146 |
objects for transfers, use the newly added ``upload_fileobj`` |
| 147 |
and ``download_fileobj`` methods that support both nonmultipart and |
| 148 |
multipart transfers. |
| 149 |
|
| 150 |
* By default, all managed transfer methods are now threaded. In prior |
| 151 |
versions, threads were only created if a non multipart upload or download |
| 152 |
was initiated. To run the managed transfer methods with no threads |
| 153 |
(i.e. all of the transfer logic happens in the main thread), set |
| 154 |
``use_threads`` to ``False`` when providing a ``TransferConfig`` object. |
| 155 |
The ``use_threads`` option is only available in ``boto3`` versions higher |
| 156 |
than ``1.4.1``. |