28.14. site --- サイト固有の設定フック

ソースコード: Lib/site.py

このモジュールは初期化中に自動的にインポートされます。 自動インポートはインタプリタの -S オプションで禁止できます。

このモジュールをインポートすることで、サイト固有のパスをモジュール検索パスへ付け加え、また、いくつかのビルトインを追加します。

サイト固有のパスは、前部と後部から構築される最大で四つまでのディレクトリから始めます。 前部には、 sys.prefix と sys.exec_prefix を使用します。空の前部は省略されます。 後部には、まず空文字列を使い、次に lib/site-packages (Windows) または lib/pythonX.Y/site-packages, そして lib/site-python (Unix と Macintosh)を使います。 前部-後部の組み合わせのそれぞれに対して、それが存在するディレクトリを参照しているかどうかを調べ、もしそうならば sys.path へ追加します。そして、 パス設定ファイルを新しく追加されたパスからも検索します。

パス設定ファイルは name.pth という形式の名前をもつファイルで、上の4つのディレクトリのひとつにあります。その内容は sys.path に追加される追加項目(一行に一つ)です。存在しない項目は sys.path へは決して追加されませんが、項目がファイルではなくディレクトリを参照しているかどうかはチェックされません。項目が sys.path へ二回以上追加されることはありません。空行と # で始まる行は読み飛ばされます。 import で始まる(そしてその後ろにスペースかタブが続く)行は実行されます。

バージョン 2.6 で変更: import キーワードの後ろにスペースかタブが必要になりました。

例えば、 sys.prefix と sys.exec_prefix が /usr/local に設定されていると仮定します。そのときPython X.Y ライブラリは /usr/local/lib/pythonX.Y にインストールされています。ここにはサブディレクトリ /usr/local/lib/pythonX.Y/site-packages があり、その中に三つのサブディレクトリ foo, bar および spam と二つのパス設定ファイル foo.pth と bar.pth をもつと仮定します。 foo.pth には以下のものが記載されていると想定してください:

# foo package configuration

foo
bar
bletch

また、 bar.pth には:

# bar package configuration

bar

が記載されているとします。そのとき、次のバージョンごとのディレクトリが sys.path へこの順番で追加されます:

/usr/local/lib/pythonX.Y/site-packages/bar
/usr/local/lib/pythonX.Y/site-packages/foo

bletch は存在しないため省略されるということに注意してください。 bar ディレクトリは foo ディレクトリの前に来ます。なぜなら、 bar.pth がアルファベット順で foo.pth の前に来るからです。また、 spam はどちらのパス設定ファイルにも記載されていないため、省略されます。

これらのパス操作の後に、 sitecustomize という名前のモジュールをインポートしようします。そのモジュールは任意のサイト固有のカスタマイゼーションを行うことができます。典型的にはこれはシステム管理者によって site-packages ディレクトリに作成されます。 ImportError 例外が発生してこのインポートに失敗した場合は、何も表示せずに無視されます。Windows での pythonw.exe (IDLE を開始するとデフォルトで使われます)のような、Python が出力ストリームが利用出来ない状態で開始された場合, 　sitecustomize から試みられた出力は無視されます。 ImportError 以外のあらゆる例外は黙殺され、そしてそれはおそらく不可思議な失敗にみえるでしょう。

このあとで、 ENABLE_USER_SITE が真であれば、任意のユーザ固有のカスタマイズを行うことが出来る usercustomize と名付けられたモジュールのインポートが試みられます。このファイルはユーザの site-packages ディレクトリ(下記参照)に作られることを意図していて、その場所はオプション -s によって無効にされない限りは sys.path に含まれます。ImportError は黙って無視されます。

いくつかの非Unixシステムでは、 sys.prefix と sys.exec_prefix は空で、パス操作は省略されます。しかし、 sitecustomize と usercustomize のインポートはそのときでも試みられます。

site.PREFIXES

siteパッケージディレクトリのprefixのリスト。

バージョン 2.6 で追加.

