"""Read and cache directory listings.



The listdir() routine returns a sorted list of the files in a directory,

using a cache to avoid reading the directory more often than necessary.

The annotate() routine appends slashes to directories."""

from warnings import warnpy3k

warnpy3k("the dircache module has been removed in Python 3.0", stacklevel=2)

del warnpy3k



import os



__all__ = ["listdir", "opendir", "annotate", "reset"]



cache = {}



def reset():

    """Reset the cache completely."""

    global cache

    cache = {}



def listdir(path):

    """List directory contents, using cache."""

    try:

        cached_mtime, list = cache[path]

        del cache[path]

    except KeyError:

        cached_mtime, list = -1, []

    mtime = os.stat(path).st_mtime

    if mtime != cached_mtime:

        list = os.listdir(path)

        list.sort()

    cache[path] = mtime, list

    return list



opendir = listdir # XXX backward compatibility



def annotate(head, list):

    """Add '/' suffixes to directories."""

    for i in range(len(list)):

        if os.path.isdir(os.path.join(head, list[i])):

            list[i] = list[i] + '/'

