1 2:mod:`zipimport` --- Import modules from Zip archives 3===================================================== 4 5.. module:: zipimport 6 :synopsis: support for importing Python modules from ZIP archives. 7.. moduleauthor:: Just van Rossum <just@letterror.com> 8 9 10.. versionadded:: 2.3 11 12This module adds the ability to import Python modules (:file:`\*.py`, 13:file:`\*.py[co]`) and packages from ZIP-format archives. It is usually not 14needed to use the :mod:`zipimport` module explicitly; it is automatically used 15by the built-in :keyword:`import` mechanism for :data:`sys.path` items that are paths 16to ZIP archives. 17 18Typically, :data:`sys.path` is a list of directory names as strings. This module 19also allows an item of :data:`sys.path` to be a string naming a ZIP file archive. 20The ZIP archive can contain a subdirectory structure to support package imports, 21and a path within the archive can be specified to only import from a 22subdirectory. For example, the path :file:`example.zip/lib/` would only 23import from the :file:`lib/` subdirectory within the archive. 24 25Any files may be present in the ZIP archive, but only files :file:`.py` and 26:file:`.py[co]` are available for import. ZIP import of dynamic modules 27(:file:`.pyd`, :file:`.so`) is disallowed. Note that if an archive only contains 28:file:`.py` files, Python will not attempt to modify the archive by adding the 29corresponding :file:`.pyc` or :file:`.pyo` file, meaning that if a ZIP archive 30doesn't contain :file:`.pyc` files, importing may be rather slow. 31 32Using the built-in :func:`reload` function will fail if called on a module 33loaded from a ZIP archive; it is unlikely that :func:`reload` would be needed, 34since this would imply that the ZIP has been altered during runtime. 35 36ZIP archives with an archive comment are currently not supported. 37 38.. seealso:: 39 40 `PKZIP Application Note <https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT>`_ 41 Documentation on the ZIP file format by Phil Katz, the creator of the format and 42 algorithms used. 43 44 :pep:`273` - Import Modules from Zip Archives 45 Written by James C. Ahlstrom, who also provided an implementation. Python 2.3 46 follows the specification in PEP 273, but uses an implementation written by Just 47 van Rossum that uses the import hooks described in PEP 302. 48 49 :pep:`302` - New Import Hooks 50 The PEP to add the import hooks that help this module work. 51 52 53This module defines an exception: 54 55.. exception:: ZipImportError 56 57 Exception raised by zipimporter objects. It's a subclass of :exc:`ImportError`, 58 so it can be caught as :exc:`ImportError`, too. 59 60 61.. _zipimporter-objects: 62 63zipimporter Objects 64------------------- 65 66:class:`zipimporter` is the class for importing ZIP files. 67 68.. class:: zipimporter(archivepath) 69 70 Create a new zipimporter instance. *archivepath* must be a path to a ZIP 71 file, or to a specific path within a ZIP file. For example, an *archivepath* 72 of :file:`foo/bar.zip/lib` will look for modules in the :file:`lib` directory 73 inside the ZIP file :file:`foo/bar.zip` (provided that it exists). 74 75 :exc:`ZipImportError` is raised if *archivepath* doesn't point to a valid ZIP 76 archive. 77 78 .. method:: find_module(fullname[, path]) 79 80 Search for a module specified by *fullname*. *fullname* must be the fully 81 qualified (dotted) module name. It returns the zipimporter instance itself 82 if the module was found, or :const:`None` if it wasn't. The optional 83 *path* argument is ignored---it's there for compatibility with the 84 importer protocol. 85 86 87 .. method:: get_code(fullname) 88 89 Return the code object for the specified module. Raise 90 :exc:`ZipImportError` if the module couldn't be found. 91 92 93 .. method:: get_data(pathname) 94 95 Return the data associated with *pathname*. Raise :exc:`IOError` if the 96 file wasn't found. 97 98 99 .. method:: get_filename(fullname) 100 101 Return the value ``__file__`` would be set to if the specified module 102 was imported. Raise :exc:`ZipImportError` if the module couldn't be 103 found. 104 105 .. versionadded:: 2.7 106 107 108 .. method:: get_source(fullname) 109 110 Return the source code for the specified module. Raise 111 :exc:`ZipImportError` if the module couldn't be found, return 112 :const:`None` if the archive does contain the module, but has no source 113 for it. 114 115 116 .. method:: is_package(fullname) 117 118 Return ``True`` if the module specified by *fullname* is a package. Raise 119 :exc:`ZipImportError` if the module couldn't be found. 120 121 122 .. method:: load_module(fullname) 123 124 Load the module specified by *fullname*. *fullname* must be the fully 125 qualified (dotted) module name. It returns the imported module, or raises 126 :exc:`ZipImportError` if it wasn't found. 127 128 129 .. attribute:: archive 130 131 The file name of the importer's associated ZIP file, without a possible 132 subpath. 133 134 135 .. attribute:: prefix 136 137 The subpath within the ZIP file where modules are searched. This is the 138 empty string for zipimporter objects which point to the root of the ZIP 139 file. 140 141 The :attr:`archive` and :attr:`prefix` attributes, when combined with a 142 slash, equal the original *archivepath* argument given to the 143 :class:`zipimporter` constructor. 144 145 146.. _zipimport-examples: 147 148Examples 149-------- 150 151Here is an example that imports a module from a ZIP archive - note that the 152:mod:`zipimport` module is not explicitly used. 153 154.. code-block:: shell-session 155 156 $ unzip -l example.zip 157 Archive: example.zip 158 Length Date Time Name 159 -------- ---- ---- ---- 160 8467 11-26-02 22:30 jwzthreading.py 161 -------- ------- 162 8467 1 file 163 $ ./python 164 Python 2.3 (#1, Aug 1 2003, 19:54:32) 165 >>> import sys 166 >>> sys.path.insert(0, 'example.zip') # Add .zip file to front of path 167 >>> import jwzthreading 168 >>> jwzthreading.__file__ 169 'example.zip/jwzthreading.py' 170 171