Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/botocore/config.py: 24%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
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. For operations that support request checksums,
106 this only applies when ``request_checksum_calculation`` is set to
107 ``when_required``. Otherwise, this is disabled for
108 streaming uploads (UploadPart and PutObject) by default.
110 * ``addressing_style`` -- Refers to the style in which to address
111 s3 endpoints. Values must be a string that equals one of:
113 * ``auto`` -- Addressing style is chosen for user. Depending
114 on the configuration of client, the endpoint may be addressed in
115 the virtual or the path style. Note that this is the default
116 behavior if no style is specified.
118 * ``virtual`` -- Addressing style is always virtual. The name of the
119 bucket must be DNS compatible or an exception will be thrown.
120 Endpoints will be addressed as such: ``amzn-s3-demo-bucket.s3.amazonaws.com``
122 * ``path`` -- Addressing style is always by path. Endpoints will be
123 addressed as such: ``s3.amazonaws.com/amzn-s3-demo-bucket``
125 * ``us_east_1_regional_endpoint`` -- Refers to what S3 endpoint to use
126 when the region is configured to be us-east-1. Values must be a
127 string that equals:
129 * ``regional`` -- Use the us-east-1.amazonaws.com endpoint if the
130 client is configured to use the us-east-1 region.
132 * ``legacy`` -- Use the s3.amazonaws.com endpoint if the client is
133 configured to use the us-east-1 region. This is the default if
134 the configuration option is not specified.
137 :type retries: dict
138 :param retries: A dictionary for configuration related to retry behavior.
139 Valid keys are:
141 * ``total_max_attempts`` -- An integer representing the maximum number of
142 total attempts that will be made on a single request. This includes
143 the initial request, so a value of 1 indicates that no requests
144 will be retried. If ``total_max_attempts`` and ``max_attempts``
145 are both provided, ``total_max_attempts`` takes precedence.
146 ``total_max_attempts`` is preferred over ``max_attempts`` because
147 it maps to the ``AWS_MAX_ATTEMPTS`` environment variable and
148 the ``max_attempts`` config file value.
149 * ``max_attempts`` -- An integer representing the maximum number of
150 retry attempts that will be made on a single request. For
151 example, setting this value to 2 will result in the request
152 being retried at most two times after the initial request. Setting
153 this value to 0 will result in no retries ever being attempted after
154 the initial request. If not provided, the number of retries will
155 default to the value specified in the service model, which is
156 typically four retries.
157 * ``mode`` -- A string representing the type of retry mode botocore
158 should use. Valid values are:
160 * ``legacy`` - The pre-existing retry behavior.
162 * ``standard`` - The standardized set of retry rules. This will also
163 default to 3 max attempts unless overridden.
165 * ``adaptive`` - Retries with additional client side throttling.
167 :type client_cert: str, (str, str)
168 :param client_cert: The path to a certificate for TLS client authentication.
170 When a string is provided it is treated as a path to a client
171 certificate to be used when creating a TLS connection.
173 If a client key is to be provided alongside the client certificate the
174 client_cert should be set to a tuple of length two where the first
175 element is the path to the client certificate and the second element is
176 the path to the certificate key.
178 :type inject_host_prefix: bool
179 :param inject_host_prefix: Whether host prefix injection should occur.
181 Defaults to None.
183 The default of None is equivalent to setting to True, which enables
184 the injection of operation parameters into the prefix of the hostname.
185 Setting this to False disables the injection of operation parameters
186 into the prefix of the hostname. Setting this to False is useful for
187 clients providing custom endpoints that should not have their host
188 prefix modified.
190 :type use_dualstack_endpoint: bool
191 :param use_dualstack_endpoint: Setting to True enables dualstack
192 endpoint resolution.
194 Defaults to None.
196 :type use_fips_endpoint: bool
197 :param use_fips_endpoint: Setting to True enables fips
198 endpoint resolution.
200 Defaults to None.
202 :type ignore_configured_endpoint_urls: bool
203 :param ignore_configured_endpoint_urls: Setting to True disables use
204 of endpoint URLs provided via environment variables and
205 the shared configuration file.
207 Defaults to None.
209 :type tcp_keepalive: bool
210 :param tcp_keepalive: Enables the TCP Keep-Alive socket option used when
211 creating new connections if set to True.
213 Defaults to False.
215 :type request_min_compression_size_bytes: int
216 :param request_min_compression_size_bytes: The minimum size in bytes that a
217 request body should be to trigger compression. All requests with
218 streaming input that don't contain the ``requiresLength`` trait will be
219 compressed regardless of this setting.
221 Defaults to None.
223 :type disable_request_compression: bool
224 :param disable_request_compression: Disables request body compression if
225 set to True.
227 Defaults to None.
229 :type sigv4a_signing_region_set: string
230 :param sigv4a_signing_region_set: A set of AWS regions to apply the signature for
231 when using SigV4a for signing. Set to ``*`` to represent all regions.
233 Defaults to None.
235 :type client_context_params: dict
236 :param client_context_params: A dictionary of parameters specific to
237 individual services. If available, valid parameters can be found in
238 the ``Client Context Parameters`` section of the service client's
239 documentation. Invalid parameters or ones that are not used by the
240 specified service will be ignored.
242 Defaults to None.
244 :type request_checksum_calculation: str
245 :param request_checksum_calculation: Determines when a checksum will be
246 calculated for request payloads. Valid values are:
248 * ``when_supported`` -- When set, a checksum will be calculated for
249 all request payloads of operations modeled with the ``httpChecksum``
250 trait where ``requestChecksumRequired`` is ``true`` or a
251 ``requestAlgorithmMember`` is modeled.
253 * ``when_required`` -- When set, a checksum will only be calculated
254 for request payloads of operations modeled with the ``httpChecksum``
255 trait where ``requestChecksumRequired`` is ``true`` or where a
256 ``requestAlgorithmMember`` is modeled and supplied.
258 Defaults to None.
260 :type response_checksum_validation: str
261 :param response_checksum_validation: Determines when checksum validation
262 will be performed on response payloads. Valid values are:
264 * ``when_supported`` -- When set, checksum validation is performed on
265 all response payloads of operations modeled with the ``httpChecksum``
266 trait where ``responseAlgorithms`` is modeled, except when no modeled
267 checksum algorithms are supported.
269 * ``when_required`` -- When set, checksum validation is not performed
270 on response payloads of operations unless the checksum algorithm is
271 supported and the ``requestValidationModeMember`` member is set to ``ENABLED``.
273 Defaults to None.
275 :type account_id_endpoint_mode: str
276 :param account_id_endpoint_mode: The value used to determine the client's
277 behavior for account ID based endpoint routing. Valid values are:
279 * ``preferred`` - The endpoint should include account ID if available.
280 * ``disabled`` - A resolved endpoint does not include account ID.
281 * ``required`` - The endpoint must include account ID. If the account ID
282 isn't available, an exception will be raised.
284 If a value is not provided, the client will default to ``preferred``.
286 Defaults to None.
288 :type auth_scheme_preference: str
289 :param auth_scheme_preference: A comma-delimited string of case-sensitive
290 auth scheme names used to determine the client's auth scheme preference.
292 Defaults to None.
293 """
295 OPTION_DEFAULTS = OrderedDict(
296 [
297 ('region_name', None),
298 ('signature_version', None),
299 ('user_agent', None),
300 ('user_agent_extra', None),
301 ('user_agent_appid', None),
302 ('connect_timeout', DEFAULT_TIMEOUT),
303 ('read_timeout', DEFAULT_TIMEOUT),
304 ('parameter_validation', True),
305 ('max_pool_connections', MAX_POOL_CONNECTIONS),
306 ('proxies', None),
307 ('proxies_config', None),
308 ('s3', None),
309 ('retries', None),
310 ('client_cert', None),
311 ('inject_host_prefix', None),
312 ('endpoint_discovery_enabled', None),
313 ('use_dualstack_endpoint', None),
314 ('use_fips_endpoint', None),
315 ('ignore_configured_endpoint_urls', None),
316 ('defaults_mode', None),
317 ('tcp_keepalive', None),
318 ('request_min_compression_size_bytes', None),
319 ('disable_request_compression', None),
320 ('client_context_params', None),
321 ('sigv4a_signing_region_set', None),
322 ('request_checksum_calculation', None),
323 ('response_checksum_validation', None),
324 ('account_id_endpoint_mode', None),
325 ('auth_scheme_preference', None),
326 ]
327 )
329 NON_LEGACY_OPTION_DEFAULTS = {
330 'connect_timeout': None,
331 }
333 # The original default value of the inject_host_prefix parameter was True.
334 # This prevented the ability to override the value from other locations in
335 # the parameter provider chain, like env vars or the shared configuration
336 # file. TO accomplish this, we need to disambiguate when the value was set
337 # by the user or not. This overrides the parameter with a property so the
338 # default value of inject_host_prefix is still True if it is not set by the
339 # user.
340 @property
341 def inject_host_prefix(self):
342 if self._inject_host_prefix == "UNSET":
343 return True
345 return self._inject_host_prefix
347 # Override the setter for the case where the user does supply a value;
348 # _inject_host_prefix will no longer be "UNSET".
349 @inject_host_prefix.setter
350 def inject_host_prefix(self, value):
351 self._inject_host_prefix = value
353 def __init__(self, *args, **kwargs):
354 self._user_provided_options = self._record_user_provided_options(
355 args, kwargs
356 )
358 # By default, we use a value that indicates the user did not
359 # set it. This value MUST persist on the Config object to be used
360 # elsewhere.
361 self._inject_host_prefix = 'UNSET'
363 # Merge the user_provided options onto the default options
364 config_vars = copy.copy(self.OPTION_DEFAULTS)
365 defaults_mode = self._user_provided_options.get(
366 'defaults_mode', 'legacy'
367 )
368 if defaults_mode != 'legacy':
369 config_vars.update(self.NON_LEGACY_OPTION_DEFAULTS)
371 config_vars.update(self._user_provided_options)
373 # Set the attributes based on the config_vars
374 for key, value in config_vars.items():
375 # Default values for the Config object are set here. We don't want
376 # to use `setattr` in the case where the user already supplied a
377 # value.
378 if (
379 key == 'inject_host_prefix'
380 and 'inject_host_prefix'
381 not in self._user_provided_options.keys()
382 ):
383 continue
384 setattr(self, key, value)
386 # Validate the s3 options
387 self._validate_s3_configuration(self.s3)
389 self._validate_retry_configuration(self.retries)
391 def _record_user_provided_options(self, args, kwargs):
392 option_order = list(self.OPTION_DEFAULTS)
393 user_provided_options = {}
395 # Iterate through the kwargs passed through to the constructor and
396 # map valid keys to the dictionary
397 for key, value in kwargs.items():
398 if key in self.OPTION_DEFAULTS:
399 user_provided_options[key] = value
400 # The key must exist in the available options
401 else:
402 raise TypeError(f"Got unexpected keyword argument '{key}'")
404 # The number of args should not be longer than the allowed
405 # options
406 if len(args) > len(option_order):
407 raise TypeError(
408 f"Takes at most {len(option_order)} arguments ({len(args)} given)"
409 )
411 # Iterate through the args passed through to the constructor and map
412 # them to appropriate keys.
413 for i, arg in enumerate(args):
414 # If a kwarg was specified for the arg, then error out
415 if option_order[i] in user_provided_options:
416 raise TypeError(
417 f"Got multiple values for keyword argument '{option_order[i]}'"
418 )
419 user_provided_options[option_order[i]] = arg
421 return user_provided_options
423 def _validate_s3_configuration(self, s3):
424 if s3 is not None:
425 addressing_style = s3.get('addressing_style')
426 if addressing_style not in ['virtual', 'auto', 'path', None]:
427 raise InvalidS3AddressingStyleError(
428 s3_addressing_style=addressing_style
429 )
431 def _validate_retry_configuration(self, retries):
432 valid_options = ('max_attempts', 'mode', 'total_max_attempts')
433 valid_modes = ('legacy', 'standard', 'adaptive')
434 if retries is not None:
435 for key, value in retries.items():
436 if key not in valid_options:
437 raise InvalidRetryConfigurationError(
438 retry_config_option=key,
439 valid_options=valid_options,
440 )
441 if key == 'max_attempts' and value < 0:
442 raise InvalidMaxRetryAttemptsError(
443 provided_max_attempts=value,
444 min_value=0,
445 )
446 if key == 'total_max_attempts' and value < 1:
447 raise InvalidMaxRetryAttemptsError(
448 provided_max_attempts=value,
449 min_value=1,
450 )
451 if key == 'mode' and value not in valid_modes:
452 raise InvalidRetryModeError(
453 provided_retry_mode=value,
454 valid_modes=valid_modes,
455 )
457 def merge(self, other_config):
458 """Merges the config object with another config object
460 This will merge in all non-default values from the provided config
461 and return a new config object
463 :type other_config: botocore.config.Config
464 :param other config: Another config object to merge with. The values
465 in the provided config object will take precedence in the merging
467 :returns: A config object built from the merged values of both
468 config objects.
469 """
470 # Make a copy of the current attributes in the config object.
471 config_options = copy.copy(self._user_provided_options)
473 # Merge in the user provided options from the other config
474 config_options.update(other_config._user_provided_options)
476 # Return a new config object with the merged properties.
477 return Config(**config_options)