"sys.path" モジュール検索パスの初期化
*************************************

モジュール検索パスは Python の開始時に初期化されます。このモジュール検
索パスは、 "sys.path" でアクセス可能です。

実行するスクリプトがある場合、モジュール検索パスの最初の項目は、そのス
クリプトがあるディレクトリです。 そうでなければ最初の項目はカレントデ
ィレクトリです。 対話型シェル、"-c" コマンド、"-m" モジュールを実行す
る場合がこれに当たります。

"PYTHONPATH" 環境変数は、検索パスにディレクトリを追加するためによく使
われます。 この環境変数が見つかると、その内容をモジュール検索パスに追
加します。

注釈:

  "PYTHONPATH" は、インストールされているすべての Python のバージョン
  と環境に影響します。 シェルのプロファイルやグローバルな環境変数で設
  定する場合は注意してください。 後述するように、"site" モジュールでは
  より細かな方法で設定できます。

次に、標準の Python モジュールと、それらが依存する *拡張モジュール* を
含むディレクトリを追加します。 拡張モジュールは Windows では ".pyd" フ
ァイル、ほかのプラットフォームでは ".so" ファイルです。 プラットフォー
ムに依存しない Python モジュールのあるディレクトリを "prefix"、拡張モ
ジュールのあるディレクトリを "exec_prefix" と呼びます。

"PYTHONHOME" 環境変数で "prefix" と "exec_prefix" の場所を設定できます
。 設定されていなければ、Python 実行ファイルを起点に、目印となる各種の
ファイルやディレクトリを探して、これらのディレクトリを特定します。 シ
ンボリックリンクはたどるため、検索の起点は Python 実行ファイルの実際の
場所になります。 Python 実行ファイルの場所を "home" と呼びます。

"home" が決まると、まず "python*majorversion**minorversion*.zip"
("python311.zip") を探して "prefix" ディレクトリを特定します。 Windows
では "home" 内を探し、Unix では "lib" 内にアーカイブがあると想定します
。 アーカイブが存在しなくても、想定される zip アーカイブの場所はモジュ
ール検索パスに追加されます。 アーカイブが見つからなければ、Windows の
Python は "Lib\os.py" を探して "prefix" の検索を続けます。 Unix の
Python は "lib/python*majorversion*.*minorversion*/os.py"
("lib/python3.11/os.py") を探します。 Windows では "prefix" と
"exec_prefix" は同じですが、ほかのプラットフォームでは
"lib/python*majorversion*.*minorversion*/lib-dynload" ("lib/python3.11
/lib-dynload") を探し、"exec_prefix" を特定する基準にします。 プラット
フォームによっては "lib" が "lib64" や別の値になる場合があります。
"sys.platlibdir" と "PYTHONPLATLIBDIR" を参照してください。

見つかった "prefix" と "exec_prefix" は、それぞれ "sys.base_prefix" と
"sys.base_exec_prefix" で取得できます。

"PYTHONHOME" が設定されておらず、メインの実行ファイルと同じディレクト
リか、その親ディレクトリに "pyvenv.cfg" が見つかると、 "sys.prefix" と
"sys.exec_prefix" は "pyvenv.cfg" のあるディレクトリに設定されます。
そうでなければ、それぞれ "sys.base_prefix" と "sys.base_exec_prefix"
と同じ値になります。 これは 仮想環境 で利用されます。

最後に "site" モジュールを処理し、"site-packages" ディレクトリをモジュ
ール検索パスに追加します。 "PYTHONUSERBASE" 環境変数はユーザーの site-
packages を探す場所を制御し、"PYTHONNOUSERSITE" 環境変数はユーザーの
site-packages の検索を完全に無効にします。 検索パスをカスタマイズする
一般的な方法は、"site" モジュールのドキュメントで説明されているように
、"sitecustomize" モジュールや "usercustomize" モジュールを作成するこ
とです。

注釈:

  コマンドラインオプション "-E"、"-P"、"-I"、"-S"、"-s" もパスの算出に
  影響します。 詳しくは各オプションのドキュメントを参照してください。

バージョン 3.14 で変更: "sys.prefix" と "sys.exec_prefix" は、パスの初
期化時に "pyvenv.cfg" のあるディレクトリに設定されるようになりました。
以前は "site" が行っていたため、"-S" の影響を受けていました。


仮想環境
========

仮想環境は、そのプレフィックスに "pyvenv.cfg" ファイルを置きます。 こ
れにより、"sys.prefix" と "sys.exec_prefix" は基となるインストール先で
はなく、仮想環境を指します。

基となるインストール先の "prefix" と "exec_prefix" は、
"sys.base_prefix" と "sys.base_exec_prefix" で取得できます。

"pyvenv.cfg" は仮想環境を識別する目印として使われるだけでなく、"site"
の初期化の設定にも使えます。 "site" の 仮想環境のドキュメント を参照し
てください。

注釈:

  "PYTHONHOME" は "pyvenv.cfg" の検出より優先されます。

注釈:

  「仮想環境」を実装する方法はほかにもあります。 ここで説明するのは
  "venv" などの "pyvenv.cfg" の仕組みに基づく実装で、多くの仮想環境の
  実装がこの方式に従っています。


_pth ファイル
=============

"sys.path" を完全に上書きするには、共有ライブラリや実行ファイルと同じ
名前の "._pth" ファイル ("python._pth" や "python311._pth") を作成しま
す。 Windows では共有ライブラリのパスは常に分かりますが、ほかのプラッ
トフォームでは取得できない場合があります。 "._pth" ファイルでは、
"sys.path" に追加するパスを 1 行に 1 つずつ指定します。 共有ライブラリ
名に基づくファイルは、実行ファイル名に基づくファイルより優先されます。
これにより、必要ならランタイムを読み込むあらゆるプログラムのパスを制限
できます。

ファイルが存在したときは、全てのレジストリと環境変数は無視され、隔離モ
ードになり、そのファイルに "import site" と指定していない限りは "site"
はインポートされません。 空行と "#" で始まる行は無視されます。 それぞ
れのパスには絶対パスか、このファイルの場所を基準とした相対パスを指定で
きます。 "site" 以外のインポート文は許可されておらず、任意のコードも書
けません。

"import site" を指定したときは、(アンダースコアが前に付かない) ".pth"
ファイルは "site" モジュールにより通常通り処理されることに注意してくだ
さい。


埋め込みの Python
=================

Python が他のアプリケーションに埋め込まれている場合は、
"Py_InitializeFromConfig()" と "PyConfig" 構造体が Python の初期化に使
用可能です。パス固有の詳細は、 Python のパス設定 で説明されています。

参考:

  * Windows の詳細についてのメモは、 モジュールの検索 を参照。

  * Unix の詳細は、 Unix プラットフォームで Python を使う を参照。
