site — 站点特定的配置钩子

源代码: Lib/site.py

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

导入此模块通常会将特定于站点的路径附加到模块搜索路径，并添加 可调用对象，包括 help() 到内置命名空间。但是，Python 启动选项 -S 会阻止此操作，并且可以安全地导入此模块，而无需对模块搜索路径进行自动修改或添加到内置对象。要显式触发通常的站点特定添加，请调用 main() 函数。

在 3.3 版本中变更: 即使在使用 -S 时，导入该模块也会触发路径操作。

它首先从头部和尾部构造最多四个目录。对于头部，它使用 sys.prefix 和 sys.exec_prefix；跳过空头部。对于尾部，它使用空字符串，然后使用 lib/site-packages (在 Windows 上) 或 lib/pythonX.Y[t]/site-packages (在 Unix 和 macOS 上)。(可选后缀 “t” 表示 自由线程 构建，如果 sys.abiflags 常量中存在 "t"，则会附加该后缀。) 对于每个不同的头尾组合，它会查看是否引用现有目录，如果是，则将其添加到 sys.path，还会检查新添加的路径中的配置文件。

在 3.5 版本中变更: 已删除对 “site-python” 目录的支持。

在 3.13 版本中变更: 在 Unix 上，自由线程 Python 安装通过版本特定目录名称中的 “t” 后缀来标识，例如 lib/python3.13t/。

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

注意

.pth 文件中的可执行行在每次 Python 启动时运行，无论是否实际使用特定模块。因此，应将其影响保持在最低限度。可执行行的主要目的是使相应的模块可导入 (加载第三方导入钩子，调整 PATH 等)。任何其他初始化都应该在模块实际导入时执行，如果并且当它发生时。将代码块限制为单行是一种有意的措施，目的是阻止在此处放置更复杂的内容。

在 3.13 版本中变更: .pth 文件现在首先由 UTF-8 解码，如果失败，则由 区域设置编码 解码。

例如，假设 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 模块。默认行为是启用 Tab 补全，并使用 ~/.python_history 作为历史记录保存文件。要禁用它，请在你的 sitecustomize 或 usercustomize 模块或者你的 PYTHONSTARTUP 文件中删除（或覆盖）sys.__interactivehook__ 属性。

在 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 的用户 site-packages 目录的路径。如果尚未调用 getusersitepackages()，则可以为 None。对于 UNIX 和非框架 macOS 构建，默认值为 ~/.local/lib/pythonX.Y[t]/site-packages；对于 macOS 框架构建，默认值为 ~/Library/Python/X.Y/lib/python/site-packages；对于 Windows，默认值为 %APPDATA%\Python\PythonXY\site-packages。可选的 “t” 表示自由线程构建。此目录是一个 site 目录，这意味着将处理其中的 .pth 文件。

site.USER_BASE

用户 site-packages 的基本目录的路径。如果尚未调用 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()

返回包含所有全局 site-packages 目录的列表。

3.2 版本新增。

site.getuserbase()

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

3.2 版本新增。

site.getusersitepackages()

返回用户特定的 site-packages 目录的路径，即 USER_SITE。如果尚未初始化，此函数还会设置它，并尊重 USER_BASE。要确定是否已将用户特定的 site-packages 添加到 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

打印用户 site-packages 目录的路径。

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

如果给出了任何选项，脚本将以以下值之一退出：如果用户站点包目录已启用，则为 0；如果该目录被用户禁用，则为 1；如果由于安全原因或被管理员禁用，则为 2；如果出现错误，则为大于 2 的值。

另请参阅