How to use Keyring (unanswered questions)

[jaraco]

10 years later, almost to the day, and this issue still applies.

From Using Keyring:

 ...
>> keyring.set_password("system", "username", "password")
 ...
$ keyring set system username
 ...

What is system ? 🤷🏻‍♂️

How do I use keyring in the most basic real-world scenario ? 🤷🏻‍♂️🤷🏻‍♂️
How do I get / set secrets from / in any of the four recommended keyring backends supported
(macOS Keychain, Freedesktop Secret Service, KDE Wallet, Windows Credential Locker) ? 🤷🏻‍♂️🤷🏻‍♂️🤷🏻‍♂️

I do remember having looked into keyring quite a few times in the last couple of years, but gave up on it quickly each time because I simply didn't understand how to use it. Now I'm somewhat forced to make it work for me because it is the only somewhat reasonable means of authentication for uv - at least until they've added support for a Rust-based solution.

I'd be happy to contribute documentation, but I can't because I don't know how keyring is supposed to work 😞

Originally posted by @dd-ssc in #116

[jaraco]

Thanks for the questions! Happy to clarify and delighted you're interested in helping contribute to the documentation. Having been immersed in the project, I lack the perspective you can bring as a new user. I'll try to answer your questions (to your satisfaction) and hope you'll be willing to refine this into a narrative that will help others avoid the same confusion.

What is system ? 🤷🏻‍♂️

System is a generic term for the context where the username and password are relevant. It might be a computer's hostname, a URL, a service (like PyPI or NPM), or any other string to identify the context. For example, I store some MFA secrets using "{entity} MFA" as the system.

How do I use keyring in the most basic real-world scenario ? 🤷🏻‍♂️🤷🏻‍♂️

At a most basic level, it's a Python de facto standard for storing and retrieving secrets (passwords, tokens, etc.) securely in Python applications and on the command line utilizing platform-specific backends to be secure and somewhat interoperable with other systems.

The most basic scenario really depends on your use-case. You might be coming to keyring because you learned that pip or twine can securely store your passwords. Or you may be wanting to save some secret to retrieve later. Or you may be an integrator wanting to enable your users to only enter their password once and then save it for the future.

Assuming you are just seeking to save a password for use later, the usage is described in the readme. It describes how to set a password and retrieve that password using the keyring. For many users, that just works out of the box. It shows how to do that using the command line tool or the Python API.

So imagine that you just created a password on a website and you want to save that to remember for later. You can do that with:

keyring set https://the.web.site/ my_user_name

Then enter the password when prompted.

Later, when you want to log into that web site again, retrieve the password with

keyring get https://the.web.site/ my_user_name

The password will be emitted to the console. Just copy and paste it into your browser.

If no password was set for the system+username combination, nothing will be emitted.

How do I get / set secrets from / in any of the four recommended keyring backends supported
(macOS Keychain, Freedesktop Secret Service, KDE Wallet, Windows Credential Locker) ? 🤷🏻‍♂️🤷🏻‍♂️🤷🏻‍♂️

By default (without any plugins installed), keyring comes bundled with a few backends for storing and retrieving passwords (the ones you listed) and will automatically filter out ones that aren't available and then choose the highest priority of the ones that are. So if running the library on macOS, the macOS Keychain will be used. On Windows, the Windows Credential Locker will be used. On Linux, the Secret Service will be preferred over the KDE wallet, but if the Secret Service is unavailable and KDE is available, it will be used.

Keyring also supports plugins to enable additional backends. If installed to the same Python environment as keyring is installed, keyring will activate those plugins, which may present additional backends at higher or lower priority. If the plugin-based backend is viable and resolves to a higher priority, it will be used.

When multiple backends are viable and recommended (priority >= 1), they will all be consulted. Passwords will be set in the highest priority backend, but retrieved from any of the backends (in priority order).

I do remember having looked into keyring quite a few times in the last couple of years, but gave up on it quickly each time because I simply didn't understand how to use it. Now I'm somewhat forced to make it work for me because it is the only somewhat reasonable means of authentication for uv

To some extent, it sounds like you may need guidance from uv on how to use keyring. You're not looking for the most basic use-case, but you're looking for a specific use-case involving a project that is supported by keyring.

How is it you're using uv and keyring? What system are you accessing that requires a credential? Are you uploading packages to PyPI and thus need to install an API token? I've not used uv for publishing packages, but I have used twine, which provides Keyring-specific guidance. Unfortunately, even that guidance is old, as it mentions a username but PyPI doesn't accept username/password authentication and only accepts token-based uploads these days. You'll want to ask the uv project how they use keyring and what you need to do to take advantage of it. But perhaps most importantly, the need for secrets becomes increasingly unnecessary if your project is configured to use trusted publishing, in which case you don't need to request tokens nor configure them in any secret store. Instead, you register a continuous integration system with a project and cut releases from that CI without any secrets needed.

I hope that helps. Let me know if you have any more questions.