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. |
| 6 | .. moduleauthor:: Just van Rossum <just@letterror.com> |
| 7 | |
| 8 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 9 | This module adds the ability to import Python modules (:file:`\*.py`, |
| 10 | :file:`\*.py[co]`) and packages from ZIP-format archives. It is usually not |
| 11 | needed to use the :mod:`zipimport` module explicitly; it is automatically used |
Ezio Melotti | 2d826e8 | 2011-06-25 19:40:06 +0300 | [diff] [blame] | 12 | 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] | 13 | to ZIP archives. |
| 14 | |
Ezio Melotti | 2d826e8 | 2011-06-25 19:40:06 +0300 | [diff] [blame] | 15 | Typically, :data:`sys.path` is a list of directory names as strings. This module |
| 16 | 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] | 17 | The ZIP archive can contain a subdirectory structure to support package imports, |
| 18 | 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] | 19 | subdirectory. For example, the path :file:`example.zip/lib/` would only |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 20 | import from the :file:`lib/` subdirectory within the archive. |
| 21 | |
| 22 | Any files may be present in the ZIP archive, but only files :file:`.py` and |
| 23 | :file:`.py[co]` are available for import. ZIP import of dynamic modules |
| 24 | (:file:`.pyd`, :file:`.so`) is disallowed. Note that if an archive only contains |
| 25 | :file:`.py` files, Python will not attempt to modify the archive by adding the |
| 26 | corresponding :file:`.pyc` or :file:`.pyo` file, meaning that if a ZIP archive |
| 27 | doesn't contain :file:`.pyc` files, importing may be rather slow. |
| 28 | |
Benjamin Peterson | a28e702 | 2010-01-09 18:53:06 +0000 | [diff] [blame] | 29 | ZIP archives with an archive comment are currently not supported. |
| 30 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 31 | .. seealso:: |
| 32 | |
Christian Heimes | dd15f6c | 2008-03-16 00:07:10 +0000 | [diff] [blame] | 33 | `PKZIP Application Note <http://www.pkware.com/documents/casestudies/APPNOTE.TXT>`_ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 34 | Documentation on the ZIP file format by Phil Katz, the creator of the format and |
| 35 | algorithms used. |
| 36 | |
Victor Stinner | 766ad36 | 2010-05-14 14:36:18 +0000 | [diff] [blame] | 37 | :pep:`273` - Import Modules from Zip Archives |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 38 | Written by James C. Ahlstrom, who also provided an implementation. Python 2.3 |
| 39 | follows the specification in PEP 273, but uses an implementation written by Just |
| 40 | van Rossum that uses the import hooks described in PEP 302. |
| 41 | |
Victor Stinner | 766ad36 | 2010-05-14 14:36:18 +0000 | [diff] [blame] | 42 | :pep:`302` - New Import Hooks |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 43 | The PEP to add the import hooks that help this module work. |
| 44 | |
| 45 | |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 46 | This module defines an exception: |
| 47 | |
| 48 | .. exception:: ZipImportError |
| 49 | |
| 50 | Exception raised by zipimporter objects. It's a subclass of :exc:`ImportError`, |
| 51 | so it can be caught as :exc:`ImportError`, too. |
| 52 | |
| 53 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 54 | .. _zipimporter-objects: |
| 55 | |
| 56 | zipimporter Objects |
| 57 | ------------------- |
| 58 | |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 59 | :class:`zipimporter` is the class for importing ZIP files. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 60 | |
| 61 | .. class:: zipimporter(archivepath) |
| 62 | |
Alexandre Vassalotti | 8ae3e05 | 2008-05-16 00:41:41 +0000 | [diff] [blame] | 63 | Create a new zipimporter instance. *archivepath* must be a path to a ZIP |
| 64 | file, or to a specific path within a ZIP file. For example, an *archivepath* |
| 65 | of :file:`foo/bar.zip/lib` will look for modules in the :file:`lib` directory |
| 66 | inside the ZIP file :file:`foo/bar.zip` (provided that it exists). |
| 67 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 68 | :exc:`ZipImportError` is raised if *archivepath* doesn't point to a valid ZIP |
| 69 | archive. |
| 70 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 71 | .. method:: find_module(fullname[, path]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 72 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 73 | Search for a module specified by *fullname*. *fullname* must be the fully |
| 74 | qualified (dotted) module name. It returns the zipimporter instance itself |
| 75 | if the module was found, or :const:`None` if it wasn't. The optional |
| 76 | *path* argument is ignored---it's there for compatibility with the |
| 77 | importer protocol. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 78 | |
| 79 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 80 | .. method:: get_code(fullname) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 81 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 82 | Return the code object for the specified module. Raise |
| 83 | :exc:`ZipImportError` if the module couldn't be found. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 84 | |
| 85 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 86 | .. method:: get_data(pathname) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 87 | |
Antoine Pitrou | 62ab10a0 | 2011-10-12 20:10:51 +0200 | [diff] [blame] | 88 | Return the data associated with *pathname*. Raise :exc:`OSError` if the |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 89 | file wasn't found. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 90 | |
Antoine Pitrou | 62ab10a0 | 2011-10-12 20:10:51 +0200 | [diff] [blame] | 91 | .. versionchanged:: 3.3 |
| 92 | :exc:`IOError` used to be raised instead of :exc:`OSError`. |
| 93 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 94 | |
Nick Coghlan | 9a1d6e3 | 2009-02-08 03:37:27 +0000 | [diff] [blame] | 95 | .. method:: get_filename(fullname) |
| 96 | |
| 97 | Return the value ``__file__`` would be set to if the specified module |
| 98 | was imported. Raise :exc:`ZipImportError` if the module couldn't be |
| 99 | found. |
| 100 | |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 101 | .. versionadded:: 3.1 |
Nick Coghlan | 9a1d6e3 | 2009-02-08 03:37:27 +0000 | [diff] [blame] | 102 | |
| 103 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 104 | .. method:: get_source(fullname) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 105 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 106 | Return the source code for the specified module. Raise |
| 107 | :exc:`ZipImportError` if the module couldn't be found, return |
| 108 | :const:`None` if the archive does contain the module, but has no source |
| 109 | for it. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 110 | |
| 111 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 112 | .. method:: is_package(fullname) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 113 | |
Serhiy Storchaka | fbc1c26 | 2013-11-29 12:17:13 +0200 | [diff] [blame] | 114 | Return ``True`` if the module specified by *fullname* is a package. Raise |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 115 | :exc:`ZipImportError` if the module couldn't be found. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 116 | |
| 117 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 118 | .. method:: load_module(fullname) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 119 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 120 | Load the module specified by *fullname*. *fullname* must be the fully |
| 121 | qualified (dotted) module name. It returns the imported module, or raises |
| 122 | :exc:`ZipImportError` if it wasn't found. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 123 | |
| 124 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 125 | .. attribute:: archive |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 126 | |
Alexandre Vassalotti | 8ae3e05 | 2008-05-16 00:41:41 +0000 | [diff] [blame] | 127 | The file name of the importer's associated ZIP file, without a possible |
| 128 | subpath. |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 129 | |
| 130 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 131 | .. attribute:: prefix |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 132 | |
Alexandre Vassalotti | 8ae3e05 | 2008-05-16 00:41:41 +0000 | [diff] [blame] | 133 | The subpath within the ZIP file where modules are searched. This is the |
| 134 | empty string for zipimporter objects which point to the root of the ZIP |
| 135 | file. |
| 136 | |
| 137 | The :attr:`archive` and :attr:`prefix` attributes, when combined with a |
| 138 | slash, equal the original *archivepath* argument given to the |
| 139 | :class:`zipimporter` constructor. |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 140 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 141 | |
| 142 | .. _zipimport-examples: |
| 143 | |
Christian Heimes | 7f04431 | 2008-01-06 17:05:40 +0000 | [diff] [blame] | 144 | Examples |
| 145 | -------- |
| 146 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 147 | Here is an example that imports a module from a ZIP archive - note that the |
| 148 | :mod:`zipimport` module is not explicitly used. :: |
| 149 | |
Petri Lehtinen | 9f74c6c | 2013-02-23 19:26:56 +0100 | [diff] [blame] | 150 | $ unzip -l example.zip |
| 151 | Archive: example.zip |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 152 | Length Date Time Name |
| 153 | -------- ---- ---- ---- |
| 154 | 8467 11-26-02 22:30 jwzthreading.py |
| 155 | -------- ------- |
| 156 | 8467 1 file |
| 157 | $ ./python |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 158 | Python 2.3 (#1, Aug 1 2003, 19:54:32) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 159 | >>> import sys |
Petri Lehtinen | 9f74c6c | 2013-02-23 19:26:56 +0100 | [diff] [blame] | 160 | >>> 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] | 161 | >>> import jwzthreading |
| 162 | >>> jwzthreading.__file__ |
Petri Lehtinen | 9f74c6c | 2013-02-23 19:26:56 +0100 | [diff] [blame] | 163 | 'example.zip/jwzthreading.py' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 164 | |