site — 站點特定的配置鉤子

原始碼: Lib/site.py

此模組在初始化期間自動匯入。 可以使用直譯器的 -S 選項來禁止自動匯入。

匯入此模組通常會將特定於站點的路徑附加到模組搜尋路徑，並新增 可呼叫物件，包括 help() 到內建名稱空間。但是，Python 啟動選項 -S 會阻止此操作，並且可以安全地匯入此模組，而無需對模組搜尋路徑進行自動修改或新增到內建物件。要顯式觸發通常的站點特定新增，請呼叫 main() 函式。

在 3.3 版本中變更: 即使在使用 -S 時，匯入該模組也會觸發路徑操作。

它首先從頭部和尾部構造最多四個目錄。對於頭部，它使用 sys.prefix 和 sys.exec_prefix；跳過空頭部。對於尾部，它使用空字串，然後使用 lib/site-packages (在 Windows 上) 或 lib/pythonX.Y[t]/site-packages (在 Unix 和 macOS 上)。(可選後綴 “t” 表示 自由執行緒 構建，如果 sys.abiflags 常量中存在 "t"，則會附加該字尾。) 對於每個不同的頭尾組合，它會檢視是否引用現有目錄，如果是，則將其新增到 sys.path，還會檢查新新增的路徑中的配置檔案。

在 3.5 版本中變更: 已刪除對 “site-python” 目錄的支援。

在 3.13 版本中變更: 在 Unix 上，自由執行緒 Python 安裝透過版本特定目錄名稱中的 “t” 字尾來標識，例如 lib/python3.13t/。

如果名為 “pyvenv.cfg” 的檔案存在於 sys.executable 上一級目錄中，則 sys.prefix 和 sys.exec_prefix 將設定為該目錄，並且還會檢查該目錄中的 site-packages (sys.base_prefix 和 sys.base_exec_prefix 將始終是 Python 安裝的“真實”字首)。如果 “pyvenv.cfg” (一個引導配置檔案) 包含鍵 “include-system-site-packages” 設定為除 “true” (不區分大小寫) 以外的任何值，則不會搜尋系統級別的 site-packages 字首；否則會搜尋。

路徑配置檔案是一個名稱格式為 name.pth 並且存在於上述四個目錄之一中的檔案；其內容是要新增到 sys.path 的附加項(每行一個)。不會將不存在的項新增到 sys.path，並且不會檢查該項是指向目錄還是檔案。不會將任何項新增到 sys.path 多次。跳過空行和以 # 開頭的行。執行以 import (後跟空格或製表符) 開頭的行。

注意

.pth 檔案中的可執行行在每次 Python 啟動時執行，無論是否實際使用特定模組。因此，應將其影響保持在最低限度。可執行行的主要目的是使相應的模組可匯入 (載入第三方匯入鉤子，調整 PATH 等)。任何其他初始化都應該在模組實際匯入時執行，如果並且當它發生時。將程式碼塊限制為單行是一種有意的措施，目的是阻止在此處放置更復雜的內容。

在 3.13 版本中變更: .pth 檔案現在首先由 UTF-8 解碼，如果失敗，則由 區域設定編碼 解碼。

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

然後，以下版本特定目錄按此順序新增到 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

在這些路徑操作之後，會嘗試匯入一個名為 sitecustomize 的模組，它可以執行任意的站點特定自定義。它通常由系統管理員在 site-packages 目錄中建立。如果此匯入失敗，並出現 ImportError 或其子類異常，並且該異常的 name 屬性等於 'sitecustomize'，則會被靜默忽略。如果 Python 在沒有輸出流可用的情況下啟動，如 Windows 上的 pythonw.exe (預設情況下用於啟動 IDLE)，則會忽略 sitecustomize 嘗試的輸出。任何其他異常都會導致程序的靜默和可能神秘的失敗。

usercustomize

之後，會嘗試匯入名為 usercustomize 的模組，如果 ENABLE_USER_SITE 為 true，則該模組可以執行任意的使用者特定自定義。此檔案旨在使用者 site-packages 目錄(參見下文)中建立，該目錄是 sys.path 的一部分，除非被 -s 停用。如果此匯入失敗，並出現 ImportError 或其子類異常，並且該異常的 name 屬性等於 'usercustomize'，則會被靜默忽略。

請注意，對於某些非 Unix 系統，sys.prefix 和 sys.exec_prefix 為空，路徑操作會被跳過；但是，仍然會嘗試匯入 sitecustomize 和 usercustomize。

Readline 配置

在支援 readline 的系統上，如果 Python 在互動模式下啟動，且沒有使用 -S 選項，此模組還會匯入和配置 rlcompleter 模組。預設行為是啟用 Tab 補全，並使用 ~/.python_history 作為歷史記錄儲存檔案。要停用它，請在你的 sitecustomize 或 usercustomize 模組或者你的 PYTHONSTARTUP 檔案中刪除（或覆蓋）sys.__interactivehook__ 屬性。

在 3.4 版本中變更: rlcompleter 和歷史記錄的啟用已改為自動進行。

模組內容

site.PREFIXES

site-packages 目錄的字首列表。

site.ENABLE_USER_SITE

標誌，顯示使用者 site-packages 目錄的狀態。True 表示已啟用並已新增到 sys.path。False 表示已被使用者請求停用（透過 -s 或 PYTHONNOUSERSITE）。None 表示由於安全原因（使用者或組 ID 與有效 ID 不匹配）或由管理員停用。

site.USER_SITE

正在執行的 Python 的使用者 site-packages 目錄的路徑。如果尚未呼叫 getusersitepackages()，則可以為 None。對於 UNIX 和非框架 macOS 構建，預設值為 ~/.local/lib/pythonX.Y[t]/site-packages；對於 macOS 框架構建，預設值為 ~/Library/Python/X.Y/lib/python/site-packages；對於 Windows，預設值為 %APPDATA%\Python\PythonXY\site-packages。可選的 “t” 表示自由執行緒構建。此目錄是一個 site 目錄，這意味著將處理其中的 .pth 檔案。

site.USER_BASE

使用者 site-packages 的基本目錄的路徑。如果尚未呼叫 getuserbase()，則可以為 None。對於 UNIX 和 macOS 非框架構建，預設值為 ~/.local；對於 macOS 框架構建，預設值為 ~/Library/Python/X.Y；對於 Windows，預設值為 %APPDATA%\Python。此值用於計算 使用者安裝方案的指令碼、資料檔案、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()

返回使用者特定的 site-packages 目錄的路徑，即 USER_SITE。如果尚未初始化，此函式還會設定它，並尊重 USER_BASE。要確定是否已將使用者特定的 site-packages 新增到 sys.path，應使用 ENABLE_USER_SITE。

3.2 版本新增。

命令列介面

site 模組還提供了一種從命令列獲取使用者目錄的方法。

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

如果它在沒有引數的情況下被呼叫，它將在標準輸出上列印 sys.path 的內容，後跟 USER_BASE 的值以及該目錄是否存在，然後對 USER_SITE 執行相同的操作，最後是 ENABLE_USER_SITE 的值。

--user-base

列印使用者基本目錄的路徑。

--user-site

列印使用者 site-packages 目錄的路徑。

如果同時給出了兩個選項，則會列印使用者基礎目錄和使用者站點目錄（始終按此順序），並使用 os.pathsep 分隔。

如果給出了任何選項，指令碼將以以下值之一退出：如果使用者站點包目錄已啟用，則為 0；如果該目錄被使用者停用，則為 1；如果由於安全原因或被管理員停用，則為 2；如果出現錯誤，則為大於 2 的值。

另請參閱