keyring
v25.5.0
Python 金鑰環庫提供了一種從 python 存取系統金鑰環服務的簡單方法。它可用於任何需要安全密碼儲存的應用程式。
支援這些推薦的密鑰環後端：
其他密鑰環實作可透過第三方後端取得。
在 Linux 上，KWallet 後端依賴 dbus-python，使用 pip 時它並不總是能正確安裝（需要編譯）。為了獲得最佳結果，請將 dbus-python 作為系統套件安裝。
macOS 鑰匙圈支援 macOS 11 (Big Sur) 和更高版本，需要 Python 3.8.7 或更高版本以及「universal2」二進位檔案。有關詳細信息，請參閱#525。
keyring 的基本用法非常簡單：只要呼叫keyring.set_password和keyring.get_password ：
>>> 匯入鑰匙圈
>>> keyring.set_password("系統", "使用者名稱", "密碼")
>>> keyring.get_password("系統", "使用者名稱")
'密碼'
Keyring 提供隨軟體包安裝的keyring指令。在大多數環境中安裝密鑰環後，該命令應該可用於設定、取得和刪除密碼。有關更多使用信息，請不帶參數或使用--help調用，如下所示：
$ 鑰匙圈--幫助 $ 密鑰環設定係統使用者名 「系統」中「使用者名稱」的密碼： $ keyring 取得系統使用者名 密碼
命令列功能也作為可執行套件公開，適合從 Python 調用，如下所示：
$ python -m 鑰匙圈 --help $ python -m keyring 設定係統使用者名 「系統」中「使用者名稱」的密碼： $ python -m keyring 取得系統使用者名 密碼
如果透過套件管理器（apt、pacman、nix、homebrew 等）安裝，這些 shell 補全可能已經隨套件一起分發（無需執行任何操作）。
如果安裝了額外的completion功能，金鑰環將提供選項卡補全功能：
$ pip install 'keyring[completion]'
然後，產生 shell 補全，如下所示：
$ 密鑰環 --print-completion bash | sudo tee /usr/share/bash-completion/completions/keyring $ 密鑰環 --print-completion zsh | sudo tee /usr/share/zsh/site-functions/_keyring $ 密鑰環 --print-completion tcsh | sudo tee /etc/profile.d/keyring.csh
注意：/usr/share 路徑主要用於GNU/Linux。對於其他作業系統，請考慮：
安裝 shell 補全後，請按照 shell 的建議說明啟用它們。例如：
. /usr/share/bash-completion/bash_completion ~/.bashrc中的. /usr/share/bash-completion/bash_completion 。autoload -Uz compinit && compinit出現在~/.zshrc中，然後grep -w keyring ~/.zcompdump來驗證 keyring 出現，表示它已正確安裝。 python 金鑰環庫包含多個後端的實作。該庫將嘗試自動選擇最適合當前環境的後端。使用者也可以在設定檔中或透過呼叫set_keyring()函數指定首選金鑰環。
配置儲存在名為「keyringrc.cfg」的檔案中，該檔案位於特定於平台的位置。若要確定設定檔的儲存位置，請執行keyring diagnose 。
若要指定金鑰環後端，請將default-keyring選項設定為該後端的類別的完整路徑，例如keyring.backends.macOS.Keyring 。
如果指定了keyring-path ，keyring 會在載入後端之前將該路徑新增至 Python 模組搜尋路徑。
例如，此配置可用於從./demo目錄中的simplekeyring模組載入SimpleKeyring （未實作）：
[後台] 預設金鑰環=simplekeyring.SimpleKeyring 密鑰環路徑=演示
除了核心金鑰環包為最常見且安全的用例提供的後端之外，還有其他金鑰環後端實作可用於其他用例。只需安裝它們即可使其可用：
keyring<24 ）。 後端的介面由keyring.backend.KeyringBackend定義。每個後端都應該從該基底類別派生並定義一個priority屬性和三個函數： get_password() 、 set_password()和delete_password() 。如果需要，可以定義get_credential()函數。
有關此類介面的更多詳細信息，請參閱backend模組。
密鑰環使用入口點來允許任何第三方包實現後端，而無需對密鑰環本身進行任何修改。鼓勵那些對創建新後端感興趣的人以 keyrings.alt 套件建模的方式在keyrings命名空間中創建新的第三方包。有關如何建立必要的入口點的提示，請參閱該項目中的setup.cfg檔案。事實證明必要的後端可能會被考慮包含在核心庫中，儘管安裝這些第三方軟體包的簡單性意味著擴充功能可能很容易獲得。
若要為密鑰環建立擴展，請提交拉取請求，將您的擴展列為可用擴展。
金鑰環也允許呼叫 api set_keyring()對後端進行程式配置。指定的後端隨後將用於儲存和檢索密碼。
呼叫set_keyring ：
# 定義一個新的 keyring 類別來擴充 KeyringBackend
導入 keyring.backend
類別 TestKeyring(keyring.backend.KeyringBackend):
“”“始終輸出相同密碼的測試密鑰環
”“”
優先權 = 1
def set_password(self, 服務名稱, 使用者名稱, 密碼):
經過
def get_password(self, 服務名稱, 使用者名稱):
回傳“來自 TestKeyring 的密碼”
def delete_password(self, 服務名, 使用者名稱):
經過
# 為金鑰環庫設定金鑰環
keyring.set_keyring(TestKeyring())
# 呼叫密鑰環庫
嘗試：
keyring.set_password("示範服務", "tarek", "passexample")
print("密碼儲存成功")
除了 keyring.errors.PasswordSetError：
print("密碼儲存失敗")
print("密碼", keyring.get_password("演示服務", "tarek"))
在許多情況下，永遠不需要卸載密鑰環。特別是在 Windows 和 macOS 上，密鑰環的行為通常是退化的，這意味著它將向呼叫者傳回空值，從而允許呼叫者回退到某些其他行為。
在某些情況下，密鑰環的預設行為是不可取的，最好完全停用密鑰環行為。有多種機制可以停用密鑰環：
PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring ，將使用Null （退化）後端。此方法會影響設定該變數的密鑰環的所有使用。keyring --disable或python -m keyring --disable為使用者永久配置空金鑰環。此方法會影響該使用者對密鑰環的所有使用。 密鑰環提供了一種透過環境變數改變密鑰環行為的機制。每個後端都實作一個KeyringBackend.set_properties_from_env ，呼叫時將尋找以KEYRING_PROPERTY_{NAME}開頭的所有環境變量，並為密鑰環上的每個{NAME.lower()}設定一個屬性。在預設/配置的密鑰環初始化期間呼叫此方法。
此機制可用於在各種密鑰環上設定一些有用的值，包括：
以下是在 Ubuntu 16.04 上的虛擬環境中安裝金鑰環的完整記錄。沒有使用設定檔：
$ sudo apt install python3-venv libdbus-glib-1-dev
$ cd /tmp
$ pyvenv py3
$ 來源 py3/bin/activate
$ pip install -U pip
$ pip安裝secretstorage dbus-python
$ pip 安裝金鑰環
$ 蟒蛇
>>> 匯入鑰匙圈
>>> keyring.get_keyring()
<keyring.backends.SecretService.Keyring 物件位於 0x7f9b9c971ba8>
>>> keyring.set_password("系統", "使用者名稱", "密碼")
>>> keyring.get_password("系統", "使用者名稱")
'密碼'
可以在沒有可用 X11 伺服器的 Linux 系統上使用 SecretService 後端（僅需要 D-Bus）。在這種情況下：
安裝 GNOME 密鑰環守護程序。
啟動 D-Bus 會話，例如執行dbus-run-session -- sh並在該 shell 內執行以下命令。
使用--unlock選項來執行gnome-keyring-daemon 。該選項的描述如下：
從標準輸入讀取密碼，並使用它來解鎖登入金鑰環，或在登入金鑰環不存在時建立它。
當該指令啟動時，在 stdin 中輸入密碼並按 Ctrl+D（資料結束）。之後，守護程序將分叉到後台（使用--foreground選項來阻止）。
現在您可以使用 Keyring 的 SecretService 後端。請記住在與守護程式相同的 D-Bus 會話中執行應用程式。
也可以在 Docker 容器中將金鑰環與 SecretService 後端一起使用。您所需要做的就是安裝必要的依賴項並添加 --privileged 標誌，以避免在嘗試解鎖系統密鑰環時出現任何「不允許操作」錯誤。
以下是在 Ubuntu 18:04 容器上安裝金鑰環的完整記錄：
docker run -it -d --privileged ubuntu:18.04
$ apt-get 更新
$ apt install -y gnome-keyring python3-venv python3-dev
$ python3 -m venv venv
$ source venv/bin/activate # 取得虛擬環境以避免污染系統
$ pip3 install --升級 pip
$ pip3 安裝金鑰環
$ dbus-run-session -- sh # 這會讓你進入一個新的 D-bus shell
$ echo 'somecredstorepass' | gnome-keyring-daemon --unlock # 解鎖系統的密鑰環
$ 蟒蛇
>>> 匯入鑰匙圈
>>> keyring.get_keyring()
<keyring.backends.SecretService.Keyring 物件位於 0x7f9b9c971ba8>
>>> keyring.set_password("系統", "使用者名稱", "密碼")
>>> keyring.get_password("系統", "使用者名稱")
'密碼'
金鑰環庫有幾個功能：
get_keyring() ：傳回目前載入的金鑰環實作。get_password(service, username) ：傳回儲存在活動金鑰環中的密碼。如果密碼不存在，則傳回None。get_credential(service, username) ：傳回儲存在活動金鑰環中的憑證物件。該物件至少包含指定服務的username和password屬性，其中傳回的username可能與參數不同。set_password(service, username, password) ：將密碼儲存在金鑰環中。delete_password(service, username) ：刪除密鑰環中儲存的密碼。如果密碼不存在，則會引發異常。在所有情況下，參數（ service 、 username 、 password ）都應該是Unicode文字。
密鑰環庫引發以下異常：
keyring.errors.KeyringError ：密鑰環庫中所有異常的基本錯誤類別。keyring.errors.InitError ：當金鑰環無法初始化時引發。keyring.errors.PasswordSetError ：當無法在金鑰環中設定密碼時引發。keyring.errors.PasswordDeleteError ：當無法刪除密鑰環中的密碼時引發。 Python keyring lib 是一個開放社群項目，熱切歡迎貢獻者。
在使用此程式庫之前，每個內建後端可能需要了解安全注意事項。我們鼓勵使用keyring的工具或庫的作者考慮這些問題。
與任何已知安全問題的清單一樣，此列表並不詳盡。可以根據需要添加其他問題。
keyring環建立的機密，而無需作業系統提示使用者輸入密碼。若要使任何特定機密在每次存取時都提示輸入密碼，請使用Keychain Access應用程式找到憑證，然後在Access Control設定中，從允許的應用程式清單中刪除Python 。該專案利用自動發布和持續整合。簡單的工作流程是標記提交並將其推送到 Github。如果在 CI 中通過測試，它將自動部署到 PyPI。
發佈時需要考慮的其他事項：
測試在 Github Actions 中持續運作。
若要在本機上執行測試，請安裝並呼叫 tox。
該項目基於 Tarek Ziade 在這篇文章中的想法。 Kang Chang 最初將其作為 Google Summer of Code 項目進行，Tarek 在該項目上指導 Kang。
作為 Tidelift 訂閱的一部分提供。
該專案和數千個其他軟體包的維護者正在與 Tidelift 合作，提供一項涵蓋您使用的所有開源軟體的企業訂閱。
了解更多。
