Doc/library/dircache.rst

   1
   2 :mod:`dircache` --- Cached directory listings
   3 =============================================
   4
   5 .. module:: dircache
   6    :synopsis: Return directory listing, with cache mechanism.
   7    :deprecated:
   8
   9 .. deprecated:: 2.6
  10    The :mod:`dircache` module has been removed in Python 3.0.
  11
  12
  13 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
  14
  15
  16 The :mod:`dircache` module defines a function for reading directory listing
  17 using a cache, and cache invalidation using the *mtime* of the directory.
  18 Additionally, it defines a function to annotate directories by appending a
  19 slash.
  20
  21 The :mod:`dircache` module defines the following functions:
  22
  23
  24 .. function:: reset()
  25
  26    Resets the directory cache.
  27
  28
  29 .. function:: listdir(path)
  30
  31    Return a directory listing of *path*, as gotten from :func:`os.listdir`. Note
  32    that unless *path* changes, further call to :func:`listdir` will not re-read the
  33    directory structure.
  34
  35    Note that the list returned should be regarded as read-only. (Perhaps a future
  36    version should change it to return a tuple?)
  37
  38
  39 .. function:: opendir(path)
  40
  41    Same as :func:`listdir`. Defined for backwards compatibility.
  42
  43
  44 .. function:: annotate(head, list)
  45
  46    Assume *list* is a list of paths relative to *head*, and append, in place, a
  47    ``'/'`` to each path which points to a directory.
  48
  49 ::
  50
  51    >>> import dircache
  52    >>> a = dircache.listdir('/')
  53    >>> a = a[:] # Copy the return value so we can change 'a'
  54    >>> a
  55    ['bin', 'boot', 'cdrom', 'dev', 'etc', 'floppy', 'home', 'initrd', 'lib', 'lost+
  56    found', 'mnt', 'proc', 'root', 'sbin', 'tmp', 'usr', 'var', 'vmlinuz']
  57    >>> dircache.annotate('/', a)
  58    >>> a
  59    ['bin/', 'boot/', 'cdrom/', 'dev/', 'etc/', 'floppy/', 'home/', 'initrd/', 'lib/
  60    ', 'lost+found/', 'mnt/', 'proc/', 'root/', 'sbin/', 'tmp/', 'usr/', 'var/', 'vm
  61    linuz']
  62