| 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 <[email protected]> |
| 8 |
|
| 9 |
**Source code:** :source:`Lib/zipimport.py` |
| 10 |
|
| 11 |
-------------- |
| 12 |
|
| 13 |
This module adds the ability to import Python modules (:file:`\*.py`, |
| 14 |
:file:`\*.pyc`) and packages from ZIP-format archives. It is usually not |
| 15 |
needed to use the :mod:`!zipimport` module explicitly; it is automatically used |
| 16 |
by the built-in :keyword:`import` mechanism for :data:`sys.path` items that are paths |
| 17 |
to ZIP archives. |
| 18 |
|
| 19 |
Typically, :data:`sys.path` is a list of directory names as strings. This module |
| 20 |
also allows an item of :data:`sys.path` to be a string naming a ZIP file archive. |
| 21 |
The ZIP archive can contain a subdirectory structure to support package imports, |
| 22 |
and a path within the archive can be specified to only import from a |
| 23 |
subdirectory. For example, the path :file:`example.zip/lib/` would only |
| 24 |
import from the :file:`lib/` subdirectory within the archive. |
| 25 |
|
| 26 |
Any 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 |
| 30 |
corresponding :file:`.pyc` file, meaning that if a ZIP archive |
| 31 |
doesn'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 |
|
| 55 |
This 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 |
|
| 65 |
zipimporter 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-removed:: 3.10 3.15 |
| 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 |
|
| 183 |
Examples |
| 184 |
-------- |
| 185 |
|
| 186 |
Here 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_archive.zip |
| 192 |
Archive: example_archive.zip |
| 193 |
Length Date Time Name |
| 194 |
-------- ---- ---- ---- |
| 195 |
8467 01-01-00 12:30 example.py |
| 196 |
-------- ------- |
| 197 |
8467 1 file |
| 198 |
|
| 199 |
.. code-block:: pycon |
| 200 |
|
| 201 |
>>> import sys |
| 202 |
>>> # Add the archive to the front of the module search path |
| 203 |
>>> sys.path.insert(0, 'example_archive.zip') |
| 204 |
>>> import example |
| 205 |
>>> example.__file__ |
| 206 |
'example_archive.zip/example.py' |
| 207 |
|