/Doc/library/linecache.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 52 lines · 32 code · 20 blank · 0 comment · 0 complexity · 600a8bd23710b87dd3d946644accb871 MD5 · raw file

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