31.4. "zipimport" --- Zip アーカイブからモジュールを import する
****************************************************************

バージョン 2.3 で追加.

このモジュールは、 Python モジュール ("*.py", "*.py[co]") やパッケージ
を ZIP 形式のアーカイブから import できるようにします。通常、
"zipimport" を明示的に使う必要はありません; 組み込みの "import" は、
"sys.path" の要素が ZIP アーカイブへのパスを指している場合にこのモジュ
ールを自動的に使います。

普通、 "sys.path" はディレクトリ名の文字列からなるリストです。このモジ
ュールを使うと、 "sys.path" の要素に ZIP ファイルアーカイブを示す文字
列を使えるようになります。ZIP アーカイブにはサブディレクトリ構造を含め
ることができ、パッケージの import をサポートさせたり、アーカイブ内のパ
スを指定してサブディレクトリ下から import を行わせたりできます。例えば
、 "example.zip/lib/" のように指定すると、アーカイブ中の  "lib/" サブ
ディレクトリ下だけから import を行います。

ZIP アーカイブ内にはどんなファイルを置いてもかまいませんが、 import で
きるのは ".py" および ".py[co]" だけです。動的モジュール (".pyd",
".so") の ZIP import は行えません。アーカイブ内に ".py" ファイルしかな
い場合、 Python は対応する ".pyc" や ".pyo" ファイルを追加してがアーカ
イブを変更しようとはしません。つまり、ZIP アーカイブ内に ".pyc" がない
場合は、 import がやや低速になるかもしれないので注意してください。

ZIP アーカイブからロードしたモジュールに対して組み込み関数 "reload()"
を呼び出すと失敗します; "reload()" が必要になることはあまり考られない
です。なぜってそれは実行時に ZIP ファイルが置き換えられてしまうことを
暗に言っているわけですから。

アーカイブコメント付きの ZIP アーカイブは現在のところサポートされてい
ません。

参考:

  PKZIP Application Note
     ZIP ファイルフォーマットおよびアルゴリズムを作成した Phil Katz に
     よるドキュメント。

  **PEP 273** - Zip アーカイブからモジュールをインポートする
     このモジュールの実装も行った、James C. Ahlstrom による PEP です。
     Python 2.3 は PEP 273 の仕様に従っていますが、Just van Rossum の
     書いた import フックによる実装を使っています。import フックは PEP
     302 で解説されています。

  **PEP 302** - 新たなインポートフック
     このモジュールを動作させる助けになっている import フックの追加を
     提案している PEP です。

このモジュールでは例外を一つ定義しています:

exception zipimport.ZipImportError

   zipimporter オブジェクトが送出する例外です。 "ImportError" のサブク
   ラスなので、 "ImportError" としても捕捉できます。


31.4.1. zipimporter オブジェクト
================================

"zipimporter" は ZIP ファイルを import するためのクラスです。

class zipimport.zipimporter(archivepath)

   新たな zipimporter インスタンスを生成します。 *archivepath* は ZIP
   ファイルへのパスまたは ZIP ファイル中の特定のパスへのパスでなければ
   なりません。たとえば、 "foo/bar.zip/lib" という *archivepath* の場
   合、 "foo/bar.zip" という ZIP ファイルの中の "lib" ディレクトリにあ
   るモジュールを (存在するものとして) 検索します。

   *archivepath* が有効な ZIP アーカイブを指していない場合、
   "ZipImportError" を送出します。

   find_module(fullname[, path])

      *fullname* で指定されたモジュールを検索します。 *fullname* は完
      全に修飾された (ドット表記の) モジュール名でなければなりません。
      モジュールが見つかった場合には zipimporter インスタンス自体を返
      し、そうでない場合には "None" を返します。オプションの *path* 引
      数は無視されます --- この引数は importer プロトコルとの互換性を
      保つためのものです。

   get_code(fullname)

      *fullname* に指定したモジュールのコードオブジェクトを返します。
      モジュールがない場合には "ZipImportError" を送出します。

   get_data(pathname)

      *pathname* に関連付けられたデータを返します。該当するファイルが
      見つからなかった場合には "IOError" を送出します。

   get_filename(fullname)

      指定されたモジュールが import された場合、そのモジュールに設定し
      た "__file__" の値を返します。モジュールが見つからない場合、
      "ZipImportError" を送出します。

   バージョン 2.7 で追加.

   get_source(fullname)

      *fullname* で指定されたモジュールのソースコードを返します。モジ
      ュールが見つからない場合、"ZipImportError" を送出します。アーカ
      イブにはモジュールがあるもののソースコードがない場合、 "None" を
      返します。

   is_package(fullname)

      *fullname* で指定されたモジュールがパッケージの場合 "True" を返
      します。モジュールを見つけられない場合 "ZipImportError" を送出し
      ます。

   load_module(fullname)

      *fullname* で指定されたモジュールをロードします。 *fullname* は
      完全修飾された (ドット表記の) モジュール名でなければなりません。
      import 済みのモジュールを返します。モジュールがない場合には
      "ZipImportError" を送出します。

   archive

      importer に関連付けられた ZIP ファイルのファイル名です。サブパス
      は含まれません。

   prefix

      モジュールを検索する ZIP ファイル中のサブパスです。この文字列は
      ZIP ファイルのルートを指している zipimporter オブジェクトでは空
      です。

   スラッシュでつなげると、"archive" と "prefix" 属性は "zipimporter"
   コンストラクタに渡された元々の *archivepath* 引数と等しくなります。


31.4.2. 例
==========

モジュールを ZIP アーカイブから import する例を以下に示します -
"zipimport" モジュールが明示的に使われていないことに注意してください。

   $ unzip -l example.zip
   Archive:  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, 'example.zip')  # Add .zip file to front of path
   >>> import jwzthreading
   >>> jwzthreading.__file__
   'example.zip/jwzthreading.py'
