docs: def list_instances(self, tag_values=None):
  
          '''
              a method to retrieve the list of instances on AWS EC2
  
          :param tag_values: [optional] list of tag values
          :return: list of strings with instance AWS ids
          '''
  
          title = '%s.list_instances' % self.__class__.__name__
  
      # validate inputs
          input_fields = {
              'tag_values': tag_values
          }
          for key, value in input_fields.items():
              if value:
                  object_title = '%s(%s=%s)' % (title, key, str(value))
                  self.fields.validate(value, '.%s' % key, object_title)
              
      # add tags to method arguments
          kw_args = {}
          tag_text = ''
          if tag_values:
              kw_args = {
                  'Filters': [ { 'Name': 'tag-value', 'Values': tag_values } ]
              }
              from labpack.parsing.grammar import join_words
              plural_value = ''
              if len(tag_values) > 1:
                  plural_value = 's'
              tag_text = ' with tag value%s %s' % (plural_value, join_words(tag_values))
              
      # request instance details from AWS
          self.iam.printer('Querying AWS region %s for instances%s.' % (self.iam.region_name, tag_text))
          instance_list = []
          try:
              if tag_values:
                  response = self.connection.describe_instances(**kw_args)
              else:
                  response = self.connection.describe_instances()
          except:
              raise AWSConnectionError(title)
  
      # repeat request if any instances are currently pending
          response_list = response['Reservations']
          for instance in response_list:
              instance_info = instance['Instances'][0]
              if instance_info['State']['Name'] == 'pending':
                  self.check_instance_state(instance_info['InstanceId'])
                  try:
                      if tag_values:
                          response = self.connection.describe_instances(**kw_args)
                      else:
                          response = self.connection.describe_instances()
                  except:
                      raise AWSConnectionError(title)
                  response_list = response['Reservations']
  
      # populate list of instances with instance details
          for instance in response_list:
              instance_info = instance['Instances'][0]
              state_name = instance_info['State']['Name']
              if state_name not in ('shutting-down', 'terminated'):
                  instance_list.append(instance_info['InstanceId'])
  
      # report results and return details
          if instance_list:
              print_out = 'Found instance'
              if len(instance_list) > 1:
                  print_out += 's'
              from labpack.parsing.grammar import join_words
              print_out += ' %s.' % join_words(instance_list)
              self.iam.printer(print_out)
          else:
              self.iam.printer('No instances found.')
  
          return instance_list