Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/botocore/config.py: 70%
54 statements
« prev ^ index » next coverage.py v7.3.2, created at 2023-12-08 06:51 +0000
1# Copyright 2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
2#
3# Licensed under the Apache License, Version 2.0 (the "License"). You
4# may not use this file except in compliance with the License. A copy of
5# the License is located at
6#
7# http://aws.amazon.com/apache2.0/
8#
9# or in the "license" file accompanying this file. This file is
10# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
11# ANY KIND, either express or implied. See the License for the specific
12# language governing permissions and limitations under the License.
13import copy
15from botocore.compat import OrderedDict
16from botocore.endpoint import DEFAULT_TIMEOUT, MAX_POOL_CONNECTIONS
17from botocore.exceptions import (
18 InvalidMaxRetryAttemptsError,
19 InvalidRetryConfigurationError,
20 InvalidRetryModeError,
21 InvalidS3AddressingStyleError,
22)
25class Config:
26 """Advanced configuration for Botocore clients.
28 :type region_name: str
29 :param region_name: The region to use in instantiating the client
31 :type signature_version: str
32 :param signature_version: The signature version when signing requests.
34 :type user_agent: str
35 :param user_agent: The value to use in the User-Agent header.
37 :type user_agent_extra: str
38 :param user_agent_extra: The value to append to the current User-Agent
39 header value.
41 :type user_agent_appid: str
42 :param user_agent_appid: A value that gets included in the User-Agent
43 string in the format "app/<user_agent_appid>". Allowed characters are
44 ASCII alphanumerics and ``!$%&'*+-.^_`|~``. All other characters will
45 be replaced by a ``-``.
47 :type connect_timeout: float or int
48 :param connect_timeout: The time in seconds till a timeout exception is
49 thrown when attempting to make a connection. The default is 60
50 seconds.
52 :type read_timeout: float or int
53 :param read_timeout: The time in seconds till a timeout exception is
54 thrown when attempting to read from a connection. The default is
55 60 seconds.
57 :type parameter_validation: bool
58 :param parameter_validation: Whether parameter validation should occur
59 when serializing requests. The default is True. You can disable
60 parameter validation for performance reasons. Otherwise, it's
61 recommended to leave parameter validation enabled.
63 :type max_pool_connections: int
64 :param max_pool_connections: The maximum number of connections to
65 keep in a connection pool. If this value is not set, the default
66 value of 10 is used.
68 :type proxies: dict
69 :param proxies: A dictionary of proxy servers to use by protocol or
70 endpoint, e.g.:
71 ``{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}``.
72 The proxies are used on each request.
74 :type proxies_config: dict
75 :param proxies_config: A dictionary of additional proxy configurations.
76 Valid keys are:
78 * ``proxy_ca_bundle`` -- The path to a custom certificate bundle to use
79 when establishing SSL/TLS connections with proxy.
81 * ``proxy_client_cert`` -- The path to a certificate for proxy
82 TLS client authentication.
84 When a string is provided it is treated as a path to a proxy client
85 certificate. When a two element tuple is provided, it will be
86 interpreted as the path to the client certificate, and the path
87 to the certificate key.
89 * ``proxy_use_forwarding_for_https`` -- For HTTPS proxies,
90 forward your requests to HTTPS destinations with an absolute
91 URI. We strongly recommend you only use this option with
92 trusted or corporate proxies. Value must be boolean.
94 :type s3: dict
95 :param s3: A dictionary of S3 specific configurations.
96 Valid keys are:
98 * ``use_accelerate_endpoint`` -- Refers to whether to use the S3
99 Accelerate endpoint. The value must be a boolean. If True, the
100 client will use the S3 Accelerate endpoint. If the S3 Accelerate
101 endpoint is being used then the addressing style will always
102 be virtual.
104 * ``payload_signing_enabled`` -- Refers to whether or not to SHA256
105 sign sigv4 payloads. By default, this is disabled for streaming
106 uploads (UploadPart and PutObject).
108 * ``addressing_style`` -- Refers to the style in which to address
109 s3 endpoints. Values must be a string that equals one of:
111 * ``auto`` -- Addressing style is chosen for user. Depending
112 on the configuration of client, the endpoint may be addressed in
113 the virtual or the path style. Note that this is the default
114 behavior if no style is specified.
116 * ``virtual`` -- Addressing style is always virtual. The name of the
117 bucket must be DNS compatible or an exception will be thrown.
118 Endpoints will be addressed as such: ``mybucket.s3.amazonaws.com``
120 * ``path`` -- Addressing style is always by path. Endpoints will be
121 addressed as such: ``s3.amazonaws.com/mybucket``
123 * ``us_east_1_regional_endpoint`` -- Refers to what S3 endpoint to use
124 when the region is configured to be us-east-1. Values must be a
125 string that equals:
127 * ``regional`` -- Use the us-east-1.amazonaws.com endpoint if the
128 client is configured to use the us-east-1 region.
130 * ``legacy`` -- Use the s3.amazonaws.com endpoint if the client is
131 configured to use the us-east-1 region. This is the default if
132 the configuration option is not specified.
135 :type retries: dict
136 :param retries: A dictionary for configuration related to retry behavior.
137 Valid keys are:
139 * ``total_max_attempts`` -- An integer representing the maximum number of
140 total attempts that will be made on a single request. This includes
141 the initial request, so a value of 1 indicates that no requests
142 will be retried. If ``total_max_attempts`` and ``max_attempts``
143 are both provided, ``total_max_attempts`` takes precedence.
144 ``total_max_attempts`` is preferred over ``max_attempts`` because
145 it maps to the ``AWS_MAX_ATTEMPTS`` environment variable and
146 the ``max_attempts`` config file value.
147 * ``max_attempts`` -- An integer representing the maximum number of
148 retry attempts that will be made on a single request. For
149 example, setting this value to 2 will result in the request
150 being retried at most two times after the initial request. Setting
151 this value to 0 will result in no retries ever being attempted after
152 the initial request. If not provided, the number of retries will
153 default to the value specified in the service model, which is
154 typically four retries.
155 * ``mode`` -- A string representing the type of retry mode botocore
156 should use. Valid values are:
158 * ``legacy`` - The pre-existing retry behavior.
160 * ``standard`` - The standardized set of retry rules. This will also
161 default to 3 max attempts unless overridden.
163 * ``adaptive`` - Retries with additional client side throttling.
165 :type client_cert: str, (str, str)
166 :param client_cert: The path to a certificate for TLS client authentication.
168 When a string is provided it is treated as a path to a client
169 certificate to be used when creating a TLS connection.
171 If a client key is to be provided alongside the client certificate the
172 client_cert should be set to a tuple of length two where the first
173 element is the path to the client certificate and the second element is
174 the path to the certificate key.
176 :type inject_host_prefix: bool
177 :param inject_host_prefix: Whether host prefix injection should occur.
179 Defaults to True.
181 Setting this to False disables the injection of operation parameters
182 into the prefix of the hostname. This is useful for clients providing
183 custom endpoints that should not have their host prefix modified.
185 :type use_dualstack_endpoint: bool
186 :param use_dualstack_endpoint: Setting to True enables dualstack
187 endpoint resolution.
189 Defaults to None.
191 :type use_fips_endpoint: bool
192 :param use_fips_endpoint: Setting to True enables fips
193 endpoint resolution.
195 Defaults to None.
197 :type ignore_configured_endpoint_urls: bool
198 :param ignore_configured_endpoint_urls: Setting to True disables use
199 of endpoint URLs provided via environment variables and
200 the shared configuration file.
202 Defaults to None.
204 :type tcp_keepalive: bool
205 :param tcp_keepalive: Enables the TCP Keep-Alive socket option used when
206 creating new connections if set to True.
208 Defaults to False.
210 :type request_min_compression_size_bytes: int
211 :param request_min_compression_size_bytes: The minimum size in bytes that a
212 request body should be to trigger compression. All requests with
213 streaming input that don't contain the ``requiresLength`` trait will be
214 compressed regardless of this setting.
216 Defaults to None.
218 :type disable_request_compression: bool
219 :param disable_request_compression: Disables request body compression if
220 set to True.
222 Defaults to None.
224 :type client_context_params: dict
225 :param client_context_params: A dictionary of parameters specific to
226 individual services. If available, valid parameters can be found in
227 the ``Client Context Parameters`` section of the service client's
228 documentation. Invalid parameters or ones that are not used by the
229 specified service will be ignored.
231 Defaults to None.
232 """
234 OPTION_DEFAULTS = OrderedDict(
235 [
236 ('region_name', None),
237 ('signature_version', None),
238 ('user_agent', None),
239 ('user_agent_extra', None),
240 ('user_agent_appid', None),
241 ('connect_timeout', DEFAULT_TIMEOUT),
242 ('read_timeout', DEFAULT_TIMEOUT),
243 ('parameter_validation', True),
244 ('max_pool_connections', MAX_POOL_CONNECTIONS),
245 ('proxies', None),
246 ('proxies_config', None),
247 ('s3', None),
248 ('retries', None),
249 ('client_cert', None),
250 ('inject_host_prefix', True),
251 ('endpoint_discovery_enabled', None),
252 ('use_dualstack_endpoint', None),
253 ('use_fips_endpoint', None),
254 ('ignore_configured_endpoint_urls', None),
255 ('defaults_mode', None),
256 ('tcp_keepalive', None),
257 ('request_min_compression_size_bytes', None),
258 ('disable_request_compression', None),
259 ('client_context_params', None),
260 ]
261 )
263 NON_LEGACY_OPTION_DEFAULTS = {
264 'connect_timeout': None,
265 }
267 def __init__(self, *args, **kwargs):
268 self._user_provided_options = self._record_user_provided_options(
269 args, kwargs
270 )
272 # Merge the user_provided options onto the default options
273 config_vars = copy.copy(self.OPTION_DEFAULTS)
274 defaults_mode = self._user_provided_options.get(
275 'defaults_mode', 'legacy'
276 )
277 if defaults_mode != 'legacy':
278 config_vars.update(self.NON_LEGACY_OPTION_DEFAULTS)
279 config_vars.update(self._user_provided_options)
281 # Set the attributes based on the config_vars
282 for key, value in config_vars.items():
283 setattr(self, key, value)
285 # Validate the s3 options
286 self._validate_s3_configuration(self.s3)
288 self._validate_retry_configuration(self.retries)
290 def _record_user_provided_options(self, args, kwargs):
291 option_order = list(self.OPTION_DEFAULTS)
292 user_provided_options = {}
294 # Iterate through the kwargs passed through to the constructor and
295 # map valid keys to the dictionary
296 for key, value in kwargs.items():
297 if key in self.OPTION_DEFAULTS:
298 user_provided_options[key] = value
299 # The key must exist in the available options
300 else:
301 raise TypeError(f"Got unexpected keyword argument '{key}'")
303 # The number of args should not be longer than the allowed
304 # options
305 if len(args) > len(option_order):
306 raise TypeError(
307 f"Takes at most {len(option_order)} arguments ({len(args)} given)"
308 )
310 # Iterate through the args passed through to the constructor and map
311 # them to appropriate keys.
312 for i, arg in enumerate(args):
313 # If a kwarg was specified for the arg, then error out
314 if option_order[i] in user_provided_options:
315 raise TypeError(
316 f"Got multiple values for keyword argument '{option_order[i]}'"
317 )
318 user_provided_options[option_order[i]] = arg
320 return user_provided_options
322 def _validate_s3_configuration(self, s3):
323 if s3 is not None:
324 addressing_style = s3.get('addressing_style')
325 if addressing_style not in ['virtual', 'auto', 'path', None]:
326 raise InvalidS3AddressingStyleError(
327 s3_addressing_style=addressing_style
328 )
330 def _validate_retry_configuration(self, retries):
331 valid_options = ('max_attempts', 'mode', 'total_max_attempts')
332 valid_modes = ('legacy', 'standard', 'adaptive')
333 if retries is not None:
334 for key, value in retries.items():
335 if key not in valid_options:
336 raise InvalidRetryConfigurationError(
337 retry_config_option=key,
338 valid_options=valid_options,
339 )
340 if key == 'max_attempts' and value < 0:
341 raise InvalidMaxRetryAttemptsError(
342 provided_max_attempts=value,
343 min_value=0,
344 )
345 if key == 'total_max_attempts' and value < 1:
346 raise InvalidMaxRetryAttemptsError(
347 provided_max_attempts=value,
348 min_value=1,
349 )
350 if key == 'mode' and value not in valid_modes:
351 raise InvalidRetryModeError(
352 provided_retry_mode=value,
353 valid_modes=valid_modes,
354 )
356 def merge(self, other_config):
357 """Merges the config object with another config object
359 This will merge in all non-default values from the provided config
360 and return a new config object
362 :type other_config: botocore.config.Config
363 :param other config: Another config object to merge with. The values
364 in the provided config object will take precedence in the merging
366 :returns: A config object built from the merged values of both
367 config objects.
368 """
369 # Make a copy of the current attributes in the config object.
370 config_options = copy.copy(self._user_provided_options)
372 # Merge in the user provided options from the other config
373 config_options.update(other_config._user_provided_options)
375 # Return a new config object with the merged properties.
376 return Config(**config_options)