cpython/Doc/library/linecache.rst

58 lines
2.0 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:01 -03:00
:mod:`linecache` --- Random access to text lines
================================================
.. module:: linecache
:synopsis: This module provides random access to individual lines from text files.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
The :mod:`linecache` module allows one to get any line from any file, while
attempting to optimize internally, using a cache, the common case where many
lines are read from a single file. This is used by the :mod:`traceback` module
to retrieve source lines for inclusion in the formatted traceback.
.. seealso::
Latest version of the `linecache module Python source code
<http://svn.python.org/view/python/branches/release27-maint/Lib/linecache.py?view=markup>`_
2007-08-15 11:28:01 -03:00
The :mod:`linecache` module defines the following functions:
.. function:: getline(filename, lineno[, module_globals])
Merged revisions 82798,82805,83659,83977,84015,84018,84141,84264,84326-84327,84480,84482,84484,84530-84531,84553,84619,84915-84916 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r82798 | georg.brandl | 2010-07-11 11:23:11 +0200 (So, 11 Jul 2010) | 1 line #6774: explain shutdown() behavior varying with platform. ........ r82805 | georg.brandl | 2010-07-11 11:42:10 +0200 (So, 11 Jul 2010) | 1 line #7935: cross-reference to ast.literal_eval() from eval() docs. ........ r83659 | georg.brandl | 2010-08-03 14:06:29 +0200 (Di, 03 Aug 2010) | 1 line Terminology fix: exceptions are raised, except in generator.throw(). ........ r83977 | georg.brandl | 2010-08-13 17:10:49 +0200 (Fr, 13 Aug 2010) | 1 line Fix copy-paste error. ........ r84015 | georg.brandl | 2010-08-14 17:44:34 +0200 (Sa, 14 Aug 2010) | 1 line Add some maintainers. ........ r84018 | georg.brandl | 2010-08-14 17:48:49 +0200 (Sa, 14 Aug 2010) | 1 line Typo fix. ........ r84141 | georg.brandl | 2010-08-17 16:11:59 +0200 (Di, 17 Aug 2010) | 1 line Markup nits. ........ r84264 | georg.brandl | 2010-08-22 22:23:38 +0200 (So, 22 Aug 2010) | 1 line #9649: fix default value description. ........ r84326 | georg.brandl | 2010-08-26 16:30:15 +0200 (Do, 26 Aug 2010) | 1 line #9689: add links from overview to in-depth class API descriptions. ........ r84327 | georg.brandl | 2010-08-26 16:30:56 +0200 (Do, 26 Aug 2010) | 1 line #9681: typo. ........ r84480 | georg.brandl | 2010-09-04 00:33:27 +0200 (Sa, 04 Sep 2010) | 1 line More inclusive title. ........ r84482 | georg.brandl | 2010-09-04 00:40:02 +0200 (Sa, 04 Sep 2010) | 1 line #9760: clarify what context expression is. ........ r84484 | georg.brandl | 2010-09-04 00:49:27 +0200 (Sa, 04 Sep 2010) | 1 line Fix missing word. ........ r84530 | georg.brandl | 2010-09-05 19:07:12 +0200 (So, 05 Sep 2010) | 1 line #9747: fix copy-paste error in getresgid() doc. ........ r84531 | georg.brandl | 2010-09-05 19:09:18 +0200 (So, 05 Sep 2010) | 1 line #9776: fix some spacing. ........ r84553 | georg.brandl | 2010-09-06 08:49:07 +0200 (Mo, 06 Sep 2010) | 1 line #9780: both { and } are not valid fill characters. ........ r84619 | georg.brandl | 2010-09-08 12:43:45 +0200 (Mi, 08 Sep 2010) | 1 line Add Lukasz. ........ r84915 | georg.brandl | 2010-09-20 08:27:02 +0200 (Mo, 20 Sep 2010) | 1 line Fix typo. ........ r84916 | georg.brandl | 2010-09-20 08:29:01 +0200 (Mo, 20 Sep 2010) | 1 line Mention % as string formatting. ........
2010-10-06 06:28:45 -03:00
Get line *lineno* from file named *filename*. This function will never raise an
2007-08-15 11:28:01 -03:00
exception --- it will return ``''`` on errors (the terminating newline character
will be included for lines that are found).
.. index:: triple: module; search; path
If a file named *filename* is not found, the function will look for it in the
module search path, ``sys.path``, after first checking for a :pep:`302`
``__loader__`` in *module_globals*, in case the module was imported from a
zipfile or other non-filesystem import source.
.. versionadded:: 2.5
The *module_globals* parameter was added.
.. function:: clearcache()
Clear the cache. Use this function if you no longer need lines from files
previously read using :func:`getline`.
.. function:: checkcache([filename])
Check the cache for validity. Use this function if files in the cache may have
changed on disk, and you require the updated version. If *filename* is omitted,
it will check all the entries in the cache.
Example::
>>> import linecache
>>> linecache.getline('/etc/passwd', 4)
'sys:x:3:3:sys:/dev:/bin/sh\n'