Where can I find an overview of how the ec2.instancesCollection is built

Question

In boto3 there's a function:

    ec2.instances.filter()

The documentation: http://boto3.readthedocs.org/en/latest/reference/services/ec2.html#instance

Say it returns a list(ec2.Instance) I wish...

when I try printing the return I get this:

    ec2.instancesCollection(ec2.ServiceResource(), ec2.Instance)

I've tried searching for any mention of an ec2.instanceCollection, but the only thing I found was something similar for ruby.

I'd like to iterate through this instanceCollection so I can see how big it is, what machines are present and things like that. Problem is I have no idea how it works, and when it's empty iteration doesn't work at all(It throws an error)

Answer 1

The filter method does not return a list, it returns an iterable. This is basically a Python generator that will produce the desired results on demand in an efficient way.

You can use this iterator in a loop like this:

for instance in ec2.instances.filter():
    # do something with instance

or if you really want a list you can turn the iterator into a list with:

instances = list(ec2.instances.filter())

Answer 2

I'm adding this answer because 5 years later I had the same question and went round in circles trying to find the answer.

First off, the return type in the documentation is wrong (still). As you say, it states that the return type is:
list(ec2.Instance)
where it should be:
ec2.instancesCollection.
At the time of writing there's an open issue in github covering this - https://github.com/boto/boto3/issues/2000.

When you call the filter method a ResourceCollection is created for the particular type of resource against which you called the method. In this case the resource type is instance which gives an instancesCollection. You can see the code for the ResourceCollection superclass of instancesCollection here: https://github.com/boto/boto3/blob/develop/boto3/resources/collection.py

The documentation here gives an overview of the collections: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/collections.html

To get to how to use it and actually answer your question, what I did was to turn the iterator into a list and iterate over the list if the size is > 0.

testList = list(ec2.instances.filter(Filters=filters))

if len(testList) > 0;
  for item in testList;
.
.
.

This may well not be the best way of doing it but it worked for me.