Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/botocore/config.py: 22%

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 

14 

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) 

23 

24 

25class Config: 

26 """Advanced configuration for Botocore clients. 

27 

28 :type region_name: str 

29 :param region_name: The region to use in instantiating the client 

30 

31 :type signature_version: str 

32 :param signature_version: The signature version when signing requests. 

33 

34 :type user_agent: str 

35 :param user_agent: The value to use in the User-Agent header. 

36 

37 :type user_agent_extra: str 

38 :param user_agent_extra: The value to append to the current User-Agent 

39 header value. 

40 

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

46 

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. 

51 

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. 

56 

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. 

62 

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. 

67 

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. 

73 

74 :type proxies_config: dict 

75 :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 use 

79 when establishing SSL/TLS connections with proxy. 

80 

81 * ``proxy_client_cert`` -- The path to a certificate for proxy 

82 TLS client authentication. 

83 

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. 

88 

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. 

93 

94 :type s3: dict 

95 :param s3: A dictionary of S3 specific configurations. 

96 Valid keys are: 

97 

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. 

103 

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). 

107 

108 * ``addressing_style`` -- Refers to the style in which to address 

109 s3 endpoints. Values must be a string that equals one of: 

110 

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. 

115 

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

119 

120 * ``path`` -- Addressing style is always by path. Endpoints will be 

121 addressed as such: ``s3.amazonaws.com/mybucket`` 

122 

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: 

126 

127 * ``regional`` -- Use the us-east-1.amazonaws.com endpoint if the 

128 client is configured to use the us-east-1 region. 

129 

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. 

133 

134 

135 :type retries: dict 

136 :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 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: 

157 

158 * ``legacy`` - The pre-existing retry behavior. 

159 

160 * ``standard`` - The standardized set of retry rules. This will also 

161 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 client 

169 certificate to be used when creating a TLS connection. 

170 

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. 

175 

176 :type inject_host_prefix: bool 

177 :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 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. 

184 

185 :type use_dualstack_endpoint: bool 

186 :param use_dualstack_endpoint: Setting to True enables dualstack 

187 endpoint resolution. 

188 

189 Defaults to None. 

190 

191 :type use_fips_endpoint: bool 

192 :param use_fips_endpoint: Setting to True enables fips 

193 endpoint resolution. 

194 

195 Defaults to None. 

196 

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. 

201 

202 Defaults to None. 

203 

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. 

207 

208 Defaults to False. 

209 

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. 

215 

216 Defaults to None. 

217 

218 :type disable_request_compression: bool 

219 :param disable_request_compression: Disables request body compression if 

220 set to True. 

221 

222 Defaults to None. 

223 

224 :type sigv4a_signing_region_set: string 

225 :param sigv4a_signing_region_set: A set of AWS regions to apply the signature for 

226 when using SigV4a for signing. Set to ``*`` to represent all regions. 

227 

228 Defaults to None. 

229 

230 :type client_context_params: dict 

231 :param client_context_params: A dictionary of parameters specific to 

232 individual services. If available, valid parameters can be found in 

233 the ``Client Context Parameters`` section of the service client's 

234 documentation. Invalid parameters or ones that are not used by the 

235 specified service will be ignored. 

236 

237 Defaults to None. 

238 """ 

239 

240 OPTION_DEFAULTS = OrderedDict( 

241 [ 

242 ('region_name', None), 

243 ('signature_version', None), 

244 ('user_agent', None), 

245 ('user_agent_extra', None), 

246 ('user_agent_appid', None), 

247 ('connect_timeout', DEFAULT_TIMEOUT), 

248 ('read_timeout', DEFAULT_TIMEOUT), 

249 ('parameter_validation', True), 

250 ('max_pool_connections', MAX_POOL_CONNECTIONS), 

251 ('proxies', None), 

252 ('proxies_config', None), 

253 ('s3', None), 

254 ('retries', None), 

255 ('client_cert', None), 

256 ('inject_host_prefix', True), 

257 ('endpoint_discovery_enabled', None), 

258 ('use_dualstack_endpoint', None), 

259 ('use_fips_endpoint', None), 

260 ('ignore_configured_endpoint_urls', None), 

261 ('defaults_mode', None), 

262 ('tcp_keepalive', None), 

263 ('request_min_compression_size_bytes', None), 

264 ('disable_request_compression', None), 

265 ('client_context_params', None), 

266 ('sigv4a_signing_region_set', None), 

267 ] 

268 ) 

