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