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