Doc/library/linecache.rst

   1
   2 :mod:`linecache` --- Random access to text lines
   3 ================================================
   4
   5 .. module:: linecache
   6    :synopsis: This module provides random access to individual lines from text files.
   7 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
   8
   9
  10 The :mod:`linecache` module allows one to get any line from any file, while
  11 attempting to optimize internally, using a cache, the common case where many
  12 lines are read from a single file.  This is used by the :mod:`traceback` module
  13 to retrieve source lines for inclusion in  the formatted traceback.
  14
  15 The :mod:`linecache` module defines the following functions:
  16
  17
  18 .. function:: getline(filename, lineno[, module_globals])
  19
  20    Get line *lineno* from file named *filename*. This function will never throw an
  21    exception --- it will return ``''`` on errors (the terminating newline character
  22    will be included for lines that are found).
  23
  24    .. index:: triple: module; search; path
  25
  26    If a file named *filename* is not found, the function will look for it in the
  27    module search path, ``sys.path``, after first checking for a :pep:`302`
  28    ``__loader__`` in *module_globals*, in case the module was imported from a
  29    zipfile or other non-filesystem import source.
  30
  31    .. versionadded:: 2.5
  32       The *module_globals* parameter was added.
  33
  34
  35 .. function:: clearcache()
  36
  37    Clear the cache.  Use this function if you no longer need lines from files
  38    previously read using :func:`getline`.
  39
  40
  41 .. function:: checkcache([filename])
  42
  43    Check the cache for validity.  Use this function if files in the cache  may have
  44    changed on disk, and you require the updated version.  If *filename* is omitted,
  45    it will check all the entries in the cache.
  46
  47 Example::
  48
  49    >>> import linecache
  50    >>> linecache.getline('/etc/passwd', 4)
  51    'sys:x:3:3:sys:/dev:/bin/sh\n'
  52