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" 目錄的支持已被移除。

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/pythonX.Y。假設有一個擁有三個孫目錄 foo, bar 和 spam 的子目錄 /usr/local/lib/pythonX.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

請注意 bletch 已被省略因為它并不存在；bar 目前在 foo 目錄之前因為 bar.pth 按字母順序排在 foo.pth 之前；而 spam 已被省略因為它在兩個路徑配置文件中都未被提及。

在這些路徑操作之后，會嘗試導入一個名為 sitecustomize 的模塊，它可以執行任意站點專屬的定制。 它通常是由系統管理員在 site-packages 目錄下創建的。 如此此導入失敗并引發 ImportError 或其子類異常，并且異常的 name 屬性等于 'sitecustomize'，則它會被靜默地忽略。 如果 Python 是在沒有可用輸出流的情況下啟動的，例如在 Windows 上使用 pythonw.exe (它默認被用于啟動 start IDLE)，則來自 sitecustomize 的輸出嘗試會被忽略。 任何其他異常都會導致靜默且可能令人迷惑不解的進程失敗。

在此之后，會嘗試導入一個名為 usercustomize 的模塊，它可以執行任意用戶專屬的定制，如果 ENABLE_USER_SITE 為真值的話。 這個文件應該在用戶的 site-packages 目錄中創建（見下文），該目錄是 sys.path 的組成部分，除非被 -s 所禁用。 如果此導入失敗并引發 ImportError 或者其子類異常，并且異常的 name 屬性等于 'usercustomize'，它會被靜默地忽略。

請注意對于某些非 Unix 系統來說，sys.prefix 和 sys.exec_prefix 均為空值，并且路徑操作會被跳過；但是仍然會嘗試導入 sitecustomize 和 usercustomize。

Readline（類庫） 配置

在支持 readline 的系統上，這個模塊也將導入并配置 rlcompleter 模塊，如果 Python 是以 交互模式 啟動并且不帶 -S 選項的話。 默認的行為是啟用 tab 鍵補全并使用 ~/.python_history 作為歷史存檔文件。 要禁用它，請刪除（或重載）你的 sitecustomize 或 usercustomize 模塊或 PYTHONSTARTUP 文件中的 sys.__interactivehook__ 屬性。

在 3.4 版更改: rlcompleter 和 history 會被自動激活。

模塊內容

site.PREFIXES

site-packages 目錄的前綴列表。

site.ENABLE_USER_SITE

顯示用戶 site-packages 目錄狀態的旗標。 True 意味著它被啟用并被添加到 sys.path。 False 意味著它按照用戶請求被禁用 (通過 -s 或 PYTHONNOUSERSITE)。 None 意味著它因安全理由（user 或 group id 和 effective id 之間不匹配）或是被管理員所禁用。

site.USER_SITE

正在運行的 Python 的用戶級 site-packages 的路徑。 它可以為 None，如果 getusersitepackages() 尚未被調用的話。 默認值在 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 的基準目錄的路徑。 它可以為 None，如果 getuserbase() 尚未被調用的話。 默認值在 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()

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

3.2 新版功能.

site.getuserbase()

返回用戶基準目錄的路徑 USER_BASE。 如果它尚未被初始化，則此函數還將參照 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

如果它被不帶參數地調用，它將在標準輸出打印 sys.path 的內容，再打印 USER_BASE 的值以及該目錄是否存在，然后打印 USER_SITE 的相應信息，最后打印 ENABLE_USER_SITE 的值。

--user-base

輸出用戶基本的路徑。

--user-site

將路徑輸出到用戶site-packages目錄。

如果同時給出了兩個選項，則將打印用戶基準目錄和用戶站點信息（總是按此順序），并以 os.pathsep 分隔。

如果給出了其中一個選項，腳本將退出并返回以下值中的一個：如果用戶級 site-packages 目錄被啟用則為 0，如果它被用戶禁用則為 1，如果它因安全理由或被管理員禁用則為 2，如果發生錯誤則為大于 2 的值。

參見

PEP 370 -- 分用戶的 site-packages 目錄