from abc import ABC, abstractmethod
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    import httpx


class Validator(ABC):
    """
    Abstract base class for API key validation strategies.
    
    This interface follows the Strategy pattern, allowing different
    validation approaches for various API providers. Each validator
    implements provider-specific logic to verify key validity.
    
    Attributes:
        name: Human-readable name of the validator
        
    Example:
        class CustomValidator(Validator):
            async def validate(self, client, key):
                # Implementation here
                return True
    """
    
    name: str = "base"
    
    @abstractmethod
    async def validate(self, client: "httpx.AsyncClient", key: str) -> bool:
        """
        Validate an API key against the provider's authentication endpoint.
        
        Args:
            client: An async HTTP client for making requests
            key: The API key to validate
            
        Returns:
            True if the key is valid, False otherwise
            
        Note:
            Implementations should handle all exceptions gracefully
            and return False on any error condition.
        """
        pass
    
    def __repr__(self) -> str:
        return f"<{self.__class__.__name__}>"
