docs: def check_image_state(self, image_id, wait=True):
  
          '''
              method for checking the state of an image on AWS EC2
  
          :param image_id: string with AWS id of image
          :param wait: [optional] boolean to wait for image while pending
          :return: string reporting state of image
          '''
  
          title = '%s.check_image_state' % self.__class__.__name__
  
      # validate inputs
          input_fields = {
              'image_id': image_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)
  
      # notify state check
          self.iam.printer('Querying AWS region %s for state of image %s.' % (self.iam.region_name, image_id))
          
      # check connection to API
          try:
              self.connection.describe_instances()
          except:
              raise AWSConnectionError(title)
  
      # check existence of image
          try:
              response = self.connection.describe_images(ImageIds=[ image_id ])
          except:
              raise ValueError('\nImage %s does not exist in your permission scope.' % image_id)
          if not 'Images' in response.keys():
              raise ValueError('\nImage %s does not exist in your permission scope.' % image_id)
          elif not response['Images'][0]:
              raise ValueError('\nImage %s does not exist in your permission scope.' % image_id)
  
      # check into state of image
          elif not 'State' in response['Images'][0].keys():
              from time import sleep
              from timeit import timeit as timer
              self.iam.printer('Checking into the status of image %s' % image_id, flush=True)
              state_timeout = 0
              while not 'State' in response['Images'][0].keys():
                  self.iam.printer('.', flush=True)
                  sleep(3)
                  state_timeout += 1
                  response = self.connection.describe_images(
                      ImageIds=[ image_id ]
                  )
                  if state_timeout > 3:
                      raise Exception('\nFailure to determine status of image %s.' % image_id)
              self.iam.printer(' done.')
          image_state = response['Images'][0]['State']
  
      # return None if image has already been deregistered or is invalid
          if image_state == 'deregistered':
              self.iam.printer('Image %s has already been deregistered.' % image_id)
              return None
          elif image_state == 'invalid' or image_state == 'transient' or image_state == 'failed':
              self.iam.printer('Image %s is %s.' % (image_id, image_state))
              return None
  
      # wait while image is pending
          elif image_state == 'pending':
              self.iam.printer('Image %s is %s.' % (image_id, image_state), flush=True)
              if not wait:
                  return image_state
              else:
                  from time import sleep
                  from timeit import timeit as timer
                  delay = 3
                  state_timeout = 0
                  while image_state != 'available':
                      self.iam.printer('.', flush=True)
                      sleep(delay)
                      t3 = timer()
                      response = self.connection.describe_images(
                          ImageIds=[ image_id ]
                      )
                      t4 = timer()
                      state_timeout += 1
                      response_time = t4 - t3
                      if 3 - response_time > 0:
                          delay = 3 - response_time
                      else:
                          delay = 0
                      if state_timeout > 300:
                          raise Exception('\nTimeout. Failure initializing image %s on AWS in less than 15min' % image_id)
                      image_state = response['Images'][0]['State']
                  self.iam.printer(' done.')
  
      # report outcome
          self.iam.printer('Image %s is %s.' % (image_id, image_state))
          
          return image_state