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**Source code:** :source:`Lib/zipimport.py`
10
11--------------
12
13This module adds the ability to import Python modules (:file:`\*.py`,
14:file:`\*.pyc`) and packages from ZIP-format archives. It is usually not
15needed to use the :mod:`zipimport` module explicitly; it is automatically used
16by the built-in :keyword:`import` mechanism for :data:`sys.path` items that are paths
17to ZIP archives.
18
19Typically, :data:`sys.path` is a list of directory names as strings.  This module
20also allows an item of :data:`sys.path` to be a string naming a ZIP file archive.
21The ZIP archive can contain a subdirectory structure to support package imports,
22and a path within the archive can be specified to only import from a
23subdirectory.  For example, the path :file:`example.zip/lib/` would only
24import from the :file:`lib/` subdirectory within the archive.
25
26Any files may be present in the ZIP archive, but only files :file:`.py` and
27:file:`.pyc` are available for import.  ZIP import of dynamic modules
28(:file:`.pyd`, :file:`.so`) is disallowed. Note that if an archive only contains
29:file:`.py` files, Python will not attempt to modify the archive by adding the
30corresponding :file:`.pyc` file, meaning that if a ZIP archive
31doesn't contain :file:`.pyc` files, importing may be rather slow.
32
33.. versionchanged:: 3.8
34   Previously, ZIP archives with an archive comment were not supported.
35
36.. seealso::
37
38   `PKZIP Application Note <https://pkware.cachefly.net/webdocs/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:`273` - 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:`302` - New Import Hooks
48      The PEP to add the import hooks that help this module work.
49
50
51This 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
61zipimporter 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:`OSError` if the
94      file wasn't found.
95
96      .. versionchanged:: 3.3
97         :exc:`IOError` used to be raised instead of :exc:`OSError`.
98
99
100   .. method:: get_filename(fullname)
101
102      Return the value ``__file__`` would be set to if the specified module
103      was imported. Raise :exc:`ZipImportError` if the module couldn't be
104      found.
105
106      .. versionadded:: 3.1
107
108
109   .. method:: get_source(fullname)
110
111      Return the source code for the specified module. Raise
112      :exc:`ZipImportError` if the module couldn't be found, return
113      :const:`None` if the archive does contain the module, but has no source
114      for it.
115
116
117   .. method:: is_package(fullname)
118
119      Return ``True`` if the module specified by *fullname* is a package. Raise
120      :exc:`ZipImportError` if the module couldn't be found.
121
122
123   .. method:: load_module(fullname)
124
125      Load the module specified by *fullname*. *fullname* must be the fully
126      qualified (dotted) module name. It returns the imported module, or raises
127      :exc:`ZipImportError` if it wasn't found.
128
129
130   .. attribute:: archive
131
132      The file name of the importer's associated ZIP file, without a possible
133      subpath.
134
135
136   .. attribute:: prefix
137
138      The subpath within the ZIP file where modules are searched.  This is the
139      empty string for zipimporter objects which point to the root of the ZIP
140      file.
141
142   The :attr:`archive` and :attr:`prefix` attributes, when combined with a
143   slash, equal the original *archivepath* argument given to the
144   :class:`zipimporter` constructor.
145
146
147.. _zipimport-examples:
148
149Examples
150--------
151
152Here is an example that imports a module from a ZIP archive - note that the
153:mod:`zipimport` module is not explicitly used.
154
155.. code-block:: shell-session
156
157   $ unzip -l example.zip
158   Archive:  example.zip
159     Length     Date   Time    Name
160    --------    ----   ----    ----
161        8467  11-26-02 22:30   jwzthreading.py
162    --------                   -------
163        8467                   1 file
164   $ ./python
165   Python 2.3 (#1, Aug 1 2003, 19:54:32)
166   >>> import sys
167   >>> sys.path.insert(0, 'example.zip')  # Add .zip file to front of path
168   >>> import jwzthreading
169   >>> jwzthreading.__file__
170   'example.zip/jwzthreading.py'
171