"""Base class for data sources."""

from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Any

from pydantic import BaseModel, Field


class DataResult(BaseModel):
    """Standardized result from any data source."""
    source: str = ""
    data: Any = None
    metadata: dict[str, Any] = Field(default_factory=dict)
    # metadata includes: unit, time_range, update_date, confidence, etc.
    error: str | None = None
    cached: bool = False


class DataSource(ABC):
    """Abstract data source."""
    name: str = "base"
    description: str = ""

    def supports(self, data_type: str, country: str | None = None) -> bool:
        """Return True if this source can handle this data type / country."""
        return True

    @abstractmethod
    async def fetch(
        self, query: str, *, data_type: str = "general", country: str | None = None, **kwargs,
    ) -> DataResult:
        ...