"""Config and DatabaseAdapter Protocol."""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any, Protocol, runtime_checkable


@dataclass
class Config:
    """Configuration for set_db_data / verify_db_data.

    Args:
        variables: Mapping of variable names to values, used to resolve
            ``$var()`` expressions in YAML fixtures.
    """

    variables: dict[str, object] = field(default_factory=dict)


@runtime_checkable
class DatabaseAdapter(Protocol):
    """Protocol that every database adapter must implement.

    Adapters translate the generic clear/write/read operations into
    database-specific calls.
    """

    def clear_group(self, group: str, parent_path: str) -> None: ...

    def write_record(self, group: str, parent_path: str, data: dict[str, Any]) -> dict[str, Any]: ...

    def read_records(self, group: str, parent_path: str) -> list[dict[str, Any]]: ...


@runtime_checkable
class HierarchicalAdapter(DatabaseAdapter, Protocol):
    """Extended adapter protocol for databases that support nested groups.

    Implementations must additionally provide ``build_child_path`` so
    that ``__children__`` in YAML fixtures can be resolved.
    """

    def build_child_path(self, parent_path: str, group: str, record: dict[str, Any]) -> str: ...
