29.13. "site" —— 指定 Site 的配置钩子
*************************************

**源代码:** Lib/site.py

======================================================================

**这个模块将在初始化时被自动导入。** 此自动导入可以通过使用解释器的
"-S" 选项来屏蔽。

导入此模块将会附加域特定的路径到模块搜索路径并且添加一些内建对象，除非
使用了 "-S" 选项。在此例中，模块可以被安全地导入，而不会对模块搜索路径
和内建对象有自动的修改或添加。要明确地触发通常域特定的添加，调用函数
"site.main()"。

3.3 版更變: 即便使用了 "-S"，也会导入用于触发路径操纵的模块。

It starts by constructing up to four directories from a head and a
tail part. For the head part, it uses "sys.prefix" and
"sys.exec_prefix"; empty heads are skipped.  For the tail part, it
uses the empty string and then "lib/site-packages" (on Windows) or
"lib/python*X.Y*/site-packages" (on Unix and Macintosh).  For each of
the distinct head-tail combinations, it sees if it refers to an
existing directory, and if so, adds it to "sys.path" and also inspects
the newly added path for configuration files.

3.5 版更變: 对 "site-python" 目录的支持已被移除。

If a file named "pyvenv.cfg" exists one directory above
sys.executable, sys.prefix and sys.exec_prefix are set to that
directory and it is also checked for site-packages (sys.base_prefix
and sys.base_exec_prefix will always be the "real" prefixes of the
Python installation). If "pyvenv.cfg" (a bootstrap configuration file)
contains the key "include-system-site-packages" set to anything other
than "false" (case-insensitive), the system-level prefixes will still
also be searched for site-packages; otherwise they won't.

一个路径配置文件是具有 "*name*.pth" 命名格式的文件，并且存在上面提到的
四个目录之一中；它的内容是要添加到 "sys.path" 中的额外项目（每行一个）
。不存在的项目不会添加到 "sys.path"，并且不会检查项目指向的是目录还是
文件。项目不会被添加到 "sys.path" 超过一次。空行和由 "#" 起始的行会被
跳过。以 "import" 开始的行（跟着空格或 TAB）会被执行。

例如，假设 "sys.prefix" 和 "sys.exec_prefix" 已经被设置为 "/usr/local"
。 Python X.Y 的库之后被安装为 "/usr/local/lib/python*X.Y*"。假设有一
个拥有三个孙目录 "foo", "bar" 和 "spam" 的子目录
"/usr/local/lib/python*X.Y*/site-packages"，并且有两个路径配置文件
"foot.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

Note that "bletch" is omitted because it doesn't exist; the "bar"
directory precedes the "foo" directory because "bar.pth" comes
alphabetically before "foo.pth"; and "spam" is omitted because it is
not mentioned in either path configuration file.

After these path manipulations, an attempt is made to import a module
named "sitecustomize", which can perform arbitrary site-specific
customizations. It is typically created by a system administrator in
the site-packages directory.  If this import fails with an
"ImportError" exception, it is silently ignored.  If Python is started
without output streams available, as with "pythonw.exe" on Windows
(which is used by default to start IDLE), attempted output from
"sitecustomize" is ignored. Any exception other than "ImportError"
causes a silent and perhaps mysterious failure of the process.

After this, an attempt is made to import a module named
"usercustomize", which can perform arbitrary user-specific
customizations, if "ENABLE_USER_SITE" is true.  This file is intended
to be created in the user site-packages directory (see below), which
is part of "sys.path" unless disabled by "-s".  An "ImportError" will
be silently ignored.

Note that for some non-Unix systems, "sys.prefix" and
"sys.exec_prefix" are empty, and the path manipulations are skipped;
however the import of "sitecustomize" and "usercustomize" is still
attempted.


29.13.1. Readline configuration
===============================

On systems that support "readline", this module will also import and
configure the "rlcompleter" module, if Python is started in
interactive mode and without the "-S" option. The default behavior is
enable tab-completion and to use "~/.python_history" as the history
save file.  To disable it, delete (or override) the
"sys.__interactivehook__" attribute in your "sitecustomize" or
"usercustomize" module or your "PYTHONSTARTUP" file.

3.4 版更變: Activation of rlcompleter and history was made automatic.


29.13.2. 模块内容
=================

site.PREFIXES

   A list of prefixes for site-packages directories.

site.ENABLE_USER_SITE

   Flag showing the status of the user site-packages directory.
   "True" means that it is enabled and was added to "sys.path".
   "False" means that it was disabled by user request (with "-s" or
   "PYTHONNOUSERSITE").  "None" means it was disabled for security
   reasons (mismatch between user or group id and effective id) or by
   an administrator.

site.USER_SITE

   Path to the user site-packages for the running Python.  Can be
   "None" if "getusersitepackages()" hasn't been called yet.  Default
   value is "~/.local/lib/python*X.Y*/site-packages" for UNIX and non-
   framework Mac OS X builds, "~/Library/Python/*X.Y*/lib/python/site-
   packages" for Mac framework builds, and
   "*%APPDATA%*\Python\Python*XY*\site-packages" on Windows.  This
   directory is a site directory, which means that ".pth" files in it
   will be processed.

site.USER_BASE

   Path to the base directory for the user site-packages.  Can be
   "None" if "getuserbase()" hasn't been called yet.  Default value is
   "~/.local" for UNIX and Mac OS X non-framework builds,
   "~/Library/Python/*X.Y*" for Mac framework builds, and
   "*%APPDATA%*\Python" for Windows.  This value is used by Distutils
   to compute the installation directories for scripts, data files,
   Python modules, etc. for the user installation scheme. See also
   "PYTHONUSERBASE".

site.main()

   Adds all the standard site-specific directories to the module
   search path.  This function is called automatically when this
   module is imported, unless the Python interpreter was started with
   the "-S" flag.

   3.3 版更變: This function used to be called unconditionally.

site.addsitedir(sitedir, known_paths=None)

   Add a directory to sys.path and process its ".pth" files.
   Typically used in "sitecustomize" or "usercustomize" (see above).

site.getsitepackages()

   Return a list containing all global site-packages directories.

   3.2 版新加入.

site.getuserbase()

   Return the path of the user base directory, "USER_BASE".  If it is
   not initialized yet, this function will also set it, respecting
   "PYTHONUSERBASE".

   3.2 版新加入.

site.getusersitepackages()

   Return the path of the user-specific site-packages directory,
   "USER_SITE".  If it is not initialized yet, this function will also
   set it, respecting "PYTHONNOUSERSITE" and "USER_BASE".

   3.2 版新加入.

"site" 模块还提供了一个从命令行获取用户目录的方式:

   $ python3 -m site --user-site
   /home/user/.local/lib/python3.3/site-packages

If it is called without arguments, it will print the contents of
"sys.path" on the standard output, followed by the value of
"USER_BASE" and whether the directory exists, then the same thing for
"USER_SITE", and finally the value of "ENABLE_USER_SITE".

--user-base

   Print the path to the user base directory.

--user-site

   Print the path to the user site-packages directory.

If both options are given, user base and user site will be printed
(always in this order), separated by "os.pathsep".

If any option is given, the script will exit with one of these values:
"0" if the user site-packages directory is enabled, "1" if it was
disabled by the user, "2" if it is disabled for security reasons or by
an administrator, and a value greater than 2 if there is an error.

也參考: **PEP 370** -- 分用户的 site-packages 目录
