Store and access your passwords safely.
Project description
What is Python keyring lib?
The Python keyring lib provides a easy way to access the system keyring service from python. It can be used in any application that needs safe password storage.
The keyring library is licensed under both the MIT license and the PSF license.
These recommended keyring backends are supported by the Python keyring lib:
Mac OS X Keychain
Linux Secret Service (requires secretstorage)
Other keyring implementations are provided in the keyrings.alt package.
Installation Instructions
easy_install or pip
Run easy_install or pip:
$ easy_install keyring $ pip install keyring
Source installation
Download the source tarball from https://pypi-hypernode.com/pypi/keyring, uncompress it, and then run “setup.py install”.
Using Keyring
The basic usage of keyring is pretty simple: just call keyring.set_password and keyring.get_password:
>>> import keyring
>>> keyring.set_password("system", "username", "password")
>>> keyring.get_password("system", "username")
'password'
Command-line Utility
Keyring supplies a keyring command which is installed with the package. After installing keyring in most environments, the command should be available for setting, getting, and deleting passwords. For more information on usage, invoke with no arguments or with --help as so:
$ keyring --help $ keyring set system username Password for 'username' in 'system': $ keyring get system username password
The command-line functionality is also exposed as an executable package, suitable for invoking from Python like so:
$ python -m keyring --help $ python -m keyring set system username Password for 'username' in 'system': $ python -m keyring get system username password
Configure your keyring lib
The python keyring lib contains implementations for several backends. The library will automatically choose the keyring that is most suitable for your current environment. You can also specify the keyring you like to be used in the config file or by calling the set_keyring() function.
Customize your keyring by config file
This section describes how to change your option in the config file.
Config file path
The configuration of the lib is stored in a file named “keyringrc.cfg”. This file must be found in a platform-specific location. To determine where the config file is stored, run the following:
python -c "import keyring.util.platform_; print(keyring.util.platform_.config_root())"
Some keyrings also store the keyring data in the file system. To determine where the data files are stored, run this command:
python -c "import keyring.util.platform_; print(keyring.util.platform_.data_root())"
Config file content
To specify a keyring backend, set the default-keyring option to the full path of the class for that backend, such as keyring.backends.OS_X.Keyring.
If keyring-path is indicated, keyring will add that path to the Python module search path before loading the backend.
For example, this config might be used to load the SimpleKeyring from the demo directory in the project checkout:
[backend] default-keyring=simplekeyring.SimpleKeyring keyring-path=/home/kang/pyworkspace/python-keyring-lib/demo/
Write your own keyring backend
The interface for the backend is defined by keyring.backend.KeyringBackend. Every backend should derive from that base class and define a priority attribute and three functions: get_password(), set_password(), and delete_password().
See the backend module for more detail on the interface of this class.
Set the keyring in runtime
Keyring additionally allows programmatic configuration of the backend calling the api set_keyring(). The indicated backend will subsequently be used to store and retrieve passwords.
Here’s an example demonstrating how to invoke set_keyring:
# define a new keyring class which extends the KeyringBackend
import keyring.backend
class TestKeyring(keyring.backend.KeyringBackend):
"""A test keyring which always outputs same password
"""
priority = 1
def set_password(self, servicename, username, password):
pass
def get_password(self, servicename, username):
return "password from TestKeyring"
def delete_password(self, servicename, username, password):
pass
# set the keyring for keyring lib
keyring.set_keyring(TestKeyring())
# invoke the keyring lib
try:
keyring.set_password("demo-service", "tarek", "passexample")
print("password stored sucessfully")
except keyring.errors.PasswordSetError:
print("failed to store password")
print("password", keyring.get_password("demo-service", "tarek"))
Using Keyring on headless Linux systems
It is possible to use the SecretService backend on Linux systems without X11 server available (only D-Bus is required). To do that, you need the following:
Install the GNOME Keyring daemon.
Start a D-Bus session, e.g. run dbus-run-session -- sh and run the following commands inside that shell.
Run gnome-keyring-daemon with --unlock option. The description of that option says:
Read a password from stdin, and use it to unlock the login keyring or create it if the login keyring does not exist.
When that command is started, enter your password into stdin and press Ctrl+D (end of data). After that the daemon will fork into background (use --foreground option to prevent that).
Now you can use the SecretService backend of Keyring. Remember to run your application in the same D-Bus session as the daemon.
Integrate the keyring lib with your application
API interface
The keyring lib has a few functions:
get_keyring(): Return the currently-loaded keyring implementation.
get_password(service, username): Returns the password stored in the active keyring. If the password does not exist, it will return None.
set_password(service, username, password): Store the password in the keyring.
delete_password(service, username): Delete the password stored in keyring. If the password does not exist, it will raise an exception.
Get involved
Python keyring lib is an open community project and highly welcomes new contributors.
Repository: https://github.com/jaraco/keyring/
Bug Tracker: https://github.com/jaraco/keyring/issues/
Mailing list: http://groups.google.com/group/python-keyring
Making Releases
Python keyring lib uses a simple tag and release process. The simplified workflow is first tag a release, then invoke setup.py release.
Other things to consider when making a release:
first ensure that tests pass (preferably on Windows and Linux)
check that the changelog is current for the intended release
after tagging, but before releasing, push the changes to the repository
Running Tests
Tests are continuously run using Travis-CI.
To run the tests yourself, you’ll want keyring installed to some environment in which it can be tested. Recommended techniques are described below.
Using pytest runner
Keyring is instrumented with pytest runner. Thus, you may invoke the tests from any supported Python (with setuptools installed) using this command:
python setup.py test
pytest runner will download any unmet dependencies and run the tests using pytest.
This technique is the one used by the Travis-CI script.
Using virtualenv and pytest/nose/unittest
Pytest and Nose are two popular test runners that will discover tests and run them. Unittest also has a mode to discover tests.
First, however, these test runners typically need a test environment in which to run. It is recommended that you install keyring to a virtual environment to avoid interfering with your system environment. For more information, see the venv documentation or the virtualenv homepage.
After you’ve created (or designated) your environment, install keyring into the environment by running:
python setup.py develop
You then need to install the test requirements with something like:
pip install $( python -c "import setup, subprocess; print(subprocess.list2cmdline(setup.test_requirements))" )
Then, invoke your favorite test runner, e.g.:
py.test
or:
nosetests
Background
The project was based on Tarek Ziade’s idea in this post. Kang Zhang initially carried it out as a Google Summer of Code project, and Tarek mentored Kang on this project.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for keyring-8.7-py2.py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 2510768eedf6a8fb4fe7a392cb1161e7ca8c93f4349c4757881850c2118a1f98 |
|
| MD5 | 905700fbf29ac72ba22ddcde25ac728a |
|
| BLAKE2b-256 | 499c83cb89bfc097b889461f39adce88465b0eb926027faf916e091971d3546f |
