"""Base protocol for output format writers.

This module defines the interface that all writers must implement,
allowing for multiple output formats in the future.
"""

from pathlib import Path
from typing import List, Protocol

from ..models import Entry


class Writer(Protocol):
    """Protocol defining the interface all writers must implement.

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

    Writers are responsible for converting Entry objects into specific
    output formats (e.g., Readlang CSV, Anki deck, etc.).
    """

    @property
    def name(self) -> str:
        """Human-readable writer name (e.g., 'readlang', 'anki').

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

    @property
    def file_extension(self) -> str:
        """Default file extension for this format (e.g., '.csv', '.txt').

        Returns:
            The file extension including the leading dot
        """
        ...

    def write(
        self,
        entries: List[Entry],
        output_path: Path,
        **options: bool | str | int | float,
    ) -> List[Path]:
        """Write entries to output file(s).

        Args:
            entries: List of Entry objects to write
            output_path: Base path for the output file
            **options: Writer-specific options (e.g., fetch_examples=True)

        Returns:
            List of paths to files created. May be multiple files if the
            writer needs to split output (e.g., for Readlang's 200-entry limit)

        Raises:
            ValueError: If entries are invalid or cannot be written
            IOError: If file writing fails
        """
        ...
