"""BaseParser — protocolo abstracto para parsers del registry."""

from __future__ import annotations

from abc import ABC, abstractmethod
from pathlib import Path
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from parse_result import ParseResult


class BaseParser(ABC):
    """Protocolo abstracto que todo parser del registry debe implementar.

    Define la interfaz minima para parsers extensibles: soportar extensiones
    de archivo, parsear desde path o desde contenido en memoria. El
    ParserRegistry usa esta interfaz para despachar parsing al parser correcto.

    Attributes:
        supported_extensions: Lista de extensiones que este parser maneja
                              (ej: [".md", ".markdown"]).
    """

    @property
    @abstractmethod
    def supported_extensions(self) -> list[str]:
        """Lista de extensiones soportadas (con punto, lowercase).

        Returns:
            Lista de strings como [".md", ".markdown"].
        """
        ...

    @abstractmethod
    async def parse(self, source: str | Path, **kwargs) -> "ParseResult":
        """Parsea un archivo desde su path o URL.

        Args:
            source: Path al archivo, directorio o URL a parsear.
            **kwargs: Argumentos adicionales especificos del parser.

        Returns:
            ParseResult con el arbol de nodos del documento.
        """
        ...

    @abstractmethod
    async def parse_content(
        self,
        content: str,
        source_path: str | None = None,
        **kwargs,
    ) -> "ParseResult":
        """Parsea un string de contenido directamente en memoria.

        Args:
            content:     Contenido del documento como string.
            source_path: Path original opcional, solo para metadata.
            **kwargs:    Argumentos adicionales especificos del parser.

        Returns:
            ParseResult con el arbol de nodos del documento.
        """
        ...

    def can_parse(self, path: str) -> bool:
        """Indica si este parser puede manejar el archivo dado.

        Args:
            path: Path del archivo a verificar.

        Returns:
            True si la extension del archivo esta en supported_extensions.
        """
        return Path(path).suffix.lower() in self.supported_extensions
