site —特定于站点的配置钩子

源代码： Lib/site.py

---

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

导入此模块会将站点特定的路径追加到模块搜索路径，并添加一些内置函数，除非使用了-S。在这种情况下，可以安全地导入该模块，而无需自动修改模块搜索路径或添加内置函数。要明确触发通常针对特定地点的添加，请调用site.main()函数。

在版本 3.3 中进行了更改：即使使用-S，也要导入用于触发路径操纵的模块。

它从头和尾部分开始最多构建四个目录。对于头部，它使用sys.prefix和sys.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 设置为该目录，并且还将检查站点包(sys.base_prefix 和 sys.base_exec_prefix 始终是 Python 安装的“真实”前缀)。如果“ pyvenv.cfg”(引导程序配置文件)包含设置为“ true”(不区分大小写)之外的任何键的“ include-system-site-packages”键，则不会在系统级前缀中搜索 site-包装;否则他们会的。

路径配置文件是名称形式为name.pth且位于上述四个目录之一中的文件；它的内容是要添加到sys.path的其他项(每行一个)。不存在的项目永远不会添加到sys.path，并且不会检查该项目是指向目录而不是文件。没有任何项目被添加到sys.path一次以上。空行和以#开头的行将被跳过。执行以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或其子类异常而失败，并且该异常的name属性等于'sitecustomize'，则它将被忽略。如果在没有可用输出流的情况下启动 Python，例如 Windows 上的pythonw.exe(默认用于启动 IDLE)，则会忽略sitecustomize的try输出。任何其他异常都会导致该过程无声的甚至是神秘的失败。

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

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

Readline configuration

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

在版本 3.4 中进行了更改：自动完成了 rlcompleter 和历史记录的激活。

Module contents

• site. PREFIXES

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

• site. ENABLE_USER_SITE

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

• 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

  • 用户站点包基本目录的路径。如果尚未调用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文件。通常在sitecustomize或usercustomize中使用(请参见上文)。

• site. getsitepackages ( )

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

3.2 版中的新Function。

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

3.2 版中的新Function。

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

3.2 版中的新Function。

命令行界面

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 目录。

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

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