| 1 |
:mod:`!linecache` --- Random access to text lines |
| 2 |
================================================= |
| 3 |
|
| 4 |
.. module:: linecache |
| 5 |
:synopsis: Provides random access to individual lines from text files. |
| 6 |
|
| 7 |
.. sectionauthor:: Moshe Zadka <[email protected]> |
| 8 |
|
| 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 |
attempting to optimize internally, using a cache, the common case where many |
| 15 |
lines are read from a single file. This is used by the :mod:`traceback` module |
| 16 |
to retrieve source lines for inclusion in the formatted traceback. |
| 17 |
|
| 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 |
The :mod:`!linecache` module defines the following functions: |
| 23 |
|
| 24 |
|
| 25 |
.. function:: getline(filename, lineno, module_globals=None) |
| 26 |
|
| 27 |
Get line *lineno* from file named *filename*. This function will never raise an |
| 28 |
exception --- it will return ``''`` on errors (the terminating newline character |
| 29 |
will be included for lines that are found). |
| 30 |
|
| 31 |
.. index:: triple: module; search; path |
| 32 |
|
| 33 |
If *filename* indicates a frozen module (starting with ``'<frozen '``), the function |
| 34 |
will attempt to get the real file name from ``module_globals['__file__']`` if |
| 35 |
*module_globals* is not ``None``. |
| 36 |
|
| 37 |
If a file named *filename* is not found, the function first checks |
| 38 |
for a :pep:`302` ``__loader__`` in *module_globals*. |
| 39 |
If there is such a loader and it defines a ``get_source`` method, |
| 40 |
then that determines the source lines |
| 41 |
(if ``get_source()`` returns ``None``, then ``''`` is returned). |
| 42 |
Finally, if *filename* is a relative filename, |
| 43 |
it is looked up relative to the entries in the module search path, ``sys.path``. |
| 44 |
|
| 45 |
.. versionchanged:: 3.14 |
| 46 |
|
| 47 |
Support *filename* of frozen modules. |
| 48 |
|
| 49 |
|
| 50 |
.. function:: clearcache() |
| 51 |
|
| 52 |
Clear the cache. Use this function if you no longer need lines from files |
| 53 |
previously read using :func:`getline`. |
| 54 |
|
| 55 |
|
| 56 |
.. function:: checkcache(filename=None) |
| 57 |
|
| 58 |
Check the cache for validity. Use this function if files in the cache may have |
| 59 |
changed on disk, and you require the updated version. If *filename* is omitted, |
| 60 |
it will check all the entries in the cache. |
| 61 |
|
| 62 |
.. function:: lazycache(filename, module_globals) |
| 63 |
|
| 64 |
Capture enough detail about a non-file-based module to permit getting its |
| 65 |
lines later via :func:`getline` even if *module_globals* is ``None`` in the later |
| 66 |
call. This avoids doing I/O until a line is actually needed, without having |
| 67 |
to carry the module globals around indefinitely. |
| 68 |
|
| 69 |
.. versionadded:: 3.5 |
| 70 |
|
| 71 |
Example:: |
| 72 |
|
| 73 |
>>> import linecache |
| 74 |
>>> linecache.getline(linecache.__file__, 8) |
| 75 |
'import sys\n' |