Remember which keyring backend was found, instead of searching every run

[Korijn]

Replaces the first version of this PR, which printed a hint telling the user to set PYTHON_KEYRING_BACKEND themselves. keycmd does it itself now, and the branch was rebuilt from master — there is nothing left of the hint machinery.

Left to itself, keyring works out which backend to use by loading every backend that every installed package registers and keeping the best of them. That search runs again on every invocation and is the single most expensive thing a keycmd run does: measured on the machine this was written on it is the difference between 0.156s and 0.085s, and it grows with the number of packages installed and with any backend that takes its time deciding it is not viable.

The answer, though, is the same every time until the packages on the machine change. So backend.py writes it down the first time a run needs a credential and loads that backend by name afterwards — the shortcut PYTHON_KEYRING_BACKEND buys, without anyone having to know the variable exists. Nothing to read, nothing to set; the second run is simply faster than the first.

keycmd: keyring backend: keyrings.alt.file.PlaintextKeyring (found in 0.12s)   # the first run
keycmd: keyring backend: keyrings.alt.file.PlaintextKeyring (remembered)       # every run after

The note, and how far it is trusted

One line, in the folder the platform keeps files a program can afford to lose: %LOCALAPPDATA% on windows, ~/Library/Caches on macOS, $XDG_CACHE_HOME on linux. Deleting it costs one slow run. It is treated as untrusted input throughout:

• is_backend_name keeps anything that is not a dotted class name from reaching an import, so a file that has been truncated or scribbled in is worth no more than a fresh search.
• A name that no longer loads sends the run back to searching, and is replaced. load_keyring asks the class for its priority on the way, which is how keyring itself decides a backend is viable, so a backend that was uninstalled and one whose daemon stopped are both caught by the same except.
• backend_name looks through the chainer, which is not a backend but the search wearing one's clothes — writing that down would leave the search in place — and names the backend it would have reached first, so the credentials keep coming from where they already did.
• PYTHON_KEYRING_BACKEND outranks the note and is never written over.
• A search that found nothing is not an answer, and is not remembered.
• The write goes through a temporary file and an os.replace, so a second keycmd running at the same moment reads either the old name or the new one. A cache folder that cannot be written is a slow run, not a failed one.

The two commands

What keycmd cannot notice by itself is a backend that still loads but is no longer the one you want — you installed a better one, or removed a package and want the runner-up. So both steps are available on purpose:

❯ keycmd --detect-backend
keycmd: remembered keyring backend keyring.backends.SecretService.Keyring, found in 0.12s

❯ keycmd --reset-backend
keycmd: forgot the remembered keyring backend

Errors that used to be tracebacks

Two ways of ending up with no backend reached the user as a traceback, and both are now errors that say what to do — logs.error grew the hint lines they need:

❯ keycmd 'npm install'
keycmd: error: keyring has no backend to read credentials from
keycmd: hint: install one for this platform, or name one you have with PYTHON_KEYRING_BACKEND
keycmd: hint: see https://github.com/jaraco/keyring#third-party-backends

Inside a distribution that error also points at the WSL section of the README, which is what the situation almost always is. A PYTHON_KEYRING_BACKEND that cannot be loaded is reported with the value it was given.

Testing

156 passed / 16 skipped with no keyring available, 169 / 3 with one. tests/test_backend.py covers the cache paths of all three platforms, the name check, remembering and forgetting, an unwritable cache, a scribbled note, a stale note, and every branch of load_backend; tests/test_cli.py covers the two flags and the run that quietly writes the note. Two things worth knowing for future tests, and now in CLAUDE.md: the autouse cache_home fixture points CACHE_HOME at tmp_path so a run never touches the note the machine is using, and a test about remembering has to delenv PYTHON_KEYRING_BACKEND first, since the README suggests running the suite with it set and it outranks everything here.

keyring stays out of the import path of a run that looks up no credential, and test_cli_import_stays_lean still passes. The version is untouched, since that moves in its own commits.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CRYugGcVh3wvC5a5pzwKU3