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

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


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

このモジュールをインポートすると、 -S オプションを使わない限り、サイト固有のパスをモジュール検索パスに追加し、いくつかの組み込み関数を追加します。 -S オプションを使った場合、このモジュールはモジュール検索パスの変更や組み込み関数の追加を自動で行うことはなく、安全にインポートできます。 通常のサイト固有の追加処理を明示的に起動するには、 site.main() 関数を呼んでください。

バージョン 3.3 で変更: 以前は -S を使っているときでも、モジュールをインポートするとパス変更が起動されていました。

site.main() 関数の処理は、前部と後部からなる最大で四つまでのディレクトリを構築するところから始まります。 前部では sys.prefixsys.exec_prefix を使用します; 空の前部は使われません。 後部では、1つ目は空文字列を使い、2つ目は lib/site-packages (Windows) または lib/pythonX.Y/site-packages (Unix と Macintosh) を使います。 前部-後部の異なる組み合わせごとに、それが存在しているディレクトリを参照しているかどうかを調べ、存在している場合は sys.path へ追加します。 そして、新しく追加されたパスからパス設定ファイルを検索します。

バージョン 3.5 で変更: "site-python" ディレクトリのサポートは削除されました。

"pyvenv.cfg" という名前のファイルが上で挙げたディレクトリの 1 つに存在していた場合、 sys.executable, sys.prefix, sys.exec_prefix にはそのディレクトリが設定され、 site-packages もチェックします (sys.base_prefix と sys.base_exec_prefix は常にインストールされているPythonの "実際の" プレフィックスです)。 (ブートストラップの設定ファイルである) "pyvenv.cfg" で、キー "include-system-site-packages" に "false" (大文字小文字は区別しない) 以外が設定されている場合は、 site-packages を探しにシステムレベルのプレフィックスも見に行きます; そうでない場合は見に行きません。

A path configuration file is a file whose name has the form name.pth and exists in one of the four directories mentioned above; its contents are additional items (one per line) to be added to sys.path. Non-existing items are never added to sys.path. No item is added to sys.path more than once. Blank lines and lines beginning with # are skipped. Lines starting with import (followed by space or tab) are executed.

例えば、 sys.prefixsys.exec_prefix/usr/local に設定されていると仮定します。そのときPython X.Y ライブラリは /usr/local/lib/pythonX.Y にインストールされています。ここにはサブディレクトリ /usr/local/lib/pythonX.Y/site-packages があり、その中に三つのサブディレクトリ foo, bar および spam と二つのパス設定ファイル foo.pthbar.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.prefixsys.exec_prefix は空で、パス操作は省略されます。しかし、 sitecustomizeusercustomize のインポートはそのときでも試みられます。

29.13.1. readline の設定

readline をサポートするシステムではこのモジュールは、Python を 対話モード-S オプションなしで開始した場合に rlcompleter モジュールをインポートして設定します。デフォルトの振る舞いでは、タブ補完を有効にし、履歴保存ファイルに ~/.python_history を使います。これを無効にするには、あなたの sitecustomize または usercustomize あるいは PYTHONSTARTUP ファイル内で sys.__interactivehook__ 属性を削除 (または上書き) してください。 (---訳注: site モジュールは __interactivehook__ に readline 設定関数を設定後に sitecustomize 等のユーザ設定を実行します。 __interactivehook__ のチェックが行われるのは site モジュール実行の後です。 ---)

バージョン 3.4 で変更: rlcompleter とhistory のアクティベーションが自動で行われるようになりました。

29.13.2. モジュールの内容

site.PREFIXES

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

site.ENABLE_USER_SITE

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

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 ファイルが処理されます。

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 も参照してください。

site.main()

モジュール検索パスに標準のサイト固有ディレクトリを追加します。この関数は、Python インタプリタが -S で開始されていない限り、このモジュールインポート時に自動的に呼び出されます。

バージョン 3.3 で変更: この関数は以前は無条件に呼び出されていました。

site.addsitedir(sitedir, known_paths=None)

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

site.getsitepackages()

全てのグローバルな site-packages ディレクトリのリストを返します。

バージョン 3.2 で追加.

site.getuserbase()

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

バージョン 3.2 で追加.

site.getusersitepackages()

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

バージョン 3.2 で追加.

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

$ python3 -m site --user-site
/home/user/.local/lib/python3.3/site-packages

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

--user-base

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

--user-site

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

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

If any option is given, the script will exit with one of these values: O if the user site-packages directory is enabled, 1 if it was disabled by the user, 2 if it is disabled for security reasons or by an administrator, and a value greater than 2 if there is an error.

参考

PEP 370 -- ユーザごとの site-packages ディレクトリ