repository·main·Indexed 23 days ago
https://github.com/jaraco/keyringA Python library providing a unified interface to access system-level credential stores such as macOS Keychain, Windows Credential Locker, and Linux Secret Service. It includes a high-level API for storing and retrieving passwords, a command-line interface (CLI) for terminal interaction, and a framework for implementing custom KeyringBackend plugins.
On macOS, any Python script or application can access secrets created by keyring from that same Python executable without the operating system prompting the user for a password.
To require a password prompt every time a specific secret is accessed:
Backends can be configured using environment variables. Any variable starting with KEYRING_PROPERTY_{NAME} will be mapped to a property named {NAME.lower()} on the backend during initialization.
For example, to set an appid for a Linux SecretService backend, use KEYRING_PROPERTY_APPID.
keyring library provides a simple interface to access system keyring services. You can store and retrieve passwords using keyring.set_password and keyring.get_password.To use the SecretService backend in a Docker container, you must install the necessary dependencies and run the container with the --privileged flag to avoid Operation not permitted errors when unlocking the keyring.
Example setup for an Ubuntu 18.04 container:
--privileged.gnome-keyring and python3-venv.dbus-run-session to create a D-Bus shell.echo '<password>' | gnome-keyring-daemon --unlock.# Start container
docker run -it -d --privileged ubuntu:18.04
# Inside the container:
apt-get update
apt install -y gnome-keyring python3-venv python3-dev
python3 -m venv venv
source venv/bin/activate
pip3 install --upgrade pip
pip3 install keyring
dbus-run-session -- sh
# Inside the D-Bus shell:
echo 'somecredstorepass' | gnome-keyring-daemon --unlockkeyring command, first install the completion extra, then generate and install the completion files for your shell.You can use the SecretService backend on Linux systems without an X11 server, provided D-Bus is available.
GNOME Keyring daemon.dbus-run-session -- sh).gnome-keyring-daemon with the --unlock option. You will be prompted to enter a password via stdin. Press Ctrl+D to end the input.To install keyring in a virtual environment on Ubuntu 16.04 without a configuration file, follow these steps:
secretstorage and dbus-python.keyring.$ sudo apt install python3-venv libdbus-glib-1-dev
$ cd /tmp
$ pyvenv py3
$ source py3/bin/activate
$ pip install -U pip
$ pip install secretstorage dbus-python
$ pip install keyringThe SchemeSelectable class allows a backend to map 'username' and 'service' to different dictionary keys (schemes). This is useful for backends that use different naming conventions (e.g., KeePassXC uses UserName and Title instead of username and service).
To use it, define a schemes dictionary and a scheme attribute in your backend class.
Keyring automatically selects the best backend, but you can override this using a keyringrc.cfg file. To find the location of your config file, run keyring diagnose.
Use the [backend] section to specify:
default-keyring: The full path to the backend class.keyring-path: A directory to add to the Python module search path before loading the backend.[backend]
default-keyring=simplekeyring.SimpleKeyring
keyring-path=demoYou can make your custom keyring backend available to the keyring library by registering it as a setuptools entry point. This allows get_all_keyring() to discover and instantiate your backend automatically.
In your package's setup.cfg or pyproject.toml, add an entry point under the group keyring.backends:
[options.entry_points]
keyring.backends =
plugin_name = mylib.mymodule:initialize_funcNote: initialize_func is optional; if provided, it will be called when the plugin is loaded.
[options.entry_points]
keyring.backends =
plugin_name = mylib.mymodule:initialize_funckeyring command-line interface allows you to get, set, and delete passwords stored in a keyring. It supports specifying a specific backend or path for the keyring operations.To create a new keyring backend, you must subclass KeyringBackend. The KeyringBackendMeta metaclass automatically registers your non-abstract subclasses so they can be discovered by the system.
priority (class property): Returns a float or int representing the backend's priority. Higher numbers indicate higher priority. If the backend is unsuitable for the environment, this should raise a RuntimeError.get_password(service: str, username: str) -> str | None: Retrieves the password for a specific service and username.set_password(service: str, username: str, password: str) -> None: Stores a password. If the backend cannot store passwords, raise errors.PasswordSetError.delete_password(service: str, username: str) -> None: Deletes a password. If unsupported, raise errors.PasswordDeleteError.get_credential(service: str, username: str | None) -> credentials.Credential | None: Returns a Credential object containing both username and password. The default implementation uses get_password.Backends can be configured via environment variables starting with KEYRING_PROPERTY_*. For example, setting KEYRING_PROPERTY_SOME_SETTING=value will automatically set self.some_setting = 'value' on the backend instance during initialization.