"""
Symphra Excel库的类型定义和类型别名

提供常用的类型别名和TypedDict定义,用于改进类型提示和IDE支持。
"""

from __future__ import annotations

import io
from pathlib import Path
from typing import TYPE_CHECKING, Any, TypeAlias, TypedDict

if TYPE_CHECKING:
    pass

# ==================== 类型别名 ====================

# 单元格和范围引用
CellRef: TypeAlias = str
"""单元格引用类型 (例如: 'A1', 'B5')"""

RangeRef: TypeAlias = str
"""范围引用类型 (例如: 'A1:B10', 'C1:D20')"""

ColumnRef: TypeAlias = str
"""列引用类型 (例如: 'A', 'AB', 'BC')"""

# 文件路径
FilePath: TypeAlias = str | Path
"""文件路径类型 (字符串或Path对象)"""

# 颜色值
ColorValue: TypeAlias = str
"""颜色值类型 (十六进制字符串,例如: '#FF0000')"""

# 图像源
ImageSource: TypeAlias = str | Path | bytes | io.BytesIO
"""图像源类型 (文件路径、字节数据或BytesIO对象)"""

# 单元格值
CellValue: TypeAlias = str | int | float | bool | None
"""单元格可以包含的值类型"""

# 行数据
RowData: TypeAlias = list[CellValue]
"""行数据类型 (单元格值列表)"""

# 工作簿模式
WorkbookMode: TypeAlias = str
"""工作簿模式类型 ('default', 'read_only', 'write_only')"""


# ==================== TypedDict 定义 ====================


class ImageOptions(TypedDict, total=False):
    """图片选项类型定义"""

    width: int
    """图片宽度(像素)"""

    height: int
    """图片高度(像素)"""

    maintain_aspect_ratio: bool
    """是否保持宽高比"""

    margin: int
    """边距(像素)"""

    anchor_to_cell: bool
    """是否锚定到单元格"""

    move_with_cells: bool
    """是否随单元格移动"""

    resize_with_cells: bool
    """是否随单元格调整大小"""

    position: str
    """位置 ('center', 'top-left', 'top-right', 'bottom-left', 'bottom-right')"""


class TemplateContext(TypedDict, total=False):
    """模板上下文类型定义"""

    title: str
    """标题"""

    date: str
    """日期"""

    author: str
    """作者"""

    data: list[dict[str, Any]]
    """数据列表"""

    variables: dict[str, Any]
    """变量字典"""


class WorkbookProperties(TypedDict, total=False):
    """工作簿属性类型定义"""

    title: str
    """标题"""

    creator: str
    """创建者"""

    description: str
    """描述"""

    subject: str
    """主题"""

    created: str
    """创建日期"""

    modified: str
    """修改日期"""

    last_modified_by: str
    """最后修改者"""

    category: str
    """分类"""

    keywords: str
    """关键词"""


class StyleOptions(TypedDict, total=False):
    """样式选项类型定义"""

    font_name: str
    """字体名称"""

    font_size: int
    """字体大小"""

    font_color: str
    """字体颜色"""

    bold: bool
    """是否粗体"""

    italic: bool
    """是否斜体"""

    underline: bool
    """是否下划线"""

    fill_color: str
    """填充颜色"""

    border_style: str
    """边框样式"""

    border_color: str
    """边框颜色"""

    alignment: str
    """对齐方式"""

    number_format: str
    """数字格式"""


class BatchImageData(TypedDict, total=False):
    """批量图片数据类型定义"""

    image: ImageSource
    """图片源"""

    cell: CellRef
    """目标单元格"""

    width: int
    """宽度(像素)"""

    height: int
    """高度(像素)"""

    options: ImageOptions
    """图片选项"""


class MemoryConfig(TypedDict, total=False):
    """内存配置类型定义"""

    max_memory_usage_mb: int
    """最大内存使用量(MB)"""

    batch_size: int
    """批处理大小"""

    streaming_chunk_size: int
    """流式处理块大小"""

    enable_compression: bool
    """是否启用压缩"""

    enable_caching: bool
    """是否启用缓存"""

    cache_size_mb: int
    """缓存大小(MB)"""

    gc_threshold: int
    """垃圾回收阈值"""

    lazy_loading: bool
    """是否启用延迟加载"""


class ProcessingStats(TypedDict, total=False):
    """处理统计信息类型定义"""

    rows_processed: int
    """已处理行数"""

    rows_skipped: int
    """跳过行数"""

    memory_usage_mb: float
    """内存使用量(MB)"""

    processing_time: float
    """处理时间(秒)"""

    errors: list[str]
    """错误列表"""


# ==================== 回调类型 ====================

# 数据处理回调
DataProcessor: TypeAlias = Any  # Callable[[list[list[Any]]], list[Any]]
"""数据处理器回调类型"""

# 进度回调
ProgressCallback: TypeAlias = Any  # Callable[[int, int], None]
"""进度回调类型 (当前进度, 总数)"""

# 错误处理回调
ErrorHandler: TypeAlias = Any  # Callable[[Exception], None]
"""错误处理器回调类型"""
