Skip to main content

29.13. site —站点特定的配置钩子

源代码: Lib/site.py


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

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

在 3.3 版更改: 导入用于触发路径操作的模块,即使使用 -S

它从头部和尾部构造最多四个目录开始。对于头部,它使用 sys.prefixsys.exec_prefix;空头被跳过。对于尾部,它使用空字符串,然后使用 lib/site-packages (在Windows上)或 lib/pythonX.Y/site-packages (在Unix和Macintosh上)。对于每个不同的头 - 尾组合,它看到它是否指现有目录,如果是,则将其添加到 sys.path 并且还检查新添加的配置文件路径。

在 3.5 版更改: 支持“site-python”目录已删除。

如果一个名为“pyvenv.cfg”的文件存在于sys.executable之上的一个目录下,sys.prefix和sys.exec_prefix被设置为该目录,并且还检查site-packages(sys.base_prefix和sys.base_exec_prefix将始终是“真正的”前缀的Python安装)。如果“pyvenv.cfg”(引导配置文件)包含设置为“false”(不区分大小写)以外的任何内容的关键字“include-system-site-packages”,系统级前缀仍将搜索站点 - 包装;否则他们不会。

路径配置文件是其名称具有形式 name.pth 并且存在于上述四个目录中的一个中的文件;其内容是要添加到 sys.path 的附加项目(每行一个)。不会向 sys.path 添加不存在的项目,并且不会检查该项目是否指向目录而不是文件。没有项目添加到 sys.path 多次。将跳过以 # 开头的空行和行。以 import 开头的行(后跟空格或制表符)被执行。

例如,假设 sys.prefixsys.exec_prefix 设置为 /usr/local。 Python X.Y库然后安装在 /usr/local/lib/pythonX.Y 中。假设这有一个子目录 /usr/local/lib/pythonX.Y/site-packages 有三个子目录,foobarspam,以及两个路径配置文件,foo.pthbar.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.pthfoo.pth 之前按字母顺序排列;并且 spam 被省略,因为它在任一路径配置文件中未提及。

在这些路径操作之后,尝试导入名为 sitecustomize 的模块,该模块可以执行任意站点特定的自定义。它通常由系统管理员在site-packages目录中创建。如果此导入失败并出现 ImportError 异常,则会被忽略。如果Python启动时没有可用的输出流,就像Windows上的 pythonw.exe (默认情况下使用它启动IDLE)一样,sitecustomize 的尝试输出被忽略。除了 ImportError 之外的任何异常都会导致该过程的沉默或者神秘的失败。

之后,尝试导入名为 usercustomize 的模块,如果 ENABLE_USER_SITE 为true,可以执行任意用户特定的自定义。此文件旨在在用户site-packages目录(见下文)中创建,这是 sys.path 的一部分,除非被 -s 禁用。将忽略 ImportError

注意,对于一些非Unix系统,sys.prefixsys.exec_prefix 是空的,并且跳过路径操纵;然而,仍然尝试进口 sitecustomizeusercustomize

29.13.1. Readline配置

在支持 readline 的系统上,如果Python在 交互模式 中启动并且没有 -S 选项,则此模块还将导入并配置 rlcompleter 模块。默认行为是启用制表符完成并使用 ~/.python_history 作为历史保存文件。要禁用它,请删除(或覆盖) sitecustomizeusercustomize 模块或 PYTHONSTARTUP 文件中的 sys.__interactivehook__ 属性。

在 3.4 版更改: 自动进行rIcompleter和历史的激活。

29.13.2. 模块内容

site.PREFIXES

site-packages目录的前缀列表。

site.ENABLE_USER_SITE

标志显示用户site-packages目录的状态。 True 意味着它已启用并添加到 sys.pathFalse 意味着它被用户请求禁用(使用 -sPYTHONNOUSERSITE)。 None 意味着它由于安全原因(用户或组ID和有效ID之间不匹配)或管理员被禁用。

site.USER_SITE

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

site.USER_BASE

用户site-packages的基本目录的路径。如果 getuserbase() 还没有被调用,可以是 None。对于UNIX和Mac OS X非框架构建,默认值为 ~/.local,对于Mac框架构建为 ~/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 文件。通常用于 sitecustomizeusercustomize (见上文)。

site.getsitepackages()

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

3.2 新版功能.

site.getuserbase()

返回用户基本目录 USER_BASE 的路径。如果尚未初始化,此函数也将设置它,尊重 PYTHONUSERBASE

3.2 新版功能.

site.getusersitepackages()

返回用户特定的site-packages目录 USER_SITE 的路径。如果尚未初始化,此函数也将设置它,遵守 PYTHONNOUSERSITEUSER_BASE

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

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

如果给定两个选项,将打印用户基本和用户站点(始终按此顺序),由 os.pathsep 分隔。

如果给出任何选项,脚本将退出,并带有以下值之一:如果启用了用户site-packages目录,则为 O,如果用户禁用则为 1,如果出于安全原因或由管理员禁用,则为 2,如果存在错误,则大于2的值。

参见

PEP 370 - 每个用户site-packages目录