バージョン 2.3 で追加.
このモジュールはパッケージを操作する関数を提供します。
パッケージを構成するモジュールのサーチパスを拡張します。パッケージの __init__.py で次のように書くことを意図したものです。
from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)
上記はパッケージの __path__ に sys.path の全ディレクトリのサブディレクトリとしてパッケージ名と同じ名前を追加します。 これは1つの論理的なパッケージの異なる部品を複数のディレクトリに分けて配布したいときに役立ちます。
同時に *.pkg の * の部分が name 引数に指定された文字列に一致するファイルの検索もおこないます。この機能は import で始まる特別な行がないことを除き *.pth ファイルに似ています (site の項を参照)。 *.pkg は重複のチェックを除き、信頼できるものとして扱われます。 *.pkg ファイルの中に見つかったエントリはファイルシステム上に実在するか否かを問わず、そのまますべてパスに追加されます。(このような仕様です。)
入力パスがリストでない場合(フリーズされたパッケージのとき)は何もせずにリターンします。入力パスが変更されていなければ、アイテムを末尾に追加しただけのコピーを返します。
sys.path はシーケンスであることが前提になっています。 sys.path の要素の内、実在するディレクトリを指す(ユニコードまたは8ビットの)文字列となっていないものは無視されます。ファイル名として使ったときにエラーが発生する sys.path のユニコード要素がある場合、 この関数(os.path.isdir() を実行している行)で例外が発生する可能性があります。
パッケージからリソースを取得します。
この関数は PEP 302 ローダーの get_data() API のラッパーです。 package 引数は標準的なモジュール形式 (foo.bar) のパッケージ名でなければなりません。 resource 引数は / をパス区切りに使った相対ファイル名の形式です。 親ディレクトリを .. としたり、ルートからの (/ で始まる) 名前を使うことはできません。
この関数が返すのは指定されたリソースの内容であるバイナリ文字列です。
ファイルシステム中に位置するパッケージで既にインポートされているものに対しては、 次と大体同じです:
d = os.path.dirname(sys.modules[package].__file__)
data = open(os.path.join(d, resource), 'rb').read()
パッケージを見出せなかったりロードできなかったり、あるいは get_data() をサポートしない PEP 302 ローダーを使ったりした場合は、 None が返されます。