安装指南¶

本页面介绍如何安装Symphra Excel及其依赖。

系统要求¶

Python 3.11 或更高版本
pip 包管理器

快速安装¶

使用pip从PyPI安装最新稳定版本：

pip install symphra-excel

开发版本安装¶

如果您想使用最新的开发版本：

# 克隆仓库
git clone https://github.com/getaix/symphra-excel.git
cd symphra-excel

# 安装为可编辑模式
pip install -e .

安装开发依赖¶

如果您想参与开发或运行测试：

# 安装开发依赖
pip install -e ".[dev]"

# 或者安装文档构建依赖
pip install -e ".[docs]"

# 安装所有可选依赖
pip install -e ".[dev,docs]"

验证安装¶

安装完成后，您可以验证安装是否成功：

import symphra_excel
print(symphra_excel.__version__)

或者运行一个简单的测试：

from symphra_excel import Workbook

# 创建一个简单的工作簿
wb = Workbook()
sheet = wb.create_worksheet("测试")
sheet.set_cell_value("A1", "Hello, Symphra Excel!")
wb.save("test.xlsx")
print("安装成功！已创建 test.xlsx")

核心依赖¶

Symphra Excel依赖以下核心库：

openpyxl (>=3.1.0) - Excel文件读写
jinja2 (>=3.1.5) - 模板引擎
pillow (>=10.3.0) - 图片处理
typing-extensions (>=4.5.0) - 类型注解增强

这些依赖会在安装时自动安装。

可选依赖¶

开发工具¶

pip install symphra-excel[dev]

包含： - pytest - 测试框架 - pytest-asyncio - 异步测试支持 - pytest-cov - 代码覆盖率 - black - 代码格式化 - isort - 导入排序 - flake8 - 代码检查 - mypy - 类型检查 - pre-commit - Git钩子

文档工具¶

pip install symphra-excel[docs]

包含： - mkdocs - 文档生成器 - mkdocs-material - Material主题 - mkdocstrings - API文档生成 - pymdown-extensions - Markdown扩展

常见问题¶

Q: pip install 失败怎么办？¶

A: 首先确保您的pip是最新版本：

pip install --upgrade pip

如果仍然失败，尝试使用国内镜像：

pip install symphra-excel -i https://pypi.tuna.tsinghua.edu.cn/simple

Q: 需要安装Microsoft Excel吗？¶

A: 不需要。Symphra Excel是纯Python库，不依赖Microsoft Excel。

Q: 支持哪些操作系统？¶

A: 支持所有主流操作系统： - Windows 10/11 - macOS 10.14+ - Linux (各主流发行版)

Q: Python 3.10可以使用吗？¶

A: Symphra Excel要求Python 3.11+。如果您使用Python 3.10，建议升级到3.11或更高版本。

虚拟环境¶

我们强烈建议在虚拟环境中安装：

使用venv¶

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

# 安装
pip install symphra-excel

使用conda¶

# 创建conda环境
conda create -n symphra python=3.11

# 激活环境
conda activate symphra

# 安装
pip install symphra-excel

升级¶

升级到最新版本：

pip install --upgrade symphra-excel

卸载¶

如果需要卸载：

pip uninstall symphra-excel