Doc/lib/libdircache.tex

   1 \section{\module{dircache} ---
   2          Cached directory listings}
   3
   4 \declaremodule{standard}{dircache}
   5 \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
   6 \modulesynopsis{Return directory listing, with cache mechanism.}
   7
   8 The \module{dircache} module defines a function for reading directory listing
   9 using a cache, and cache invalidation using the \var{mtime} of the directory.
  10 Additionally, it defines a function to annotate directories by appending
  11 a slash.
  12
  13 The \module{dircache} module defines the following functions:
  14
  15 \begin{funcdesc}{listdir}{path}
  16 Return a directory listing of \var{path}, as gotten from
  17 \function{os.listdir()}. Note that unless \var{path} changes, further call
  18 to \function{listdir()} will not re-read the directory structure.
  19
  20 Note that the list returned should be regarded as read-only. (Perhaps
  21 a future version should change it to return a tuple?)
  22 \end{funcdesc}
  23
  24 \begin{funcdesc}{opendir}{path}
  25 Same as \function{listdir()}. Defined for backwards compatibility.
  26 \end{funcdesc}
  27
  28 \begin{funcdesc}{annotate}{head, list}
  29 Assume \var{list} is a list of paths relative to \var{head}, and append,
  30 in place, a \character{/} to each path which points to a directory.
  31 \end{funcdesc}
  32
  33 \begin{verbatim}
  34 >>> import dircache
  35 >>> a=dircache.listdir('/')
  36 >>> a=a[:] # Copy the return value so we can change 'a'
  37 >>> a
  38 ['bin', 'boot', 'cdrom', 'dev', 'etc', 'floppy', 'home', 'initrd', 'lib', 'lost+
  39 found', 'mnt', 'proc', 'root', 'sbin', 'tmp', 'usr', 'var', 'vmlinuz']
  40 >>> dircache.annotate('/', a)
  41 >>> a
  42 ['bin/', 'boot/', 'cdrom/', 'dev/', 'etc/', 'floppy/', 'home/', 'initrd/', 'lib/
  43 ', 'lost+found/', 'mnt/', 'proc/', 'root/', 'sbin/', 'tmp/', 'usr/', 'var/', 'vm
  44 linuz']
  45 \end{verbatim}