Debian Codegraph @

Doc/library/linecache.rst

raw
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'