codekingpro/portable-devtools

1# Copyright 2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.2#3# Licensed under the Apache License, Version 2.0 (the "License"). You4# may not use this file except in compliance with the License. A copy of5# the License is located at6#7# http://aws.amazon.com/apache2.0/8#9# or in the "license" file accompanying this file. This file is10# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF11# ANY KIND, either express or implied. See the License for the specific12# language governing permissions and limitations under the License.13import copy14 15from botocore.compat import OrderedDict16from botocore.endpoint import DEFAULT_TIMEOUT, MAX_POOL_CONNECTIONS17from botocore.exceptions import (18    InvalidMaxRetryAttemptsError,19    InvalidRetryConfigurationError,20    InvalidRetryModeError,21    InvalidS3AddressingStyleError,22)23 24 25class Config:26    """Advanced configuration for Botocore clients.27 28    :type region_name: str29    :param region_name: The region to use in instantiating the client30 31    :type signature_version: str32    :param signature_version: The signature version when signing requests.33 34    :type user_agent: str35    :param user_agent: The value to use in the User-Agent header.36 37    :type user_agent_extra: str38    :param user_agent_extra: The value to append to the current User-Agent39        header value.40 41    :type user_agent_appid: str42    :param user_agent_appid: A value that gets included in the User-Agent43        string in the format "app/<user_agent_appid>". Allowed characters are44        ASCII alphanumerics and ``!$%&'*+-.^_`|~``. All other characters will45        be replaced by a ``-``.46 47    :type connect_timeout: float or int48    :param connect_timeout: The time in seconds till a timeout exception is49        thrown when attempting to make a connection. The default is 6050        seconds.51 52    :type read_timeout: float or int53    :param read_timeout: The time in seconds till a timeout exception is54        thrown when attempting to read from a connection. The default is55        60 seconds.56 57    :type parameter_validation: bool58    :param parameter_validation: Whether parameter validation should occur59        when serializing requests. The default is True.  You can disable60        parameter validation for performance reasons.  Otherwise, it's61        recommended to leave parameter validation enabled.62 63    :type max_pool_connections: int64    :param max_pool_connections: The maximum number of connections to65        keep in a connection pool.  If this value is not set, the default66        value of 10 is used.67 68    :type proxies: dict69    :param proxies: A dictionary of proxy servers to use by protocol or70        endpoint, e.g.:71        ``{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}``.72        The proxies are used on each request.73 74    :type proxies_config: dict75    :param proxies_config: A dictionary of additional proxy configurations.76        Valid keys are:77 78        * ``proxy_ca_bundle`` -- The path to a custom certificate bundle to use79          when establishing SSL/TLS connections with proxy.80 81        * ``proxy_client_cert`` -- The path to a certificate for proxy82          TLS client authentication.83 84          When a string is provided it is treated as a path to a proxy client85          certificate. When a two element tuple is provided, it will be86          interpreted as the path to the client certificate, and the path87          to the certificate key.88 89        * ``proxy_use_forwarding_for_https`` -- For HTTPS proxies,90          forward your requests to HTTPS destinations with an absolute91          URI. We strongly recommend you only use this option with92          trusted or corporate proxies. Value must be boolean.93 94    :type s3: dict95    :param s3: A dictionary of S3 specific configurations.96        Valid keys are:97 98        * ``use_accelerate_endpoint`` -- Refers to whether to use the S399          Accelerate endpoint. The value must be a boolean. If True, the100          client will use the S3 Accelerate endpoint. If the S3 Accelerate101          endpoint is being used then the addressing style will always102          be virtual.103 104        * ``payload_signing_enabled`` -- Refers to whether or not to SHA256105          sign sigv4 payloads. By default, this is disabled for streaming106          uploads (UploadPart and PutObject).107 108        * ``addressing_style`` -- Refers to the style in which to address109          s3 endpoints. Values must be a string that equals one of:110 111          * ``auto`` -- Addressing style is chosen for user. Depending112            on the configuration of client, the endpoint may be addressed in113            the virtual or the path style. Note that this is the default114            behavior if no style is specified.115 116          * ``virtual`` -- Addressing style is always virtual. The name of the117            bucket must be DNS compatible or an exception will be thrown.118            Endpoints will be addressed as such: ``mybucket.s3.amazonaws.com``119 120          * ``path`` -- Addressing style is always by path. Endpoints will be121            addressed as such: ``s3.amazonaws.com/mybucket``122 123        * ``us_east_1_regional_endpoint`` -- Refers to what S3 endpoint to use124          when the region is configured to be us-east-1. Values must be a125          string that equals:126 127          * ``regional`` -- Use the us-east-1.amazonaws.com endpoint if the128            client is configured to use the us-east-1 region.129 130          * ``legacy`` -- Use the s3.amazonaws.com endpoint if the client is131            configured to use the us-east-1 region. This is the default if132            the configuration option is not specified.133 134 135    :type retries: dict136    :param retries: A dictionary for configuration related to retry behavior.137        Valid keys are:138 139        * ``total_max_attempts`` -- An integer representing the maximum number of140          total attempts that will be made on a single request.  This includes141          the initial request, so a value of 1 indicates that no requests142          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`` because145          it maps to the ``AWS_MAX_ATTEMPTS`` environment variable and146          the ``max_attempts`` config file value.147        * ``max_attempts`` -- An integer representing the maximum number of148          retry attempts that will be made on a single request. For149          example, setting this value to 2 will result in the request150          being retried at most two times after the initial request. Setting151          this value to 0 will result in no retries ever being attempted after152          the initial request. If not provided, the number of retries will153          default to the value specified in the service model, which is154          typically four retries.155        * ``mode`` -- A string representing the type of retry mode botocore156          should use.  Valid values are:157 158          * ``legacy`` - The pre-existing retry behavior.159 160          * ``standard`` - The standardized set of retry rules. This will also161            default to 3 max attempts unless overridden.162 163          * ``adaptive`` - Retries with additional client side throttling.164 165    :type client_cert: str, (str, str)166    :param client_cert: The path to a certificate for TLS client authentication.167 168        When a string is provided it is treated as a path to a client169        certificate to be used when creating a TLS connection.170 171        If a client key is to be provided alongside the client certificate the172        client_cert should be set to a tuple of length two where the first173        element is the path to the client certificate and the second element is174        the path to the certificate key.175 176    :type inject_host_prefix: bool177    :param inject_host_prefix: Whether host prefix injection should occur.178 179        Defaults to True.180 181        Setting this to False disables the injection of operation parameters182        into the prefix of the hostname. This is useful for clients providing183        custom endpoints that should not have their host prefix modified.184 185    :type use_dualstack_endpoint: bool186    :param use_dualstack_endpoint: Setting to True enables dualstack187        endpoint resolution.188 189        Defaults to None.190 191    :type use_fips_endpoint: bool192    :param use_fips_endpoint: Setting to True enables fips193        endpoint resolution.194 195        Defaults to None.196 197    :type ignore_configured_endpoint_urls: bool198    :param ignore_configured_endpoint_urls: Setting to True disables use199        of endpoint URLs provided via environment variables and200        the shared configuration file.201 202        Defaults to None.203 204    :type tcp_keepalive: bool205    :param tcp_keepalive: Enables the TCP Keep-Alive socket option used when206        creating new connections if set to True.207 208        Defaults to False.209 210    :type request_min_compression_size_bytes: int211    :param request_min_compression_size_bytes: The minimum size in bytes that a212        request body should be to trigger compression. All requests with213        streaming input that don't contain the ``requiresLength`` trait will be214        compressed regardless of this setting.215 216        Defaults to None.217 218    :type disable_request_compression: bool219    :param disable_request_compression: Disables request body compression if220        set to True.221 222        Defaults to None.223 224    :type client_context_params: dict225    :param client_context_params: A dictionary of parameters specific to226        individual services. If available, valid parameters can be found in227        the ``Client Context Parameters`` section of the service client's228        documentation. Invalid parameters or ones that are not used by the229        specified service will be ignored.230 231        Defaults to None.232    """233 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    )262 263    NON_LEGACY_OPTION_DEFAULTS = {264        'connect_timeout': None,265    }266 267    def __init__(self, *args, **kwargs):268        self._user_provided_options = self._record_user_provided_options(269            args, kwargs270        )271 272        # Merge the user_provided options onto the default options273        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)280 281        # Set the attributes based on the config_vars282        for key, value in config_vars.items():283            setattr(self, key, value)284 285        # Validate the s3 options286        self._validate_s3_configuration(self.s3)287 288        self._validate_retry_configuration(self.retries)289 290    def _record_user_provided_options(self, args, kwargs):291        option_order = list(self.OPTION_DEFAULTS)292        user_provided_options = {}293 294        # Iterate through the kwargs passed through to the constructor and295        # map valid keys to the dictionary296        for key, value in kwargs.items():297            if key in self.OPTION_DEFAULTS:298                user_provided_options[key] = value299            # The key must exist in the available options300            else:301                raise TypeError(f"Got unexpected keyword argument '{key}'")302 303        # The number of args should not be longer than the allowed304        # options305        if len(args) > len(option_order):306            raise TypeError(307                f"Takes at most {len(option_order)} arguments ({len(args)} given)"308            )309 310        # Iterate through the args passed through to the constructor and map311        # them to appropriate keys.312        for i, arg in enumerate(args):313            # If a kwarg was specified for the arg, then error out314            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]] = arg319 320        return user_provided_options321 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_style328                )329 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                    )355 356    def merge(self, other_config):357        """Merges the config object with another config object358 359        This will merge in all non-default values from the provided config360        and return a new config object361 362        :type other_config: botocore.config.Config363        :param other config: Another config object to merge with. The values364            in the provided config object will take precedence in the merging365 366        :returns: A config object built from the merged values of both367            config objects.368        """369        # Make a copy of the current attributes in the config object.370        config_options = copy.copy(self._user_provided_options)371 372        # Merge in the user provided options from the other config373        config_options.update(other_config._user_provided_options)374 375        # Return a new config object with the merged properties.376        return Config(**config_options)377