
:mod:`pkgutil` --- パッケージ拡張ユーティリティ
===============================================

.. module:: pkgutil
   :synopsis: パッケージの拡張をサポートするユーティリティです。


.. versionadded:: 2.3

このモジュールはパッケージを操作する関数を提供します。


.. function:: extend_path(path, name)

   パッケージを構成するモジュールのサーチパスを拡張します。パッケージの :file:`__init__.py` で次のように書くことを意図したものです。 ::

      from pkgutil import extend_path
      __path__ = extend_path(__path__, __name__)

   上記はパッケージの ``__path__`` に ``sys.path`` の全ディレクトリ\
   のサブディレクトリとしてパッケージ名と同じ名前を追加します。
   これは1つの論理的なパッケージの異なる部品を複数のディレクトリに分けて配布したい\
   ときに役立ちます。

   同時に :file:`\*.pkg` の ``*`` の部分が *name* 引数に指定された文字列に一致するファイルの検索もおこないます。この機能は
   ``import`` で始まる特別な行がないことを除き :file:`\*.pth` ファイルに似ています (:mod:`site`
   の項を参照)。 :file:`\*.pkg` は重複のチェックを除き、信頼できるものとして扱われます。 :file:`\*.pkg` ファイルの中に見つかったエ\
   ントリはファイルシステム上に実在するか否かを問わず、そのまますべてパスに追加されます。(このような仕様です。)

   入力パスがリストでない場合(フリーズされたパッケージのとき)は何もせずにリターンします。入力パスが変更されていなければ、アイテムを末尾に追加し\
   ただけのコピーを返します。

   ``sys.path`` はシーケンスであることが前提になっています。 ``sys.path`` の要素の内、実在するディレクトリを指す(ユニコードまた\
   は8ビットの)文字列となっていないものは無視されます。ファイル名として使ったときにエラーが発生する ``sys.path`` のユニコード要素がある場合、
   この関数(:func:`os.path.isdir` を実行している行)で例外が発生する可能性があります。

.. function:: get_data(package, resource)

   パッケージからリソースを取得します。

   この関数は PEP 302 ローダーの :func:`get_data` API のラッパーです。
   package 引数は標準的なモジュール形式 (foo.bar) のパッケージ名でなければなりません。
   resource 引数は ``/`` をパス区切りに使った相対ファイル名の形式です。
   親ディレクトリを ``..`` としたり、ルートからの (``/`` で始まる) 名前を使うことはできません。

   この関数が返すのは指定されたリソースの内容であるバイナリ文字列です。

   ファイルシステム中に位置するパッケージで既にインポートされているものに対しては、
   次と大体同じです::

       d = os.path.dirname(sys.modules[package].__file__)
       data = open(os.path.join(d, resource), 'rb').read()

   パッケージを見出せなかったりロードできなかったり、あるいは :func:`get_data`
   をサポートしない PEP 302 ローダーを使ったりした場合は、 None が返されます。

.. TODO: マークアップが足りていない。もっとも原文からそうだから、まずはバグ報告。
   --> Issue8851
