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 合作，提供一项涵盖您使用的所有开源软件的企业订阅。
了解更多。
