This document is for an old version of Python that is no longer supported. You should upgrade and read the Python documentation for the current stable release.

# 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