site — 站点特定的配置钩子 — Python 文档
site — 站点特定的配置钩子
该模块在初始化时自动导入。 使用解释器的-S选项可以抑制自动导入。
导入此模块会将特定于站点的路径附加到模块搜索路径并添加一些内置函数,除非使用了 -S。 在这种情况下,可以安全地导入该模块,而无需自动修改模块搜索路径或添加内置函数。 要显式触发通常的站点特定添加,请调用 site.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”目录的支持。
如果一个名为“pyvenv.cfg”的文件存在于 sys.executable 之上的一个目录中,则 sys.prefix 和 sys.exec_prefix 被设置为该目录,并且还会检查站点包(sys.base_prefix 和 sys.base_exec_prefix 将始终是Python 安装的“真实”前缀)。 如果“pyvenv.cfg”(引导程序配置文件)包含键“include-system-site-packages”设置为“true”以外的任何值(不区分大小写),则不会在系统级前缀中搜索 site-包裹; 否则他们会的。
路径配置文件是名称为name.pth
形式的文件,存在于上述四个目录之一中; 它的内容是要添加到 sys.path
的附加项目(每行一个)。 不存在的项目永远不会添加到 sys.path
,并且不会检查该项目是指目录而不是文件。 没有项目被多次添加到 sys.path
。 空白行和以 #
开头的行将被跳过。 执行以 import
(后跟空格或制表符)开头的行。
笔记
.pth
文件中的可执行行在每次 Python 启动时运行,无论是否实际使用特定模块。 因此,其影响应保持在最低限度。 可执行行的主要目的是使相应的模块可导入(加载第 3 方导入钩子,调整 PATH
等)。 任何其他初始化都应该在模块的实际导入时完成,如果发生的话。 将代码块限制为一行是一种有意的措施,以阻止在此处放置任何更复杂的内容。
例如,假设 sys.prefix
和 sys.exec_prefix
设置为 /usr/local
。 然后将 Python XY 库安装在 /usr/local/lib/pythonX.Y
中。 假设这里有一个子目录/usr/local/lib/pythonX.Y/site-packages
,有三个子子目录,foo
、bar
和spam
,以及两个路径配置文件,foo.pth
和[ X156X]。 假设 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
的模块,该模块可以执行任意站点特定的自定义。 它通常由系统管理员在 site-packages 目录中创建。 如果此导入失败并出现 ImportError 或其子类异常,并且该异常的 name
属性等于 'sitecustomize'
,则会被静默忽略。 如果 Python 在没有可用输出流的情况下启动,就像 Windows 上的 pythonw.exe
(默认用于启动 IDLE)一样,尝试从 sitecustomize
输出的尝试将被忽略。 任何其他异常都会导致进程无声且可能是神秘的失败。
在此之后,尝试导入名为 usercustomize
的模块,如果 ENABLE_USER_SITE 为真,它可以执行任意用户特定的自定义。 该文件旨在在用户站点包目录(见下文)中创建,该目录是 sys.path
的一部分,除非被 -s 禁用。 如果此导入失败并出现 ImportError 或其子类异常,并且该异常的 name
属性等于 'usercustomize'
,则会被静默忽略。
注意对于一些非Unix系统,sys.prefix
和sys.exec_prefix
为空,跳过路径操作; 然而,仍然尝试导入 sitecustomize
和 usercustomize
。
读取线配置
在支持 readline 的系统上,该模块还将导入和配置 rlcompleter 模块,如果 Python 以 交互模式 启动并且没有 -S 选项。 默认行为是启用制表符完成并使用 ~/.python_history
作为历史保存文件。 要禁用它,请删除(或覆盖) sitecustomize
或 usercustomize
模块或 PYTHONSTARTUP 中的 sys.__interactivehook__ 属性] 文件。
3.4 版更改: 自动激活 rlcompleter 和历史记录。
模块内容
- site.PREFIXES
- 站点包目录的前缀列表。
- site.ENABLE_USER_SITE
- 显示用户站点包目录状态的标志。
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
。 Distutils 使用此值来计算脚本、数据文件、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 模块还提供了一种从命令行获取用户目录的方法:
$ python3 -m site --user-site
/home/user/.local/lib/python3.3/site-packages
如果不带参数调用,会在标准输出上打印sys.path的内容,然后是USER_BASE的值和目录是否存在,那么同样的事情USER_SITE,最后是ENABLE_USER_SITE的值。
- --user-base
- 打印用户基本目录的路径。
- --user-site
- 打印用户站点包目录的路径。
如果两个选项都给出,用户群和用户站点将被打印(总是按这个顺序),由 os.pathsep 分隔。
如果给出任何选项,脚本将以下列值之一退出:0
如果用户站点包目录已启用,1
如果用户禁用它,[ X175X] 如果出于安全原因或由管理员禁用它,如果有错误,则值大于 2。