Doc/library/zipimport.rst

   1
   2 :mod:`zipimport` --- Import modules from Zip archives
   3 =====================================================
   4
   5 .. module:: zipimport
   6    :synopsis: support for importing Python modules from ZIP archives.
   7 .. moduleauthor:: Just van Rossum <just@letterror.com>
   8
   9
  10 .. versionadded:: 2.3
  11
  12 This module adds the ability to import Python modules (:file:`\*.py`,
  13 :file:`\*.py[co]`) and packages from ZIP-format archives. It is usually not
  14 needed to use the :mod:`zipimport` module explicitly; it is automatically used
  15 by the builtin :keyword:`import` mechanism for ``sys.path`` items that are paths
  16 to ZIP archives.
  17
  18 Typically, ``sys.path`` is a list of directory names as strings.  This module
  19 also allows an item of ``sys.path`` to be a string naming a ZIP file archive.
  20 The ZIP archive can contain a subdirectory structure to support package imports,
  21 and a path within the archive can be specified to only import from a
  22 subdirectory.  For example, the path :file:`/tmp/example.zip/lib/` would only
  23 import from the :file:`lib/` subdirectory within the archive.
  24
  25 Any files may be present in the ZIP archive, but only files :file:`.py` and
  26 :file:`.py[co]` are available for import.  ZIP import of dynamic modules
  27 (:file:`.pyd`, :file:`.so`) is disallowed. Note that if an archive only contains
  28 :file:`.py` files, Python will not attempt to modify the archive by adding the
  29 corresponding :file:`.pyc` or :file:`.pyo` file, meaning that if a ZIP archive
  30 doesn't contain :file:`.pyc` files, importing may be rather slow.
  31
  32 Using the built-in :func:`reload` function will fail if called on a module
  33 loaded from a ZIP archive; it is unlikely that :func:`reload` would be needed,
  34 since this would imply that the ZIP has been altered during runtime.
  35
  36 .. seealso::
  37
  38    `PKZIP Application Note <http://www.pkware.com/documents/casestudies/APPNOTE.TXT>`_
  39       Documentation on the ZIP file format by Phil Katz, the creator of the format and
  40       algorithms used.
  41
  42    :pep:`0273` - Import Modules from Zip Archives
  43       Written by James C. Ahlstrom, who also provided an implementation. Python 2.3
  44       follows the specification in PEP 273, but uses an implementation written by Just
  45       van Rossum that uses the import hooks described in PEP 302.
  46
  47    :pep:`0302` - New Import Hooks
  48       The PEP to add the import hooks that help this module work.
  49
  50
  51 This module defines an exception:
  52
  53 .. exception:: ZipImportError
  54
  55    Exception raised by zipimporter objects. It's a subclass of :exc:`ImportError`,
  56    so it can be caught as :exc:`ImportError`, too.
  57
  58
  59 .. _zipimporter-objects:
  60
  61 zipimporter Objects
  62 -------------------
  63
  64 :class:`zipimporter` is the class for importing ZIP files.
  65
  66 .. class:: zipimporter(archivepath)
  67
  68    Create a new zipimporter instance. *archivepath* must be a path to a ZIP
  69    file, or to a specific path within a ZIP file.  For example, an *archivepath*
  70    of :file:`foo/bar.zip/lib` will look for modules in the :file:`lib` directory
  71    inside the ZIP file :file:`foo/bar.zip` (provided that it exists).
  72
  73    :exc:`ZipImportError` is raised if *archivepath* doesn't point to a valid ZIP
  74    archive.
  75
  76    .. method:: find_module(fullname[, path])
  77
  78       Search for a module specified by *fullname*. *fullname* must be the fully
  79       qualified (dotted) module name. It returns the zipimporter instance itself
  80       if the module was found, or :const:`None` if it wasn't. The optional
  81       *path* argument is ignored---it's there for compatibility with the
  82       importer protocol.
  83
  84
  85    .. method:: get_code(fullname)
  86
  87       Return the code object for the specified module. Raise
  88       :exc:`ZipImportError` if the module couldn't be found.
  89
  90
  91    .. method:: get_data(pathname)
  92
  93       Return the data associated with *pathname*. Raise :exc:`IOError` if the
  94       file wasn't found.
  95
  96
  97    .. method:: get_source(fullname)
  98
  99       Return the source code for the specified module. Raise
 100       :exc:`ZipImportError` if the module couldn't be found, return
 101       :const:`None` if the archive does contain the module, but has no source
 102       for it.
 103
 104
 105    .. method:: is_package(fullname)
 106
 107       Return True if the module specified by *fullname* is a package. Raise
 108       :exc:`ZipImportError` if the module couldn't be found.
 109
 110
 111    .. method:: load_module(fullname)
 112
 113       Load the module specified by *fullname*. *fullname* must be the fully
 114       qualified (dotted) module name. It returns the imported module, or raises
 115       :exc:`ZipImportError` if it wasn't found.
 116
 117
 118    .. attribute:: archive
 119
 120       The file name of the importer's associated ZIP file, without a possible
 121       subpath.
 122
 123
 124    .. attribute:: prefix
 125
 126       The subpath within the ZIP file where modules are searched.  This is the
 127       empty string for zipimporter objects which point to the root of the ZIP
 128       file.
 129
 130    The :attr:`archive` and :attr:`prefix` attributes, when combined with a
 131    slash, equal the original *archivepath* argument given to the
 132    :class:`zipimporter` constructor.
 133
 134
 135 .. _zipimport-examples:
 136
 137 Examples
 138 --------
 139
 140 Here is an example that imports a module from a ZIP archive - note that the
 141 :mod:`zipimport` module is not explicitly used. ::
 142
 143    $ unzip -l /tmp/example.zip
 144    Archive:  /tmp/example.zip
 145      Length     Date   Time    Name
 146     --------    ----   ----    ----
 147         8467  11-26-02 22:30   jwzthreading.py
 148     --------                   -------
 149         8467                   1 file
 150    $ ./python
 151    Python 2.3 (#1, Aug 1 2003, 19:54:32)
 152    >>> import sys
 153    >>> sys.path.insert(0, '/tmp/example.zip')  # Add .zip file to front of path
 154    >>> import jwzthreading
 155    >>> jwzthreading.__file__
 156    '/tmp/example.zip/jwzthreading.py'
 157