Debian Codegraph @

docs/source/guide/upgrading.rst

raw
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``.