Fred Drake | 21572fd | 1999-06-14 19:47:47 +0000 | [diff] [blame] | 1 | \section{\module{linecache} --- |
Fred Drake | 97c2fa0 | 1999-06-17 16:38:18 +0000 | [diff] [blame] | 2 | Random access to text lines} |
Fred Drake | 21572fd | 1999-06-14 19:47:47 +0000 | [diff] [blame] | 3 | |
| 4 | \declaremodule{standard}{linecache} |
| 5 | \sectionauthor{Moshe Zadka}{mzadka@geocities.com} |
Fred Drake | 97c2fa0 | 1999-06-17 16:38:18 +0000 | [diff] [blame] | 6 | \modulesynopsis{This module provides random access to individual lines |
| 7 | from text files.} |
Fred Drake | 21572fd | 1999-06-14 19:47:47 +0000 | [diff] [blame] | 8 | |
| 9 | |
| 10 | The \module{linecache} module allows one to get any line from any file, |
| 11 | while attempting to optimize internally, using a cache, the common case |
Fred Drake | 97c2fa0 | 1999-06-17 16:38:18 +0000 | [diff] [blame] | 12 | where many lines are read from a single file. This is used by the |
| 13 | \refmodule{traceback} module to retrieve source lines for inclusion in |
| 14 | the formatted traceback. |
Fred Drake | 21572fd | 1999-06-14 19:47:47 +0000 | [diff] [blame] | 15 | |
| 16 | The \module{linecache} module defines the following functions: |
| 17 | |
| 18 | \begin{funcdesc}{getline}{filename, lineno} |
| 19 | Get line \var{lineno} from file named \var{filename}. This function |
| 20 | will never throw an exception --- it will return \code{''} on errors. |
| 21 | |
| 22 | If a file named \var{filename} is not found, the function will look |
Fred Drake | 97c2fa0 | 1999-06-17 16:38:18 +0000 | [diff] [blame] | 23 | for it in the module\indexiii{module}{search}{path} search path, |
| 24 | \code{sys.path}. |
Fred Drake | 21572fd | 1999-06-14 19:47:47 +0000 | [diff] [blame] | 25 | \end{funcdesc} |
| 26 | |
| 27 | \begin{funcdesc}{clearcache}{} |
Fred Drake | 97c2fa0 | 1999-06-17 16:38:18 +0000 | [diff] [blame] | 28 | Clear the cache. Use this function if you know that you do not need |
| 29 | to read lines from many of files you already read from using this |
| 30 | module. |
Fred Drake | 21572fd | 1999-06-14 19:47:47 +0000 | [diff] [blame] | 31 | \end{funcdesc} |
| 32 | |
| 33 | \begin{funcdesc}{checkcache}{} |
Fred Drake | 97c2fa0 | 1999-06-17 16:38:18 +0000 | [diff] [blame] | 34 | Check the cache for validity. Use this function if files in the cache |
| 35 | may have changed on disk, and you require the updated version. |
Fred Drake | 21572fd | 1999-06-14 19:47:47 +0000 | [diff] [blame] | 36 | \end{funcdesc} |
| 37 | |
| 38 | Example: |
| 39 | |
| 40 | \begin{verbatim} |
| 41 | >>> import linecache |
| 42 | >>> linecache.getline('/etc/passwd', 4) |
| 43 | 'sys:x:3:3:sys:/dev:/bin/sh\012' |
| 44 | \end{verbatim} |