Doc/lib/liblinecache.tex

   1 \section{\module{linecache} ---
   2          Random access to text lines}
   3
   4 \declaremodule{standard}{linecache}
   5 \sectionauthor{Moshe Zadka}{mzadka@geocities.com}
   6 \modulesynopsis{This module provides random access to individual lines
   7                 from text files.}
   8
   9
  10 The \module{linecache} module allows one to get any line from any file,
  11 while attempting to optimize internally, using a cache, the common case
  12 where many lines are read from a single file.  This is used by the
  13 \refmodule{traceback} module to retrieve source lines for inclusion in
  14 the formatted traceback.
  15
  16 The \module{linecache} module defines the following functions:
  17
  18 \begin{funcdesc}{getline}{filename, lineno}
  19 Get line \var{lineno} from file named \var{filename}. This function
  20 will never throw an exception --- it will return \code{''} on errors.
  21
  22 If a file named \var{filename} is not found, the function will look
  23 for it in the module\indexiii{module}{search}{path} search path,
  24 \code{sys.path}.
  25 \end{funcdesc}
  26
  27 \begin{funcdesc}{clearcache}{}
  28 Clear the cache.  Use this function if you know that you do not need
  29 to read lines from many of files you already read from using this
  30 module.
  31 \end{funcdesc}
  32
  33 \begin{funcdesc}{checkcache}{}
  34 Check the cache for validity.  Use this function if files in the cache
  35 may have changed on disk, and you require the updated version.
  36 \end{funcdesc}
  37
  38 Example:
  39
  40 \begin{verbatim}
  41 >>> import linecache
  42 >>> linecache.getline('/etc/passwd', 4)
  43 'sys:x:3:3:sys:/dev:/bin/sh\012'
  44 \end{verbatim}