Doc/lib/liblinecache.tex

   1 \section{\module{linecache} ---
   2          Random access to text lines}
   3
   4 \declaremodule{standard}{linecache}
   5 \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
   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\optional{, module_globals}}
  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 (the terminating newline character will be included for lines that are
  22 found).
  23
  24 If a file named \var{filename} is not found, the function will look
  25 for it in the module\indexiii{module}{search}{path} search path,
  26 \code{sys.path}, after first checking for a \pep{302} \code{__loader__}
  27 in \var{module_globals}, in case the module was imported from a zipfile
  28 or other non-filesystem import source.
  29
  30 \versionadded[The \var{module_globals} parameter was added]{2.5}
  31 \end{funcdesc}
  32
  33 \begin{funcdesc}{clearcache}{}
  34 Clear the cache.  Use this function if you no longer need lines from
  35 files previously read using \function{getline()}.
  36 \end{funcdesc}
  37
  38 \begin{funcdesc}{checkcache}{\optional{filename}}
  39 Check the cache for validity.  Use this function if files in the cache
  40 may have changed on disk, and you require the updated version.  If
  41 \var{filename} is omitted, it will check all the entries in the cache.
  42 \end{funcdesc}
  43
  44 Example:
  45
  46 \begin{verbatim}
  47 >>> import linecache
  48 >>> linecache.getline('/etc/passwd', 4)
  49 'sys:x:3:3:sys:/dev:/bin/sh\n'
  50 \end{verbatim}