symphra-excel 0.0.1
High-performance Excel processing library for Python 3.11+
Requires Python: >=3.11
Keywords: excel, spreadsheet, xlsx, template, high-performance

# 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文档和更多示例持续补充中

## 快速开始

### 安装

```bash
pip install symphra-excel
```

### 5分钟快速上手

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

```python
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报表！

## 详细文档

### 核心模块

#### 工作簿和工作表操作

```python
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()
```

#### 性能模式

```python
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")
```

#### 单元格操作

```python
# 设置单元格值
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')
```

#### 行列操作

```python
# 插入行
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列
```

### 样式系统

#### 创建自定义样式

```python
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)
```

#### 使用预定义样式

```python
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)
```

#### 颜色系统

```python
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')
```

### 模板引擎

#### 基本模板使用

```python
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模板语法：

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

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

#### 循环与条件块设计

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

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

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

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

#### 模板图片占位符

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

```excel
{{ 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`

### 异步处理

#### 异步工作簿操作

```python
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())
```

#### 批量异步处理

```python
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
```

### 内存操作

#### 内存工作簿

```python
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)
```

#### 模板内存工作簿

```python
from symphra_excel import InMemoryTemplateWorkbook

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

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

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

#### 内存优化工作簿

```python
from symphra_excel import MemoryOptimizedWorkbook

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

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

# 清理资源
workbook.cleanup()
```

### 图片处理

#### 插入图片

```python
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)
```

#### 批量插入图片

```python
# 准备图片信息
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)
```

### 性能优化

#### 内存管理

```python
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()
```

#### 大数据处理

```python
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. 错误处理

```python
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. 资源管理

```python
# 使用上下文管理器
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

### 开发环境设置

```bash
# 克隆项目
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](LICENSE) 文件了解详情。

## 支持

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

- 创建 [GitHub Issue](https://github.com/getaix/symphra-excel/issues)
- 发送邮件到: group@getaix.tech
- 查看 [文档网站](https://getaix.github.io/symphra-excel)

## 更新日志

### 2025-10-30

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

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