类型定义参考¶
本页面提供Symphra Excel库中所有类型定义和TypedDict的详细参考。
概述¶
type_definitions.py模块提供了完整的类型别名和TypedDict定义，用于改进类型提示和IDE支持。这些类型定义使代码更加清晰，并提供更好的开发体验。
类型别名 (Type Aliases)¶
单元格和范围引用¶
CellRef: TypeAlias = str
"""单元格引用类型 (例如: 'A1', 'B5')"""
RangeRef: TypeAlias = str
"""范围引用类型 (例如: 'A1:B10', 'C1:D20')"""
ColumnRef: TypeAlias = str
"""列引用类型 (例如: 'A', 'AB', 'BC')"""
示例用法:
from symphra_excel.utils.type_definitions import CellRef, RangeRef
def set_cell_value(cell: CellRef, value: str) -> None:
"""设置单元格值"""
pass
def get_range_values(range_ref: RangeRef) -> list[list[str]]:
"""获取范围值"""
pass
文件路径¶
示例用法:
from symphra_excel.utils.type_definitions import FilePath
def load_workbook(file_path: FilePath) -> Workbook:
"""加载工作簿"""
pass
颜色值¶
示例用法:
from symphra_excel.utils.type_definitions import ColorValue
def set_fill_color(color: ColorValue) -> None:
"""设置填充颜色"""
pass
# 使用
set_fill_color("#FF0000") # 红色
set_fill_color("FF0000") # 红色（不带#）
图像源¶
示例用法:
from symphra_excel.utils.type_definitions import ImageSource
def insert_image(image_source: ImageSource) -> None:
"""插入图片"""
pass
# 使用
insert_image("logo.png") # 文件路径
insert_image(Path("logo.png")) # Path对象
insert_image(b"\x89PNG\r\n\x1a\n...") # 字节数据
insert_image(io.BytesIO(image_bytes)) # BytesIO对象
单元格值¶
示例用法:
from symphra_excel.utils.type_definitions import CellValue
def set_value(value: CellValue) -> None:
"""设置单元格值"""
pass
# 使用
set_value("文本") # 字符串
set_value(123) # 整数
set_value(45.67) # 浮点数
set_value(True) # 布尔值
set_value(None) # None值
行数据¶
示例用法:
from symphra_excel.utils.type_definitions import RowData
def set_row_data(row_data: RowData) -> None:
"""设置行数据"""
pass
# 使用
set_row_data(["产品A", 100, 50.5, True])
工作簿模式¶
示例用法:
from symphra_excel.utils.type_definitions import WorkbookMode
def create_workbook(mode: WorkbookMode = "default") -> Workbook:
"""创建工作簿"""
pass
TypedDict 定义¶
ImageOptions - 图片选项¶
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')"""
示例用法:
from symphra_excel.utils.type_definitions import ImageOptions
options: ImageOptions = {
"width": 100,
"height": 100,
"margin": 8,
"maintain_aspect_ratio": True,
}
TemplateContext - 模板上下文¶
class TemplateContext(TypedDict, total=False):
"""模板上下文类型定义"""
title: str
"""标题"""
date: str
"""日期"""
author: str
"""作者"""
data: list[dict[str, Any]]
"""数据列表"""
variables: dict[str, Any]
"""变量字典"""
示例用法:
from symphra_excel.utils.type_definitions import TemplateContext
context: TemplateContext = {
"title": "月度报告",
"date": "2024-11-02",
"author": "张三",
"data": [
{"name": "产品A", "value": 100},
{"name": "产品B", "value": 200},
],
}
WorkbookProperties - 工作簿属性¶
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
"""关键词"""
示例用法:
from symphra_excel.utils.type_definitions import WorkbookProperties
props: WorkbookProperties = {
"title": "销售报告",
"creator": "系统",
"description": "2024年第一季度销售数据",
"category": "报表",
"keywords": "销售,报表,2024",
}
StyleOptions - 样式选项¶
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
"""数字格式"""
示例用法:
from symphra_excel.utils.type_definitions import StyleOptions
style: StyleOptions = {
"font_name": "Arial",
"font_size": 12,
"bold": True,
"fill_color": "#FF0000",
"alignment": "center",
}
BatchImageData - 批量图片数据¶
class BatchImageData(TypedDict, total=False):
"""批量图片数据类型定义"""
image: ImageSource
"""图片源"""
cell: CellRef
"""目标单元格"""
width: int
"""宽度(像素)"""
height: int
"""高度(像素)"""
options: ImageOptions
"""图片选项"""
示例用法:
from symphra_excel.utils.type_definitions import BatchImageData
batch_data: BatchImageData = {
"image": "logo.png",
"cell": "A1",
"width": 100,
"height": 50,
"options": {"margin": 8},
}
MemoryConfig - 内存配置¶
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
"""是否启用延迟加载"""
示例用法:
from symphra_excel.utils.type_definitions import MemoryConfig
config: MemoryConfig = {
"max_memory_usage_mb": 512,
"batch_size": 1000,
"enable_compression": True,
"enable_caching": True,
"cache_size_mb": 64,
}
ProcessingStats - 处理统计信息¶
class ProcessingStats(TypedDict, total=False):
"""处理统计信息类型定义"""
rows_processed: int
"""已处理行数"""
rows_skipped: int
"""跳过行数"""
memory_usage_mb: float
"""内存使用量(MB)"""
processing_time: float
"""处理时间(秒)"""
errors: list[str]
"""错误列表"""
示例用法:
from symphra_excel.utils.type_definitions import ProcessingStats
stats: ProcessingStats = {
"rows_processed": 10000,
"rows_skipped": 5,
"memory_usage_mb": 128.5,
"processing_time": 3.42,
"errors": ["警告：第100行格式异常"],
}
回调类型¶
DataProcessor - 数据处理回调¶
ProgressCallback - 进度回调¶
ErrorHandler - 错误处理回调¶
示例用法:
from symphra_excel.utils.type_definitions import ProgressCallback, ErrorHandler
def progress_callback(current: int, total: int) -> None:
"""进度回调函数"""
percent = (current / total) * 100
print(f"进度: {percent:.1f}% ({current}/{total})")
def error_handler(error: Exception) -> None:
"""错误处理函数"""
print(f"发生错误: {error}")
# 使用
process_data(progress_callback=progress_callback, error_handler=error_handler)
使用类型定义¶
在函数参数中使用¶
from symphra_excel.utils.type_definitions import (
CellRef, ImageSource, ImageOptions, TemplateContext
)
def insert_image(
image: ImageSource,
cell: CellRef,
options: ImageOptions | None = None
) -> None:
"""插入图片"""
pass
def render_template(context: TemplateContext) -> None:
"""渲染模板"""
pass
在类属性中使用¶
from symphra_excel.utils.type_definitions import ImageOptions
class ImageProcessor:
"""图片处理器"""
def __init__(self) -> None:
self.default_options: ImageOptions = {
"margin": 8,
"maintain_aspect_ratio": True,
}
在返回值中使用¶
from symphra_excel.utils.type_definitions import ProcessingStats
def process_large_file() -> ProcessingStats:
"""处理大文件"""
stats: ProcessingStats = {
"rows_processed": 100000,
"memory_usage_mb": 256.0,
"processing_time": 5.2,
"errors": [],
}
return stats
类型验证¶
使用TypedDict确保类型安全¶
from typing import get_type_hints
from symphra_excel.utils.type_definitions import ImageOptions
def validate_options(options: dict) -> ImageOptions:
"""验证图片选项"""
# TypedDict允许额外的键，但提示时只显示定义的键
return options # 类型安全
# 使用
options: ImageOptions = {
"width": 100,
"height": 100,
"custom_option": "额外选项", # 允许，但不在类型提示中
}
最佳实践¶
✅ 推荐做法¶
# 1. 使用类型别名提高代码可读性
from symphra_excel.utils.type_definitions import CellRef, CellValue
def set_cell_value(cell: CellRef, value: CellValue) -> None:
"""设置单元格值"""
pass
# 2. 使用TypedDict确保配置的结构化
from symphra_excel.utils.type_definitions import ImageOptions
def process_image(options: ImageOptions) -> None:
"""处理图片"""
width = options.get("width", 100)
height = options.get("height", 100)
# ...
❌ 避免的做法¶
# 1. 不使用类型定义（降低可读性）
def set_value(cell: str, value: str | int | float | bool | None) -> None:
pass
# 应该：
# def set_value(cell: CellRef, value: CellValue) -> None:
# 2. 混用类型系统
# 不要在同一个项目混用TypedDict和dict
IDE 支持¶
自动补全¶
使用这些类型定义可以获得更好的IDE自动补全：
from symphra_excel.utils.type_definitions import ImageOptions
options: ImageOptions = {
# IDE会提示：width, height, margin, etc.
}
类型检查¶
结合mypy进行静态类型检查：