site --- サイト固有の設定フック¶
ソースコード: Lib/site.py
このモジュールは初期化中に自動的にインポートされます。 自動インポートはインタプリタの -S オプションで禁止できます。
このモジュールをインポートすると、 -S オプションを使わない限り、サイト固有のパスをモジュール検索パスに追加し、いくつかの組み込み関数を追加します。
-S オプションを使った場合、このモジュールはモジュール検索パスの変更や組み込み関数の追加を自動で行うことはなく、安全にインポートできます。
通常のサイト固有の追加処理を明示的に起動するには、 site.main() 関数を呼んでください。
バージョン 3.3 で変更: 以前は -S を使っているときでも、モジュールをインポートするとパス変更が起動されていました。
site.main() 関数の処理は、前部と後部からなる最大で四つまでのディレクトリを構築するところから始まります。
前部では sys.prefix と sys.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" に "true" (大文字小文字は区別しない) 以外が設定されている場合は、 site-packages を探しにシステムレベルのプレフィックスも見に行きません; そうでない場合は見に行きます。
パス設定ファイルは name.pth という形式の名前をもつファイルで、上の4つのディレクトリのひとつにあります。その内容は sys.path に追加される追加項目(一行に一つ)です。存在しない項目は sys.path へは決して追加されませんが、項目がファイルではなくディレクトリを参照しているかどうかはチェックされません。項目が sys.path へ二回以上追加されることはありません。空行と # で始まる行は読み飛ばされます。 import で始まる(そしてその後ろにスペースかタブが続く)行は実行されます。
注釈
.pth ファイル内の実行可能な行は、特定のモジュールが実際に使用されるかどうかに関係なく、Pythonの起動時に毎回実行されます。したがって、その影響は最小限に抑えられるべきです。実行可能な行の主な目的は、対応するモジュールをインポート可能にすることです(サードパーティ製インポートフックのロード、 PATH の調整など)。その他の初期化は、モジュールが実際にインポートされたときに行われます。コードのチャンクを1行に制限することは、より複雑なものをここに入れないようにするための意図的な手段です。
例えば、 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 またはそのサブクラス例外で失敗し、例外の name 属性が 'sitecustomize' に等しい場合は、何も表示せずに無視されます。Pythonが出力ストリームを利用できない状態で起動された場合、Windowsでは pythonw.exe (IDLEを開始するとデフォルトで使われます)のような、mod:sitecustomize から試みられた出力は無視されます。その他の例外は黙殺され、そしてそれはおそらく不可思議な失敗にみえるでしょう。
このあとで、 ENABLE_USER_SITE が真であれば、任意のユーザ固有のカスタマイズを行うことが出来る usercustomize と名付けられたモジュールのインポートが試みられます。このファイルはユーザの site-packages ディレクトリ(下記参照)に作られることを意図していて、その場所はオプション -s によって無効にされない限りは sys.path に含まれます。このインポートが ImportError またはそのサブクラス例外で失敗し、例外の name 属性が 'usercustomize' と等しい場合、それは黙って無視されます。
いくつかの非Unixシステムでは、 sys.prefix と sys.exec_prefix は空で、パス操作は省略されます。しかし、 sitecustomize と usercustomize のインポートはそのときでも試みられます。
readline の設定¶
readline をサポートするシステムではこのモジュールは、Python を 対話モード で -S オプションなしで開始した場合に rlcompleter モジュールをインポートして設定します。デフォルトの振る舞いでは、タブ補完を有効にし、履歴保存ファイルに ~/.python_history を使います。これを無効にするには、あなたの sitecustomize または usercustomize あるいは PYTHONSTARTUP ファイル内で sys.__interactivehook__ 属性を削除 (または上書き) してください。 (---訳注: site モジュールは __interactivehook__ に readline 設定関数を設定後に sitecustomize 等のユーザ設定を実行します。 __interactivehook__ のチェックが行われるのは site モジュール実行の後です。 ---)
バージョン 3.4 で変更: rlcompleter とhistory のアクティベーションが自動で行われるようになりました。
モジュールの内容¶
-
site.PREFIXES¶ siteパッケージディレクトリのprefixのリスト。
-
site.ENABLE_USER_SITE¶ ユーザサイトディレクトリのステータスを示すフラグ。
Trueの場合、ユーザサイトディレクトリが有効でsys.pathに追加されていることを意味しています。Falseの場合、ユーザによるリクエスト(オプション-sかPYTHONNOUSERSITE)によって、Noneの場合セキュリティ上の理由(ユーザまたはグループIDと実効IDの間のミスマッチ)あるいは管理者によって、ユーザサイトディレクトリが無効になっていることを示しています。ユーザサイトディレクトリのステータスを示すフラグ。Trueの場合、ユーザサイトディレクトリが有効でsys.pathに追加されていることを意味しています。Falseの場合、ユーザによるリクエスト(オプション-sかPYTHONNOUSERSITE)によって、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ファイル群を処理します。典型的にはsitecustomizeかusercustomize内で使われます(上述)。
-
site.getsitepackages()¶ 全てのグローバルな site-packages ディレクトリのリストを返します。
バージョン 3.2 で追加.
-
site.getuserbase()¶ ユーザのベースディレクトリへのパス
USER_BASEを返します。未初期化であればこの関数はPYTHONUSERBASEを参考にして、設定もします。バージョン 3.2 で追加.
-
site.getusersitepackages()¶ ユーザ固有の site パッケージのディレクトリへのパス
USER_SITEを返します。未初期化であればこの関数はUSER_BASEを参考にして、設定もします。 ユーザ固有の site パッケージがsys.pathに追加されたかどうかを確認するにはENABLE_USER_SITEを使ってください。バージョン 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 区切りで表示されます。
いずれかのオプションが与えられた場合に、このスクリプトは次のいずれかの終了コードで終了します: ユーザの site-packages が有効ならば 0 、ユーザにより無効にされていれば 1 、セキュリティ的な理由あるいは管理者によって無効にされている場合 2 、そして何かエラーがあった場合は 2 より大きな値。
参考
PEP 370 -- ユーザごとの site-packages ディレクトリ