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 importers are only invoked for 27:file:`.py` and :file:`.pyc` files. 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 :mod:`importlib` - The implementation of the import machinery 48 Package providing the relevant protocols for all importers to 49 implement. 50 51 52This module defines an exception: 53 54.. exception:: ZipImportError 55 56 Exception raised by zipimporter objects. It's a subclass of :exc:`ImportError`, 57 so it can be caught as :exc:`ImportError`, too. 58 59 60.. _zipimporter-objects: 61 62zipimporter Objects 63------------------- 64 65:class:`zipimporter` is the class for importing ZIP files. 66 67.. class:: zipimporter(archivepath) 68 69 Create a new zipimporter instance. *archivepath* must be a path to a ZIP 70 file, or to a specific path within a ZIP file. For example, an *archivepath* 71 of :file:`foo/bar.zip/lib` will look for modules in the :file:`lib` directory 72 inside the ZIP file :file:`foo/bar.zip` (provided that it exists). 73 74 :exc:`ZipImportError` is raised if *archivepath* doesn't point to a valid ZIP 75 archive. 76 77 .. method:: create_module(spec) 78 79 Implementation of :meth:`importlib.abc.Loader.create_module` that returns 80 :const:`None` to explicitly request the default semantics. 81 82 .. versionadded:: 3.10 83 84 85 .. method:: exec_module(module) 86 87 Implementation of :meth:`importlib.abc.Loader.exec_module`. 88 89 .. versionadded:: 3.10 90 91 92 .. method:: find_loader(fullname, path=None) 93 94 An implementation of :meth:`importlib.abc.PathEntryFinder.find_loader`. 95 96 .. deprecated:: 3.10 97 98 Use :meth:`find_spec` instead. 99 100 101 .. method:: find_module(fullname, path=None) 102 103 Search for a module specified by *fullname*. *fullname* must be the fully 104 qualified (dotted) module name. It returns the zipimporter instance itself 105 if the module was found, or :const:`None` if it wasn't. The optional 106 *path* argument is ignored---it's there for compatibility with the 107 importer protocol. 108 109 .. deprecated:: 3.10 110 111 Use :meth:`find_spec` instead. 112 113 114 .. method:: find_spec(fullname, target=None) 115 116 An implementation of :meth:`importlib.abc.PathEntryFinder.find_spec`. 117 118 .. versionadded:: 3.10 119 120 121 .. method:: get_code(fullname) 122 123 Return the code object for the specified module. Raise 124 :exc:`ZipImportError` if the module couldn't be imported. 125 126 127 .. method:: get_data(pathname) 128 129 Return the data associated with *pathname*. Raise :exc:`OSError` if the 130 file wasn't found. 131 132 .. versionchanged:: 3.3 133 :exc:`IOError` used to be raised instead of :exc:`OSError`. 134 135 136 .. method:: get_filename(fullname) 137 138 Return the value ``__file__`` would be set to if the specified module 139 was imported. Raise :exc:`ZipImportError` if the module couldn't be 140 imported. 141 142 .. versionadded:: 3.1 143 144 145 .. method:: get_source(fullname) 146 147 Return the source code for the specified module. Raise 148 :exc:`ZipImportError` if the module couldn't be found, return 149 :const:`None` if the archive does contain the module, but has no source 150 for it. 151 152 153 .. method:: is_package(fullname) 154 155 Return ``True`` if the module specified by *fullname* is a package. Raise 156 :exc:`ZipImportError` if the module couldn't be found. 157 158 159 .. method:: load_module(fullname) 160 161 Load the module specified by *fullname*. *fullname* must be the fully 162 qualified (dotted) module name. Returns the imported module on success, 163 raises :exc:`ZipImportError` on failure. 164 165 .. deprecated:: 3.10 166 167 Use :meth:`exec_module` instead. 168 169 170 .. method:: invalidate_caches() 171 172 Clear out the internal cache of information about files found within 173 the ZIP archive. 174 175 .. versionadded:: 3.10 176 177 178 .. attribute:: archive 179 180 The file name of the importer's associated ZIP file, without a possible 181 subpath. 182 183 184 .. attribute:: prefix 185 186 The subpath within the ZIP file where modules are searched. This is the 187 empty string for zipimporter objects which point to the root of the ZIP 188 file. 189 190 The :attr:`archive` and :attr:`prefix` attributes, when combined with a 191 slash, equal the original *archivepath* argument given to the 192 :class:`zipimporter` constructor. 193 194 195.. _zipimport-examples: 196 197Examples 198-------- 199 200Here is an example that imports a module from a ZIP archive - note that the 201:mod:`zipimport` module is not explicitly used. 202 203.. code-block:: shell-session 204 205 $ unzip -l example.zip 206 Archive: example.zip 207 Length Date Time Name 208 -------- ---- ---- ---- 209 8467 11-26-02 22:30 jwzthreading.py 210 -------- ------- 211 8467 1 file 212 $ ./python 213 Python 2.3 (#1, Aug 1 2003, 19:54:32) 214 >>> import sys 215 >>> sys.path.insert(0, 'example.zip') # Add .zip file to front of path 216 >>> import jwzthreading 217 >>> jwzthreading.__file__ 218 'example.zip/jwzthreading.py' 219