# `site` --- サイト固有の設定フック

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

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

Importing this module normally appends site-specific paths to the module search path and adds callables, including `help()` to the built-in namespace. However, Python startup option `-S` blocks this and this module can be safely imported with no automatic modifications to the module search path or additions to the builtins. To explicitly trigger the usual site-specific additions, call the `main()` function.

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

It starts by constructing up to four directories from a head and a tail part. For the head part, it uses `sys.prefix` and `sys.exec_prefix`; empty heads are skipped. For the tail part, it uses the empty string and then `lib/site-packages` (on Windows) or `lib/pythonX.Y[t]/site-packages` (on Unix and macOS). (The optional suffix "t" indicates the free threading build, and is appended if `"t"` is present in the `sys.abiflags` constant.) For each of the distinct head-tail combinations, it sees if it refers to an existing directory, and if so, adds it to `sys.path` and also inspects the newly added path for configuration files.

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

バージョン 3.13 で変更: On Unix, Free threading Python installations are identified by the "t" suffix in the version-specific directory name, such as `lib/python3.13t/`.

"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行に制限することは、より複雑なものをここに入れないようにするための意図的な手段です。

バージョン 3.13 で変更: `.pth` ファイルは、最初に UTF-8 で、失敗した場合は locale encoding でデコードされるようになります。

例えば、 `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`

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

## `usercustomize`

このあとで、 `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の間のミスマッチ)あるいは管理者によって、ユーザサイトディレクトリが無効になっていることを示しています。

site.USER_SITE

  Path to the user site-packages for the running Python. Can be `None` if `getusersitepackages()` hasn't been called yet. Default value is `~/.local/lib/pythonX.Y[t]/site-packages` for UNIX and non-framework macOS builds, `~/Library/Python/X.Y/lib/python/site-packages` for macOS framework builds, and `%APPDATA%\Python\PythonXY\site-packages` on Windows. The optional "t" indicates the free-threaded build. This directory is a site directory, which means that `.pth` files in it will be processed.

site.USER_BASE

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

site.main()

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

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

site.addsitedir(sitedir, known_paths=None)

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

site.getsitepackages()

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

  Added in version 3.2.

site.getuserbase()

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

  Added in version 3.2.

site.getusersitepackages()

  ユーザ固有の site パッケージのディレクトリへのパス `USER_SITE` を返します。未初期化であればこの関数は `USER_BASE` を参考にして、設定もします。 ユーザ固有の site パッケージが `sys.path` に追加されたかどうかを確認するには `ENABLE_USER_SITE` を使ってください。

  Added in version 3.2.

## コマンドラインインターフェイス

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

    $ python -m site --user-site
    /home/user/.local/lib/python3.11/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` ディレクトリ

- sys.path モジュール検索パスの初期化 -- `sys.path`. の初期化。