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 (a] letterror.com> 8 9 -------------- 10 11 This module adds the ability to import Python modules (:file:`\*.py`, 12 :file:`\*.pyc`) and packages from ZIP-format archives. It is usually not 13 needed to use the :mod:`zipimport` module explicitly; it is automatically used 14 by the built-in :keyword:`import` mechanism for :data:`sys.path` items that are paths 15 to ZIP archives. 16 17 Typically, :data:`sys.path` is a list of directory names as strings. This module 18 also allows an item of :data:`sys.path` to be a string naming a ZIP file archive. 19 The ZIP archive can contain a subdirectory structure to support package imports, 20 and a path within the archive can be specified to only import from a 21 subdirectory. For example, the path :file:`example.zip/lib/` would only 22 import from the :file:`lib/` subdirectory within the archive. 23 24 Any 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 28 corresponding :file:`.pyc` file, meaning that if a ZIP archive 29 doesn't contain :file:`.pyc` files, importing may be rather slow. 30 31 ZIP 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 48 This 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 58 zipimporter 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 146 Examples 147 -------- 148 149 Here 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
