\section{\module{pkgutil} ---
         パッケージ拡張ユーティリティ}

\declaremodule{standard}{pkgutil}
\modulesynopsis{パッケージの拡張をサポートするユーティリティです。}

\versionadded{2.3}

このモジュールは次の単一の関数を提供します。

\begin{funcdesc}{extend_path}{path, name}
  パッケージを構成するモジュールのサーチパスを拡張します。
  パッケージの \file{__init__.py} で次のように書くことを意図したもので
  す。

\begin{verbatim}
from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)
\end{verbatim}

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

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

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

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

\end{funcdesc}
