"""Data-warehouse adapter contract."""

from dataclasses import dataclass
from typing import Protocol, runtime_checkable

from tht.execute import ExecResult, PlanSummary
from tht.mschema.models import PhysicalSchema


@dataclass(frozen=True)
class DwhCapabilities:
    introspection: bool = True
    explain: bool = True
    sampling: bool = True
    distinct_values: bool = True


@dataclass(frozen=True)
class DwhHealth:
    ok: bool
    detail: str | None = None
    database: str | None = None
    schema: str | None = None
    endpoint: str | None = None
    read_only: bool | None = None
    writable_tables: tuple[str, ...] = ()
    can_create: bool = False
    error_kind: str | None = None


@dataclass(frozen=True)
class DistinctValues:
    values: list[object]
    truncated: bool


class UnsupportedCapability(Exception):
    """Raised when an adapter cannot provide an optional DWH operation."""


@runtime_checkable
class DwhAdapter(Protocol):
    @property
    def capabilities(self) -> DwhCapabilities: ...

    def health(self) -> DwhHealth: ...

    def introspect(self) -> PhysicalSchema: ...

    def run_query(self, sql: str, *, limit: int) -> ExecResult: ...

    def explain(self, sql: str) -> PlanSummary: ...

    def sample_column(self, table: str, column: str, *, limit: int) -> list[object]: ...

    def distinct_values(self, table: str, column: str, *, limit: int) -> DistinctValues: ...