/Doc/library/pkgutil.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 64 lines · 44 code · 20 blank · 0 comment · 0 complexity · e32f2517766fa700f70a4bddee89ed5a MD5 · raw file

  1. :mod:`pkgutil` --- Package extension utility
  2. ============================================
  3. .. module:: pkgutil
  4. :synopsis: Utilities to support extension of packages.
  5. .. versionadded:: 2.3
  6. This module provides functions to manipulate packages:
  7. .. function:: extend_path(path, name)
  8. Extend the search path for the modules which comprise a package. Intended use is
  9. to place the following code in a package's :file:`__init__.py`::
  10. from pkgutil import extend_path
  11. __path__ = extend_path(__path__, __name__)
  12. This will add to the package's ``__path__`` all subdirectories of directories on
  13. ``sys.path`` named after the package. This is useful if one wants to distribute
  14. different parts of a single logical package as multiple directories.
  15. It also looks for :file:`\*.pkg` files beginning where ``*`` matches the *name*
  16. argument. This feature is similar to :file:`\*.pth` files (see the :mod:`site`
  17. module for more information), except that it doesn't special-case lines starting
  18. with ``import``. A :file:`\*.pkg` file is trusted at face value: apart from
  19. checking for duplicates, all entries found in a :file:`\*.pkg` file are added to
  20. the path, regardless of whether they exist on the filesystem. (This is a
  21. feature.)
  22. If the input path is not a list (as is the case for frozen packages) it is
  23. returned unchanged. The input path is not modified; an extended copy is
  24. returned. Items are only appended to the copy at the end.
  25. It is assumed that ``sys.path`` is a sequence. Items of ``sys.path`` that are
  26. not (Unicode or 8-bit) strings referring to existing directories are ignored.
  27. Unicode items on ``sys.path`` that cause errors when used as filenames may cause
  28. this function to raise an exception (in line with :func:`os.path.isdir`
  29. behavior).
  30. .. function:: get_data(package, resource)
  31. Get a resource from a package.
  32. This is a wrapper for the PEP 302 loader :func:`get_data` API. The package
  33. argument should be the name of a package, in standard module format
  34. (foo.bar). The resource argument should be in the form of a relative
  35. filename, using ``/`` as the path separator. The parent directory name
  36. ``..`` is not allowed, and nor is a rooted name (starting with a ``/``).
  37. The function returns a binary string that is the contents of the
  38. specified resource.
  39. For packages located in the filesystem, which have already been imported,
  40. this is the rough equivalent of::
  41. d = os.path.dirname(sys.modules[package].__file__)
  42. data = open(os.path.join(d, resource), 'rb').read()
  43. If the package cannot be located or loaded, or it uses a PEP 302 loader
  44. which does not support :func:`get_data`, then None is returned.