"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" 相同的值。该值将被 虚拟环境 使用。

最后，将会处理 "site" 模块并将 "site-packages" 目录添加到模块搜索路径
。 自定义搜索路径的一个常用方式是创建 "sitecustomize" 或
"usercustomize" 模块，如 "site" 模块文档所描述的那样。

备注:

  特定的命令行选项可能对路径计算造成额外的影响。请参阅 "-E", "-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" 检测。

备注:

  还有其他一些方式可以实现“虚拟环境”，本文档介绍了基于 "pyvenv.cfg" 机
  制的实现，如 "venv"。 大多数虚拟环境实现都遵循由 "venv" 所设定的模型
  ，但也可能存在与其不同的新奇实现。


_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 的相关细节。
