zipimport.rst 5.67 KB
Newer Older
1 2 3 4 5
:mod:`zipimport` --- Import modules from Zip archives
=====================================================

.. module:: zipimport
   :synopsis: support for importing Python modules from ZIP archives.
6

7 8
.. moduleauthor:: Just van Rossum <just@letterror.com>

9
--------------
10 11

This module adds the ability to import Python modules (:file:`\*.py`,
12
:file:`\*.pyc`) and packages from ZIP-format archives. It is usually not
13
needed to use the :mod:`zipimport` module explicitly; it is automatically used
14
by the built-in :keyword:`import` mechanism for :data:`sys.path` items that are paths
15 16
to ZIP archives.

17 18
Typically, :data:`sys.path` is a list of directory names as strings.  This module
also allows an item of :data:`sys.path` to be a string naming a ZIP file archive.
19 20
The ZIP archive can contain a subdirectory structure to support package imports,
and a path within the archive can be specified to only import from a
21
subdirectory.  For example, the path :file:`example.zip/lib/` would only
22 23 24
import from the :file:`lib/` subdirectory within the archive.

Any files may be present in the ZIP archive, but only files :file:`.py` and
25
:file:`.pyc` are available for import.  ZIP import of dynamic modules
26 27
(:file:`.pyd`, :file:`.so`) is disallowed. Note that if an archive only contains
:file:`.py` files, Python will not attempt to modify the archive by adding the
28
corresponding :file:`.pyc` file, meaning that if a ZIP archive
29 30
doesn't contain :file:`.pyc` files, importing may be rather slow.

31 32
ZIP archives with an archive comment are currently not supported.

33 34
.. seealso::

35
   `PKZIP Application Note <https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT>`_
36 37 38
      Documentation on the ZIP file format by Phil Katz, the creator of the format and
      algorithms used.

39
   :pep:`273` - Import Modules from Zip Archives
40 41 42 43
      Written by James C. Ahlstrom, who also provided an implementation. Python 2.3
      follows the specification in PEP 273, but uses an implementation written by Just
      van Rossum that uses the import hooks described in PEP 302.

44
   :pep:`302` - New Import Hooks
45 46 47
      The PEP to add the import hooks that help this module work.


48 49 50 51 52 53 54 55
This module defines an exception:

.. exception:: ZipImportError

   Exception raised by zipimporter objects. It's a subclass of :exc:`ImportError`,
   so it can be caught as :exc:`ImportError`, too.


56 57 58 59 60
.. _zipimporter-objects:

zipimporter Objects
-------------------

61
:class:`zipimporter` is the class for importing ZIP files.
62 63 64

.. class:: zipimporter(archivepath)

65 66 67 68 69
   Create a new zipimporter instance. *archivepath* must be a path to a ZIP
   file, or to a specific path within a ZIP file.  For example, an *archivepath*
   of :file:`foo/bar.zip/lib` will look for modules in the :file:`lib` directory
   inside the ZIP file :file:`foo/bar.zip` (provided that it exists).

70 71 72
   :exc:`ZipImportError` is raised if *archivepath* doesn't point to a valid ZIP
   archive.

73
   .. method:: find_module(fullname[, path])
74

75 76 77 78 79
      Search for a module specified by *fullname*. *fullname* must be the fully
      qualified (dotted) module name. It returns the zipimporter instance itself
      if the module was found, or :const:`None` if it wasn't. The optional
      *path* argument is ignored---it's there for compatibility with the
      importer protocol.
80 81


82
   .. method:: get_code(fullname)
83

84 85
      Return the code object for the specified module. Raise
      :exc:`ZipImportError` if the module couldn't be found.
86 87


88
   .. method:: get_data(pathname)
89

90
      Return the data associated with *pathname*. Raise :exc:`OSError` if the
91
      file wasn't found.
92

93 94 95
      .. versionchanged:: 3.3
         :exc:`IOError` used to be raised instead of :exc:`OSError`.

96

97 98 99 100 101 102
   .. method:: get_filename(fullname)

      Return the value ``__file__`` would be set to if the specified module
      was imported. Raise :exc:`ZipImportError` if the module couldn't be
      found.

103
      .. versionadded:: 3.1
104 105


106
   .. method:: get_source(fullname)
107

108 109 110 111
      Return the source code for the specified module. Raise
      :exc:`ZipImportError` if the module couldn't be found, return
      :const:`None` if the archive does contain the module, but has no source
      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 123 124
      Load the module specified by *fullname*. *fullname* must be the fully
      qualified (dotted) module name. It returns the imported module, or raises
      :exc:`ZipImportError` if it wasn't found.
125 126


127
   .. attribute:: archive
128

129 130
      The file name of the importer's associated ZIP file, without a possible
      subpath.
131 132


133
   .. attribute:: prefix
134

135 136 137 138 139 140 141
      The subpath within the ZIP file where modules are searched.  This is the
      empty string for zipimporter objects which point to the root of the ZIP
      file.

   The :attr:`archive` and :attr:`prefix` attributes, when combined with a
   slash, equal the original *archivepath* argument given to the
   :class:`zipimporter` constructor.
142

143 144 145

.. _zipimport-examples:

146 147 148
Examples
--------

149
Here is an example that imports a module from a ZIP archive - note that the
150 151 152
:mod:`zipimport` module is not explicitly used.

.. code-block:: shell-session
153

154 155
   $ unzip -l example.zip
   Archive:  example.zip
156 157 158 159 160 161
     Length     Date   Time    Name
    --------    ----   ----    ----
        8467  11-26-02 22:30   jwzthreading.py
    --------                   -------
        8467                   1 file
   $ ./python
162
   Python 2.3 (#1, Aug 1 2003, 19:54:32)
163
   >>> import sys
164
   >>> sys.path.insert(0, 'example.zip')  # Add .zip file to front of path
165 166
   >>> import jwzthreading
   >>> jwzthreading.__file__
167
   'example.zip/jwzthreading.py'