"""Reader 基类，定义所有文档阅读器的公共接口。"""

from abc import ABC, abstractmethod
from pathlib import Path
from typing import List, Optional, Tuple


class BaseReader(ABC):
    """文档阅读器基类。"""

    @abstractmethod
    def supports(self, file_path: str) -> bool:
        """
        判断是否支持给定的输入（轻量检查）。

        仅做初步判断（如扩展名、URL 模式），不进行完整验证。
        完整验证（文件存在、格式有效性）在 parse() 中进行。
        不访问文件系统，不打开文件。

        Args:
            file_path: 文件路径或 URL

        Returns:
            True 如果可能支持，False 否则
        """
        pass

    @abstractmethod
    def parse(self, file_path: str) -> Tuple[Optional[str], List[str]]:
        """
        解析文件并返回 Markdown 内容。

        需要检查文件存在和格式有效性，然后执行实际解析逻辑。

        Args:
            file_path: 文件路径或 URL

        Returns: (content, failures)
        - content: 成功时返回 Markdown 内容，失败时返回 None
        - failures: 各解析器的失败原因列表

        异常处理规范：
        -----------------
        文档读取系统采用三级降级链设计，使用元组返回而非抛出异常：

        1. Parser 层（最底层）：
           - 每个 parser 函数返回 (content, error) 元组
           - 必须捕获所有预期异常（ImportError, OSError, 解析异常等）
           - 返回清晰的错误信息，如 "库未安装"、"解析失败: xxx"

        2. Reader 层（中间层）：
           - 遍历多个 parser，收集失败原因
           - 必须在 parser 循环中添加 try-except 防护层
           - 捕获意外异常并记录："[意外异常] ExceptionType: message"
           - 任一 parser 成功即返回，失败则继续尝试下一个

        3. 调用层（最顶层）：
           - parse_input() 遍历多个 reader
           - 无 reader 支持时抛出 ReaderNotFoundError

        设计原则：
        - "失败是预期分支，而非异常情况"
        - 元组返回优于异常抛出（除顶层外）
        - 双层异常保护：Parser 层处理预期错误，Reader 层捕获意外异常
        """
        pass