"zipimport" --- Zip アーカイブからモジュールをインポートする
************************************************************

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

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

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

普通、 "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.15 で変更: Zstandard (*zstd*) で圧縮された zip ファイルの
エントリーをサポートしました。

バージョン 3.13 で変更: ZIP64 をサポートしました。

バージョン 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" の実装
     すべてのインポーターが実装するための関連プロトコルを提供するパッ
     ケージ。

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

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

   バージョン 3.12 で変更: 3.10 で非推奨になった "find_loader()" メソ
   ッドと "find_module()" メソッドを削除しました。 代わりに
   "find_spec()" を使ってください。

   create_module(spec)

      "importlib.abc.Loader.create_module()" の実装で、"None" を返して
      デフォルトの動作を明示的に要求します。

      Added in version 3.10.

   exec_module(module)

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

      Added in version 3.10.

   find_spec(fullname, target=None)

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

      Added in version 3.10.

   get_code(fullname)

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

   get_data(pathname)

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

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

   get_filename(fullname)

      指定したモジュールをインポートした場合に "__file__" に設定される
      値を返します。 モジュールが見つからない場合は "ZipImportError"
      を送出します。

      Added in version 3.1.

   get_source(fullname)

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

   is_package(fullname)

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

   invalidate_caches()

      ZIP アーカイブ内のファイルに関する情報を保持する内部キャッシュを
      クリアします。

      Added in version 3.10.

   archive

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

   prefix

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

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


使用例
======

以下は ZIP アーカイブからモジュールをインポートする例です。
"zipimport" モジュールを明示的に使っていないことに注目してください。

   $ unzip -l example_archive.zip
   Archive:  example_archive.zip
     Length     Date   Time    Name
    --------    ----   ----    ----
        8467  01-01-00 12:30   example.py
    --------                   -------
        8467                   1 file

   >>> import sys
   >>> # モジュール検索パスの先頭にアーカイブを追加する
   >>> sys.path.insert(0, 'example_archive.zip')
   >>> import example
   >>> example.__file__
   'example_archive.zip/example.py'
