| 1 | \section{\module{zipimport} ---
|
|---|
| 2 | Import modules from Zip archives}
|
|---|
| 3 |
|
|---|
| 4 | \declaremodule{standard}{zipimport}
|
|---|
| 5 | \modulesynopsis{support for importing Python modules from ZIP archives.}
|
|---|
| 6 | \moduleauthor{Just van Rossum}{[email protected]}
|
|---|
| 7 |
|
|---|
| 8 | \versionadded{2.3}
|
|---|
| 9 |
|
|---|
| 10 | This module adds the ability to import Python modules (\file{*.py},
|
|---|
| 11 | \file{*.py[co]}) and packages from ZIP-format archives. It is usually
|
|---|
| 12 | not needed to use the \module{zipimport} module explicitly; it is
|
|---|
| 13 | automatically used by the builtin \keyword{import} mechanism for
|
|---|
| 14 | \code{sys.path} items that are paths to ZIP archives.
|
|---|
| 15 |
|
|---|
| 16 | Typically, \code{sys.path} is a list of directory names as strings. This
|
|---|
| 17 | module also allows an item of \code{sys.path} to be a string naming a ZIP
|
|---|
| 18 | file archive. The ZIP archive can contain a subdirectory structure to
|
|---|
| 19 | support package imports, and a path within the archive can be specified to
|
|---|
| 20 | only import from a subdirectory. For example, the path
|
|---|
| 21 | \file{/tmp/example.zip/lib/} would only import from the
|
|---|
| 22 | \file{lib/} subdirectory within the archive.
|
|---|
| 23 |
|
|---|
| 24 | Any files may be present in the ZIP archive, but only files \file{.py} and
|
|---|
| 25 | \file{.py[co]} are available for import. ZIP import of dynamic modules
|
|---|
| 26 | (\file{.pyd}, \file{.so}) is disallowed. Note that if an archive only
|
|---|
| 27 | contains \file{.py} files, Python will not attempt to modify the archive
|
|---|
| 28 | by adding the corresponding \file{.pyc} or \file{.pyo} file, meaning that
|
|---|
| 29 | if a ZIP archive doesn't contain \file{.pyc} files, importing may be rather
|
|---|
| 30 | slow.
|
|---|
| 31 |
|
|---|
| 32 | Using the built-in \function{reload()} function will
|
|---|
| 33 | fail if called on a module loaded from a ZIP archive; it is unlikely that
|
|---|
| 34 | \function{reload()} would be needed, since this would imply that the ZIP
|
|---|
| 35 | has been altered during runtime.
|
|---|
| 36 |
|
|---|
| 37 | The available attributes of this module are:
|
|---|
| 38 |
|
|---|
| 39 | \begin{excdesc}{ZipImportError}
|
|---|
| 40 | Exception raised by zipimporter objects. It's a subclass of
|
|---|
| 41 | \exception{ImportError}, so it can be caught as \exception{ImportError},
|
|---|
| 42 | too.
|
|---|
| 43 | \end{excdesc}
|
|---|
| 44 |
|
|---|
| 45 | \begin{classdesc*}{zipimporter}
|
|---|
| 46 | The class for importing ZIP files. See
|
|---|
| 47 | ``\citetitle{zipimporter Objects}'' (section \ref{zipimporter-objects})
|
|---|
| 48 | for constructor details.
|
|---|
| 49 | \end{classdesc*}
|
|---|
| 50 |
|
|---|
| 51 |
|
|---|
| 52 | \begin{seealso}
|
|---|
| 53 | \seetitle[http://www.pkware.com/business_and_developers/developer/appnote/]
|
|---|
| 54 | {PKZIP Application Note}{Documentation on the ZIP file format by
|
|---|
| 55 | Phil Katz, the creator of the format and algorithms used.}
|
|---|
| 56 |
|
|---|
| 57 | \seepep{0273}{Import Modules from Zip Archives}{Written by James C.
|
|---|
| 58 | Ahlstrom, who also provided an implementation. Python 2.3
|
|---|
| 59 | follows the specification in PEP 273, but uses an
|
|---|
| 60 | implementation written by Just van Rossum that uses the import
|
|---|
| 61 | hooks described in PEP 302.}
|
|---|
| 62 |
|
|---|
| 63 | \seepep{0302}{New Import Hooks}{The PEP to add the import hooks that help
|
|---|
| 64 | this module work.}
|
|---|
| 65 | \end{seealso}
|
|---|
| 66 |
|
|---|
| 67 |
|
|---|
| 68 | \subsection{zipimporter Objects \label{zipimporter-objects}}
|
|---|
| 69 |
|
|---|
| 70 | \begin{classdesc}{zipimporter}{archivepath}
|
|---|
| 71 | Create a new zipimporter instance. \var{archivepath} must be a path to
|
|---|
| 72 | a zipfile. \exception{ZipImportError} is raised if \var{archivepath}
|
|---|
| 73 | doesn't point to a valid ZIP archive.
|
|---|
| 74 | \end{classdesc}
|
|---|
| 75 |
|
|---|
| 76 | \begin{methoddesc}{find_module}{fullname\optional{, path}}
|
|---|
| 77 | Search for a module specified by \var{fullname}. \var{fullname} must be
|
|---|
| 78 | the fully qualified (dotted) module name. It returns the zipimporter
|
|---|
| 79 | instance itself if the module was found, or \constant{None} if it wasn't.
|
|---|
| 80 | The optional \var{path} argument is ignored---it's there for
|
|---|
| 81 | compatibility with the importer protocol.
|
|---|
| 82 | \end{methoddesc}
|
|---|
| 83 |
|
|---|
| 84 | \begin{methoddesc}{get_code}{fullname}
|
|---|
| 85 | Return the code object for the specified module. Raise
|
|---|
| 86 | \exception{ZipImportError} if the module couldn't be found.
|
|---|
| 87 | \end{methoddesc}
|
|---|
| 88 |
|
|---|
| 89 | \begin{methoddesc}{get_data}{pathname}
|
|---|
| 90 | Return the data associated with \var{pathname}. Raise \exception{IOError}
|
|---|
| 91 | if the file wasn't found.
|
|---|
| 92 | \end{methoddesc}
|
|---|
| 93 |
|
|---|
| 94 | \begin{methoddesc}{get_source}{fullname}
|
|---|
| 95 | Return the source code for the specified module. Raise
|
|---|
| 96 | \exception{ZipImportError} if the module couldn't be found, return
|
|---|
| 97 | \constant{None} if the archive does contain the module, but has
|
|---|
| 98 | no source for it.
|
|---|
| 99 | \end{methoddesc}
|
|---|
| 100 |
|
|---|
| 101 | \begin{methoddesc}{is_package}{fullname}
|
|---|
| 102 | Return True if the module specified by \var{fullname} is a package.
|
|---|
| 103 | Raise \exception{ZipImportError} if the module couldn't be found.
|
|---|
| 104 | \end{methoddesc}
|
|---|
| 105 |
|
|---|
| 106 | \begin{methoddesc}{load_module}{fullname}
|
|---|
| 107 | Load the module specified by \var{fullname}. \var{fullname} must be the
|
|---|
| 108 | fully qualified (dotted) module name. It returns the imported
|
|---|
| 109 | module, or raises \exception{ZipImportError} if it wasn't found.
|
|---|
| 110 | \end{methoddesc}
|
|---|
| 111 |
|
|---|
| 112 | \subsection{Examples}
|
|---|
| 113 | \nodename{zipimport Examples}
|
|---|
| 114 |
|
|---|
| 115 | Here is an example that imports a module from a ZIP archive - note that
|
|---|
| 116 | the \module{zipimport} module is not explicitly used.
|
|---|
| 117 |
|
|---|
| 118 | \begin{verbatim}
|
|---|
| 119 | $ unzip -l /tmp/example.zip
|
|---|
| 120 | Archive: /tmp/example.zip
|
|---|
| 121 | Length Date Time Name
|
|---|
| 122 | -------- ---- ---- ----
|
|---|
| 123 | 8467 11-26-02 22:30 jwzthreading.py
|
|---|
| 124 | -------- -------
|
|---|
|
|---|