269 

270 NON_LEGACY_OPTION_DEFAULTS = { 

271 'connect_timeout': None, 

272 } 

273 

274 def __init__(self, *args, **kwargs): 

275 self._user_provided_options = self._record_user_provided_options( 

276 args, kwargs 

277 ) 

278 

279 # Merge the user_provided options onto the default options 

280 config_vars = copy.copy(self.OPTION_DEFAULTS) 

281 defaults_mode = self._user_provided_options.get( 

282 'defaults_mode', 'legacy' 

283 ) 

284 if defaults_mode != 'legacy': 

285 config_vars.update(self.NON_LEGACY_OPTION_DEFAULTS) 

286 config_vars.update(self._user_provided_options) 

287 

288 # Set the attributes based on the config_vars 

289 for key, value in config_vars.items(): 

290 setattr(self, key, value) 

291 

292 # Validate the s3 options 

293 self._validate_s3_configuration(self.s3) 

294 

295 self._validate_retry_configuration(self.retries) 

296 

297 def _record_user_provided_options(self, args, kwargs): 

298 option_order = list(self.OPTION_DEFAULTS) 

299 user_provided_options = {} 

300 

301 # Iterate through the kwargs passed through to the constructor and 

302 # map valid keys to the dictionary 

303 for key, value in kwargs.items(): 

304 if key in self.OPTION_DEFAULTS: 

305 user_provided_options[key] = value 

306 # The key must exist in the available options 

307 else: 

308 raise TypeError(f"Got unexpected keyword argument '{key}'") 

309 

310 # The number of args should not be longer than the allowed 

311 # options 

312 if len(args) > len(option_order): 

313 raise TypeError( 

314 f"Takes at most {len(option_order)} arguments ({len(args)} given)" 

315 ) 

316 

317 # Iterate through the args passed through to the constructor and map 

318 # them to appropriate keys. 

319 for i, arg in enumerate(args): 

320 # If a kwarg was specified for the arg, then error out 

321 if option_order[i] in user_provided_options: 

322 raise TypeError( 

323 f"Got multiple values for keyword argument '{option_order[i]}'" 

324 ) 

325 user_provided_options[option_order[i]] = arg 

326 

327 return user_provided_options 

328 

329 def _validate_s3_configuration(self, s3): 

330 if s3 is not None: 

331 addressing_style = s3.get('addressing_style') 

332 if addressing_style not in ['virtual', 'auto', 'path', None]: 

333 raise InvalidS3AddressingStyleError( 

334 s3_addressing_style=addressing_style 

335 ) 

336 

337 def _validate_retry_configuration(self, retries): 

338 valid_options = ('max_attempts', 'mode', 'total_max_attempts') 

339 valid_modes = ('legacy', 'standard', 'adaptive') 

340 if retries is not None: 

341 for key, value in retries.items(): 

342 if key not in valid_options: 

343 raise InvalidRetryConfigurationError( 

344 retry_config_option=key, 

345 valid_options=valid_options, 

346 ) 

347 if key == 'max_attempts' and value < 0: 

348 raise InvalidMaxRetryAttemptsError( 

349 provided_max_attempts=value, 

350 min_value=0, 

351 ) 

352 if key == 'total_max_attempts' and value < 1: 

353 raise InvalidMaxRetryAttemptsError( 

354 provided_max_attempts=value, 

355 min_value=1, 

356 ) 

357 if key == 'mode' and value not in valid_modes: 

358 raise InvalidRetryModeError( 

359 provided_retry_mode=value, 

360 valid_modes=valid_modes, 

361 ) 

362 

363 def merge(self, other_config): 

364 """Merges the config object with another config object 

365 

366 This will merge in all non-default values from the provided config 

367 and return a new config object 

368 

369 :type other_config: botocore.config.Config 

370 :param other config: Another config object to merge with. The values 

371 in the provided config object will take precedence in the merging 

372 

373 :returns: A config object built from the merged values of both 

374 config objects. 

375 """ 

376 # Make a copy of the current attributes in the config object. 

377 config_options = copy.copy(self._user_provided_options) 

378 

379 # Merge in the user provided options from the other config 

380 config_options.update(other_config._user_provided_options) 

381 

382 # Return a new config object with the merged properties. 

383 return Config(**config_options)