Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`zipimport` --- Import modules from Zip archives |
| 2 | ===================================================== |
| 3 | |
| 4 | .. module:: zipimport |
| 5 | :synopsis: support for importing Python modules from ZIP archives. |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 6 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | .. moduleauthor:: Just van Rossum <just@letterror.com> |
| 8 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 9 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 11 | This module adds the ability to import Python modules (:file:`\*.py`, |
Xiang Zhang | 0710d75 | 2017-03-11 13:02:52 +0800 | [diff] [blame] | 12 | :file:`\*.pyc`) and packages from ZIP-format archives. It is usually not |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 13 | needed to use the :mod:`zipimport` module explicitly; it is automatically used |
Ezio Melotti | 2d826e8 | 2011-06-25 19:40:06 +0300 | [diff] [blame] | 14 | by the built-in :keyword:`import` mechanism for :data:`sys.path` items that are paths |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 15 | to ZIP archives. |
| 16 | |
Ezio Melotti | 2d826e8 | 2011-06-25 19:40:06 +0300 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Petri Lehtinen | 9f74c6c | 2013-02-23 19:26:56 +0100 | [diff] [blame] | 21 | subdirectory. For example, the path :file:`example.zip/lib/` would only |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Brett Cannon | f299abd | 2015-04-13 14:21:02 -0400 | [diff] [blame] | 25 | :file:`.pyc` are available for import. ZIP import of dynamic modules |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Brett Cannon | f299abd | 2015-04-13 14:21:02 -0400 | [diff] [blame] | 28 | corresponding :file:`.pyc` file, meaning that if a ZIP archive |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 29 | doesn't contain :file:`.pyc` files, importing may be rather slow. |
| 30 | |
Benjamin Peterson | a28e702 | 2010-01-09 18:53:06 +0000 | [diff] [blame] | 31 | ZIP archives with an archive comment are currently not supported. |
| 32 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 33 | .. seealso:: |
| 34 | |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame] | 35 | `PKZIP Application Note <https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT>`_ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 36 | Documentation on the ZIP file format by Phil Katz, the creator of the format and |
| 37 | algorithms used. |
| 38 | |
Victor Stinner | 766ad36 | 2010-05-14 14:36:18 +0000 | [diff] [blame] | 39 | :pep:`273` - Import Modules from Zip Archives |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Victor Stinner | 766ad36 | 2010-05-14 14:36:18 +0000 | [diff] [blame] | 44 | :pep:`302` - New Import Hooks |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 45 | The PEP to add the import hooks that help this module work. |
| 46 | |
| 47 | |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 56 | .. _zipimporter-objects: |
| 57 | |
| 58 | zipimporter Objects |
| 59 | ------------------- |
| 60 | |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 61 | :class:`zipimporter` is the class for importing ZIP files. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 62 | |
| 63 | .. class:: zipimporter(archivepath) |
| 64 | |
Alexandre Vassalotti | 8ae3e05 | 2008-05-16 00:41:41 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 70 | :exc:`ZipImportError` is raised if *archivepath* doesn't point to a valid ZIP |
| 71 | archive. |
| 72 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 73 | .. method:: find_module(fullname[, path]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 74 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 80 | |
| 81 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 82 | .. method:: get_code(fullname) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 83 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 84 | Return the code object for the specified module. Raise |
| 85 | :exc:`ZipImportError` if the module couldn't be found. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 86 | |
| 87 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 88 | .. method:: get_data(pathname) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 89 | |
Antoine Pitrou | 62ab10a0 | 2011-10-12 20:10:51 +0200 | [diff] [blame] | 90 | Return the data associated with *pathname*. Raise :exc:`OSError` if the |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 91 | file wasn't found. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 92 | |
Antoine Pitrou | 62ab10a0 | 2011-10-12 20:10:51 +0200 | [diff] [blame] | 93 | .. versionchanged:: 3.3 |
| 94 | :exc:`IOError` used to be raised instead of :exc:`OSError`. |
| 95 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 96 | |
Nick Coghlan | 9a1d6e3 | 2009-02-08 03:37:27 +0000 | [diff] [blame] | 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 | |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 103 | .. versionadded:: 3.1 |
Nick Coghlan | 9a1d6e3 | 2009-02-08 03:37:27 +0000 | [diff] [blame] | 104 | |
| 105 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 106 | .. method:: get_source(fullname) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 107 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 112 | |
| 113 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 114 | .. method:: is_package(fullname) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 115 | |
Serhiy Storchaka | fbc1c26 | 2013-11-29 12:17:13 +0200 | [diff] [blame] | 116 | Return ``True`` if the module specified by *fullname* is a package. Raise |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 117 | :exc:`ZipImportError` if the module couldn't be found. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 118 | |
| 119 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 120 | .. method:: load_module(fullname) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 121 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 125 | |
| 126 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 127 | .. attribute:: archive |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 128 | |
Alexandre Vassalotti | 8ae3e05 | 2008-05-16 00:41:41 +0000 | [diff] [blame] | 129 | The file name of the importer's associated ZIP file, without a possible |
| 130 | subpath. |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 131 | |
| 132 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 133 | .. attribute:: prefix |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 134 | |
Alexandre Vassalotti | 8ae3e05 | 2008-05-16 00:41:41 +0000 | [diff] [blame] | 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. |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 142 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 143 | |
| 144 | .. _zipimport-examples: |
| 145 | |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 146 | Examples |
| 147 | -------- |
| 148 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 149 | Here is an example that imports a module from a ZIP archive - note that the |
Martin Panter | 1050d2d | 2016-07-26 11:18:21 +0200 | [diff] [blame] | 150 | :mod:`zipimport` module is not explicitly used. |
| 151 | |
| 152 | .. code-block:: shell-session |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 153 | |
Petri Lehtinen | 9f74c6c | 2013-02-23 19:26:56 +0100 | [diff] [blame] | 154 | $ unzip -l example.zip |
| 155 | Archive: example.zip |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 156 | Length Date Time Name |
| 157 | -------- ---- ---- ---- |
| 158 | 8467 11-26-02 22:30 jwzthreading.py |
| 159 | -------- ------- |
| 160 | 8467 1 file |
| 161 | $ ./python |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 162 | Python 2.3 (#1, Aug 1 2003, 19:54:32) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 163 | >>> import sys |
Petri Lehtinen | 9f74c6c | 2013-02-23 19:26:56 +0100 | [diff] [blame] | 164 | >>> sys.path.insert(0, 'example.zip') # Add .zip file to front of path |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 165 | >>> import jwzthreading |
| 166 | >>> jwzthreading.__file__ |
Petri Lehtinen | 9f74c6c | 2013-02-23 19:26:56 +0100 | [diff] [blame] | 167 | 'example.zip/jwzthreading.py' |