134 lines
5.1 KiB
TeX
134 lines
5.1 KiB
TeX
\section{\module{zipimport} ---
|
|
Import modules from Zip archives}
|
|
|
|
\declaremodule{standard}{zipimport}
|
|
\modulesynopsis{support for importing Python modules from ZIP archives.}
|
|
\moduleauthor{Just van Rossum}{just@letterror.com}
|
|
|
|
\versionadded{2.3}
|
|
|
|
This module adds the ability to import Python modules (\file{*.py},
|
|
\file{*.py[co]}) and packages from ZIP-format archives. It is usually
|
|
not needed to use the \module{zipimport} module explicitly; it is
|
|
automatically used by the builtin \keyword{import} mechanism for
|
|
\code{sys.path} items that are paths to ZIP archives.
|
|
|
|
Typically, \code{sys.path} is a list of directory names as strings. This
|
|
module also allows an item of \code{sys.path} to be a string naming a ZIP
|
|
file archive. The ZIP archive can contain a subdirectory structure to
|
|
support package imports, and a path within the archive can be specified to
|
|
only import from a subdirectory. For example, the path
|
|
\file{/tmp/example.zip/lib/} would only import from the
|
|
\file{lib/} subdirectory within the archive.
|
|
|
|
Any files may be present in the ZIP archive, but only files \file{.py} and
|
|
\file{.py[co]} are available for import. ZIP import of dynamic modules
|
|
(\file{.pyd}, \file{.so}) is disallowed. Note that if an archive only
|
|
contains \file{.py} files, Python will not attempt to modify the archive
|
|
by adding the corresponding \file{.pyc} or \file{.pyo} file, meaning that
|
|
if a ZIP archive doesn't contain \file{.pyc} files, importing may be rather
|
|
slow.
|
|
|
|
Using the built-in \function{reload()} function will
|
|
fail if called on a module loaded from a ZIP archive; it is unlikely that
|
|
\function{reload()} would be needed, since this would imply that the ZIP
|
|
has been altered during runtime.
|
|
|
|
The available attributes of this module are:
|
|
|
|
\begin{excdesc}{ZipImportError}
|
|
Exception raised by zipimporter objects. It's a subclass of
|
|
\exception{ImportError}, so it can be caught as \exception{ImportError},
|
|
too.
|
|
\end{excdesc}
|
|
|
|
\begin{classdesc*}{zipimporter}
|
|
The class for importing ZIP files. See
|
|
``\citetitle{zipimporter Objects}'' (section \ref{zipimporter-objects})
|
|
for constructor details.
|
|
\end{classdesc*}
|
|
|
|
|
|
\begin{seealso}
|
|
\seetitle[http://www.pkware.com/appnote.html]{PKZIP Application
|
|
Note}{Documentation on the ZIP file format by Phil
|
|
Katz, the creator of the format and algorithms used.}
|
|
|
|
\seepep{0273}{Import Modules from Zip Archives}{Written by James C.
|
|
Ahlstrom, who also provided an implementation. Python 2.3
|
|
follows the specification in PEP 273, but uses an
|
|
implementation written by Just van Rossum that uses the import
|
|
hooks described in PEP 302.}
|
|
|
|
\seepep{0302}{New Import Hooks}{The PEP to add the import hooks that help
|
|
this module work.}
|
|
\end{seealso}
|
|
|
|
|
|
\subsection{zipimporter Objects \label{zipimporter-objects}}
|
|
|
|
\begin{classdesc}{zipimporter}{archivepath}
|
|
Create a new zipimporter instance. \var{archivepath} must be a path to
|
|
a zipfile. \exception{ZipImportError} is raised if \var{archivepath}
|
|
doesn't point to a valid ZIP archive.
|
|
\end{classdesc}
|
|
|
|
\begin{methoddesc}{find_module}{fullname\optional{, path}}
|
|
Search for a module specified by \var{fullname}. \var{fullname} must be
|
|
the fully qualified (dotted) module name. It returns the zipimporter
|
|
instance itself if the module was found, or \constant{None} if it wasn't.
|
|
The optional \var{path} argument is ignored---it's there for
|
|
compatibility with the importer protocol.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{get_code}{fullname}
|
|
Return the code object for the specified module. Raise
|
|
\exception{ZipImportError} if the module couldn't be found.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{get_data}{pathname}
|
|
Return the data associated with \var{pathname}. Raise \exception{IOError}
|
|
if the file wasn't found.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{get_source}{fullname}
|
|
Return the source code for the specified module. Raise
|
|
\exception{ZipImportError} if the module couldn't be found, return
|
|
\constant{None} if the archive does contain the module, but has
|
|
no source for it.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{is_package}{fullname}
|
|
Return True if the module specified by \var{fullname} is a package.
|
|
Raise \exception{ZipImportError} if the module couldn't be found.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{load_module}{fullname}
|
|
Load the module specified by \var{fullname}. \var{fullname} must be the
|
|
fully qualified (dotted) module name. It returns the imported
|
|
module, or raises \exception{ZipImportError} if it wasn't found.
|
|
\end{methoddesc}
|
|
|
|
\subsection{Examples}
|
|
\nodename{zipimport Examples}
|
|
|
|
Here is an example that imports a module from a ZIP archive - note that
|
|
the \module{zipimport} module is not explicitly used.
|
|
|
|
\begin{verbatim}
|
|
$ unzip -l /tmp/example.zip
|
|
Archive: /tmp/example.zip
|
|
Length Date Time Name
|
|
-------- ---- ---- ----
|
|
8467 11-26-02 22:30 jwzthreading.py
|
|
-------- -------
|
|
8467 1 file
|
|
$ ./python
|
|
Python 2.3 (#1, Aug 1 2003, 19:54:32)
|
|
>>> import sys
|
|
>>> sys.path.insert(0, '/tmp/example.zip') # Add .zip file to front of path
|
|
>>> import jwzthreading
|
|
>>> jwzthreading.__file__
|
|
'/tmp/example.zip/jwzthreading.py'
|
|
\end{verbatim}
|