"zipimport" --- Import modules from Zip archives
************************************************

**ソースコード:** Lib/zipimport.py

======================================================================

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

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

ZIP アーカイブ内にはどんなファイルを置いてもかまいませんが、インポート
は ".py" および ".pyc" ファイルにのみ呼び出されます。動的モジュール
(".pyd", ".so") の ZIP インポートは行えません。アーカイブ内に ".py" フ
ァイルしかない場合、 Python は対応する ".pyc" ファイルを追加してアーカ
イブを変更しようとはしません。つまり、 ZIP アーカイブ内に ".pyc" がな
い場合は、インポートが多少遅くなるかもしれないので注意してください。

バージョン 3.8 で変更: 以前は、アーカイブコメント付きの ZIP アーカイブ
はサポートされていませんでした。

参考:

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

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

  "importlib" - "import" の実装
     Package providing the relevant protocols for all importers to
     implement.

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

exception zipimport.ZipImportError

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


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" を送出します。

   create_module(spec)

      Implementation of "importlib.abc.Loader.create_module()" that
      returns "None" to explicitly request the default semantics.

      バージョン 3.10 で追加.

   exec_module(module)

      "importlib.abc.Loader.exec_module()" の実装です。

      バージョン 3.10 で追加.

   find_loader(fullname, path=None)

      An implementation of
      "importlib.abc.PathEntryFinder.find_loader()".

      バージョン 3.10 で非推奨: Use "find_spec()" instead.

   find_module(fullname, path=None)

      Search for a module specified by *fullname*. *fullname* must be
      the fully qualified (dotted) module name. It returns the
      zipimporter instance itself if the module was found, or "None"
      if it wasn't. The optional *path* argument is ignored---it's
      there for compatibility with the importer protocol.

      バージョン 3.10 で非推奨: Use "find_spec()" instead.

   find_spec(fullname, target=None)

      "importlib.abc.PathEntryFinder.find_spec()" の実装です。

      バージョン 3.10 で追加.

   get_code(fullname)

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

   get_data(pathname)

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

      バージョン 3.3 で変更: 以前は "IOError" が送出されました; それは
      現在 "OSError" のエイリアスです。

   get_filename(fullname)

      指定されたモジュールが import された場合、そのモジュールに設定し
      た "__file__" の値を返します。モジュールがインポートできなかった
      場合、 "ZipImportError" を送出します。

      バージョン 3.1 で追加.

   get_source(fullname)

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

   is_package(fullname)

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

   load_module(fullname)

      Load the module specified by *fullname*. *fullname* must be the
      fully qualified (dotted) module name. Returns the imported
      module on success, raises "ZipImportError" on failure.

      バージョン 3.10 で非推奨: 代わりに "exec_module()" を使用してく
      ださい。

   invalidate_caches()

      Clear out the internal cache of information about files found
      within the ZIP archive.

      バージョン 3.10 で追加.

   archive

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

   prefix

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

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


使用例
======

モジュールを 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'
