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_filename(fullname)
  98
  99       Return the value ``__file__`` would be set to if the specified module
 100       was imported. Raise :exc:`ZipImportError` if the module couldn't be
 101       found.
 102
 103    .. versionadded:: 2.7
 104
 105
 106    .. method:: get_source(fullname)
 107
 108       Return the source code for the specified module. Raise
 109       :exc:`ZipImportError` if the module couldn't be found, return
 110       :const:`None` if the archive does contain the module, but has no source
 111       for it.
 112
 113
 114    .. method:: is_package(fullname)
 115
 116       Return True if the module specified by *fullname* is a package. Raise
 117       :exc:`ZipImportError` if the module couldn't be found.
 118
 119
 120    .. method:: load_module(fullname)
 121
 122       Load the module specified by *fullname*. *fullname* must be the fully
 123       qualified (dotted) module name. It returns the imported module, or raises
 124       :exc:`ZipImportError` if it wasn't found.
 125
 126
 127    .. attribute:: archive
 128
 129       The file name of the importer's associated ZIP file, without a possible
 130       subpath.
 131
 132
 133    .. attribute:: prefix
 134
 135       The subpath within the ZIP file where modules are searched.  This is the
 136       empty string for zipimporter objects which point to the root of the ZIP
 137       file.
 138
 139    The :attr:`archive` and :attr:`prefix` attributes, when combined with a
 140    slash, equal the original *archivepath* argument given to the
 141    :class:`zipimporter` constructor.
 142
 143
 144 .. _zipimport-examples:
 145
 146 Examples
 147 --------
 148
 149 Here is an example that imports a module from a ZIP archive - note that the
 150 :mod:`zipimport` module is not explicitly used. ::
 151
 152    $ unzip -l /tmp/example.zip
 153    Archive:  /tmp/example.zip
 154      Length     Date   Time    Name
 155     --------    ----   ----    ----
 156         8467  11-26-02 22:30   jwzthreading.py
 157     --------                   -------
 158         8467                   1 file
 159    $ ./python
 160    Python 2.3 (#1, Aug 1 2003, 19:54:32)
 161    >>> import sys
 162    >>> sys.path.insert(0, '/tmp/example.zip')  # Add .zip file to front of path
 163    >>> import jwzthreading
 164    >>> jwzthreading.__file__
 165    '/tmp/example.zip/jwzthreading.py'
 166