Start moving get_all_instances to get_all_reservations

get_all_instances doesn't actually get all instances, but rather gets
all *reservations*, which themselves contain instances.  This commit
starts the process of making get_all_instances actually return a list of
instances by doing a few things:

1. Rename the current get_all_instances to get_all_reservations.
2. Make get_all_instances a stub that warns and then calls
   get_all_reservations.
3. Add a new get_only_instances method that will eventually become the
   new behavior of get_all_instances.

People can then transition to get_all_reservations and
get_only_instances as appropriate until get_all_instances finally
switches over in a future release.

Author: gholms

bin/elbadmin

@@ -118,9 +118,8 @@ def get(elb, name):
         instances = [state.instance_id for state in instance_health]
 
         names = {}
-        for r in ec2.get_all_instances(instances):
-            for i in r.instances:
-                names[i.id] = i.tags.get('Name', '')
+        for i in ec2.get_only_instances(instances):
+            names[i.id] = i.tags.get('Name', '')
 
         name_column_width = max([4] + [len(v) for k,v in names.iteritems()]) + 2
 

bin/instance_events

@@ -51,7 +51,7 @@ def list(region, headers, order, completed):
 
     ec2 = boto.connect_ec2(region=region)
 
-    reservations = ec2.get_all_instances()
+    reservations = ec2.get_all_reservations()
 
     instanceinfo = {}
     events = {}

bin/list_instances

@@ -76,7 +76,7 @@ def main():
         print format_string % headers
         print "-" * len(format_string % headers)
 
-    for r in ec2.get_all_instances(filters=filters):
+    for r in ec2.get_all_reservations(filters=filters):
         groups = [g.name for g in r.groups]
         for i in r.instances:
             i.groups = ','.join(groups)

boto/ec2/connection.py

@@ -435,12 +435,69 @@ def reset_image_attribute(self, image_id, attribute='launchPermission'):
     # Instance methods
 
     def get_all_instances(self, instance_ids=None, filters=None):
+        """
+        Retrieve all the instance reservations associated with your account.
+
+        .. note::
+        This method's current behavior is deprecated in favor of
+        :meth:`get_all_reservations`.  A future major release will change
+        :meth:`get_all_instances` to return a list of
+        :class:`boto.ec2.instance.Instance` objects as its name suggests.
+        To obtain that behavior today, use :meth:`get_only_instances`.
+
+        :type instance_ids: list
+        :param instance_ids: A list of strings of instance IDs
+
+        :type filters: dict
+        :param filters: Optional filters that can be used to limit the
+            results returned.  Filters are provided in the form of a
+            dictionary consisting of filter names as the key and
+            filter values as the value.  The set of allowable filter
+            names/values is dependent on the request being performed.
+            Check the EC2 API guide for details.
+
+        :rtype: list
+        :return: A list of  :class:`boto.ec2.instance.Reservation`
+
+        """
+        warnings.warn(('The current get_all_instances implementation will be '
+                       'replaced with get_all_reservations.'),
+                      PendingDeprecationWarning)
+        return self.get_all_reservations(instance_ids=instance_ids,
+                                         filters=filters)
+
+    def get_only_instances(self, instance_ids=None, filters=None):
+        # A future release should rename this method to get_all_instances
+        # and make get_only_instances an alias for that.
         """
         Retrieve all the instances associated with your account.
 
         :type instance_ids: list
         :param instance_ids: A list of strings of instance IDs
 
+        :type filters: dict
+        :param filters: Optional filters that can be used to limit the
+            results returned.  Filters are provided in the form of a
+            dictionary consisting of filter names as the key and
+            filter values as the value.  The set of allowable filter
+            names/values is dependent on the request being performed.
+            Check the EC2 API guide for details.
+
+        :rtype: list
+        :return: A list of  :class:`boto.ec2.instance.Instance`
+        """
+        reservations = self.get_all_reservations(instance_ids=instance_ids,
+                                                 filters=filters)
+        return [instance for reservation in reservations
+                for instance in reservation.instances]
+
+    def get_all_reservations(self, instance_ids=None, filters=None):
+        """
+        Retrieve all the instance reservations associated with your account.
+
+        :type instance_ids: list
+        :param instance_ids: A list of strings of instance IDs
+
         :type filters: dict
         :param filters: Optional filters that can be used to limit the
             results returned.  Filters are provided in the form of a

boto/ec2/instance.py

@@ -418,7 +418,7 @@ def update(self, validate=False):
                          raise a ValueError exception if no data is
                          returned from EC2.
         """
