symphra-excel 0.0.1

High-performance Excel processing library for Python 3.11+

Symphra Excel Library

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

功能特性

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

项目状态（2025-10-31）

• ✅ 核心功能完整：同步/异步 Workbook 与 Worksheet API 支持读写模式切换、批量写入、样式管理、图片插入
• ✅ 测试覆盖充分：49个pytest测试用例全部通过，包括同步/异步/模板/样式等核心功能
• ✅ 类型安全改善：mypy核心库错误从292个降至32个（减少89%），剩余错误不影响运行
• 🎨 模板引擎可用：基于Jinja2沙箱的模板系统，支持循环/条件/图片占位，参考 examples/03_template_examples.py
• 🚀 生产可用：核心API稳定，适合中小规模Excel处理需求
• 📚 文档完善中：API文档和更多示例持续补充中

快速开始

安装

pip install symphra-excel

5分钟快速上手

最简单的Excel生成示例（完整代码见 quickstart.py）：

from symphra_excel import Workbook, PredefinedStyles

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

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

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

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

运行以上代码将生成一个包含样式的专业Excel报表！

详细文档

核心模块

工作簿和工作表操作

from symphra_excel import Workbook

# 创建工作簿
workbook = Workbook()

# 创建工作表
sheet1 = workbook.create_worksheet('数据表1')
sheet2 = workbook.create_worksheet('数据表2')

# 获取工作表
sheet = workbook.get_worksheet('数据表1')

# 删除工作表
workbook.delete_worksheet('数据表2')

# 保存工作簿
workbook.save('输出文件.xlsx')

# 保存到内存
file_data = workbook.save_to_memory()

性能模式

from symphra_excel import Workbook

# 只读访问大文件（不会写回原文件）
readonly_wb = Workbook("report.xlsx", mode="read_only")
value = readonly_wb.get_worksheet("Sheet1").get_cell_value("A1")

# 写入流式导出，按行追加数据
stream_wb = Workbook(mode="write_only")
stream_sheet = stream_wb.create_worksheet("Stream")
stream_sheet.append_row(["姓名", "分数"])
stream_sheet.append_rows([["张三", 90], ["李四", 85]])
stream_wb.save("stream_output.xlsx")

单元格操作

# 设置单元格值
sheet.set_cell_value('A1', 'Hello World')
sheet.set_cell_value('B1', 123.45)
sheet.set_cell_value('C1', '=A1+B1')  # 公式

# 获取单元格值
value = sheet.get_cell_value('A1')

# 批量设置范围值
data = [
    ['姓名', '年龄', '城市'],
    ['张三', 25, '北京'],
    ['李四', 30, '上海']
]
sheet.set_range_values('A1:C3', data)

# 获取范围值
range_values = sheet.get_range_values('A1:C3')

行列操作

# 插入行
sheet.insert_rows(2, 3)  # 在第2行插入3行

# 删除行
sheet.delete_rows(2, 3)  # 从第2行开始删除3行

# 插入列
sheet.insert_columns(2, 2)  # 在第2列插入2列

# 删除列
sheet.delete_columns(2, 2)  # 从第2列开始删除2列

样式系统

创建自定义样式

from symphra_excel import CellStyle, Color

# 创建样式
style = CellStyle()

# 设置字体
style.set_font(
    name='微软雅黑',
    size=12,
    bold=True,
    italic=False,
    color=Color.WHITE
)

# 设置背景颜色
style.set_background_color(Color.DARK_BLUE)

# 设置边框
style.set_border(
    left=True, right=True, top=True, bottom=True,
    left_color=Color.BLACK,
    right_color=Color.BLACK,
    top_color=Color.BLACK,
    bottom_color=Color.BLACK
)

# 设置对齐方式
style.set_alignment(horizontal='center', vertical='center')

# 设置数字格式
style.set_number_format('0.00')

# 应用样式到单元格
sheet.set_cell_style('A1', style)

使用预定义样式

from symphra_excel import PredefinedStyles

# 表头样式
header_style = PredefinedStyles.header_style()
sheet.set_cell_style('A1', header_style)

# 标题样式
title_style = PredefinedStyles.title_style()
sheet.set_cell_style('A1', title_style)

