28.14. site-特定于站点的配置钩子

源代码： Lib/site.py

---

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

导入此模块会将特定于站点的路径附加到模块搜索路径，并添加一些内置函数。

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

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

在 2.6 版中进行了更改：import 关键字之后现在需要空格或制表符。

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

然后将以下特定于版本的目录按此 Sequences 添加到sys.path：

/usr/local/lib/pythonX.Y/site-packages/bar
/usr/local/lib/pythonX.Y/site-packages/foo

注意bletch被Ellipsis，因为它不存在。 bar目录先于foo目录，因为bar.pth按字母 Sequences 在foo.pth之前；和spam被Ellipsis，因为在两个路径配置文件中均未提及。

经过这些路径操作后，try导入名为sitecustomize的模块，该模块可以执行任意特定于站点的自定义。它通常由系统 Management 员在 site-packages 目录中创建。如果此导入失败并出现ImportError异常，它将被忽略。如果在没有可用输出流的情况下启动 Python，例如 Windows 上的pythonw.exe(默认用于启动 IDLE)，则会忽略sitecustomize的try输出。 ImportError以外的任何异常都会导致该过程无声的甚至是神秘的失败。

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

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

• site. PREFIXES
  • 网站软件包目录的前缀列表。

2.6 版的新Function。

• site. ENABLE_USER_SITE
  • 显示用户 site-packages 目录状态的标志。 True表示已启用它并将其添加到sys.path中。 False表示它已被用户请求禁用(使用-s或 PYTHONNOUSERSITE)。 None表示出于安全原因(用户或组 ID 与有效 ID 不匹配)或由 Management 员禁用了它。

2.6 版的新Function。

• 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个文件。

2.6 版的新Function。

• site. USER_BASE
  • 用户站点包基本目录的路径。如果尚未调用getuserbase()，则可以为None。对于 UNIX 和 Mac OS X 非框架版本，默认值为~/.local；对于 Mac 框架版本，默认值为~/Library/Python/X.Y；对于 Windows，默认值为%APPDATA%\Python。 Distutils 使用此值来计算用户安装方案的脚本，数据文件，Python 模块等的安装目录。另请参见 PYTHONUSERBASE。

2.6 版的新Function。

• site. addsitedir(* sitedir ， known_paths = None *)

  • 将目录添加到 sys.path 并处理其.pth文件。通常在sitecustomize或usercustomize中使用(请参见上文)。

• site. getsitepackages ( )

  • 返回一个列表，其中包含所有全局站点包目录(可能还有 site-python)。

2.7 版的新Function。

• site. getuserbase ( )
  • 返回用户基本目录的路径USER_BASE。如果尚未初始化，则此函数还将按照 PYTHONUSERBASE进行设置。

2.7 版的新Function。

• site. getusersitepackages ( )
  • 返回特定于用户的 site-packages 目录USER_SITE的路径。如果尚未初始化，则此函数还将按照 PYTHONNOUSERSITE和USER_BASE进行设置。

2.7 版的新Function。

site模块还提供了一种从命令行获取用户目录的方法：

$ python -m site --user-site
/home/user/.local/lib/python2.7/site-packages

如果不带参数调用它，它将在标准输出上打印sys.path的内容，然后打印USER_BASE的值以及该目录是否存在，然后对USER_SITE进行相同的处理，最后打印ENABLE_USER_SITE的值。

• --user-base ``

  • 将路径打印到用户基本目录。

• --user-site ``

  • 将路径打印到用户 site-packages 目录。

如果同时给出两个选项，则将打印用户名和用户站点(始终按此 Sequences)，并以os.pathsep分隔。

如果提供了任何选项，则脚本将以以下值之一退出：0如果启用了用户 site-packages 目录，1如果被用户禁用了，2如果出于安全原因或 Management 员被禁用了，2如果有错误，则该值大于 2.