Debian Codegraph @

Doc/library/zipimport.rst

raw
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