linecache.rst 2.5 KB
Newer Older
1 2 3 4 5
:mod:`linecache` --- Random access to text lines
================================================

.. module:: linecache
   :synopsis: This module provides random access to individual lines from text files.
6

7 8
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>

9
**Source code:** :source:`Lib/linecache.py`
10

11 12
--------------

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

18
The :func:`tokenize.open` function is used to open files. This
19
function uses :func:`tokenize.detect_encoding` to get the encoding of the
20
file; in the absence of an encoding token, the file encoding defaults to UTF-8.
21

22 23 24
The :mod:`linecache` module defines the following functions:


25
.. function:: getline(filename, lineno, module_globals=None)
26

27
   Get line *lineno* from file named *filename*. This function will never raise an
28 29 30 31 32
   exception --- it will return ``''`` on errors (the terminating newline character
   will be included for lines that are found).

   .. index:: triple: module; search; path

33 34 35 36 37 38 39
   If a file named *filename* is not found, the function first checks
   for a :pep:`302` ``__loader__`` in *module_globals*.
   If there is such a loader and it defines a ``get_source`` method,
   then that determines the source lines
   (if ``get_source()`` returns ``None``, then ``''`` is returned).
   Finally, if *filename* is a relative filename,
   it is looked up relative to the entries in the module search path, ``sys.path``.
40 41 42 43 44 45 46 47


.. function:: clearcache()

   Clear the cache.  Use this function if you no longer need lines from files
   previously read using :func:`getline`.


48
.. function:: checkcache(filename=None)
49 50 51 52 53

   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.

54 55
.. function:: lazycache(filename, module_globals)

56
   Capture enough detail about a non-file-based module to permit getting its
57
   lines later via :func:`getline` even if *module_globals* is ``None`` in the later
58 59 60 61
   call. This avoids doing I/O until a line is actually needed, without having
   to carry the module globals around indefinitely.

   .. versionadded:: 3.5
62

63 64 65
Example::

   >>> import linecache
66 67
   >>> linecache.getline(linecache.__file__, 8)
   'import sys\n'