10.9. "linecache" — Random access to text lines
***********************************************

**Source code:** Lib/linecache.py

======================================================================

The "linecache" module allows one to get any line from any file, while
attempting to optimize internally, using a cache, the common case
where many lines are read from a single file.  This is used by the
"traceback" module to retrieve source lines for inclusion in  the
formatted traceback.

The "linecache" module defines the following functions:

linecache.getline(filename, lineno[, module_globals])

   Get line *lineno* from file named *filename*. This function will
   never raise an exception — it will return "''" on errors (the
   terminating newline character will be included for lines that are
   found).

   If a file named *filename* is not found, the function will look for
   it in the module search path, "sys.path", after first checking for
   a **PEP 302** "__loader__" in *module_globals*, in case the module
   was imported from a zipfile or other non-filesystem import source.

   New in version 2.5: The *module_globals* parameter was added.

linecache.clearcache()

   Clear the cache.  Use this function if you no longer need lines
   from files previously read using "getline()".

linecache.checkcache([filename])

   Check the cache for validity.  Use this function if files in the
   cache  may have changed on disk, and you require the updated
   version.  If *filename* is omitted, it will check all the entries
   in the cache.

Example:

   >>> import linecache
   >>> linecache.getline('/etc/passwd', 4)
   'sys:x:3:3:sys:/dev:/bin/sh\n'