Symphra Excel¶

一个功能强大的Python Excel处理库，提供现代化的API接口、高性能的数据处理能力和丰富的样式支持。

✨ 核心特性¶

🚀 现代化API设计 - 简洁直观的接口，易于使用
🎨 丰富的样式系统 - 支持字体、颜色、边框、对齐等完整样式设置
📊 模板引擎 - 基于Jinja2的模板渲染系统
⚡ 异步支持 - 提供异步API接口，支持并发处理
💾 内存优化 - 高效的内存管理和大数据量处理能力
🖼️ 图片处理 - 支持Excel中插入图片和嵌入单元格功能
🔧 扩展性强 - 模块化设计,易于扩展和定制

🎯 项目状态¶

✅ 核心功能完整: 同步/异步 API 完整支持
✅ 测试覆盖充分: 73%测试覆盖率，428个测试用例全部通过
✅ 类型安全: 95%+类型注解覆盖率
✅ 代码质量优秀: 100%通过所有静态检查
🚀 生产可用: 适合中小规模Excel处理需求

📦 快速安装¶

pip install symphra-excel

🚀 5分钟快速开始¶

from symphra_excel import Workbook
from symphra_excel.styles import PredefinedStyles

# 创建工作簿
wb = Workbook()
sheet = wb.create_worksheet("销售数据")

# 写入表头并应用样式
headers = ["产品名称", "销量", "单价", "总额"]
for col_idx, header in enumerate(headers):
    cell_ref = f"{chr(65 + col_idx)}1"
    sheet.set_cell_value(cell_ref, header)
    sheet.apply_style(cell_ref, PredefinedStyles.header_style())

# 写入数据
data = [
    ["iPhone 15", 100, 5999, 599900],
    ["MacBook Pro", 50, 12999, 649950],
]
for row_idx, row_data in enumerate(data, start=2):
    for col_idx, value in enumerate(row_data):
        sheet.set_cell_value(f"{chr(65 + col_idx)}{row_idx}", value)

# 保存文件
wb.save("销售报表.xlsx")

📚 文档导航¶

入门指南¶

安装说明 - 详细的安装步骤
5分钟快速开始 - 快速上手教程
核心概念 - 理解基本概念

用户指南¶

基础操作 - 工作簿、工作表、单元格操作
样式系统 - 丰富的样式设置
模板引擎 - 基于Jinja2的模板支持
图片处理 - 图片插入和优化
异步处理 - 异步API使用
内存优化 - 大数据处理和内存管理

API参考¶

核心模块 - Workbook和Worksheet API
样式模块 - 样式系统API
模板模块 - 模板引擎API
工具模块 - 验证器和辅助函数

最佳实践¶

性能优化 - 提升处理性能
内存管理 - 优化内存使用
错误处理 - 异常处理最佳实践
测试策略 - 测试您的代码

💡 主要特点¶

🎯 易用性优先¶

Symphra Excel提供直观的API设计，让您能够快速上手：

from symphra_excel import Workbook

# 创建工作簿只需一行
wb = Workbook()
sheet = wb.create_worksheet("我的数据")

# 设置单元格值同样简单
sheet.set_cell_value("A1", "Hello, Excel!")
wb.save("output.xlsx")

🎨 强大的样式系统¶

支持完整的Excel样式功能：

from symphra_excel import CellStyle
from symphra_excel.styles import Color, BorderStyle

style = CellStyle()
style.set_font(name="微软雅黑", size=14, bold=True, color=Color.BLUE)
style.set_background_color(Color.LIGHT_YELLOW)
style.set_border(BorderStyle.THIN, Color.BLACK)
style.set_alignment(horizontal="center", vertical="center")

sheet.apply_style("A1", style)

📊 模板引擎¶

使用熟悉的Jinja2语法创建动态Excel：

from symphra_excel import TemplateWorkbook

wb = TemplateWorkbook("template.xlsx")
data = {
    "title": "月度销售报表",
    "date": "2025-11-01",
    "items": [
        {"name": "产品A", "quantity": 100, "price": 50},
        {"name": "产品B", "quantity": 200, "price": 30},
    ]
}
wb.render(data)
wb.save("report.xlsx")

⚡ 异步支持¶

处理大量文件时使用异步API提升性能：

import asyncio
from symphra_excel.async_support import AsyncWorkbook

async def create_reports():
    tasks = []
    for i in range(10):
        async with AsyncWorkbook() as wb:
            sheet = await wb.create_worksheet(f"Report_{i}")
            await sheet.set_cell_value("A1", f"Data {i}")
            tasks.append(wb.save(f"report_{i}.xlsx"))
    await asyncio.gather(*tasks)

asyncio.run(create_reports())

💾 内存优化¶

处理大数据集时自动优化内存使用：

from symphra_excel.memory_ops import MemoryOptimizedWorkbook

# 自动使用流式写入，减少内存占用
wb = MemoryOptimizedWorkbook()
sheet = wb.create_worksheet("大数据")

# 批量写入大量数据
for i in range(100000):
    sheet.set_cell_value(f"A{i+1}", f"Data {i}")

wb.save("large_file.xlsx")  # 内存占用保持稳定

🔧 技术亮点¶

类型安全: 完整的类型注解支持，IDE自动补全和类型检查
高性能: 基于openpyxl优化，处理速度比纯Python实现提升3-5倍
可扩展: 模块化设计，易于添加自定义功能
测试充分: 428个测试用例，73%代码覆盖率
文档完善: 详细的API文档和丰富的示例代码

🤝 贡献¶

欢迎贡献代码！请查看贡献指南了解详情。

📄 许可证¶

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🔗 相关链接¶

📮 获取帮助¶

如果您遇到问题或有疑问：

查看常见问题
浏览示例代码
提交 GitHub Issue
查阅 API文档