yera.creds.loaders

Credential store loading and validation helpers.

Symbols

def flatten_json — Recursively flatten *obj* into dotted keys rooted at *prefix*.
def is_leaf — Return ``True`` when *key* is a stored credential leaf.
def is_namespace — Return ``True`` when leaves exist under *key* (proper prefix).
def leaves_under — Return all leaf entries whose key starts with ``path + '.'``.
def load_credentials — Load the credential store from disk.
def raise_if_credential_group_key_prefix_conflict — Raise if *credentials* keys contain a leaf-namespace prefix pair.
def raise_if_flat_credential_keys_prefix_conflict — Raise if any key is a proper dotted prefix of another (leaf-namespace conflict).
def require_credential_entry_string_value — Return *entry*'s ``value`` after validating against :class:`CredentialEntry`.
def validate_credential_group_name — Validate a credential group name.
def validate_credential_key — Validate a credential key as a dotted path.

flatten_json

flatten_json(
    obj: dict[str, Any],
    prefix: str,
) → dict[str, str]

Recursively flatten obj into dotted keys rooted at prefix.

Returns a flat {dotted_key: str_value} mapping.

Raises

CredentialKeyError

a flattened key fails structural validation, two source entries produce the same flattened key (duplicate collision), or two flattened keys stand in a prefix relationship (leaf-namespace conflict).

``TypeError``

a leaf value is not a string.

is_leaf

is_leaf(
    key: str,
    creds: dict[str, dict[str, Any]],
) → bool

Return True when key is a stored credential leaf.

is_namespace

is_namespace(
    key: str,
    creds: dict[str, dict[str, Any]],
) → bool

Return True when leaves exist under key (proper prefix).

leaves_under

leaves_under(
    path: str,
    creds: dict[str, dict[str, Any]],
) → dict[str, dict[str, Any]]

Return all leaf entries whose key starts with path + '.'.

load_credentials

load_credentials() → CredentialStore

Load the credential store from disk.

Three-step sequence (as per spec):

  1. Read and deserialise JSON. Absent file → empty CredentialStore().
  2. Pre-construction version check. Unknown version → CredentialVersionError.
  3. Construct CredentialStore(**data).

Raises

CredentialStoreCorruptError

file exists but contains invalid JSON or a non-object top-level value.

CredentialVersionError

the version field is not in _SUPPORTED_VERSIONS.

CredentialKeyError

a credential group contains two dotted keys where one is a proper prefix of the other (leaf-namespace conflict).

raise_if_credential_group_key_prefix_conflict

raise_if_credential_group_key_prefix_conflict(
    credentials: dict[str, Any],
    group_name: str,
    credentials_file: Path,
) → None

Raise if credentials keys contain a leaf-namespace prefix pair.

Raises

CredentialKeyError

includes group_name and credentials_file in the message.

raise_if_flat_credential_keys_prefix_conflict

raise_if_flat_credential_keys_prefix_conflict(
    keys: Iterable[str],
    prefix_message: str,
) → None

Raise if any key is a proper dotted prefix of another (leaf-namespace conflict).

keys are dotted credential paths. After sorting, only adjacent pairs need checking: if K immediately precedes K.<segment> lexicographically among sorted keys, every prefix relationship appears as some adjacent pair.

Raises

CredentialKeyError

two keys stand in prefix relationship.

require_credential_entry_string_value

require_credential_entry_string_value(
    dotted_key: str,
    entry: object,
) → str

Return entry's value after validating against :class:CredentialEntry.

Credential groups store raw dicts so entries can be validated lazily; this function applies the same shape the CLI writes when materialising secrets.

Raises

CredentialKeyError

entry is not a well-formed credential object.

validate_credential_group_name

validate_credential_group_name(
    name: str,
) → None

Validate a credential group name.

A valid credential group name: - Is non-empty and not whitespace-only. - Contains no dots (.). - Contains no control characters (U+0000-U+001F).

Raises

CredentialGroupNameError

the name fails any structural rule.

validate_credential_key

validate_credential_key(
    key: str,
) → None

Validate a credential key as a dotted path.

A valid key: - Is non-empty. - When split on ".", produces only non-empty segments (no leading dot, trailing dot, or consecutive dots). - Contains no control characters (U+0000-U+001F) in any segment.

Raises

CredentialKeyError

the key fails any structural rule.