"""
基类模块,提供通用的抽象基类和混入类。
"""

from abc import ABC, abstractmethod
from typing import Any

from .utils.memory_manager import MemoryManager, MemoryStrategy


class BaseMemoryWorkbook(ABC):
    """
    内存工作簿的抽象基类,定义通用的内存管理和资源管理接口。

    这个基类提供:
    1. 统一的内存管理器初始化
    2. 上下文管理器协议支持
    3. 资源清理接口
    4. 内存管理公共逻辑

    子类需要实现:
    - cleanup(): 特定的资源清理逻辑
    """

    def __init__(
        self,
        memory_manager: MemoryManager | None = None,
        default_strategy: MemoryStrategy = MemoryStrategy.STANDARD,
    ) -> None:
        """
        初始化基础内存工作簿。

        Args:
            memory_manager: 可选的内存管理器实例,如果为None则创建新实例
            default_strategy: 默认内存管理策略

        Note:
            子类应在调用super().__init__()后注册自身到内存管理器
        """
        self._memory_manager = memory_manager or MemoryManager()
        if memory_manager is None:
            # 只在创建新实例时设置默认策略
            self._memory_manager.set_strategy(default_strategy)

    @property
    def memory_manager(self) -> MemoryManager:
        """
        获取内存管理器实例。

        Returns:
            MemoryManager实例
        """
        return self._memory_manager

    @abstractmethod
    def cleanup(self) -> None:
        """
        清理资源的抽象方法。

        子类必须实现具体的清理逻辑,如:
        - 关闭文件句柄
        - 释放内存缓冲区
        - 清理临时文件

        Note:
            此方法在上下文管理器退出时自动调用
        """
        pass

    def __enter__(self) -> "BaseMemoryWorkbook":
        """
        上下文管理器入口。

        Returns:
            self实例
        """
        return self

    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
        """
        上下文管理器出口,自动调用cleanup()。

        Args:
            exc_type: 异常类型
            exc_val: 异常值
            exc_tb: 异常追踪信息
        """
        self.cleanup()

    def get_memory_usage(self) -> dict[str, Any]:
        """
        获取内存使用情况的基础实现。

        Returns:
            内存使用统计信息字典

        Note:
            子类可以重写此方法以添加更多统计信息
        """
        return {
            "memory_strategy": self._memory_manager.strategy.value,
            "registered_objects": self._memory_manager.get_registered_object_count(),
            "cache_entries": self._memory_manager.get_cache_entry_count(),
            "memory_usage_mb": self._memory_manager.get_memory_usage_mb(),
        }

    def optimize_memory(self) -> dict[str, Any]:
        """
        优化内存使用。

        Returns:
            优化统计信息
        """
        return self._memory_manager.optimize_memory()


class WorkbookOperationsMixin:
    """
    工作簿操作的混入类,提供通用的工作表管理方法。

    这个混入类假设子类具有:
    - _workbook 属性 (Workbook实例)

    提供的方法:
    - get_sheet_names(): 获取所有工作表名称
    - to_bytes(): 转换为字节数据 (需要子类实现具体逻辑)
    """

    _workbook: Any  # 类型注解,实际为 Workbook

    def get_sheet_names(self) -> list[str]:
        """
        获取所有工作表名称。

        Returns:
            工作表名称列表

        Raises:
            AttributeError: 如果 _workbook 未初始化
        """
        if not hasattr(self, "_workbook"):
            raise AttributeError("_workbook 未初始化")
        return self._workbook.sheetnames
