"""Base protocol for input format parsers.

This module defines the interface that all parsers must implement,
allowing for easy addition of new input formats.
"""

from pathlib import Path
from typing import List, Protocol

from ..models import Entry


class Parser(Protocol):
    """Protocol defining the interface all parsers must implement.

    Using Protocol instead of ABC allows duck typing while still
    providing type checking and IDE support. Parsers don't need to
    explicitly inherit from this class.

    Parsers are responsible for reading vocabulary files in various
    formats and converting them to a list of Entry objects.
    """

    @property
    def name(self) -> str:
        """Human-readable parser name (e.g., 'pod101', 'languagereactor').

        This name is used in the CLI and for parser registration.

        Returns:
            The name of this parser
        """
        ...

    @property
    def description(self) -> str:
        """Brief description of what format this parser handles.

        This description is shown in help text and when listing available parsers.

        Returns:
            A human-readable description of the input format

        Example:
            "Pod101 vocabulary export (UTF-16 CSV with Word,English columns)"
        """
        ...

    def parse(self, file_path: Path) -> List[Entry]:
        """Parse the input file and return a list of Entry objects.

        Args:
            file_path: Path to the input file to parse

        Returns:
            List of Entry objects extracted from the file

        Raises:
            FileNotFoundError: If the file doesn't exist
            ValueError: If the file format is invalid or cannot be parsed
            UnicodeDecodeError: If the file encoding cannot be detected

        Example:
            >>> parser = Pod101Parser()
            >>> entries = parser.parse(Path("words.csv"))
            >>> len(entries)
            42
            >>> entries[0].word
            'ainakin'
            >>> entries[0].translation
            'at least'
        """
        ...
