← Back to branch summary

~ubuntu-branches/ubuntu/maverick/python3.1/maverick

« back to all changes in this revision

Viewing changes to Doc/library/linecache.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-03-23 00:01:27 UTC
  • Revision ID: james.westby@ubuntu.com-20090323000127-5fstfxju4ufrhthq
Tags: upstream-3.1~a1+20090322
Import upstream version 3.1~a1+20090322

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/library/linecache.rst
 
1
 
 
2
:mod:`linecache` --- Random access to text lines
 
3
================================================
 
4
 
 
5
.. module:: linecache
 
6
   :synopsis: This module provides random access to individual lines from text files.
 
7
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
 
8
 
 
9
 
 
10
The :mod:`linecache` module allows one to get any line from any file, while
 
11
attempting to optimize internally, using a cache, the common case where many
 
12
lines are read from a single file.  This is used by the :mod:`traceback` module
 
13
to retrieve source lines for inclusion in  the formatted traceback.
 
14
 
 
15
The :mod:`linecache` module defines the following functions:
 
16
 
 
17
 
 
18
.. function:: getline(filename, lineno[, module_globals])
 
19
 
 
20
   Get line *lineno* from file named *filename*. This function will never throw an
 
21
   exception --- it will return ``''`` on errors (the terminating newline character
 
22
   will be included for lines that are found).
 
23
 
 
24
   .. index:: triple: module; search; path
 
25
 
 
26
   If a file named *filename* is not found, the function will look for it in the
 
27
   module search path, ``sys.path``, after first checking for a :pep:`302`
 
28
   ``__loader__`` in *module_globals*, in case the module was imported from a
 
29
   zipfile or other non-filesystem import source.
 
30
 
 
31
 
 
32
.. function:: clearcache()
 
33
 
 
34
   Clear the cache.  Use this function if you no longer need lines from files
 
35
   previously read using :func:`getline`.
 
36
 
 
37
 
 
38
.. function:: checkcache([filename])
 
39
 
 
40
   Check the cache for validity.  Use this function if files in the cache  may have
 
41
   changed on disk, and you require the updated version.  If *filename* is omitted,
 
42
   it will check all the entries in the cache.
 
43
 
 
44
Example::
 
45
 
 
46
   >>> import linecache
 
47
   >>> linecache.getline('/etc/passwd', 4)
 
48
   'sys:x:3:3:sys:/dev:/bin/sh\n'
 
49