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. 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: ``amzn-s3-demo-bucket.s3.amazonaws.com``
120 * ``path`` -- Addressing style is always by path. Endpoints will be
121 addressed as such: ``s3.amazonaws.com/amzn-s3-demo-bucket``
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 None.
181 The default of None is equivalent to setting to True, which enables
182 the injection of operation parameters into the prefix of the hostname.
183 Setting this to False disables the injection of operation parameters
184 into the prefix of the hostname. Setting this to False is useful for
185 clients providing custom endpoints that should not have their host
186 prefix modified.
188 :type use_dualstack_endpoint: bool
189 :param use_dualstack_endpoint: Setting to True enables dualstack
190 endpoint resolution.
192 Defaults to None.
194 :type use_fips_endpoint: bool
195 :param use_fips_endpoint: Setting to True enables fips
196 endpoint resolution.
198 Defaults to None.
200 :type ignore_configured_endpoint_urls: bool
201 :param ignore_configured_endpoint_urls: Setting to True disables use
202 of endpoint URLs provided via environment variables and
203 the shared configuration file.
205 Defaults to None.
207 :type tcp_keepalive: bool
208 :param tcp_keepalive: Enables the TCP Keep-Alive socket option used when
209 creating new connections if set to True.
211 Defaults to False.
213 :type request_min_compression_size_bytes: int
214 :param request_min_compression_size_bytes: The minimum size in bytes that a
215 request body should be to trigger compression. All requests with
216 streaming input that don't contain the ``requiresLength`` trait will be
217 compressed regardless of this setting.
219 Defaults to None.
221 :type disable_request_compression: bool
222 :param disable_request_compression: Disables request body compression if
223 set to True.
225 Defaults to None.
227 :type sigv4a_signing_region_set: string
228 :param sigv4a_signing_region_set: A set of AWS regions to apply the signature for
229 when using SigV4a for signing. Set to ``*`` to represent all regions.
231 Defaults to None.
233 :type client_context_params: dict
234 :param client_context_params: A dictionary of parameters specific to
235 individual services. If available, valid parameters can be found in
236 the ``Client Context Parameters`` section of the service client's
237 documentation. Invalid parameters or ones that are not used by the
238 specified service will be ignored.
240 Defaults to None.
242 :type request_checksum_calculation: str
243 :param request_checksum_calculation: Determines when a checksum will be
244 calculated for request payloads. Valid values are:
246 * ``when_supported`` -- When set, a checksum will be calculated for
247 all request payloads of operations modeled with the ``httpChecksum``
248 trait where ``requestChecksumRequired`` is ``true`` or a
249 ``requestAlgorithmMember`` is modeled.
251 * ``when_required`` -- When set, a checksum will only be calculated
252 for request payloads of operations modeled with the ``httpChecksum``
253 trait where ``requestChecksumRequired`` is ``true`` or where a
254 ``requestAlgorithmMember`` is modeled and supplied.
256 Defaults to None.
258 :type response_checksum_validation: str
259 :param response_checksum_validation: Determines when checksum validation
260 will be performed on response payloads. Valid values are:
262 * ``when_supported`` -- When set, checksum validation is performed on
263 all response payloads of operations modeled with the ``httpChecksum``
264 trait where ``responseAlgorithms`` is modeled, except when no modeled
265 checksum algorithms are supported.
267 * ``when_required`` -- When set, checksum validation is not performed
268 on response payloads of operations unless the checksum algorithm is
269 supported and the ``requestValidationModeMember`` member is set to ``ENABLED``.
271 Defaults to None.
273 :type account_id_endpoint_mode: str
274 :param account_id_endpoint_mode: The value used to determine the client's
275 behavior for account ID based endpoint routing. Valid values are:
277 * ``preferred`` - The endpoint should include account ID if available.
278 * ``disabled`` - A resolved endpoint does not include account ID.
279 * ``required`` - The endpoint must include account ID. If the account ID
280 isn't available, an exception will be raised.
282 If a value is not provided, the client will default to ``preferred``.
284 Defaults to None.
286 :type auth_scheme_preference: str
287 :param auth_scheme_preference: A comma-delimited string of case-sensitive
288 auth scheme names used to determine the client's auth scheme preference.
290 Defaults to None.
291 """
293 OPTION_DEFAULTS = OrderedDict(
294 [
295 ('region_name', None),
296 ('signature_version', None),
297 ('user_agent', None),
298 ('user_agent_extra', None),
299 ('user_agent_appid', None),
300 ('connect_timeout', DEFAULT_TIMEOUT),
301 ('read_timeout', DEFAULT_TIMEOUT),
302 ('parameter_validation', True),
303 ('max_pool_connections', MAX_POOL_CONNECTIONS),
304 ('proxies', None),
305 ('proxies_config', None),
306 ('s3', None),
307 ('retries', None),
308 ('client_cert', None),
309 ('inject_host_prefix', None),
310 ('endpoint_discovery_enabled', None),
311 ('use_dualstack_endpoint', None),
312 ('use_fips_endpoint', None),
313 ('ignore_configured_endpoint_urls', None),
314 ('defaults_mode', None),
315 ('tcp_keepalive', None),
316 ('request_min_compression_size_bytes', None),
317 ('disable_request_compression', None),
318 ('client_context_params', None),
319 ('sigv4a_signing_region_set', None),
320 ('request_checksum_calculation', None),
321 ('response_checksum_validation', None),
322 ('account_id_endpoint_mode', None),
323 ('auth_scheme_preference', None),
324 ]
325 )
327 NON_LEGACY_OPTION_DEFAULTS = {
328 'connect_timeout': None,
329 }
331 # The original default value of the inject_host_prefix parameter was True.
332 # This prevented the ability to override the value from other locations in
333 # the parameter provider chain, like env vars or the shared configuration
334 # file. TO accomplish this, we need to disambiguate when the value was set
335 # by the user or not. This overrides the parameter with a property so the
336 # default value of inject_host_prefix is still True if it is not set by the
337 # user.
338 @property
339 def inject_host_prefix(self):
340 if self._inject_host_prefix == "UNSET":
341 return True
343 return self._inject_host_prefix
345 # Override the setter for the case where the user does supply a value;
346 # _inject_host_prefix will no longer be "UNSET".
347 @inject_host_prefix.setter
348 def inject_host_prefix(self, value):
349 self._inject_host_prefix = value
351 def __init__(self, *args, **kwargs):
352 self._user_provided_options = self._record_user_provided_options(
353 args, kwargs
354 )
356 # By default, we use a value that indicates the user did not
357 # set it. This value MUST persist on the Config object to be used
358 # elsewhere.
359 self._inject_host_prefix = 'UNSET'
361 # Merge the user_provided options onto the default options
362 config_vars = copy.copy(self.OPTION_DEFAULTS)
363 defaults_mode = self._user_provided_options.get(
364 'defaults_mode', 'legacy'
365 )
366 if defaults_mode != 'legacy':
367 config_vars.update(self.NON_LEGACY_OPTION_DEFAULTS)
369 config_vars.update(self._user_provided_options)
371 # Set the attributes based on the config_vars
372 for key, value in config_vars.items():
373 # Default values for the Config object are set here. We don't want
374 # to use `setattr` in the case where the user already supplied a
375 # value.
376 if (
377 key == 'inject_host_prefix'
378 and 'inject_host_prefix'
379 not in self._user_provided_options.keys()
380 ):
381 continue
382 setattr(self, key, value)
384 # Validate the s3 options
385 self._validate_s3_configuration(self.s3)
387 self._validate_retry_configuration(self.retries)
389 def _record_user_provided_options(self, args, kwargs):
390 option_order = list(self.OPTION_DEFAULTS)
391 user_provided_options = {}
393 # Iterate through the kwargs passed through to the constructor and
394 # map valid keys to the dictionary
395 for key, value in kwargs.items():
396 if key in self.OPTION_DEFAULTS:
397 user_provided_options[key] = value
398 # The key must exist in the available options
399 else:
400 raise TypeError(f"Got unexpected keyword argument '{key}'")
402 # The number of args should not be longer than the allowed
403 # options
404 if len(args) > len(option_order):
405 raise TypeError(
406 f"Takes at most {len(option_order)} arguments ({len(args)} given)"
407 )
409 # Iterate through the args passed through to the constructor and map
410 # them to appropriate keys.
411 for i, arg in enumerate(args):
412 # If a kwarg was specified for the arg, then error out
413 if option_order[i] in user_provided_options:
414 raise TypeError(
415 f"Got multiple values for keyword argument '{option_order[i]}'"
416 )
417 user_provided_options[option_order[i]] = arg
419 return user_provided_options
421 def _validate_s3_configuration(self, s3):
422 if s3 is not None:
423 addressing_style = s3.get('addressing_style')
424 if addressing_style not in ['virtual', 'auto', 'path', None]:
425 raise InvalidS3AddressingStyleError(
426 s3_addressing_style=addressing_style
427 )
429 def _validate_retry_configuration(self, retries):
430 valid_options = ('max_attempts', 'mode', 'total_max_attempts')
431 valid_modes = ('legacy', 'standard', 'adaptive')
432 if retries is not None:
433 for key, value in retries.items():
434 if key not in valid_options:
435 raise InvalidRetryConfigurationError(
436 retry_config_option=key,
437 valid_options=valid_options,
438 )
439 if key == 'max_attempts' and value < 0:
440 raise InvalidMaxRetryAttemptsError(
441 provided_max_attempts=value,
442 min_value=0,
443 )
444 if key == 'total_max_attempts' and value < 1:
445 raise InvalidMaxRetryAttemptsError(
446 provided_max_attempts=value,
447 min_value=1,
448 )
449 if key == 'mode' and value not in valid_modes:
450 raise InvalidRetryModeError(
451 provided_retry_mode=value,
452 valid_modes=valid_modes,
453 )
455 def merge(self, other_config):
456 """Merges the config object with another config object
458 This will merge in all non-default values from the provided config
459 and return a new config object
461 :type other_config: botocore.config.Config
462 :param other config: Another config object to merge with. The values
463 in the provided config object will take precedence in the merging
465 :returns: A config object built from the merged values of both
466 config objects.
467 """
468 # Make a copy of the current attributes in the config object.
469 config_options = copy.copy(self._user_provided_options)
471 # Merge in the user provided options from the other config
472 config_options.update(other_config._user_provided_options)
474 # Return a new config object with the merged properties.
475 return Config(**config_options)