docs: def read_instance(self, instance_id):
  
          '''
              a method to retrieving the details of a single instances on AWS EC2
  
          :param instance_id: string of instance id on AWS
          :return: dictionary with instance attributes
  
          relevant fields:
          
          'instance_id': '',
          'image_id': '',
          'instance_type': '',
          'region': '',
          'state': { 'name': '' },
          'key_name': '',
          'public_dns_name': '',
          'public_ip_address': '',
          'tags': [{'key': '', 'value': ''}]
          '''
  
          title = '%s.read_instance' % self.__class__.__name__
  
      # validate inputs
          input_fields = {
              'instance_id': instance_id
          }
          for key, value in input_fields.items():
              object_title = '%s(%s=%s)' % (title, key, str(value))
              self.fields.validate(value, '.%s' % key, object_title)
  
      # report query
          self.iam.printer('Querying AWS region %s for properties of instance %s.' % (self.iam.region_name, instance_id))
  
      # check instance state
          self.iam.printer_on = False
          self.check_instance_state(instance_id)
          self.iam.printer_on = True
  
      # discover details associated with instance id
          try:
              response = self.connection.describe_instances(InstanceIds=[ instance_id ])
          except:
              raise AWSConnectionError(title)
          instance_info = response['Reservations'][0]['Instances'][0]
  
      # repeat request if any instances are currently pending
          if instance_info['State']['Name'] == 'pending':
              self.check_instance_state(instance_info['InstanceId'])
              try:
                  response = self.connection.describe_instances(
                      InstanceIds=[ instance_id ]
                  )
              except:
                  raise AWSConnectionError(title)
              instance_info = response['Reservations'][0]['Instances'][0]
  
      # create dictionary of instance details
          instance_details = {
              'instance_id': '',
              'image_id': '',
              'key_name': '',
              'instance_type': '',
              'region': self.iam.region_name,
              'tags': [],
              'public_ip_address': '',
              'public_dns_name': '',
              'security_groups': [],
              'subnet_id': '',
              'vpc_id': ''
          }
          instance_details = self.iam.ingest(instance_info, instance_details)
  
          return instance_details