# 高亮样式
highlight_style = PredefinedStyles.highlight_style()
sheet.set_cell_style('A2', highlight_style)

# 货币样式
currency_style = PredefinedStyles.currency_style()
sheet.set_cell_style('B2', currency_style)

颜色系统

from symphra_excel import Color, PredefinedStyles

# 使用预定义颜色
red = Color.RED
blue = Color.BLUE
green = Color.GREEN

# 使用十六进制颜色
hex_color = Color.from_hex('#FF6B35')

# 使用RGB颜色
rgb_color = Color.from_rgb(255, 107, 53)

# 使用主题颜色
primary_color = PredefinedStyles.get_theme_color('primary')
secondary_color = PredefinedStyles.get_theme_color('secondary')

模板引擎

基本模板使用

from symphra_excel import TemplateWorkbook

# 加载模板
template = TemplateWorkbook.load_template('report_template.xlsx')

# 准备数据
context = {
    'title': '月度销售报告',
    'date': '2024年1月',
    'total_sales': 150000,
    'products': [
        {'name': '产品A', 'sales': 50000},
        {'name': '产品B', 'sales': 75000},
        {'name': '产品C', 'sales': 25000}
    ]
}

# 渲染模板
workbook = template.render(context)

# 保存结果
workbook.save('生成的报告.xlsx')

模板语法

支持Jinja2模板语法：

{{ title }}                    # 简单变量
{{ date.strftime('%Y-%m') }}   # 日期格式化
{% for product in products %}    # 循环
{{ product.name }}
{{ product.sales }}
{% endfor %}

{{ total_sales | number_format }}  # 数字格式化
{{ title | upper }}                # 文本转换

循环与条件块设计

在模板中，循环/条件控制语句应独立占一整行，后续行用于放置实际单元格内容。例如：

{% for row in items %}
{{ row.name }}	{{ row.amount }}
{% endfor %}

{% if show_summary %}
汇总	{{ summary }}
{% endif %}

渲染时会自动展开循环并保留单元格格式；条件块在布尔表达式为 False 时将被整体移除。

模板图片占位符

模板单元格可使用 insert_image 占位符延迟插图：

{{ insert_image(logo_path, width=120, height=60, maintain_aspect_ratio=True) }}

渲染后占位符所在单元格值会被清空，图片根据参数插入。

上下文安全约束

• 仅允许传入 str、int、float、bool、None 以及由这些值组成的 dict/list/tuple/set
• 上下文中禁止包含可调用对象或以 "__" 开头的键
• 允许的过滤器包括 default、length、upper、lower、title、capitalize、replace、trim、striptags、join、round
• 自定义函数需要通过受控的 environment.globals 注册，默认仅开放 insert_image

异步处理

异步工作簿操作

import asyncio
from symphra_excel import AsyncWorkbook

async def process_excel_files():
    # 异步创建工作簿
    workbook = AsyncWorkbook()
    await workbook.create()
    
    # 异步创建工作表
    sheet = await workbook.create_worksheet('异步数据')
    
    # 异步设置数据
    await sheet.set_cell_value('A1', '异步处理的数据')
    
    # 异步保存
    await workbook.save('异步输出.xlsx')

# 运行异步函数
asyncio.run(process_excel_files())

批量异步处理

from symphra_excel import AsyncBatchProcessor

async def batch_process_files(file_paths):
    processor = AsyncBatchProcessor(max_workers=8)
    
    def process_workbook(workbook):
        # 处理工作簿的逻辑
        sheet = workbook.create_worksheet('处理结果')
        sheet.set_cell_value('A1', '已处理')
        return workbook
    
    # 异步批量处理
    results = await processor.process_multiple_files(
        file_paths, process_workbook
    )
    
    await processor.close()
    return results

内存操作

内存工作簿

from symphra_excel import InMemoryWorkbook

# 创建内存工作簿
workbook = InMemoryWorkbook()
sheet = workbook.create_worksheet('内存数据')

# 设置数据
sheet.set_cell_value('A1', '内存中的数据')

# 转换为字节数据
file_data = workbook.to_bytes()

# 从字节数据加载
loaded_workbook = InMemoryWorkbook.from_bytes(file_data)

模板内存工作簿

from symphra_excel import InMemoryTemplateWorkbook

