1:mod:`zipimport` --- Import modules from Zip archives
2=====================================================
3
4.. module:: zipimport
5   :synopsis: support for importing Python modules from ZIP archives.
6
7.. moduleauthor:: Just van Rossum <just@letterror.com>
8
9--------------
10
11This module adds the ability to import Python modules (:file:`\*.py`,
12:file:`\*.pyc`) and packages from ZIP-format archives. It is usually not
13needed to use the :mod:`zipimport` module explicitly; it is automatically used
14by the built-in :keyword:`import` mechanism for :data:`sys.path` items that are paths
15to ZIP archives.
16
17Typically, :data:`sys.path` is a list of directory names as strings.  This module
18also allows an item of :data:`sys.path` to be a string naming a ZIP file archive.
19The ZIP archive can contain a subdirectory structure to support package imports,
20and a path within the archive can be specified to only import from a
21subdirectory.  For example, the path :file:`example.zip/lib/` would only
22import from the :file:`lib/` subdirectory within the archive.
23
24Any 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(:file:`.pyd`, :file:`.so`) is disallowed. Note that if an archive only contains
27:file:`.py` files, Python will not attempt to modify the archive by adding the
28corresponding :file:`.pyc` file, meaning that if a ZIP archive
29doesn't contain :file:`.pyc` files, importing may be rather slow.
30
31ZIP archives with an archive comment are currently not supported.
32
33.. seealso::
34
35   `PKZIP Application Note <https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT>`_
36      Documentation on the ZIP file format by Phil Katz, the creator of the format and
37      algorithms used.
38
39   :pep:`273` - Import Modules from Zip Archives
40      Written by James C. Ahlstrom, who also provided an implementation. Python 2.3
41      follows the specification in PEP 273, but uses an implementation written by Just
42      van Rossum that uses the import hooks described in PEP 302.
43
44   :pep:`302` - New Import Hooks
45      The PEP to add the import hooks that help this module work.
46
47
48This module defines an exception:
49
50.. exception:: ZipImportError
51
52   Exception raised by zipimporter objects. It's a subclass of :exc:`ImportError`,
53   so it can be caught as :exc:`ImportError`, too.
54
55
56.. _zipimporter-objects:
57
58zipimporter Objects
59-------------------
60
61:class:`zipimporter` is the class for importing ZIP files.
62
63.. class:: zipimporter(archivepath)
64
65   Create a new zipimporter instance. *archivepath* must be a path to a ZIP
66   file, or to a specific path within a ZIP file.  For example, an *archivepath*
67   of :file:`foo/bar.zip/lib` will look for modules in the :file:`lib` directory
68   inside the ZIP file :file:`foo/bar.zip` (provided that it exists).
69
70   :exc:`ZipImportError` is raised if *archivepath* doesn't point to a valid ZIP
71   archive.
72
73   .. method:: find_module(fullname[, path])
74
75      Search for a module specified by *fullname*. *fullname* must be the fully
76      qualified (dotted) module name. It returns the zipimporter instance itself
77      if the module was found, or :const:`None` if it wasn't. The optional
78      *path* argument is ignored---it's there for compatibility with the
79      importer protocol.
80
81
82   .. method:: get_code(fullname)
83
84      Return the code object for the specified module. Raise
85      :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      .. versionchanged:: 3.3
94         :exc:`IOError` used to be raised instead of :exc:`OSError`.
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:: 3.1
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
146Examples
147--------
148
149Here is an example that imports a module from a ZIP archive - note that the
150:mod:`zipimport` module is not explicitly used.
151
152.. code-block:: shell-session
153
154   $ unzip -l example.zip
155   Archive:  example.zip
156     Length     Date   Time    Name
157    --------    ----   ----    ----
158        8467  11-26-02 22:30   jwzthreading.py
159    --------                   -------
160        8467                   1 file
161   $ ./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   >>> import jwzthreading
166   >>> jwzthreading.__file__
167   'example.zip/jwzthreading.py'
168