Collections reference#

class ibm_boto3.resources.collection.CollectionFactory[source]#

A factory to create new CollectionManager and ResourceCollection subclasses from a Collection model. These subclasses include methods to perform batch operations.

load_from_definition(resource_name, collection_model, service_context, event_emitter)[source]#

Loads a collection from a model, creating a new CollectionManager subclass with the correct properties and methods, named based on the service and resource name, e.g. ec2.InstanceCollectionManager. It also creates a new ResourceCollection subclass which is used by the new manager class.

Parameters:

resource_name (string) – Name of the resource to look up. For services, this should match the service_name.
service_context (ServiceContext) – Context about the AWS service
event_emitter (HierarchialEmitter) – An event emitter

Return type:

Subclass of CollectionManager

Returns:

The collection class.

class ibm_boto3.resources.collection.CollectionManager(collection_model, parent, factory, service_context)[source]#

A collection manager provides access to resource collection instances, which can be iterated and filtered. The manager exposes some convenience functions that are also found on resource collections, such as all() and filter().

Get all items:

>>> for bucket in s3.buckets.all():
...     print(bucket.name)

Get only some items via filtering:

>>> for queue in sqs.queues.filter(QueueNamePrefix='AWS'):
...     print(queue.url)

Get whole pages of items:

>>> for page in s3.Bucket('ibm_boto3').objects.pages():
...     for obj in page:
...         print(obj.key)

A collection manager is not iterable. You must call one of the methods that return a ResourceCollection before trying to iterate, slice, or convert to a list.

See the guide_collections guide for a high-level overview of collections, including when remote service requests are performed.

Parameters:

model – Collection model
parent (ServiceResource) – The collection’s parent resource
factory (ResourceFactory) – The resource factory to create new resources
service_context (ServiceContext) – Context about the AWS service

all()[source]#

Get all items from the collection, optionally with a custom page size and item count limit.

This method returns an iterable generator which yields individual resource instances. Example use:

# Iterate through items
>>> for queue in sqs.queues.all():
...     print(queue.url)
'https://url1'
'https://url2'

# Convert to list
>>> queues = list(sqs.queues.all())
>>> len(queues)
2

filter(**kwargs)[source]#

Get items from the collection, passing keyword arguments along as parameters to the underlying service operation, which are typically used to filter the results.

This method returns an iterable generator which yields individual resource instances. Example use:

# Iterate through items
>>> for queue in sqs.queues.filter(Param='foo'):
...     print(queue.url)
'https://url1'
'https://url2'

# Convert to list
>>> queues = list(sqs.queues.filter(Param='foo'))
>>> len(queues)
2

Return type:: ResourceCollection

iterator(**kwargs)[source]#

Get a resource collection iterator from this manager.

Return type:: ResourceCollection
Returns:: An iterable representing the collection of resources

limit(count)[source]#

Return at most this many resources.

>>> for bucket in s3.buckets.limit(5):
...     print(bucket.name)
'bucket1'
'bucket2'
'bucket3'
'bucket4'
'bucket5'

Parameters:: count (int) – Return no more than this many items
Return type:: ResourceCollection

page_size(count)[source]#

Fetch at most this many resources per service request.

>>> for obj in s3.Bucket('ibm_boto3').objects.page_size(100):
...     print(obj.key)

Parameters:: count (int) – Fetch this many items per request
Return type:: ResourceCollection

pages()[source]#

A generator which yields pages of resource instances after doing the appropriate service operation calls and handling any pagination on your behalf. Non-paginated calls will return a single page of items.

Page size, item limit, and filter parameters are applied if they have previously been set.

>>> bucket = s3.Bucket('ibm_boto3')
>>> for page in bucket.objects.pages():
...     for obj in page:
...         print(obj.key)
'key1'
'key2'

Return type:: list(ServiceResource)
Returns:: List of resource instances

class ibm_boto3.resources.collection.ResourceCollection(model, parent, handler, **kwargs)[source]#

Represents a collection of resources, which can be iterated through, optionally with filtering. Collections automatically handle pagination for you.

See guide_collections for a high-level overview of collections, including when remote service requests are performed.

Parameters:

model (Collection) – Collection model
parent (ServiceResource) – The collection’s parent resource
handler (ResourceHandler) – The resource response handler used to create resource instances

all()[source]#

Get all items from the collection, optionally with a custom page size and item count limit.

This method returns an iterable generator which yields individual resource instances. Example use:

# Iterate through items
>>> for queue in sqs.queues.all():
...     print(queue.url)
'https://url1'
'https://url2'

# Convert to list
>>> queues = list(sqs.queues.all())
>>> len(queues)
2

filter(**kwargs)[source]#

Get items from the collection, passing keyword arguments along as parameters to the underlying service operation, which are typically used to filter the results.

This method returns an iterable generator which yields individual resource instances. Example use:

# Iterate through items
>>> for queue in sqs.queues.filter(Param='foo'):
...     print(queue.url)
'https://url1'
'https://url2'

# Convert to list
>>> queues = list(sqs.queues.filter(Param='foo'))
>>> len(queues)
2

Return type:: ResourceCollection

limit(count)[source]#

Return at most this many resources.

>>> for bucket in s3.buckets.limit(5):
...     print(bucket.name)
'bucket1'
'bucket2'
'bucket3'
'bucket4'
'bucket5'

Parameters:: count (int) – Return no more than this many items
Return type:: ResourceCollection

page_size(count)[source]#

Fetch at most this many resources per service request.

>>> for obj in s3.Bucket('ibm_boto3').objects.page_size(100):
...     print(obj.key)

Parameters:: count (int) – Fetch this many items per request
Return type:: ResourceCollection

pages()[source]#

Page size, item limit, and filter parameters are applied if they have previously been set.

>>> bucket = s3.Bucket('ibm_boto3')
>>> for page in bucket.objects.pages():
...     for obj in page:
...         print(obj.key)
'key1'
'key2'

Return type:: list(ServiceResource)
Returns:: List of resource instances