Overview¶

Resources represent an object-oriented interface to Amazon Web Services (AWS).They provide a higher-level abstraction than the raw, low-level calls made byservice clients. To use resources, you invoke theresource() method of aSession and pass in a service name:

# Get resources from the default sessionsqs=boto3.resource('sqs')s3=boto3.resource('s3')

Every resource instance has a number of attributes and methods. These canconceptually be split up into identifiers, attributes, actions, references,sub-resources, and collections. Each of these is described in further detailbelow and in the following section.

Resources themselves can also be conceptually split into service resources(likesqs,s3,ec2, etc) and individual resources (likesqs.Queue ors3.Bucket). Service resourcesdo not haveidentifiers or attributes. The two share the same components otherwise.

Identifiers and attributes¶

An identifier is a unique value that is used to call actions on the resource.Resourcesmust have at least one identifier, except for the top-levelservice resources (e.g.sqs ors3). An identifier is set at instancecreation-time, and failing to provide all necessary identifiers duringinstantiation will result in an exception. Examples of identifiers:

# SQS Queue (url is an identifier)queue=sqs.Queue(url='http://...')print(queue.url)# S3 Object (bucket_name and key are identifiers)obj=s3.Object(bucket_name='amzn-s3-demo-bucket',key='test.py')print(obj.bucket_name)print(obj.key)# Raises exception, missing identifier: key!obj=s3.Object(bucket_name='amzn-s3-demo-bucket')

Identifiers may also be passed as positional arguments:

# SQS Queuequeue=sqs.Queue('http://...')# S3 Objectobj=s3.Object('boto3','test.py')# Raises exception, missing key!obj=s3.Object('boto3')

Identifiers also play a role in resource instance equality. For twoinstances of a resource to be considered equal, their identifiers mustbe equal:

>>>bucket1=s3.Bucket('amzn-s3-demo-bucket1')>>>bucket2=s3.Bucket('amzn-s3-demo-bucket1')>>>bucket3=s3.Bucket('amzn-s3-demo-bucket3')>>>bucket1==bucket2True>>>bucket1==bucket3False

Resources may also have attributes, which arelazy-loaded properties on theinstance. They may be set at creation time from the response of an action onanother resource, or they may be set when accessed or via an explicit call totheload orreload action. Examples of attributes:

# SQS Messagemessage.body# S3 Objectobj.last_modifiedobj.e_tag

Actions¶

An action is a method which makes a call to the service. Actions may return alow-level response, a new resource instance or a list of new resourceinstances. Actions automatically set the resource identifiers as parameters,but allow you to pass additional parameters via keyword arguments. Examplesof actions:

# SQS Queuemessages=queue.receive_messages()# SQS Messageformessageinmessages:message.delete()# S3 Objectobj=s3.Object(bucket_name='amzn-s3-demo-bucket',key='test.py')response=obj.get()data=response['Body'].read()

Examples of sending additional parameters:

# SQS Servicequeue=sqs.get_queue_by_name(QueueName='test')# SQS Queuequeue.send_message(MessageBody='hello')

References¶

A reference is an attribute which may beNone or a related resourceinstance. The resource instance does not share identifiers with itsreference resource, that is, it is not a strict parent to child relationship.In relational terms, these can be considered many-to-one or one-to-one.Examples of references:

# EC2 Instanceinstance.subnetinstance.vpc

In the above example, an EC2 instance may have exactly one associatedsubnet, and may have exactly one associated VPC. The subnet does notrequire the instance ID to exist, hence it is not a parent to childrelationship.

Sub-resources¶

A sub-resource is similar to a reference, but is a related class rather thanan instance. Sub-resources, when instantiated, share identifiers with theirparent. It is a strict parent-child relationship. In relational terms, thesecan be considered one-to-many. Examples of sub-resources:

# SQSqueue=sqs.Queue(url='...')message=queue.Message(receipt_handle='...')print(queue.url==message.queue_url)print(message.receipt_handle)# S3obj=bucket.Object(key='new_file.txt')print(obj.bucket_name)print(obj.key)

Because an SQS message cannot exist without a queue, and an S3 object cannotexist without a bucket, these are parent to child relationships.

Waiters¶

A waiter is similar to an action. A waiter will poll the status of aresource and suspend execution until the resource reaches the state that isbeing polled for or a failure occurs while polling.Waiters automatically set the resourceidentifiers as parameters, but allow you to pass additional parameters viakeyword arguments. Examples of waiters include:

# S3: Wait for a bucket to exist.bucket.wait_until_exists()# EC2: Wait for an instance to reach the running state.instance.wait_until_running()

Multithreading or multiprocessing with resources¶

Resource instances arenot thread safe and should not be sharedacross threads or processes. These special classes contain additionalmeta data that cannot be shared. It’s recommended to create a newResource for each thread or process:

importboto3importboto3.sessionimportthreadingclassMyTask(threading.Thread):defrun(self):# Here we create a new session per threadsession=boto3.session.Session()# Next, we create a resource client using our thread's session objects3=session.resource('s3')# Put your thread-safe code here

In the example above, each thread would have its own Boto3 session andits own instance of the S3 resource. This is a good idea becauseresources contain shared data when loaded and calling actions, accessingproperties, or manually loading or reloading the resource can modifythis data.