Determine less messy keychain for Linux

[strawgate]

Right now if you try to use the keychain store on Linux it will fail to compile the package on Linux systems without dbus, this prevents us from doing runtime checking as you can't even run the library

Let's figure out a way to do this where we can gracefully fallback to runtime errors on systems without a keychain

[github-actions]

Claude finished @strawgate's task in 4m 13s —— View job

---

Recommendation

The current implementation already provides graceful runtime fallback - no code changes are needed. However, the keyring-linux extra in pyproject.toml includes dbus-python, which fails to compile without system D-Bus headers. This extra should be removed or replaced.

Findings

Current State

1. keyring library already handles this gracefully: The keyring library (v25.6.0) uses secretstorage + jeepney (pure Python D-Bus implementation) as its Linux backend. When D-Bus is unavailable, it falls back to a fail.Keyring backend that raises NoKeyringError at runtime, not import time.

2. Verified behavior on this Linux runner (no D-Bus):

   from key_value.aio.stores.keyring import KeyringStore  # ✓ Imports fine
   store = KeyringStore()
   await store.put(...)  # ✓ Raises NoKeyringError at runtime

3. The problematic extra: The keyring-linux extra includes dbus-python>=1.4.0, which requires system D-Bus development headers (libdbus-1-dev) to compile. This is the source of the compile-time failure you're experiencing.

Why dbus-python was originally included

The dbus-python library provides a native D-Bus binding used by the KWallet backend on KDE systems. However:

• Modern versions of keyring use jeepney (pure Python) for the SecretService backend
• KWallet is rarely used outside KDE environments
• The compilation requirement creates a poor user experience

Current dependency structure

keyring = ["keyring>=25.6.0"]              # Works - uses jeepney/secretstorage
keyring-linux = ["keyring>=25.6.0", "dbus-python>=1.4.0"]  # Fails to compile

Verification

I tested on this Linux GitHub Actions runner:

# keyring imports fine and provides runtime error
$ uv run python3 -c "from key_value.aio.stores.keyring import KeyringStore; print('OK')"
OK

$ uv run python3 -c "import keyring; print(keyring.get_keyring())"
keyring.backends.fail.Keyring (priority: 0)

# dbus-python fails to compile
$ uv pip install dbus-python
× Failed to build `dbus-python==1.4.0`
  Run-time dependency dbus-1 found: NO (tried pkgconfig and cmake)

Detailed Action Plan

Option 1: Remove keyring-linux extra (Recommended)

The keyring-linux extra serves no practical purpose since:

1. The base keyring extra already works on Linux via jeepney
2. dbus-python only adds KWallet support, which most users don't need
3. Users who specifically need KWallet can install dbus-python manually

Changes:

1. Remove keyring-linux line from pyproject.toml:44
2. Update any documentation referencing keyring-linux
3. Run uv lock to update the lockfile

Option 2: Make keyring-linux a documentation alias

If you want to preserve backwards compatibility for users who might have keyring-linux in their dependencies:

1. Change keyring-linux to be identical to keyring:

   keyring-linux = ["keyring>=25.6.0"]  # Alias for keyring, kept for compatibility

Option 3: Add a file-based fallback backend

For users who want keyring functionality on systems without D-Bus, add a keyrings.alt dependency:

keyring = ["keyring>=25.6.0"]
keyring-file = ["keyring>=25.6.0", "keyrings.alt>=4.0.0"]  # File-based fallback

This provides an encrypted file-based backend that doesn't require D-Bus.

Note: This option adds complexity and keyrings.alt backends have security implications.

Related Files

File	Relevance	Lines
pyproject.toml	Contains the keyring-linux extra that includes dbus-python	43-44
src/key_value/aio/stores/keyring/store.py	KeyringStore implementation - no changes needed	-
tests/stores/keyring/test_keyring.py	Tests skip Linux - could add Linux test with mocked backend	36

Related Webpages

Name	URL	Relevance
keyring - Moving forward with SecretStorage and D-Bus bindings	jaraco/keyring#301	Original discussion about switching from dbus-python to jeepney
keyring - Import fails when secretstorage unavailable	jaraco/keyring#338	Shows how keyring now handles missing D-Bus gracefully
keyring PyPI	https://pypi.org/project/keyring/	Current keyring documentation and backend options
keyrings.alt PyPI	https://pypi.org/project/keyrings.alt/	Alternative file-based backends

---

Why is Claude responding? | Type @claude to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[strawgate]

@claude make a PR please

[github-actions]

Claude finished @strawgate's task in 1m 38s —— View job • claude/issue-294-20260203-0845 • Create PR ➔

---

PR Ready

• Gather context and understand the recommendation
• Remove the keyring-linux extra from pyproject.toml
• Update uv.lock file (removed dbus-python)
• Run linting and type checking (passed)
• Commit and push changes

Summary

Removed the keyring-linux optional dependency extra that included dbus-python>=1.4.0, which requires system D-Bus development headers (libdbus-1-dev) to compile.

Why this is safe:

• The base keyring extra already works on Linux via jeepney (pure Python D-Bus implementation)
• When D-Bus is unavailable, keyring gracefully falls back to a fail.Keyring backend that raises NoKeyringError at runtime, not import time
• Users who specifically need KWallet support can install dbus-python manually

--- | Branch: claude/issue-294-20260203-0845

---

Why is Claude responding? | Type @claude to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.