# 从模板创建内存工作簿
template_workbook = InMemoryTemplateWorkbook('template.xlsx')

# 渲染模板
context = {'title': '报告标题'}
workbook = template_workbook.render(context)

# 获取字节数据
data = workbook.to_bytes()

内存优化工作簿

from symphra_excel import MemoryOptimizedWorkbook

# 创建内存优化工作簿
workbook = MemoryOptimizedWorkbook()

# 使用流式处理大数据
workbook.create_sheet_with_streaming(
    '大数据表',
    data_iterator=large_data_iterator
)

# 清理资源
workbook.cleanup()

图片处理

插入图片

from symphra_excel import ImageProcessor
from symphra_excel.images.image_processor import CellImageOptions

# 创建图片处理器（可选，用于预处理图片）
processor = ImageProcessor()

# 插入图片到工作表（支持本地路径/字节流）
sheet.insert_image('logo.png', 'A1', width=120, height=60)

# 使用单元格尺寸自适应
sheet.insert_image_with_size('logo.png', 'B1', cell_width=80, cell_height=40)

批量插入图片

# 准备图片信息
images_info = [
    {'image': 'image1.png', 'cell': 'A1', 'width': 80},
    {'image': 'image2.jpg', 'cell': 'B1'},
    {'image': 'image3.png', 'cell': 'C1', 'options': CellImageOptions(margin=4)}
]

# 批量插入
sheet.insert_images_batch(images_info)

性能优化

内存管理

from symphra_excel import MemoryManager, MemoryStrategy

# 创建内存管理器
memory_manager = MemoryManager(
    strategy=MemoryStrategy.BATCHED
)

# 注册对象
memory_manager.register_object(workbook, 'my_workbook')

# 优化内存
memory_manager.optimize_memory()

# 获取内存使用统计
stats = memory_manager.get_memory_stats()

大数据处理

from symphra_excel import LargeDataProcessor

# 创建大数据处理器
processor = LargeDataProcessor()

# 导出大数据集
processor.export_large_dataset(
    data_iterator=large_data_iterator,
    output_path='large_dataset.xlsx',
    batch_size=1000,
    memory_strategy=MemoryStrategy.STREAMING
)

# 转换文件格式
processor.convert_file_format(
    input_path='data.csv',
    output_path='data.xlsx',
    input_format='csv',
    output_format='xlsx'
)

最佳实践

1. 内存管理

• 对于大文件处理，使用流式处理策略
• 及时清理不再使用的对象
• 使用内存管理器监控内存使用情况

2. 性能优化

• 批量操作比单个操作更高效
• 使用异步处理提高并发性能
• 选择合适的内存策略

3. 错误处理

from symphra_excel import ValidationError, MemoryError

try:
    workbook = Workbook.load('large_file.xlsx')
except ValidationError as e:
    print(f'文件验证错误: {e}')
except MemoryError as e:
    print(f'内存错误: {e}')
except Exception as e:
    print(f'其他错误: {e}')

4. 资源管理

# 使用上下文管理器
with InMemoryWorkbook() as workbook:
    # 处理工作簿
    sheet = workbook.create_worksheet('Test')
    sheet.set_cell_value('A1', 'Test Data')
    data = workbook.to_bytes()
# 自动清理资源

# 异步资源清理
async with AsyncWorkbook() as workbook:
    await workbook.create()
    # 异步操作...

贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 项目仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

开发环境设置

# 克隆项目
git clone https://github.com/yourusername/symphra-excel.git

# 进入项目目录
cd symphra-excel

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows

# 安装依赖
pip install -e .

# 运行测试
pytest tests/

许可证

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

支持

如果你有任何问题或建议，请：

• 创建 GitHub Issue
• 发送邮件到: [e-mail]
• 查看 文档网站

更新日志

2025-10-30

• 清理整个仓库的导入顺序与代码格式，isort / black 均通过。
• 强化静态检查，修正图片处理裸捕获异常，并把测试用 sys.path 注入逻辑收敛到 tests/conftest.py。
• pytest 回归 49 项全绿，ruff check 通过；mypy 在沙箱环境受限暂未执行。

历史版本详情待补充至 CHANGELOG.md，当前维持 README 内部速记。