Doc/lib/libzipimport.tex

   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}{just@letterror.com}
   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}{ZipImporterError}
  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/appnote.html]{PKZIP Application
  54             Note}{Documentation on the ZIP file format by Phil
  55             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.  \class{ZipImportError} is raised if \var{archivepath} doesn't
  73   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   \class{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   \class{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 \class{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 \class{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  --------                   -------
 125      8467                   1 file
 126 $ ./python
 127 Python 2.3 (#1, Aug 1 2003, 19:54:32)
 128 >>> import sys
 129 >>> sys.path.insert(0, '/tmp/example.zip')  # Add .zip file to front of path
 130 >>> import jwzthreading
 131 >>> jwzthreading.__file__
 132 '/tmp/example.zip/jwzthreading.py'
 133 \end{verbatim}