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