.readthedocs.yaml

@@ -3,7 +3,7 @@ python:
   install:
   - path: .
     extra_requirements:
-      - docs
+      - doc
 
 # required boilerplate readthedocs/readthedocs.org#10401
 build:

NEWS.rst

@@ -1,3 +1,12 @@
+v25.3.0
+=======
+
+Features
+--------
+
+- Deprecated support for empty usernames. Now all backends will reject an empty string as input for the 'username' field when setting a password. Later this deprecation will become a more visible user warning and even later an error. If this warning is triggered in your environment, please consider using a static value (even 'username') or comment in the issue and describe the use-case that demands support for empty usernames. (#668)
+
+
 v25.2.1
 =======
 

keyring/backend.py

@@ -6,10 +6,12 @@
 
 import abc
 import copy
+import functools
 import logging
 import operator
 import os
 import typing
+import warnings
 
 from jaraco.context import ExceptionTrap
 from jaraco.functools import once
@@ -27,18 +29,38 @@
 
 class KeyringBackendMeta(abc.ABCMeta):
     """
-    A metaclass that's both an ABCMeta and a type that keeps a registry of
-    all (non-abstract) types.
+    Specialized subclass behavior.
+
+    Keeps a registry of all (non-abstract) types.
+
+    Wraps set_password to validate the username.
     """
 
     def __init__(cls, name, bases, dict):
         super().__init__(name, bases, dict)
+        cls._register()
+        cls._validate_username_in_set_password()
+
+    def _register(cls):
         if not hasattr(cls, '_classes'):
             cls._classes = set()
         classes = cls._classes
         if not cls.__abstractmethods__:
             classes.add(cls)
 
+    def _validate_username_in_set_password(cls):
+        """
+        Wrap ``set_password`` such to validate the passed username.
+        """
+        orig = cls.set_password
+
+        @functools.wraps(orig)
+        def wrapper(self, system, username, *args, **kwargs):
+            self._validate_username(username)
+            return orig(self, system, username, *args, **kwargs)
+
+        cls.set_password = wrapper
+
 
 class KeyringBackend(metaclass=KeyringBackendMeta):
     """The abstract base class of the keyring, every backend must implement
@@ -103,6 +125,18 @@ def get_password(self, service: str, username: str) -> str | None:
         """Get password of the username for the service"""
         return None
 
+    def _validate_username(self, username: str) -> None:
+        """
+        Ensure the username is not empty.
+        """
+        if not username:
+            warnings.warn(
+                "Empty usernames are deprecated. See #668",
+                DeprecationWarning,
+                stacklevel=3,
+            )
+            # raise ValueError("Username cannot be empty")
+
     @abc.abstractmethod
     def set_password(self, service: str, username: str, password: str) -> None:
         """Set password for the username of the service.

keyring/core.py

@@ -37,6 +37,13 @@ def get_keyring() -> backend.KeyringBackend:
 def disable() -> None:
     """
     Configure the null keyring as the default.
+
+    >>> fs = getfixture('fs')
+    >>> disable()
+    >>> disable()
+    Traceback (most recent call last):
+    ...
+    RuntimeError: Refusing to overwrite...
     """
     root = platform.config_root()
     try:
@@ -47,7 +54,7 @@ def disable() -> None:
     if os.path.exists(filename):
         msg = f"Refusing to overwrite {filename}"
         raise RuntimeError(msg)
-    with open(filename, 'w') as file:
+    with open(filename, 'w', encoding='utf-8') as file:
         file.write('[backend]\ndefault-keyring=keyring.backends.null.Keyring')
 
 

keyring/testing/backend.py

@@ -163,6 +163,12 @@ def test_credential(self):
             ('user2', 'password2'),
         )
 
+    @pytest.mark.xfail("platform.system() == 'Windows'", reason="#668")
+    def test_empty_username(self):
+        with pytest.deprecated_call():
+            self.set_password('service1', '', 'password1')
+        assert self.keyring.get_password('service1', '') == 'password1'
+
     def test_set_properties(self, monkeypatch):
         env = dict(KEYRING_PROPERTY_FOO_BAR='fizz buzz', OTHER_SETTING='ignore me')
         monkeypatch.setattr(os, 'environ', env)

pyproject.toml

@@ -33,21 +33,22 @@ dependencies = [
 dynamic = ["version"]
 
 [project.urls]
-Homepage = "https://github.com/jaraco/keyring"
+Source = "https://github.com/jaraco/keyring"
 
 [project.optional-dependencies]
-testing = [
+test = [
 	# upstream
 	"pytest >= 6, != 8.1.*",
 	"pytest-checkdocs >= 2.4",
 	"pytest-cov",
 	"pytest-mypy",
 	"pytest-enabler >= 2.2",
-	"pytest-ruff >= 0.2.1",
+	"pytest-ruff >= 0.2.1; sys_platform != 'cygwin'",
 
 	# local
+	"pyfakefs",
 ]
-docs = [
+doc = [
 	# upstream
 	"sphinx >= 3.5",
 	"jaraco.packaging >= 9.3",

ruff.toml

@@ -1,6 +1,7 @@
 [lint]
 extend-select = [
 	"C901",
+	"PERF401",
 	"W",
 ]
 ignore = [
@@ -22,7 +23,8 @@ ignore = [
 ]
 
 [format]
-# Enable preview, required for quote-style = "preserve"
+# Enable preview to get hugged parenthesis unwrapping and other nice surprises
+# See https://github.com/jaraco/skeleton/pull/133#issuecomment-2239538373
 preview = true
-# https://docs.astral.sh/ruff/settings/#format-quote-style
+# https://docs.astral.sh/ruff/settings/#format_quote-style
 quote-style = "preserve"

tox.ini

@@ -7,7 +7,7 @@ commands =
 	pytest {posargs}
 usedevelop = True
 extras =
-	testing
+	test
 
 [testenv:diffcov]
 description = run tests and check that diff from main is covered
@@ -22,8 +22,8 @@ commands =
 [testenv:docs]
 description = build the documentation
 extras =
-	docs
-	testing
+	doc
+	test
 changedir = docs
 commands =
 	python -m sphinx -W --keep-going . {toxinidir}/build/html