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

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