site — 站点特定配置挂钩

源代码： Lib/site.py

此模块在初始化期间自动导入。可以使用解释器的 -S 选项禁止自动导入。

导入此模块将向模块搜索路径追加特定于站点的路径，并添加一些内置函数，除非使用了 -S。在这种情况下，可以安全地导入此模块，而不会自动修改模块搜索路径或向内置函数添加内容。要显式触发通常的特定于站点的添加，请调用 main() 函数。

3.3 版中已更改： 导入模块过去会在使用 -S 时触发路径操作。

它首先从头部和尾部部分构建最多四个目录。对于头部部分，它使用 sys.prefix 和 sys.exec_prefix；跳过空头部。对于尾部部分，它使用空字符串，然后使用 lib/site-packages（在 Windows 上）或 lib/pythonX.Y/site-packages（在 Unix 和 macOS 上）。对于每个不同的头部尾部组合，它会查看它是否引用现有目录，如果是，则将其添加到 sys.path 中，并检查新添加的路径以查找配置文件。

3.5 版中已更改： 已移除对“site-python”目录的支持。

如果在 sys.executable 上方一个目录中存在名为“pyvenv.cfg”的文件，则 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 的文件，存在于上述四个目录之一中；其内容是添加到 sys.path 中的其他项目（每行一个）。不存在的项目绝不会添加到 sys.path 中，并且不会检查该项目是指向目录还是文件。任何项目都不会被多次添加到 sys.path 中。空行和以 # 开头的行将被跳过。以 import（后跟空格或制表符）开头的行将被执行。

注意

.pth 文件中的可执行行在每次 Python 启动时都会运行，而不管是否实际使用特定模块。因此，其影响应保持在最低限度。可执行行的主要预期目的是使相应的模块可导入（加载第三方导入挂钩，调整 PATH 等）。任何其他初始化都应该在模块实际导入时进行（如果发生）。将代码块限制为单行是一项深思熟虑的措施，目的是阻止在此处放置任何更复杂的内容。

例如，假设 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

在此之后，尝试导入名为 usercustomize 的模块，该模块可以执行任意特定于用户的自定义，如果 ENABLE_USER_SITE 为 true。此文件旨在创建在用户 site-packages 目录（见下文）中，该目录是 sys.path 的一部分，除非被 -s 禁用。如果此导入因 ImportError 或其子类异常而失败，并且异常的 name 属性等于 'usercustomize'，则会静默忽略它。

请注意，对于某些非 Unix 系统，sys.prefix 和 sys.exec_prefix 为空，并且路径操作被跳过；但是仍然尝试导入 sitecustomize 和 usercustomize。

Readline 配置

在支持 readline 的系统上，如果 Python 在 交互模式 下启动且没有 -S 选项，此模块还将导入和配置 rlcompleter 模块。默认行为是启用制表符补全，并将 ~/.python_history 用作历史记录保存文件。要禁用它，请删除（或覆盖） sys.__interactivehook__ 属性，该属性位于 sitecustomize 或 usercustomize 模块或 PYTHONSTARTUP 文件中。

3.4 版中的更改： rlcompleter 和历史记录的激活已自动完成。

模块内容

site.PREFIXES

site-packages 目录的前缀列表。

site.ENABLE_USER_SITE

显示用户 site-packages 目录状态的标志。 True 表示已启用并已添加到 sys.path。 False 表示已由用户请求禁用（使用 -s 或 PYTHONNOUSERSITE）。 None 表示已出于安全原因（用户或组 ID 与有效 ID 不匹配）或由管理员禁用。

site.USER_SITE

运行 Python 的用户站点包的路径。如果 getusersitepackages() 尚未被调用，则可以是 None。对于 UNIX 和非框架 macOS 构建，默认值为 ~/.local/lib/pythonX.Y/site-packages；对于 macOS 框架构建，默认值为 ~/Library/Python/X.Y/lib/python/site-packages；对于 Windows，默认值为 %APPDATA%\Python\PythonXY\site-packages。此目录是站点目录，这意味着将处理其中的 .pth 文件。

site.USER_BASE

用户站点包的基本目录的路径。如果 getuserbase() 尚未被调用，则可以是 None。对于 UNIX 和 macOS 非框架构建，默认值为 ~/.local；对于 macOS 框架构建，默认值为 ~/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()

返回一个包含所有全局站点包目录的列表。

在 3.2 版本中添加。

site.getuserbase()

返回用户基本目录的路径，USER_BASE。如果尚未初始化，此函数还将设置它，并遵循 PYTHONUSERBASE。

在 3.2 版本中添加。

site.getusersitepackages()

返回用户特定站点包目录的路径，USER_SITE。如果尚未初始化，此函数还将设置它，并遵循 USER_BASE。要确定用户特定的站点包是否已添加到 sys.path，应使用 ENABLE_USER_SITE。

在 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

打印用户站点包目录的路径。

如果同时给出这两个选项，将打印用户基本目录和用户站点（始终按此顺序），并用 os.pathsep 分隔。

如果给出任何选项，脚本将退出，并带有以下值之一：0（如果启用了用户站点包目录）、1（如果用户禁用了它）、2（如果出于安全原因或管理员禁用了它），以及大于 2 的值（如果出现错误）。

另请参阅