Add line comments and shuffle logging in secrets module

confidence/secrets.py

@@ -6,7 +6,10 @@
 LOG = logging.getLogger(__name__)
 
 
+# default key for a mapping with a single key that signals being a secret
 DEFAULT_SINGLE_KEY_IDENTIFIER = '$secret'
+# default keys within a secret mapping to be passed to a callback
+# (this deliberately mimics keyring's get_password function)
 DEFAULT_SINGLE_KEY_ARGS = ('service', 'username')
 
 
@@ -46,11 +49,19 @@ def resolve_n_key_secret_callback(value: typing.Mapping[str, typing.Any],
                                   single_key: str,
                                   args: typing.Iterable[str]) -> typing.Optional[str]:
     try:
-        secret = value[single_key]
-        return callback(*(secret[arg] for arg in args))
+        mapping = value[single_key]
+        LOG.debug(f'getting values for ({", ".join(args)}) to use as secret retrieval parameters')
+        parameters = tuple(mapping[arg] for arg in args)
+        # logging parameters' *values* might still leak things a user would rather not log
+        LOG.info(f'passing {len(parameters)} to secret callback {callback}')
+        return callback(*parameters)
     except KeyError as e:
-        missing_key = e.args[0] if e.args[0] == single_key else f'{single_key}.{e.args[0]}'
-        LOG.warning(f'resolving secret failed, missing key {missing_key}')
+        if missing_key := e.args[0] if e.args[0] == single_key else f'{single_key}.{e.args[0]}':
+            LOG.warning(f'resolving secret failed, missing key {missing_key}')
+        else:
+            LOG.warning(f'resolving secret failed')
+        # logging out of the way, there's not actually anything we can do to fix the error here
+        # if the caller was Configuration.get(), it will handle the KeyError according to it's policies
         raise
 
 
@@ -59,6 +70,8 @@ def __init__(self,
                  callback: SecretCallback,
                  single_key: str = DEFAULT_SINGLE_KEY_IDENTIFIER,
                  args: typing.Iterable[str] = DEFAULT_SINGLE_KEY_ARGS):
+        # use is_single_key_secret and resolve_n_key_secret_callback to turn the callback we've been handed here into
+        # something that will implement the Secrets protocol
         self.matches = partial(
             is_single_key_secret,
             key=single_key,