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

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

======================================================================

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

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

サイト固有のパスは、前部と後部から構築される最大で四つまでのディレクト
リから始めます。 前部には、 "sys.prefix" と "sys.exec_prefix" を使用し
ます。空の前部は省略されます。 後部には、まず空文字列を使い、次に "lib
/site-packages" (Windows) または "lib/python*X.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/python*X.Y*" にインストールされています。ここにはサブ
ディレクトリ "/usr/local/lib/python*X.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/python*X.Y*/site-packages" 、Mac framework ビルド
   では "~/Library/Python/*X.Y*/lib/python/site-packages"、Windows で
   は "*%APPDATA%*\Python\Python*XY*\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" 区切りで表示されます。

If any option is given, the script will exit with one of these values:
"0" 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** -- Per user site-packages directory