-        rs = self.connection.get_all_instances([self.id])
+        rs = self.connection.get_all_reservations([self.id])
         if len(rs) > 0:
             r = rs[0]
             for i in r.instances:

boto/ec2/securitygroup.py

@@ -271,9 +271,13 @@ def instances(self):
         """
         rs = []
         if self.vpc_id:
-            rs.extend(self.connection.get_all_instances(filters={'instance.group-id': self.id}))
+            rs.extend(self.connection.get_all_reservations(
+                filters={'instance.group-id': self.id}
+            ))
         else:
-            rs.extend(self.connection.get_all_instances(filters={'group-id': self.id}))
+            rs.extend(self.connection.get_all_reservations(
+                filters={'group-id': self.id}
+            ))
         instances = [i for r in rs for i in r.instances]
         return instances
 

boto/manage/server.py

@@ -353,7 +353,7 @@ def create_from_instance_id(cls, instance_id, name, description=''):
         for region in regions:
             ec2 = region.connect()
             try:
-                rs = ec2.get_all_instances([instance_id])
+                rs = ec2.get_all_reservations([instance_id])
             except:
                 rs = []
             if len(rs) == 1:
@@ -377,7 +377,7 @@ def create_from_current_instances(cls):
         regions = boto.ec2.regions()
         for region in regions:
             ec2 = region.connect()
-            rs = ec2.get_all_instances()
+            rs = ec2.get_all_reservations()
             for reservation in rs:
                 for instance in reservation.instances:
                     try:
@@ -413,7 +413,7 @@ def _setup_ec2(self):
                         self.ec2 = region.connect()
                         if self.instance_id and not self._instance:
                             try:
-                                rs = self.ec2.get_all_instances([self.instance_id])
+                                rs = self.ec2.get_all_reservations([self.instance_id])
                                 if len(rs) >= 1:
                                     for instance in rs[0].instances:
                                         if instance.id == self.instance_id:

boto/mashups/server.py

@@ -114,7 +114,7 @@ def getInstance(self):
         if not self._instance:
             if self.instance_id:
                 try:
-                    rs = self.ec2.get_all_instances([self.instance_id])
+                    rs = self.ec2.get_all_reservations([self.instance_id])
                 except:
                     return None
                 if len(rs) > 0:

boto/pyami/installers/ubuntu/ebs.py

@@ -122,7 +122,7 @@ def attach(self):
         while volume.update() != 'available':
             boto.log.info('Volume %s not yet available. Current status = %s.' % (volume.id, volume.status))
             time.sleep(5)
-        instance = ec2.get_all_instances([self.instance_id])[0].instances[0]
+        instance = ec2.get_only_instances([self.instance_id])[0]
         attempt_attach = True
         while attempt_attach:
             try:

docs/source/autoscale_tut.rst

@@ -201,8 +201,7 @@ To retrieve the instances in your autoscale group:
 >>> ec2 = boto.ec2.connect_to_region('us-west-2)
 >>> conn.get_all_groups(names=['my_group'])[0]
 >>> instance_ids = [i.instance_id for i in group.instances]
->>> reservations = ec2.get_all_instances(instance_ids)
->>> instances = [i for r in reservations for i in r.instances]
+>>> instances = ec2.get_only_instances(instance_ids)
 
 To delete your autoscale group, we first need to shutdown all the
 instances: