/Doc/library/zipimport.rst

  1
  2:mod:`zipimport` --- Import modules from Zip archives
  3=====================================================
  4
  5.. module:: zipimport
  6   :synopsis: support for importing Python modules from ZIP archives.
  7.. moduleauthor:: Just van Rossum <just@letterror.com>
  8
  9
 10.. versionadded:: 2.3
 11
 12This module adds the ability to import Python modules (:file:`\*.py`,
 13:file:`\*.py[co]`) and packages from ZIP-format archives. It is usually not
 14needed to use the :mod:`zipimport` module explicitly; it is automatically used
 15by the builtin :keyword:`import` mechanism for ``sys.path`` items that are paths
 16to ZIP archives.
 17
 18Typically, ``sys.path`` is a list of directory names as strings.  This module
 19also allows an item of ``sys.path`` to be a string naming a ZIP file archive.
 20The ZIP archive can contain a subdirectory structure to support package imports,
 21and a path within the archive can be specified to only import from a
 22subdirectory.  For example, the path :file:`/tmp/example.zip/lib/` would only
 23import from the :file:`lib/` subdirectory within the archive.
 24
 25Any files may be present in the ZIP archive, but only files :file:`.py` and
 26:file:`.py[co]` are available for import.  ZIP import of dynamic modules
 27(:file:`.pyd`, :file:`.so`) is disallowed. Note that if an archive only contains
 28:file:`.py` files, Python will not attempt to modify the archive by adding the
 29corresponding :file:`.pyc` or :file:`.pyo` file, meaning that if a ZIP archive
 30doesn't contain :file:`.pyc` files, importing may be rather slow.
 31
 32Using the built-in :func:`reload` function will fail if called on a module
 33loaded from a ZIP archive; it is unlikely that :func:`reload` would be needed,
 34since this would imply that the ZIP has been altered during runtime.
 35
 36.. seealso::
 37
 38   `PKZIP Application Note <http://www.pkware.com/documents/casestudies/APPNOTE.TXT>`_
 39      Documentation on the ZIP file format by Phil Katz, the creator of the format and
 40      algorithms used.
 41
 42   :pep:`0273` - Import Modules from Zip Archives
 43      Written by James C. Ahlstrom, who also provided an implementation. Python 2.3
 44      follows the specification in PEP 273, but uses an implementation written by Just
 45      van Rossum that uses the import hooks described in PEP 302.
 46
 47   :pep:`0302` - New Import Hooks
 48      The PEP to add the import hooks that help this module work.
 49
 50
 51This module defines an exception:
 52
 53.. exception:: ZipImportError
 54
 55   Exception raised by zipimporter objects. It's a subclass of :exc:`ImportError`,
 56   so it can be caught as :exc:`ImportError`, too.
 57
 58
 59.. _zipimporter-objects:
 60
 61zipimporter Objects
 62-------------------
 63
 64:class:`zipimporter` is the class for importing ZIP files.
 65
 66.. class:: zipimporter(archivepath)
 67
 68   Create a new zipimporter instance. *archivepath* must be a path to a ZIP
 69   file, or to a specific path within a ZIP file.  For example, an *archivepath*
 70   of :file:`foo/bar.zip/lib` will look for modules in the :file:`lib` directory
 71   inside the ZIP file :file:`foo/bar.zip` (provided that it exists).
 72
 73   :exc:`ZipImportError` is raised if *archivepath* doesn't point to a valid ZIP
 74   archive.
 75
 76   .. method:: find_module(fullname[, path])
 77
 78      Search for a module specified by *fullname*. *fullname* must be the fully
 79      qualified (dotted) module name. It returns the zipimporter instance itself
 80      if the module was found, or :const:`None` if it wasn't. The optional
 81      *path* argument is ignored---it's there for compatibility with the
 82      importer protocol.
 83
 84
 85   .. method:: get_code(fullname)
 86
 87      Return the code object for the specified module. Raise
 88      :exc:`ZipImportError` if the module couldn't be found.
 89
 90
 91   .. method:: get_data(pathname)
 92
 93      Return the data associated with *pathname*. Raise :exc:`IOError` if the
 94      file wasn't found.
 95
 96
 97   .. method:: get_source(fullname)
 98
 99      Return the source code for the specified module. Raise
100      :exc:`ZipImportError` if the module couldn't be found, return
101      :const:`None` if the archive does contain the module, but has no source
102      for it.
103
104
105   .. method:: is_package(fullname)
106
107      Return True if the module specified by *fullname* is a package. Raise
108      :exc:`ZipImportError` if the module couldn't be found.
109
110
111   .. method:: load_module(fullname)
112
113      Load the module specified by *fullname*. *fullname* must be the fully
114      qualified (dotted) module name. It returns the imported module, or raises
115      :exc:`ZipImportError` if it wasn't found.
116
117
118   .. attribute:: archive
119
120      The file name of the importer's associated ZIP file, without a possible
121      subpath.
122
123
124   .. attribute:: prefix
125
126      The subpath within the ZIP file where modules are searched.  This is the
127      empty string for zipimporter objects which point to the root of the ZIP
128      file.
129
130   The :attr:`archive` and :attr:`prefix` attributes, when combined with a
131   slash, equal the original *archivepath* argument given to the
132   :class:`zipimporter` constructor.
133
134
135.. _zipimport-examples:
136
137Examples
138--------
139
140Here is an example that imports a module from a ZIP archive - note that the
141:mod:`zipimport` module is not explicitly used. ::
142
143   $ unzip -l /tmp/example.zip
144   Archive:  /tmp/example.zip
145     Length     Date   Time    Name
146    --------    ----   ----    ----
147        8467  11-26-02 22:30   jwzthreading.py
148    --------                   -------
149        8467                   1 file
150   $ ./python
151   Python 2.3 (#1, Aug 1 2003, 19:54:32)
152   >>> import sys
153   >>> sys.path.insert(0, '/tmp/example.zip')  # Add .zip file to front of path
154   >>> import jwzthreading
155   >>> jwzthreading.__file__
156   '/tmp/example.zip/jwzthreading.py'
157