From ffcbab073e3543017530e5f2677291df680dbedf Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Wed, 19 Jan 2005 05:42:50 +0000 Subject: documentation for the zipimport module using contributed patch (closes SF bug #853800; markup adjusted) --- Doc/Makefile.deps | 1 + Doc/lib/lib.tex | 1 + Doc/lib/libzipimport.tex | 133 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 135 insertions(+) create mode 100644 Doc/lib/libzipimport.tex diff --git a/Doc/Makefile.deps b/Doc/Makefile.deps index 0194cc7..6686f53 100644 --- a/Doc/Makefile.deps +++ b/Doc/Makefile.deps @@ -125,6 +125,7 @@ LIBFILES= $(MANSTYLES) $(INDEXSTYLES) $(COMMONTEX) \ lib/libmarshal.tex \ lib/libwarnings.tex \ lib/libimp.tex \ + lib/libzipimport.tex \ lib/libpkgutil.tex \ lib/libparser.tex \ lib/libbltin.tex \ diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 1350dd9..ac6b62d 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -91,6 +91,7 @@ and how to embed it in other applications. \input{libmarshal} \input{libwarnings} \input{libimp} +\input{libzipimport} \input{libpkgutil} \input{libcode} \input{libcodeop} diff --git a/Doc/lib/libzipimport.tex b/Doc/lib/libzipimport.tex new file mode 100644 index 0000000..9455310 --- /dev/null +++ b/Doc/lib/libzipimport.tex @@ -0,0 +1,133 @@ +\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}{ZipImporterError} + 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. \class{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 + \class{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 + \class{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 \class{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 \class{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} -- cgit v0.12