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

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

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

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

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

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

"site.main()" 関数の処理は、前部と後部からなる最大で四つまでのディレク
トリを構築するところから始まります。 前部では "sys.prefix" と
"sys.exec_prefix" を使用します; 空の前部は使われません。 後部では、1つ
目は空文字列を使い、2つ目は "lib/site-packages" (Windows) または
"lib/python*X.Y*/site-packages" (Unix と macOS) を使います。 前部-後部
の異なる組み合わせごとに、それが存在しているディレクトリを参照している
かどうかを調べ、存在している場合は "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行に
  制限することは、より複雑なものをここに入れないようにするための意図的
  な手段です。

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

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

これらのパス操作の後に、 "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

   Python 実行時のユーザの site-packages へのパスです。
   "getusersitepackages()" がまだ呼び出されていなければ "None" かもし
   れません。デフォルト値は UNIX と frameworkなしの macOS ビルドでは
   "~/.local/lib/python*X.Y*/site-packages" 、macOS framework ビルドで
   は "~/Library/Python/*X.Y*/lib/python/site-packages"、Windows では
   "*%APPDATA%*\Python\Python*XY*\site-packages" です。このディレクト
   リは site ディレクトリなので、 ここにいる ".pth" ファイルが処理され
   ます。

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". の初期化。
