boto3.session
1# Copyright 2014 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# https://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. 13 14import copy 15import os 16 17import botocore.session 18from botocore.client import Config 19from botocore.exceptions import ( 20 DataNotFoundError, 21 NoCredentialsError, 22 UnknownServiceError, 23) 24 25import boto3 26import boto3.utils 27from boto3.exceptions import ResourceNotExistsError, UnknownAPIVersionError 28 29from .resources.factory import ResourceFactory 30 31 32class Session: 33 """ 34 A session stores configuration state and allows you to create service 35 clients and resources. 36 37 :type aws_access_key_id: string 38 :param aws_access_key_id: AWS access key ID 39 :type aws_secret_access_key: string 40 :param aws_secret_access_key: AWS secret access key 41 :type aws_session_token: string 42 :param aws_session_token: AWS temporary session token 43 :type region_name: string 44 :param region_name: Default region when creating new connections 45 :type botocore_session: botocore.session.Session 46 :param botocore_session: Use this Botocore session instead of creating 47 a new default one. 48 :type profile_name: string 49 :param profile_name: The name of a profile to use. If not given, then 50 the default profile is used. 51 :type aws_account_id: string 52 :param aws_account_id: AWS account ID 53 """ 54 55 def __init__( 56 self, 57 aws_access_key_id=None, 58 aws_secret_access_key=None, 59 aws_session_token=None, 60 region_name=None, 61 botocore_session=None, 62 profile_name=None, 63 aws_account_id=None, 64 ): 65 if botocore_session is not None: 66 self._session = botocore_session 67 else: 68 # Create a new default session 69 self._session = botocore.session.get_session() 70 71 # Setup custom user-agent string if it isn't already customized 72 if self._session.user_agent_name == 'Botocore': 73 botocore_info = f'Botocore/{self._session.user_agent_version}' 74 if self._session.user_agent_extra: 75 self._session.user_agent_extra += ' ' + botocore_info 76 else: 77 self._session.user_agent_extra = botocore_info 78 self._session.user_agent_name = 'Boto3' 79 self._session.user_agent_version = boto3.__version__ 80 81 if profile_name is not None: 82 self._session.set_config_variable('profile', profile_name) 83 84 creds = ( 85 aws_access_key_id, 86 aws_secret_access_key, 87 aws_session_token, 88 aws_account_id, 89 ) 90 if any(creds): 91 if self._account_id_set_without_credentials( 92 aws_account_id, aws_access_key_id, aws_secret_access_key 93 ): 94 raise NoCredentialsError() 95 self._session.set_credentials( 96 aws_access_key_id, 97 aws_secret_access_key, 98 aws_session_token, 99 aws_account_id, 100 ) 101 102 if region_name is not None: 103 self._session.set_config_variable('region', region_name) 104 105 self.resource_factory = ResourceFactory( 106 self._session.get_component('event_emitter') 107 ) 108 self._setup_loader() 109 self._register_default_handlers() 110 111 def __repr__(self): 112 return '{}(region_name={})'.format( 113 self.__class__.__name__, 114 repr(self._session.get_config_variable('region')), 115 ) 116 117 @property 118 def profile_name(self): 119 """ 120 The **read-only** profile name. 121 """ 122 return self._session.profile or 'default' 123 124 @property 125 def region_name(self): 126 """ 127 The **read-only** region name. 128 """ 129 return self._session.get_config_variable('region') 130 131 @property 132 def events(self): 133 """ 134 The event emitter for a session 135 """ 136 return self._session.get_component('event_emitter') 137 138 @property 139 def available_profiles(self): 140 """ 141 The profiles available to the session credentials 142 """ 143 return self._session.available_profiles 144 145 def _setup_loader(self): 146 """ 147 Setup loader paths so that we can load resources. 148 """ 149 self._loader = self._session.get_component('data_loader') 150 self._loader.search_paths.append( 151 os.path.join(os.path.dirname(__file__), 'data') 152 ) 153 154 def get_available_services(self): 155 """ 156 Get a list of available services that can be loaded as low-level 157 clients via :py:meth:`Session.client`. 158 159 :rtype: list 160 :return: List of service names 161 """ 162 return self._session.get_available_services() 163 164 def get_available_resources(self): 165 """ 166 Get a list of available services that can be loaded as resource 167 clients via :py:meth:`Session.resource`. 168 169 :rtype: list 170 :return: List of service names 171 """ 172 return self._loader.list_available_services(type_name='resources-1') 173 174 def get_available_partitions(self): 175 """Lists the available partitions 176 177 :rtype: list 178 :return: Returns a list of partition names (e.g., ["aws", "aws-cn"]) 179 """ 180 return self._session.get_available_partitions() 181 182 def get_available_regions( 183 self, service_name, partition_name='aws', allow_non_regional=False 184 ): 185 """Lists the region and endpoint names of a particular partition. 186 187 The list of regions returned by this method are regions that are 188 explicitly known by the client to exist and is not comprehensive. A 189 region not returned in this list may still be available for the 190 provided service. 191 192 :type service_name: string 193 :param service_name: Name of a service to list endpoint for (e.g., s3). 194 195 :type partition_name: string 196 :param partition_name: Name of the partition to limit endpoints to. 197 (e.g., aws for the public AWS endpoints, aws-cn for AWS China 198 endpoints, aws-us-gov for AWS GovCloud (US) Endpoints, etc.) 199 200 :type allow_non_regional: bool 201 :param allow_non_regional: Set to True to include endpoints that are 202 not regional endpoints (e.g., s3-external-1, 203 fips-us-gov-west-1, etc). 204 205 :return: Returns a list of endpoint names (e.g., ["us-east-1"]). 206 """ 207 return self._session.get_available_regions( 208 service_name=service_name, 209 partition_name=partition_name, 210 allow_non_regional=allow_non_regional, 211 ) 212 213 def get_credentials(self): 214 """ 215 Return the :class:`botocore.credentials.Credentials` object 216 associated with this session. If the credentials have not 217 yet been loaded, this will attempt to load them. If they 218 have already been loaded, this will return the cached 219 credentials. 220 """ 221 return self._session.get_credentials() 222 223 def get_partition_for_region(self, region_name): 224 """Lists the partition name of a particular region. 225 226 :type region_name: string 227 :param region_name: Name of the region to list partition for (e.g., 228 us-east-1). 229 230 :rtype: string 231 :return: Returns the respective partition name (e.g., aws). 232 """ 233 return self._session.get_partition_for_region(region_name) 234 235 def client( 236 self, 237 service_name, 238 region_name=None, 239 api_version=None, 240 use_ssl=True, 241 verify=None, 242 endpoint_url=None, 243 aws_access_key_id=None, 244 aws_secret_access_key=None, 245 aws_session_token=None, 246 config=None, 247 aws_account_id=None, 248 ): 249 """ 250 Create a low-level service client by name. 251 252 :type service_name: string 253 :param service_name: The name of a service, e.g. 's3' or 'ec2'. You 254 can get a list of available services via 255 :py:meth:`get_available_services`. 256 257 :type region_name: string 258 :param region_name: The name of the region associated with the client. 259 A client is associated with a single region. 260 261 :type api_version: string 262 :param api_version: The API version to use. By default, botocore will 263 use the latest API version when creating a client. You only need 264 to specify this parameter if you want to use a previous API version 265 of the client. 266 267 :type use_ssl: boolean 268 :param use_ssl: Whether or not to use SSL. By default, SSL is used. 269 Note that not all services support non-ssl connections. 270 271 :type verify: boolean/string 272 :param verify: Whether or not to verify SSL certificates. By default 273 SSL certificates are verified. You can provide the following 274 values: 275 276 * False - do not validate SSL certificates. SSL will still be 277 used (unless use_ssl is False), but SSL certificates 278 will not be verified. 279 * path/to/cert/bundle.pem - A filename of the CA cert bundle to 280 uses. You can specify this argument if you want to use a 281 different CA cert bundle than the one used by botocore. 282 283 :type endpoint_url: string 284 :param endpoint_url: The complete URL to use for the constructed 285 client. Normally, botocore will automatically construct the 286 appropriate URL to use when communicating with a service. You 287 can specify a complete URL (including the "http/https" scheme) 288 to override this behavior. If this value is provided, 289 then ``use_ssl`` is ignored. 290 291 :type aws_access_key_id: string 292 :param aws_access_key_id: The access key to use when creating 293 the client. This is entirely optional, and if not provided, 294 the credentials configured for the session will automatically 295 be used. You only need to provide this argument if you want 296 to override the credentials used for this specific client. 297 298 :type aws_secret_access_key: string 299 :param aws_secret_access_key: The secret key to use when creating 300 the client. Same semantics as aws_access_key_id above. 301 302 :type aws_session_token: string 303 :param aws_session_token: The session token to use when creating 304 the client. Same semantics as aws_access_key_id above. 305 306 :type config: botocore.client.Config 307 :param config: Advanced client configuration options. If region_name 308 is specified in the client config, its value will take precedence 309 over environment variables and configuration values, but not over 310 a region_name value passed explicitly to the method. See 311 `botocore config documentation 312 <https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html>`_ 313 for more details. 314 315 :type aws_account_id: string 316 :param aws_account_id: The account id to use when creating 317 the client. Same semantics as aws_access_key_id above. 318 319 :return: Service client instance 320 321 """ 322 return self._session.create_client( 323 service_name, 324 region_name=region_name, 325 api_version=api_version, 326 use_ssl=use_ssl, 327 verify=verify, 328 endpoint_url=endpoint_url, 329 aws_access_key_id=aws_access_key_id, 330 aws_secret_access_key=aws_secret_access_key, 331 aws_session_token=aws_session_token, 332 config=config, 333 aws_account_id=aws_account_id, 334 ) 335 336 def resource( 337 self, 338 service_name, 339 region_name=None, 340 api_version=None, 341 use_ssl=True, 342 verify=None, 343 endpoint_url=None, 344 aws_access_key_id=None, 345 aws_secret_access_key=None, 346 aws_session_token=None, 347 config=None, 348 ): 349 """ 350 Create a resource service client by name. 351 352 :type service_name: string 353 :param service_name: The name of a service, e.g. 's3' or 'ec2'. You 354 can get a list of available services via 355 :py:meth:`get_available_resources`. 356 357 :type region_name: string 358 :param region_name: The name of the region associated with the client. 359 A client is associated with a single region. 360 361 :type api_version: string 362 :param api_version: The API version to use. By default, botocore will 363 use the latest API version when creating a client. You only need 364 to specify this parameter if you want to use a previous API version 365 of the client. 366 367 :type use_ssl: boolean 368 :param use_ssl: Whether or not to use SSL. By default, SSL is used. 369 Note that not all services support non-ssl connections. 370 371 :type verify: boolean/string 372 :param verify: Whether or not to verify SSL certificates. By default 373 SSL certificates are verified. You can provide the following 374 values: 375 376 * False - do not validate SSL certificates. SSL will still be 377 used (unless use_ssl is False), but SSL certificates 378 will not be verified. 379 * path/to/cert/bundle.pem - A filename of the CA cert bundle to 380 uses. You can specify this argument if you want to use a 381 different CA cert bundle than the one used by botocore. 382 383 :type endpoint_url: string 384 :param endpoint_url: The complete URL to use for the constructed 385 client. Normally, botocore will automatically construct the 386 appropriate URL to use when communicating with a service. You 387 can specify a complete URL (including the "http/https" scheme) 388 to override this behavior. If this value is provided, 389 then ``use_ssl`` is ignored. 390 391 :type aws_access_key_id: string 392 :param aws_access_key_id: The access key to use when creating 393 the client. This is entirely optional, and if not provided, 394 the credentials configured for the session will automatically 395 be used. You only need to provide this argument if you want 396 to override the credentials used for this specific client. 397 398 :type aws_secret_access_key: string 399 :param aws_secret_access_key: The secret key to use when creating 400 the client. Same semantics as aws_access_key_id above. 401 402 :type aws_session_token: string 403 :param aws_session_token: The session token to use when creating 404 the client. Same semantics as aws_access_key_id above. 405 406 :type config: botocore.client.Config 407 :param config: Advanced client configuration options. If region_name 408 is specified in the client config, its value will take precedence 409 over environment variables and configuration values, but not over 410 a region_name value passed explicitly to the method. If 411 user_agent_extra is specified in the client config, it overrides 412 the default user_agent_extra provided by the resource API. See 413 `botocore config documentation 414 <https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html>`_ 415 for more details. 416 417 :return: Subclass of :py:class:`~boto3.resources.base.ServiceResource` 418 """ 419 try: 420 resource_model = self._loader.load_service_model( 421 service_name, 'resources-1', api_version 422 ) 423 except UnknownServiceError: 424 available = self.get_available_resources() 425 has_low_level_client = ( 426 service_name in self.get_available_services() 427 ) 428 raise ResourceNotExistsError( 429 service_name, available, has_low_level_client 430 ) 431 except DataNotFoundError: 432 # This is because we've provided an invalid API version. 433 available_api_versions = self._loader.list_api_versions( 434 service_name, 'resources-1' 435 ) 436 raise UnknownAPIVersionError( 437 service_name, api_version, ', '.join(available_api_versions) 438 ) 439 440 if api_version is None: 441 # Even though botocore's load_service_model() can handle 442 # using the latest api_version if not provided, we need 443 # to track this api_version in boto3 in order to ensure 444 # we're pairing a resource model with a client model 445 # of the same API version. It's possible for the latest 446 # API version of a resource model in boto3 to not be 447 # the same API version as a service model in botocore. 448 # So we need to look up the api_version if one is not 449 # provided to ensure we load the same API version of the 450 # client. 451 # 452 # Note: This is relying on the fact that 453 # loader.load_service_model(..., api_version=None) 454 # and loader.determine_latest_version(..., 'resources-1') 455 # both load the same api version of the file. 456 api_version = self._loader.determine_latest_version( 457 service_name, 'resources-1' 458 ) 459 460 # Creating a new resource instance requires the low-level client 461 # and service model, the resource version and resource JSON data. 462 # We pass these to the factory and get back a class, which is 463 # instantiated on top of the low-level client. 464 if config is not None: 465 if config.user_agent_extra is None: 466 config = copy.deepcopy(config) 467 config.user_agent_extra = 'Resource' 468 else: 469 config = Config(user_agent_extra='Resource') 470 client = self.client( 471 service_name, 472 region_name=region_name, 473 api_version=api_version, 474 use_ssl=use_ssl, 475 verify=verify, 476 endpoint_url=endpoint_url, 477 aws_access_key_id=aws_access_key_id, 478 aws_secret_access_key=aws_secret_access_key, 479 aws_session_token=aws_session_token, 480 config=config, 481 ) 482 service_model = client.meta.service_model 483 484 # Create a ServiceContext object to serve as a reference to 485 # important read-only information about the general service. 486 service_context = boto3.utils.ServiceContext( 487 service_name=service_name, 488 service_model=service_model, 489 resource_json_definitions=resource_model['resources'], 490 service_waiter_model=boto3.utils.LazyLoadedWaiterModel( 491 self._session, service_name, api_version 492 ), 493 ) 494 495 # Create the service resource class. 496 cls = self.resource_factory.load_from_definition( 497 resource_name=service_name, 498 single_resource_json_definition=resource_model['service'], 499 service_context=service_context, 500 ) 501 502 return cls(client=client) 503 504 def _register_default_handlers(self): 505 # S3 customizations 506 self._session.register( 507 'creating-client-class.s3', 508 boto3.utils.lazy_call( 509 'boto3.s3.inject.inject_s3_transfer_methods' 510 ), 511 ) 512 self._session.register( 513 'creating-resource-class.s3.Bucket', 514 boto3.utils.lazy_call('boto3.s3.inject.inject_bucket_methods'), 515 ) 516 self._session.register( 517 'creating-resource-class.s3.Object', 518 boto3.utils.lazy_call('boto3.s3.inject.inject_object_methods'), 519 ) 520 self._session.register( 521 'creating-resource-class.s3.ObjectSummary', 522 boto3.utils.lazy_call( 523 'boto3.s3.inject.inject_object_summary_methods' 524 ), 525 ) 526 527 # DynamoDb customizations 528 self._session.register( 529 'creating-resource-class.dynamodb', 530 boto3.utils.lazy_call( 531 'boto3.dynamodb.transform.register_high_level_interface' 532 ), 533 unique_id='high-level-dynamodb', 534 ) 535 self._session.register( 536 'creating-resource-class.dynamodb.Table', 537 boto3.utils.lazy_call( 538 'boto3.dynamodb.table.register_table_methods' 539 ), 540 unique_id='high-level-dynamodb-table', 541 ) 542 543 # EC2 Customizations 544 self._session.register( 545 'creating-resource-class.ec2.ServiceResource', 546 boto3.utils.lazy_call('boto3.ec2.createtags.inject_create_tags'), 547 ) 548 549 self._session.register( 550 'creating-resource-class.ec2.Instance', 551 boto3.utils.lazy_call( 552 'boto3.ec2.deletetags.inject_delete_tags', 553 event_emitter=self.events, 554 ), 555 ) 556 557 def _account_id_set_without_credentials( 558 self, account_id, access_key, secret_key 559 ): 560 if account_id is None: 561 return False 562 elif access_key is None or secret_key is None: 563 return True 564 return False
class
Session:
33class Session: 34 """ 35 A session stores configuration state and allows you to create service 36 clients and resources. 37 38 :type aws_access_key_id: string 39 :param aws_access_key_id: AWS access key ID 40 :type aws_secret_access_key: string 41 :param aws_secret_access_key: AWS secret access key 42 :type aws_session_token: string 43 :param aws_session_token: AWS temporary session token 44 :type region_name: string 45 :param region_name: Default region when creating new connections 46 :type botocore_session: botocore.session.Session 47 :param botocore_session: Use this Botocore session instead of creating 48 a new default one. 49 :type profile_name: string 50 :param profile_name: The name of a profile to use. If not given, then 51 the default profile is used. 52 :type aws_account_id: string 53 :param aws_account_id: AWS account ID 54 """ 55 56 def __init__( 57 self, 58 aws_access_key_id=None, 59 aws_secret_access_key=None, 60 aws_session_token=None, 61 region_name=None, 62 botocore_session=None, 63 profile_name=None, 64 aws_account_id=None, 65 ): 66 if botocore_session is not None: 67 self._session = botocore_session 68 else: 69 # Create a new default session 70 self._session = botocore.session.get_session() 71 72 # Setup custom user-agent string if it isn't already customized 73 if self._session.user_agent_name == 'Botocore': 74 botocore_info = f'Botocore/{self._session.user_agent_version}' 75 if self._session.user_agent_extra: 76 self._session.user_agent_extra += ' ' + botocore_info 77 else: 78 self._session.user_agent_extra = botocore_info 79 self._session.user_agent_name = 'Boto3' 80 self._session.user_agent_version = boto3.__version__ 81 82 if profile_name is not None: 83 self._session.set_config_variable('profile', profile_name) 84 85 creds = ( 86 aws_access_key_id, 87 aws_secret_access_key, 88 aws_session_token, 89 aws_account_id, 90 ) 91 if any(creds): 92 if self._account_id_set_without_credentials( 93 aws_account_id, aws_access_key_id, aws_secret_access_key 94 ): 95 raise NoCredentialsError() 96 self._session.set_credentials( 97 aws_access_key_id, 98 aws_secret_access_key, 99 aws_session_token, 100 aws_account_id, 101 ) 102 103 if region_name is not None: 104 self._session.set_config_variable('region', region_name) 105 106 self.resource_factory = ResourceFactory( 107 self._session.get_component('event_emitter') 108 ) 109 self._setup_loader() 110 self._register_default_handlers() 111 112 def __repr__(self): 113 return '{}(region_name={})'.format( 114 self.__class__.__name__, 115 repr(self._session.get_config_variable('region')), 116 ) 117 118 @property 119 def profile_name(self): 120 """ 121 The **read-only** profile name. 122 """ 123 return self._session.profile or 'default' 124 125 @property 126 def region_name(self): 127 """ 128 The **read-only** region name. 129 """ 130 return self._session.get_config_variable('region') 131 132 @property 133 def events(self): 134 """ 135 The event emitter for a session 136 """ 137 return self._session.get_component('event_emitter') 138 139 @property 140 def available_profiles(self): 141 """ 142 The profiles available to the session credentials 143 """ 144 return self._session.available_profiles 145 146 def _setup_loader(self): 147 """ 148 Setup loader paths so that we can load resources. 149 """ 150 self._loader = self._session.get_component('data_loader') 151 self._loader.search_paths.append( 152 os.path.join(os.path.dirname(__file__), 'data') 153 ) 154 155 def get_available_services(self): 156 """ 157 Get a list of available services that can be loaded as low-level 158 clients via :py:meth:`Session.client`. 159 160 :rtype: list 161 :return: List of service names 162 """ 163 return self._session.get_available_services() 164 165 def get_available_resources(self): 166 """ 167 Get a list of available services that can be loaded as resource 168 clients via :py:meth:`Session.resource`. 169 170 :rtype: list 171 :return: List of service names 172 """ 173 return self._loader.list_available_services(type_name='resources-1') 174 175 def get_available_partitions(self): 176 """Lists the available partitions 177 178 :rtype: list 179 :return: Returns a list of partition names (e.g., ["aws", "aws-cn"]) 180 """ 181 return self._session.get_available_partitions() 182 183 def get_available_regions( 184 self, service_name, partition_name='aws', allow_non_regional=False 185 ): 186 """Lists the region and endpoint names of a particular partition. 187 188 The list of regions returned by this method are regions that are 189 explicitly known by the client to exist and is not comprehensive. A 190 region not returned in this list may still be available for the 191 provided service. 192 193 :type service_name: string 194 :param service_name: Name of a service to list endpoint for (e.g., s3). 195 196 :type partition_name: string 197 :param partition_name: Name of the partition to limit endpoints to. 198 (e.g., aws for the public AWS endpoints, aws-cn for AWS China 199 endpoints, aws-us-gov for AWS GovCloud (US) Endpoints, etc.) 200 201 :type allow_non_regional: bool 202 :param allow_non_regional: Set to True to include endpoints that are 203 not regional endpoints (e.g., s3-external-1, 204 fips-us-gov-west-1, etc). 205 206 :return: Returns a list of endpoint names (e.g., ["us-east-1"]). 207 """ 208 return self._session.get_available_regions( 209 service_name=service_name, 210 partition_name=partition_name, 211 allow_non_regional=allow_non_regional, 212 ) 213 214 def get_credentials(self): 215 """ 216 Return the :class:`botocore.credentials.Credentials` object 217 associated with this session. If the credentials have not 218 yet been loaded, this will attempt to load them. If they 219 have already been loaded, this will return the cached 220 credentials. 221 """ 222 return self._session.get_credentials() 223 224 def get_partition_for_region(self, region_name): 225 """Lists the partition name of a particular region. 226 227 :type region_name: string 228 :param region_name: Name of the region to list partition for (e.g., 229 us-east-1). 230 231 :rtype: string 232 :return: Returns the respective partition name (e.g., aws). 233 """ 234 return self._session.get_partition_for_region(region_name) 235 236 def client( 237 self, 238 service_name, 239 region_name=None, 240 api_version=None, 241 use_ssl=True, 242 verify=None, 243 endpoint_url=None, 244 aws_access_key_id=None, 245 aws_secret_access_key=None, 246 aws_session_token=None, 247 config=None, 248 aws_account_id=None, 249 ): 250 """ 251 Create a low-level service client by name. 252 253 :type service_name: string 254 :param service_name: The name of a service, e.g. 's3' or 'ec2'. You 255 can get a list of available services via 256 :py:meth:`get_available_services`. 257 258 :type region_name: string 259 :param region_name: The name of the region associated with the client. 260 A client is associated with a single region. 261 262 :type api_version: string 263 :param api_version: The API version to use. By default, botocore will 264 use the latest API version when creating a client. You only need 265 to specify this parameter if you want to use a previous API version 266 of the client. 267 268 :type use_ssl: boolean 269 :param use_ssl: Whether or not to use SSL. By default, SSL is used. 270 Note that not all services support non-ssl connections. 271 272 :type verify: boolean/string 273 :param verify: Whether or not to verify SSL certificates. By default 274 SSL certificates are verified. You can provide the following 275 values: 276 277 * False - do not validate SSL certificates. SSL will still be 278 used (unless use_ssl is False), but SSL certificates 279 will not be verified. 280 * path/to/cert/bundle.pem - A filename of the CA cert bundle to 281 uses. You can specify this argument if you want to use a 282 different CA cert bundle than the one used by botocore. 283 284 :type endpoint_url: string 285 :param endpoint_url: The complete URL to use for the constructed 286 client. Normally, botocore will automatically construct the 287 appropriate URL to use when communicating with a service. You 288 can specify a complete URL (including the "http/https" scheme) 289 to override this behavior. If this value is provided, 290 then ``use_ssl`` is ignored. 291 292 :type aws_access_key_id: string 293 :param aws_access_key_id: The access key to use when creating 294 the client. This is entirely optional, and if not provided, 295 the credentials configured for the session will automatically 296 be used. You only need to provide this argument if you want 297 to override the credentials used for this specific client. 298 299 :type aws_secret_access_key: string 300 :param aws_secret_access_key: The secret key to use when creating 301 the client. Same semantics as aws_access_key_id above. 302 303 :type aws_session_token: string 304 :param aws_session_token: The session token to use when creating 305 the client. Same semantics as aws_access_key_id above. 306 307 :type config: botocore.client.Config 308 :param config: Advanced client configuration options. If region_name 309 is specified in the client config, its value will take precedence 310 over environment variables and configuration values, but not over 311 a region_name value passed explicitly to the method. See 312 `botocore config documentation 313 <https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html>`_ 314 for more details. 315 316 :type aws_account_id: string 317 :param aws_account_id: The account id to use when creating 318 the client. Same semantics as aws_access_key_id above. 319 320 :return: Service client instance 321 322 """ 323 return self._session.create_client( 324 service_name, 325 region_name=region_name, 326 api_version=api_version, 327 use_ssl=use_ssl, 328 verify=verify, 329 endpoint_url=endpoint_url, 330 aws_access_key_id=aws_access_key_id, 331 aws_secret_access_key=aws_secret_access_key, 332 aws_session_token=aws_session_token, 333 config=config, 334 aws_account_id=aws_account_id, 335 ) 336 337 def resource( 338 self, 339 service_name, 340 region_name=None, 341 api_version=None, 342 use_ssl=True, 343 verify=None, 344 endpoint_url=None, 345 aws_access_key_id=None, 346 aws_secret_access_key=None, 347 aws_session_token=None, 348 config=None, 349 ): 350 """ 351 Create a resource service client by name. 352 353 :type service_name: string 354 :param service_name: The name of a service, e.g. 's3' or 'ec2'. You 355 can get a list of available services via 356 :py:meth:`get_available_resources`. 357 358 :type region_name: string 359 :param region_name: The name of the region associated with the client. 360 A client is associated with a single region. 361 362 :type api_version: string 363 :param api_version: The API version to use. By default, botocore will 364 use the latest API version when creating a client. You only need 365 to specify this parameter if you want to use a previous API version 366 of the client. 367 368 :type use_ssl: boolean 369 :param use_ssl: Whether or not to use SSL. By default, SSL is used. 370 Note that not all services support non-ssl connections. 371 372 :type verify: boolean/string 373 :param verify: Whether or not to verify SSL certificates. By default 374 SSL certificates are verified. You can provide the following 375 values: 376 377 * False - do not validate SSL certificates. SSL will still be 378 used (unless use_ssl is False), but SSL certificates 379 will not be verified. 380 * path/to/cert/bundle.pem - A filename of the CA cert bundle to 381 uses. You can specify this argument if you want to use a 382 different CA cert bundle than the one used by botocore. 383 384 :type endpoint_url: string 385 :param endpoint_url: The complete URL to use for the constructed 386 client. Normally, botocore will automatically construct the 387 appropriate URL to use when communicating with a service. You 388 can specify a complete URL (including the "http/https" scheme) 389 to override this behavior. If this value is provided, 390 then ``use_ssl`` is ignored. 391 392 :type aws_access_key_id: string 393 :param aws_access_key_id: The access key to use when creating 394 the client. This is entirely optional, and if not provided, 395 the credentials configured for the session will automatically 396 be used. You only need to provide this argument if you want 397 to override the credentials used for this specific client. 398 399 :type aws_secret_access_key: string 400 :param aws_secret_access_key: The secret key to use when creating 401 the client. Same semantics as aws_access_key_id above. 402 403 :type aws_session_token: string 404 :param aws_session_token: The session token to use when creating 405 the client. Same semantics as aws_access_key_id above. 406 407 :type config: botocore.client.Config 408 :param config: Advanced client configuration options. If region_name 409 is specified in the client config, its value will take precedence 410 over environment variables and configuration values, but not over 411 a region_name value passed explicitly to the method. If 412 user_agent_extra is specified in the client config, it overrides 413 the default user_agent_extra provided by the resource API. See 414 `botocore config documentation 415 <https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html>`_ 416 for more details. 417 418 :return: Subclass of :py:class:`~boto3.resources.base.ServiceResource` 419 """ 420 try: 421 resource_model = self._loader.load_service_model( 422 service_name, 'resources-1', api_version 423 ) 424 except UnknownServiceError: 425 available = self.get_available_resources() 426 has_low_level_client = ( 427 service_name in self.get_available_services() 428 ) 429 raise ResourceNotExistsError( 430 service_name, available, has_low_level_client 431 ) 432 except DataNotFoundError: 433 # This is because we've provided an invalid API version. 434 available_api_versions = self._loader.list_api_versions( 435 service_name, 'resources-1' 436 ) 437 raise UnknownAPIVersionError( 438 service_name, api_version, ', '.join(available_api_versions) 439 ) 440 441 if api_version is None: 442 # Even though botocore's load_service_model() can handle 443 # using the latest api_version if not provided, we need 444 # to track this api_version in boto3 in order to ensure 445 # we're pairing a resource model with a client model 446 # of the same API version. It's possible for the latest 447 # API version of a resource model in boto3 to not be 448 # the same API version as a service model in botocore. 449 # So we need to look up the api_version if one is not 450 # provided to ensure we load the same API version of the 451 # client. 452 # 453 # Note: This is relying on the fact that 454 # loader.load_service_model(..., api_version=None) 455 # and loader.determine_latest_version(..., 'resources-1') 456 # both load the same api version of the file. 457 api_version = self._loader.determine_latest_version( 458 service_name, 'resources-1' 459 ) 460 461 # Creating a new resource instance requires the low-level client 462 # and service model, the resource version and resource JSON data. 463 # We pass these to the factory and get back a class, which is 464 # instantiated on top of the low-level client. 465 if config is not None: 466 if config.user_agent_extra is None: 467 config = copy.deepcopy(config) 468 config.user_agent_extra = 'Resource' 469 else: 470 config = Config(user_agent_extra='Resource') 471 client = self.client( 472 service_name, 473 region_name=region_name, 474 api_version=api_version, 475 use_ssl=use_ssl, 476 verify=verify, 477 endpoint_url=endpoint_url, 478 aws_access_key_id=aws_access_key_id, 479 aws_secret_access_key=aws_secret_access_key, 480 aws_session_token=aws_session_token, 481 config=config, 482 ) 483 service_model = client.meta.service_model 484 485 # Create a ServiceContext object to serve as a reference to 486 # important read-only information about the general service. 487 service_context = boto3.utils.ServiceContext( 488 service_name=service_name, 489 service_model=service_model, 490 resource_json_definitions=resource_model['resources'], 491 service_waiter_model=boto3.utils.LazyLoadedWaiterModel( 492 self._session, service_name, api_version 493 ), 494 ) 495 496 # Create the service resource class. 497 cls = self.resource_factory.load_from_definition( 498 resource_name=service_name, 499 single_resource_json_definition=resource_model['service'], 500 service_context=service_context, 501 ) 502 503 return cls(client=client) 504 505 def _register_default_handlers(self): 506 # S3 customizations 507 self._session.register( 508 'creating-client-class.s3', 509 boto3.utils.lazy_call( 510 'boto3.s3.inject.inject_s3_transfer_methods' 511 ), 512 ) 513 self._session.register( 514 'creating-resource-class.s3.Bucket', 515 boto3.utils.lazy_call('boto3.s3.inject.inject_bucket_methods'), 516 ) 517 self._session.register( 518 'creating-resource-class.s3.Object', 519 boto3.utils.lazy_call('boto3.s3.inject.inject_object_methods'), 520 ) 521 self._session.register( 522 'creating-resource-class.s3.ObjectSummary', 523 boto3.utils.lazy_call( 524 'boto3.s3.inject.inject_object_summary_methods' 525 ), 526 ) 527 528 # DynamoDb customizations 529 self._session.register( 530 'creating-resource-class.dynamodb', 531 boto3.utils.lazy_call( 532 'boto3.dynamodb.transform.register_high_level_interface' 533 ), 534 unique_id='high-level-dynamodb', 535 ) 536 self._session.register( 537 'creating-resource-class.dynamodb.Table', 538 boto3.utils.lazy_call( 539 'boto3.dynamodb.table.register_table_methods' 540 ), 541 unique_id='high-level-dynamodb-table', 542 ) 543 544 # EC2 Customizations 545 self._session.register( 546 'creating-resource-class.ec2.ServiceResource', 547 boto3.utils.lazy_call('boto3.ec2.createtags.inject_create_tags'), 548 ) 549 550 self._session.register( 551 'creating-resource-class.ec2.Instance', 552 boto3.utils.lazy_call( 553 'boto3.ec2.deletetags.inject_delete_tags', 554 event_emitter=self.events, 555 ), 556 ) 557 558 def _account_id_set_without_credentials( 559 self, account_id, access_key, secret_key 560 ): 561 if account_id is None: 562 return False 563 elif access_key is None or secret_key is None: 564 return True 565 return False
A session stores configuration state and allows you to create service clients and resources.
Parameters
- aws_access_key_id: AWS access key ID
- aws_secret_access_key: AWS secret access key
- aws_session_token: AWS temporary session token
- region_name: Default region when creating new connections
- botocore_session: Use this Botocore session instead of creating a new default one.
- profile_name: The name of a profile to use. If not given, then the default profile is used.
- aws_account_id: AWS account ID
Session( aws_access_key_id=None, aws_secret_access_key=None, aws_session_token=None, region_name=None, botocore_session=None, profile_name=None, aws_account_id=None)
56 def __init__( 57 self, 58 aws_access_key_id=None, 59 aws_secret_access_key=None, 60 aws_session_token=None, 61 region_name=None, 62 botocore_session=None, 63 profile_name=None, 64 aws_account_id=None, 65 ): 66 if botocore_session is not None: 67 self._session = botocore_session 68 else: 69 # Create a new default session 70 self._session = botocore.session.get_session() 71 72 # Setup custom user-agent string if it isn't already customized 73 if self._session.user_agent_name == 'Botocore': 74 botocore_info = f'Botocore/{self._session.user_agent_version}' 75 if self._session.user_agent_extra: 76 self._session.user_agent_extra += ' ' + botocore_info 77 else: 78 self._session.user_agent_extra = botocore_info 79 self._session.user_agent_name = 'Boto3' 80 self._session.user_agent_version = boto3.__version__ 81 82 if profile_name is not None: 83 self._session.set_config_variable('profile', profile_name) 84 85 creds = ( 86 aws_access_key_id, 87 aws_secret_access_key, 88 aws_session_token, 89 aws_account_id, 90 ) 91 if any(creds): 92 if self._account_id_set_without_credentials( 93 aws_account_id, aws_access_key_id, aws_secret_access_key 94 ): 95 raise NoCredentialsError() 96 self._session.set_credentials( 97 aws_access_key_id, 98 aws_secret_access_key, 99 aws_session_token, 100 aws_account_id, 101 ) 102 103 if region_name is not None: 104 self._session.set_config_variable('region', region_name) 105 106 self.resource_factory = ResourceFactory( 107 self._session.get_component('event_emitter') 108 ) 109 self._setup_loader() 110 self._register_default_handlers()
profile_name
118 @property 119 def profile_name(self): 120 """ 121 The **read-only** profile name. 122 """ 123 return self._session.profile or 'default'
The read-only profile name.
region_name
125 @property 126 def region_name(self): 127 """ 128 The **read-only** region name. 129 """ 130 return self._session.get_config_variable('region')
The read-only region name.
events
132 @property 133 def events(self): 134 """ 135 The event emitter for a session 136 """ 137 return self._session.get_component('event_emitter')
The event emitter for a session
available_profiles
139 @property 140 def available_profiles(self): 141 """ 142 The profiles available to the session credentials 143 """ 144 return self._session.available_profiles
The profiles available to the session credentials
def
get_available_services(self):
155 def get_available_services(self): 156 """ 157 Get a list of available services that can be loaded as low-level 158 clients via :py:meth:`Session.client`. 159 160 :rtype: list 161 :return: List of service names 162 """ 163 return self._session.get_available_services()
Get a list of available services that can be loaded as low-level
clients via Session.client().
Returns
List of service names
def
get_available_resources(self):
165 def get_available_resources(self): 166 """ 167 Get a list of available services that can be loaded as resource 168 clients via :py:meth:`Session.resource`. 169 170 :rtype: list 171 :return: List of service names 172 """ 173 return self._loader.list_available_services(type_name='resources-1')
Get a list of available services that can be loaded as resource
clients via Session.resource().
Returns
List of service names
def
get_available_partitions(self):
175 def get_available_partitions(self): 176 """Lists the available partitions 177 178 :rtype: list 179 :return: Returns a list of partition names (e.g., ["aws", "aws-cn"]) 180 """ 181 return self._session.get_available_partitions()
Lists the available partitions
Returns
Returns a list of partition names (e.g., ["aws", "aws-cn"])
def
get_available_regions(self, service_name, partition_name='aws', allow_non_regional=False):
183 def get_available_regions( 184 self, service_name, partition_name='aws', allow_non_regional=False 185 ): 186 """Lists the region and endpoint names of a particular partition. 187 188 The list of regions returned by this method are regions that are 189 explicitly known by the client to exist and is not comprehensive. A 190 region not returned in this list may still be available for the 191 provided service. 192 193 :type service_name: string 194 :param service_name: Name of a service to list endpoint for (e.g., s3). 195 196 :type partition_name: string 197 :param partition_name: Name of the partition to limit endpoints to. 198 (e.g., aws for the public AWS endpoints, aws-cn for AWS China 199 endpoints, aws-us-gov for AWS GovCloud (US) Endpoints, etc.) 200 201 :type allow_non_regional: bool 202 :param allow_non_regional: Set to True to include endpoints that are 203 not regional endpoints (e.g., s3-external-1, 204 fips-us-gov-west-1, etc). 205 206 :return: Returns a list of endpoint names (e.g., ["us-east-1"]). 207 """ 208 return self._session.get_available_regions( 209 service_name=service_name, 210 partition_name=partition_name, 211 allow_non_regional=allow_non_regional, 212 )
Lists the region and endpoint names of a particular partition.
The list of regions returned by this method are regions that are explicitly known by the client to exist and is not comprehensive. A region not returned in this list may still be available for the provided service.
Parameters
service_name: Name of a service to list endpoint for (e.g., s3).
partition_name: Name of the partition to limit endpoints to. (e.g., aws for the public AWS endpoints, aws-cn for AWS China endpoints, aws-us-gov for AWS GovCloud (US) Endpoints, etc.)
allow_non_regional: Set to True to include endpoints that are not regional endpoints (e.g., s3-external-1, fips-us-gov-west-1, etc).
Returns
Returns a list of endpoint names (e.g., ["us-east-1"]).
def
get_credentials(self):
214 def get_credentials(self): 215 """ 216 Return the :class:`botocore.credentials.Credentials` object 217 associated with this session. If the credentials have not 218 yet been loaded, this will attempt to load them. If they 219 have already been loaded, this will return the cached 220 credentials. 221 """ 222 return self._session.get_credentials()
Return the botocore.credentials.Credentials object
associated with this session. If the credentials have not
yet been loaded, this will attempt to load them. If they
have already been loaded, this will return the cached
credentials.
def
get_partition_for_region(self, region_name):
224 def get_partition_for_region(self, region_name): 225 """Lists the partition name of a particular region. 226 227 :type region_name: string 228 :param region_name: Name of the region to list partition for (e.g., 229 us-east-1). 230 231 :rtype: string 232 :return: Returns the respective partition name (e.g., aws). 233 """ 234 return self._session.get_partition_for_region(region_name)
Lists the partition name of a particular region.
Parameters
- region_name: Name of the region to list partition for (e.g., us-east-1).
Returns
Returns the respective partition name (e.g., aws).
def
client( self, service_name, region_name=None, api_version=None, use_ssl=True, verify=None, endpoint_url=None, aws_access_key_id=None, aws_secret_access_key=None, aws_session_token=None, config=None, aws_account_id=None):
236 def client( 237 self, 238 service_name, 239 region_name=None, 240 api_version=None, 241 use_ssl=True, 242 verify=None, 243 endpoint_url=None, 244 aws_access_key_id=None, 245 aws_secret_access_key=None, 246 aws_session_token=None, 247 config=None, 248 aws_account_id=None, 249 ): 250 """ 251 Create a low-level service client by name. 252 253 :type service_name: string 254 :param service_name: The name of a service, e.g. 's3' or 'ec2'. You 255 can get a list of available services via 256 :py:meth:`get_available_services`. 257 258 :type region_name: string 259 :param region_name: The name of the region associated with the client. 260 A client is associated with a single region. 261 262 :type api_version: string 263 :param api_version: The API version to use. By default, botocore will 264 use the latest API version when creating a client. You only need 265 to specify this parameter if you want to use a previous API version 266 of the client. 267 268 :type use_ssl: boolean 269 :param use_ssl: Whether or not to use SSL. By default, SSL is used. 270 Note that not all services support non-ssl connections. 271 272 :type verify: boolean/string 273 :param verify: Whether or not to verify SSL certificates. By default 274 SSL certificates are verified. You can provide the following 275 values: 276 277 * False - do not validate SSL certificates. SSL will still be 278 used (unless use_ssl is False), but SSL certificates 279 will not be verified. 280 * path/to/cert/bundle.pem - A filename of the CA cert bundle to 281 uses. You can specify this argument if you want to use a 282 different CA cert bundle than the one used by botocore. 283 284 :type endpoint_url: string 285 :param endpoint_url: The complete URL to use for the constructed 286 client. Normally, botocore will automatically construct the 287 appropriate URL to use when communicating with a service. You 288 can specify a complete URL (including the "http/https" scheme) 289 to override this behavior. If this value is provided, 290 then ``use_ssl`` is ignored. 291 292 :type aws_access_key_id: string 293 :param aws_access_key_id: The access key to use when creating 294 the client. This is entirely optional, and if not provided, 295 the credentials configured for the session will automatically 296 be used. You only need to provide this argument if you want 297 to override the credentials used for this specific client. 298 299 :type aws_secret_access_key: string 300 :param aws_secret_access_key: The secret key to use when creating 301 the client. Same semantics as aws_access_key_id above. 302 303 :type aws_session_token: string 304 :param aws_session_token: The session token to use when creating 305 the client. Same semantics as aws_access_key_id above. 306 307 :type config: botocore.client.Config 308 :param config: Advanced client configuration options. If region_name 309 is specified in the client config, its value will take precedence 310 over environment variables and configuration values, but not over 311 a region_name value passed explicitly to the method. See 312 `botocore config documentation 313 <https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html>`_ 314 for more details. 315 316 :type aws_account_id: string 317 :param aws_account_id: The account id to use when creating 318 the client. Same semantics as aws_access_key_id above. 319 320 :return: Service client instance 321 322 """ 323 return self._session.create_client( 324 service_name, 325 region_name=region_name, 326 api_version=api_version, 327 use_ssl=use_ssl, 328 verify=verify, 329 endpoint_url=endpoint_url, 330 aws_access_key_id=aws_access_key_id, 331 aws_secret_access_key=aws_secret_access_key, 332 aws_session_token=aws_session_token, 333 config=config, 334 aws_account_id=aws_account_id, 335 )
Create a low-level service client by name.
Parameters
service_name: The name of a service, e.g. 's3' or 'ec2'. You can get a list of available services via
get_available_services().region_name: The name of the region associated with the client. A client is associated with a single region.
api_version: The API version to use. By default, botocore will use the latest API version when creating a client. You only need to specify this parameter if you want to use a previous API version of the client.
use_ssl: Whether or not to use SSL. By default, SSL is used. Note that not all services support non-ssl connections.
verify: Whether or not to verify SSL certificates. By default SSL certificates are verified. You can provide the following values:
- False - do not validate SSL certificates. SSL will still be used (unless use_ssl is False), but SSL certificates will not be verified.
- path/to/cert/bundle.pem - A filename of the CA cert bundle to uses. You can specify this argument if you want to use a different CA cert bundle than the one used by botocore.
endpoint_url: The complete URL to use for the constructed client. Normally, botocore will automatically construct the appropriate URL to use when communicating with a service. You can specify a complete URL (including the "http/https" scheme) to override this behavior. If this value is provided, then
use_sslis ignored.aws_access_key_id: The access key to use when creating the client. This is entirely optional, and if not provided, the credentials configured for the session will automatically be used. You only need to provide this argument if you want to override the credentials used for this specific client.
aws_secret_access_key: The secret key to use when creating the client. Same semantics as aws_access_key_id above.
aws_session_token: The session token to use when creating the client. Same semantics as aws_access_key_id above.
config: Advanced client configuration options. If region_name is specified in the client config, its value will take precedence over environment variables and configuration values, but not over a region_name value passed explicitly to the method. See botocore config documentation for more details.
aws_account_id: The account id to use when creating the client. Same semantics as aws_access_key_id above.
Returns
Service client instance
def
resource( self, service_name, region_name=None, api_version=None, use_ssl=True, verify=None, endpoint_url=None, aws_access_key_id=None, aws_secret_access_key=None, aws_session_token=None, config=None):
337 def resource( 338 self, 339 service_name, 340 region_name=None, 341 api_version=None, 342 use_ssl=True, 343 verify=None, 344 endpoint_url=None, 345 aws_access_key_id=None, 346 aws_secret_access_key=None, 347 aws_session_token=None, 348 config=None, 349 ): 350 """ 351 Create a resource service client by name. 352 353 :type service_name: string 354 :param service_name: The name of a service, e.g. 's3' or 'ec2'. You 355 can get a list of available services via 356 :py:meth:`get_available_resources`. 357 358 :type region_name: string 359 :param region_name: The name of the region associated with the client. 360 A client is associated with a single region. 361 362 :type api_version: string 363 :param api_version: The API version to use. By default, botocore will 364 use the latest API version when creating a client. You only need 365 to specify this parameter if you want to use a previous API version 366 of the client. 367 368 :type use_ssl: boolean 369 :param use_ssl: Whether or not to use SSL. By default, SSL is used. 370 Note that not all services support non-ssl connections. 371 372 :type verify: boolean/string 373 :param verify: Whether or not to verify SSL certificates. By default 374 SSL certificates are verified. You can provide the following 375 values: 376 377 * False - do not validate SSL certificates. SSL will still be 378 used (unless use_ssl is False), but SSL certificates 379 will not be verified. 380 * path/to/cert/bundle.pem - A filename of the CA cert bundle to 381 uses. You can specify this argument if you want to use a 382 different CA cert bundle than the one used by botocore. 383 384 :type endpoint_url: string 385 :param endpoint_url: The complete URL to use for the constructed 386 client. Normally, botocore will automatically construct the 387 appropriate URL to use when communicating with a service. You 388 can specify a complete URL (including the "http/https" scheme) 389 to override this behavior. If this value is provided, 390 then ``use_ssl`` is ignored. 391 392 :type aws_access_key_id: string 393 :param aws_access_key_id: The access key to use when creating 394 the client. This is entirely optional, and if not provided, 395 the credentials configured for the session will automatically 396 be used. You only need to provide this argument if you want 397 to override the credentials used for this specific client. 398 399 :type aws_secret_access_key: string 400 :param aws_secret_access_key: The secret key to use when creating 401 the client. Same semantics as aws_access_key_id above. 402 403 :type aws_session_token: string 404 :param aws_session_token: The session token to use when creating 405 the client. Same semantics as aws_access_key_id above. 406 407 :type config: botocore.client.Config 408 :param config: Advanced client configuration options. If region_name 409 is specified in the client config, its value will take precedence 410 over environment variables and configuration values, but not over 411 a region_name value passed explicitly to the method. If 412 user_agent_extra is specified in the client config, it overrides 413 the default user_agent_extra provided by the resource API. See 414 `botocore config documentation 415 <https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html>`_ 416 for more details. 417 418 :return: Subclass of :py:class:`~boto3.resources.base.ServiceResource` 419 """ 420 try: 421 resource_model = self._loader.load_service_model( 422 service_name, 'resources-1', api_version 423 ) 424 except UnknownServiceError: 425 available = self.get_available_resources() 426 has_low_level_client = ( 427 service_name in self.get_available_services() 428 ) 429 raise ResourceNotExistsError( 430 service_name, available, has_low_level_client 431 ) 432 except DataNotFoundError: 433 # This is because we've provided an invalid API version. 434 available_api_versions = self._loader.list_api_versions( 435 service_name, 'resources-1' 436 ) 437 raise UnknownAPIVersionError( 438 service_name, api_version, ', '.join(available_api_versions) 439 ) 440 441 if api_version is None: 442 # Even though botocore's load_service_model() can handle 443 # using the latest api_version if not provided, we need 444 # to track this api_version in boto3 in order to ensure 445 # we're pairing a resource model with a client model 446 # of the same API version. It's possible for the latest 447 # API version of a resource model in boto3 to not be 448 # the same API version as a service model in botocore. 449 # So we need to look up the api_version if one is not 450 # provided to ensure we load the same API version of the 451 # client. 452 # 453 # Note: This is relying on the fact that 454 # loader.load_service_model(..., api_version=None) 455 # and loader.determine_latest_version(..., 'resources-1') 456 # both load the same api version of the file. 457 api_version = self._loader.determine_latest_version( 458 service_name, 'resources-1' 459 ) 460 461 # Creating a new resource instance requires the low-level client 462 # and service model, the resource version and resource JSON data. 463 # We pass these to the factory and get back a class, which is 464 # instantiated on top of the low-level client. 465 if config is not None: 466 if config.user_agent_extra is None: 467 config = copy.deepcopy(config) 468 config.user_agent_extra = 'Resource' 469 else: 470 config = Config(user_agent_extra='Resource') 471 client = self.client( 472 service_name, 473 region_name=region_name, 474 api_version=api_version, 475 use_ssl=use_ssl, 476 verify=verify, 477 endpoint_url=endpoint_url, 478 aws_access_key_id=aws_access_key_id, 479 aws_secret_access_key=aws_secret_access_key, 480 aws_session_token=aws_session_token, 481 config=config, 482 ) 483 service_model = client.meta.service_model 484 485 # Create a ServiceContext object to serve as a reference to 486 # important read-only information about the general service. 487 service_context = boto3.utils.ServiceContext( 488 service_name=service_name, 489 service_model=service_model, 490 resource_json_definitions=resource_model['resources'], 491 service_waiter_model=boto3.utils.LazyLoadedWaiterModel( 492 self._session, service_name, api_version 493 ), 494 ) 495 496 # Create the service resource class. 497 cls = self.resource_factory.load_from_definition( 498 resource_name=service_name, 499 single_resource_json_definition=resource_model['service'], 500 service_context=service_context, 501 ) 502 503 return cls(client=client)
Create a resource service client by name.
Parameters
service_name: The name of a service, e.g. 's3' or 'ec2'. You can get a list of available services via
get_available_resources().region_name: The name of the region associated with the client. A client is associated with a single region.
api_version: The API version to use. By default, botocore will use the latest API version when creating a client. You only need to specify this parameter if you want to use a previous API version of the client.
use_ssl: Whether or not to use SSL. By default, SSL is used. Note that not all services support non-ssl connections.
verify: Whether or not to verify SSL certificates. By default SSL certificates are verified. You can provide the following values:
- False - do not validate SSL certificates. SSL will still be used (unless use_ssl is False), but SSL certificates will not be verified.
- path/to/cert/bundle.pem - A filename of the CA cert bundle to uses. You can specify this argument if you want to use a different CA cert bundle than the one used by botocore.
endpoint_url: The complete URL to use for the constructed client. Normally, botocore will automatically construct the appropriate URL to use when communicating with a service. You can specify a complete URL (including the "http/https" scheme) to override this behavior. If this value is provided, then
use_sslis ignored.aws_access_key_id: The access key to use when creating the client. This is entirely optional, and if not provided, the credentials configured for the session will automatically be used. You only need to provide this argument if you want to override the credentials used for this specific client.
aws_secret_access_key: The secret key to use when creating the client. Same semantics as aws_access_key_id above.
aws_session_token: The session token to use when creating the client. Same semantics as aws_access_key_id above.
config: Advanced client configuration options. If region_name is specified in the client config, its value will take precedence over environment variables and configuration values, but not over a region_name value passed explicitly to the method. If user_agent_extra is specified in the client config, it overrides the default user_agent_extra provided by the resource API. See botocore config documentation for more details.
Returns
Subclass of
~boto3.resources.base.ServiceResource