"sys.path" 模块搜索路径的初始化
*******************************

模块搜索路径是在 Python 启动时被初始化的。这个模块搜索路径可通过
"sys.path" 来访问。

模块搜索路径的第一个条目是包含输入脚本的目录，如果存在输入脚本的话。否
则，第一个条目将是当前目录，当执行交互式 shell, "-c" 命令，或 "-m" 模
块时都属于这种情况。

"PYTHONPATH" 环境变量经常被用于将目录添加到搜索路径。如果发现了该环境
变量则其内容将被添加到模块搜索路径中。

备注:

  "PYTHONPATH" 将影响所有已安装的 Python 版本/环境。在你的 shell 用户
  配置或全局环境变量中设置它时需要小心谨慎。 "site" 模块提供了下文所述
  的更细微的技巧。

随后加入的条目是包含标准 Python 模块以及这些模块所依赖的任何
*extension module* 的目录。扩展模块在 Windows 上为 ".pyd" 文件而在其他
平台上则为 ".so" 文件。独立于平台的 Python 模块的目录称为 "prefix"。扩
展模块的目录称为 "exec_prefix"。

"PYTHONHOME" 环境变量可以被用于设置 "prefix" 和 "exec_prefix" 的位置。
在其他情况下这些目录将使用 Python 可执行文件作为起始点来确定然后再查找
几处 '地标' 文件和目录。 请注意任何符号链接也会被追踪解析以便使用实际
的 Python 可执行文件位置作为搜索起始点。这个 Python 可执行文件位置被称
为 "home".

一旦确定了 "home"，则 "prefix" 目录将通过首先查找
"python*majorversion**minorversion*.zip" ("python311.zip") 来找到。在
Windows 上将会到 "home" 中搜索 zip 归档而在 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" 相同的值。该值将被 虚拟环境 使用。

Finally, the "site" module is processed and "site-packages"
directories are added to the module search path. A common way to
customize the search path is to create "sitecustomize" or
"usercustomize" modules as described in the "site" module
documentation.

备注:

  Certain command line options may further affect path calculations.
  See "-E", "-I", "-s" and "-S" for further details.

在 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" 检测。

备注:

  There are other ways how "virtual environments" could be
  implemented, this documentation refers implementations based on the
  "pyvenv.cfg" mechanism, such as "venv". Most virtual environment
  implementations follow the model set by "venv", but there may be
  exotic implementations that diverge from it.


_pth 文件
=========

若要完全覆盖 "sys.path" 则请创建一个与共享库或可执行文件
("python._pth" 或 "python311._pth") 同名的 "._pth" 文件。共享库路径在
Windows 上始终是已知的，但这在其他平台上也许会不可用。 请在 "._pth" 文
件中为添加到 "sys.path" 的每个路径指定对应的一行。 基于共享库名称的文
件会覆盖基于可执行文件的对应文件，这允许在必要时为任何加载运行时的程序
限制路径。

当文件存在时，将忽略所有注册表和环境变量，启用隔离模式，并且：除非文件
中的一行指定 "import site"，否则不会导入 "site"。空白路径和以 "#" 开头
的行将被忽略。每个路径可以是绝对的或相对于文件的位置。不允许使用除
"site" 以外的导入语句，并且不能指定任意代码。

请注意，当指定 "import site" 时，".pth" 文件（没有前导下划线）将由
"site" 模块正常处理。


嵌入式 Python
=============

如果 Python 被嵌入其他应用程序中则 "Py_InitializeFromConfig()" 和
"PyConfig" 结构体可被用来初始化 Python。路径专属的细节描述见 Python 路
径配置。

参见:

  * 查找模块 了解更多有关 Windows 的细节说明。

  * 在类Unix环境下使用Python 了解 Unix 的相关细节。
