Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/liblinecache.tex @ 39042:c02fa187e0f4 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Part of SF patch #1484695. This removes dead code. The chksum was already verified in .frombuf() on the lines above. If there was a problem an exception is raised, so there was no way this condition could have been true.
author Neal Norwitz <nnorwitz@gmail.com>
date Mon, 10 Jul 2006 00:23:17 +0000
parents 7cb6a304460f
children 6567c32ab881
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
10982
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1 \section{\module{linecache} ---
11003
086b2bc7578f Small English usage nits.
Fred Drake <fdrake@acm.org>
parents: 10982
diff changeset
2 Random access to text lines}
10982
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
3
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
4 \declaremodule{standard}{linecache}
15467
d7864345b1c8 Update Moshe Zadka's email address to one works and might last a while.
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
5 \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
11003
086b2bc7578f Small English usage nits.
Fred Drake <fdrake@acm.org>
parents: 10982
diff changeset
6 \modulesynopsis{This module provides random access to individual lines
086b2bc7578f Small English usage nits.
Fred Drake <fdrake@acm.org>
parents: 10982
diff changeset
7 from text files.}
10982
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
8
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
9
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
10 The \module{linecache} module allows one to get any line from any file,
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
11 while attempting to optimize internally, using a cache, the common case
11003
086b2bc7578f Small English usage nits.
Fred Drake <fdrake@acm.org>
parents: 10982
diff changeset
12 where many lines are read from a single file. This is used by the
086b2bc7578f Small English usage nits.
Fred Drake <fdrake@acm.org>
parents: 10982
diff changeset
13 \refmodule{traceback} module to retrieve source lines for inclusion in
086b2bc7578f Small English usage nits.
Fred Drake <fdrake@acm.org>
parents: 10982
diff changeset
14 the formatted traceback.
10982
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
15
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
16 The \module{linecache} module defines the following functions:
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
17
37576
d11366f7e1e7 Updated the warnings, linecache, inspect, traceback, site, and doctest modules
Phillip J. Eby <pje@telecommunity.com>
parents: 33839
diff changeset
18 \begin{funcdesc}{getline}{filename, lineno\optional{, module_globals}}
10982
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
19 Get line \var{lineno} from file named \var{filename}. This function
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11003
diff changeset
20 will never throw an exception --- it will return \code{''} on errors
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11003
diff changeset
21 (the terminating newline character will be included for lines that are
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11003
diff changeset
22 found).
10982
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
23
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
24 If a file named \var{filename} is not found, the function will look
11003
086b2bc7578f Small English usage nits.
Fred Drake <fdrake@acm.org>
parents: 10982
diff changeset
25 for it in the module\indexiii{module}{search}{path} search path,
37577
7cb6a304460f Forgot to mark up a PEP reference
Phillip J. Eby <pje@telecommunity.com>
parents: 37576
diff changeset
26 \code{sys.path}, after first checking for a \pep{302} \code{__loader__}
37576
d11366f7e1e7 Updated the warnings, linecache, inspect, traceback, site, and doctest modules
Phillip J. Eby <pje@telecommunity.com>
parents: 33839
diff changeset
27 in \var{module_globals}, in case the module was imported from a zipfile
d11366f7e1e7 Updated the warnings, linecache, inspect, traceback, site, and doctest modules
Phillip J. Eby <pje@telecommunity.com>
parents: 33839
diff changeset
28 or other non-filesystem import source.
d11366f7e1e7 Updated the warnings, linecache, inspect, traceback, site, and doctest modules
Phillip J. Eby <pje@telecommunity.com>
parents: 33839
diff changeset
29
d11366f7e1e7 Updated the warnings, linecache, inspect, traceback, site, and doctest modules
Phillip J. Eby <pje@telecommunity.com>
parents: 33839
diff changeset
30 \versionadded[The \var{module_globals} parameter was added]{2.5}
10982
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
31 \end{funcdesc}
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
32
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
33 \begin{funcdesc}{clearcache}{}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11003
diff changeset
34 Clear the cache. Use this function if you no longer need lines from
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11003
diff changeset
35 files previously read using \function{getline()}.
10982
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
36 \end{funcdesc}
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
37
33839
4dd97c37c2cc SF #737473: Show up-to-date source code in tracebacks always.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 16226
diff changeset
38 \begin{funcdesc}{checkcache}{\optional{filename}}
11003
086b2bc7578f Small English usage nits.
Fred Drake <fdrake@acm.org>
parents: 10982
diff changeset
39 Check the cache for validity. Use this function if files in the cache
33839
4dd97c37c2cc SF #737473: Show up-to-date source code in tracebacks always.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 16226
diff changeset
40 may have changed on disk, and you require the updated version. If
4dd97c37c2cc SF #737473: Show up-to-date source code in tracebacks always.
Hye-Shik Chang <hyeshik@gmail.com>
parents: 16226
diff changeset
41 \var{filename} is omitted, it will check the whole cache entries.
10982
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
42 \end{funcdesc}
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
43
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
44 Example:
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
45
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
46 \begin{verbatim}
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
47 >>> import linecache
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
48 >>> linecache.getline('/etc/passwd', 4)
16226
c7c404b35f33 Show '\011', '\012', and '\015' as '\t', '\n', '\r' in strings.
Ka-Ping Yee <ping@zesty.ca>
parents: 15467
diff changeset
49 'sys:x:3:3:sys:/dev:/bin/sh\n'
10982
bef46ea5ef75 New sections from Moshe Zadka <moshez@math.huji.ac.il>.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
50 \end{verbatim}