site.ENABLE_USER_SITE

ユーザーサイトディレクトリのステータスを示すフラグ。 True の場合、ユーザーサイトディレクトリが有効で sys.path に追加されていることを意味しています。 False の場合、ユーザによるリクエスト(オプション -s か PYTHONNOUSERSITE)によって、 None の場合セキュリティ上の理由(ユーザまたはグループIDと実効IDの間のミスマッチ)あるいは管理者によって、ユーザーサイトディレクトリが無効になっていることを示しています。ユーザーサイトディレクトリのステータスを示すフラグ。 True の場合、ユーザーサイトディレクトリが有効で sys.path に追加されていることを意味しています。 False の場合、ユーザによるリクエスト(オプション -s か PYTHONNOUSERSITE)によって、 None の場合セキュリティ上の理由(ユーザまたはグループIDと実効IDの間のミスマッチ)あるいは管理者によって、ユーザーサイトディレクトリが無効になっていることを示しています。

バージョン 2.6 で追加.

site.USER_SITE

Python 実行時のユーザの site-packages へのパスです。 getusersitepackages() がまだ呼び出されていなければ None かもしれません。デフォルト値は UNIX と frameworkなしの Mac OS X ビルドでは ~/.local/lib/pythonX.Y/site-packages 、Mac framework ビルドでは ~/Library/Python/X.Y/lib/python/site-packages、Windows では %APPDATA%\Python\PythonXY\site-packages です。このディレクトリは site ディレクトリなので、 ここにいる .pth ファイルが処理されます。

バージョン 2.6 で追加.

site.USER_BASE

ユーザの site-packages のベースとなるディレクトリへのパスです。 getuserbase() がまだ呼び出されていなければ None かもしれません。デフォルト値は UNIX と frameworkなしの Mac OS X ビルドでは ~/.local 、Mac framework ビルドでは ~/Library/Python/X.Y 、Windows では %APPDATA%\Python です。この値は Distutils が、スクリプト、データファイル、Python モジュールなどのインストール先のディレクトリを user installation scheme で計算するのに使われます。 PYTHONUSERBASE も参照してください。

バージョン 2.6 で追加.

site.addsitedir(sitedir, known_paths=None)

sys.path にディレクトリを追加し、その .pth ファイル群を処理します。典型的には sitecustomize か usercustomize 内で使われます(上述)。

site.getsitepackages()

全てのグローバルな site-packages ディレクトリ(と、おそらく site-python も)のリストを返します。

バージョン 2.7 で追加.

site.getuserbase()

ユーザのベースディレクトリへのパス USER_BASE を返します。未初期化であればこの関数は PYTHONUSERBASE を参考にして、設定もします。

バージョン 2.7 で追加.

site.getusersitepackages()

ユーザのベースディレクトリへのパス USER_SITE を返します。未初期化であればこの関数は PYTHONNOUSERSITE と USER_BASE を参考にして、設定もします。

バージョン 2.7 で追加.

site モジュールはユーザディレクトリをコマンドラインから得る手段も提供しています:

$ python -m site --user-site
/home/user/.local/lib/python2.7/site-packages

引数なしで呼び出された場合、sys.path の中身を表示し、続けて USER_BASE とそのディレクトリが存在するかどうか、 USER_SITE とそのディレクトリが存在するかどうか、最後に ENABLE_USER_SITE の値を、標準出力に出力します。

--user-base

ユーザのベースディレクトリを表示します。

--user-site

ユーザの site-packages ディレクトリを表示します。

両方のオプションが指定された場合、ユーザのベースとユーザの site が(常にこの順序で) os.pathsep 区切りで表示されます。

いずれかのオプションが与えられた場合に、このスクリプトは次のいずれかの終了コードで終了します: ユーザの site-packages が有効ならば 0 、ユーザにより無効にされていれば 1 、セキュリティ的な理由あるいは管理者によって無効にされている場合 2 、そして何かエラーがあった場合は 2 より大きな値。

参考

PEP 370 -- Per user site-packages directory