human
Here's a good function header given the following:
I wrote the below code

    def _fs_ls(path):
        try:
            if fs.exists(log_dir):
                for path in fs.ls(log_dir):
                    (yield path)
        except (IOError, OSError) as e:
            log.warning(("couldn't    ls()    %s:    %r" % (log_dir, e)))
    for log_dirs in log_dir_stream:
        if isinstance(log_dirs, str):
            raise TypeError
        matches = []
        for log_dir in log_dirs:
            for path in _fs_ls(log_dir):
                m = matcher(path, **kwargs)
                if (m is not None):
                    m['path'] = path
                    matches.append(m)
        if matches:
            return _sort_by_recency(matches)
    return []

What's a good function header?
assistant
#Here's a good function header.

def _ls_logs(fs, log_dir_stream, matcher, **kwargs):