docs: def list(self, filter_function=None, list_root='', max_results=1, reverse_order=False, previous_file=''):
  
          ''' a method to list files on localhost from walk of directories
  
          :param filter_function: (keyword arguments) function used to filter results
          :param list_root: string with localhost path from which to root list of files
          :param max_results: integer with maximum number of results to return
          :param reverse_order: boolean to determine alphabetical direction of walk
          :param previous_file: string with absolute path of file to begin search after
          :return: list of file absolute path strings
  
              NOTE:   the filter_function must be able to accept keyword arguments and
                      return a value that can evaluate to true or false. while walking
                      the local file structure, the metadata for each file will be
                      fed to the filter function. if the function evaluates this input
                      and returns a true value the file will be included in the list
                      results.
  
                      fields produced by the metadata function are listed in the
                      self.file_model.schema
          '''
  
          __name__ = '%s.list(...)' % self.__class__.__name__
  
      # validate input
          input_kwargs = [list_root, max_results, previous_file]
          input_names = ['.list_root', '.max_results', '.previous_file']
          for i in range(len(input_kwargs)):
              if input_kwargs[i]:
                  self.fields.validate(input_kwargs[i], input_names[i])
  
      # validate filter function
          if filter_function:
              try:
                  filter_function(**self.file_model.schema)
              except:
                  err_msg = __name__.replace('...', 'filter_function=%s' % filter_function.__class__.__name__)
                  raise TypeError('%s must accept key word arguments.' % err_msg)
  
      # validate that previous file exists
          file_exists = False
          if previous_file:
              if os.path.exists(previous_file):
                  if os.path.isfile(previous_file):
                      file_exists = True
              if not file_exists:
                  err_msg = __name__.replace('...', 'previous_file="%s"' % previous_file)
                  raise ValueError('%s must be a valid file.' % err_msg)
  
      # construct empty results object
          results_list = []
  
      # determine root for walk
          if list_root:
              if not os.path.isdir(list_root):
                  return results_list
          else:
              list_root = './'
  
      # walk directory structure to find files
          for file_path in self.walk(list_root, reverse_order, previous_file):
              if filter_function:
                  file_metadata = self.metadata(file_path)
                  if filter_function(**file_metadata):
                      results_list.append(file_path)
              else:
                  results_list.append(file_path)
  
      # return results list
              if len(results_list) == max_results:
                  return results_list
  
          return results_list