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/。

3.14 版本中已更改: site 不再負責在 虛擬環境 中更新 sys.prefix 和 sys.exec_prefix。這現在在 路徑初始化 期間完成。因此，在 虛擬環境 下，sys.prefix 和 sys.exec_prefix 不再依賴於 site 初始化，因此不受 -S 的影響。

在 虛擬環境 中執行時，會檢查 sys.prefix 中的 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 解碼，如果失敗，則透過 locale encoding 解碼。

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

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

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

Readline 配置

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

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”表示自由執行緒構建。此目錄是一個站點目錄，這意味著其中的 .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 分隔。

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

參見