1 :mod:`linecache` --- Random access to text lines 2 ================================================ 3 4 .. module:: linecache 5 :synopsis: This module provides random access to individual lines from text files. 6 7 .. sectionauthor:: Moshe Zadka <moshez (a] zadka.site.co.il> 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 a file named *filename* is not found, the function will look for it in the 34 module search path, ``sys.path``, after first checking for a :pep:`302` 35 ``__loader__`` in *module_globals*, in case the module was imported from a 36 zipfile or other non-filesystem import source. 37 38 39 .. function:: clearcache() 40 41 Clear the cache. Use this function if you no longer need lines from files 42 previously read using :func:`getline`. 43 44 45 .. function:: checkcache(filename=None) 46 47 Check the cache for validity. Use this function if files in the cache may have 48 changed on disk, and you require the updated version. If *filename* is omitted, 49 it will check all the entries in the cache. 50 51 .. function:: lazycache(filename, module_globals) 52 53 Capture enough detail about a non-file-based module to permit getting its 54 lines later via :func:`getline` even if *module_globals* is ``None`` in the later 55 call. This avoids doing I/O until a line is actually needed, without having 56 to carry the module globals around indefinitely. 57 58 .. versionadded:: 3.5 59 60 Example:: 61 62 >>> import linecache 63 >>> linecache.getline(linecache.__file__, 8) 64 'import sys\n' 65