Metadata-Version: 2.4
Name: x2x-excel
Version: 0.1.0
Summary: 通过 Excel COM、SQLite 和独立子进程重建 xlsx 工作簿
Author: minionszyw
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/minionszyw/x2x
Project-URL: Repository, https://github.com/minionszyw/x2x.git
Project-URL: Issues, https://github.com/minionszyw/x2x/issues
Keywords: excel,xlsx,sqlite,com,windows
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openpyxl<4,>=3.1
Requires-Dist: pywin32>=306; sys_platform == "win32"
Dynamic: license-file

# x2x

通过 Excel COM 读取 `.xlsx`，暂存到 SQLite，再由独立 Python 进程重新构造工作簿。

## 快速开始

运行环境：

- Windows
- Python 3.10 或更高版本
- Microsoft Excel

安装：

```powershell
python -m pip install x2x-excel
```

转换文件：

```powershell
x2x test.xlsx
```

安装包名是 `x2x-excel`，安装后的命令名是 `x2x`。`openpyxl` 和 `pywin32` 会由 pip 自动安装。

默认在源文件旁生成 `<源文件名>_rebuilt.xlsx`。例如，以上命令会生成 `test_rebuilt.xlsx`。

## 常用命令

指定输出文件：

```powershell
x2x test.xlsx -o result.xlsx
```

一次转换多个文件：

```powershell
x2x test.xlsx test1.xlsx test2.xlsx
```

批量模式按输入顺序处理，并分别生成 `test_rebuilt.xlsx`、`test1_rebuilt.xlsx` 和 `test2_rebuilt.xlsx`。`-o/--output` 只适用于单文件模式。

路径包含中文或空格时使用引号：

```powershell
x2x "C:\Excel 文件\test.xlsx" -o "C:\Excel 文件\result.xlsx"
```

查看帮助：

```powershell
x2x --help
```

## 常见问题

### 找不到 `x2x` 命令

先尝试通过 Python 模块运行：

```powershell
python -m x2x test.xlsx
```

如果该命令可用，请将当前 Python 的 `Scripts` 目录加入 Windows `PATH`。

### 安装过 PyPI 上旧的 `x2x` 包

PyPI 已有一个与本项目无关的 `x2x` 包，并且可能安装同名命令。请先卸载旧包，再安装本项目：

```powershell
python -m pip uninstall x2x
python -m pip install --upgrade x2x-excel
```

### 输出文件已存在

为避免误覆盖，程序会拒绝写入已有文件。请删除旧输出，或通过 `-o` 指定新文件名。

## 保留范围

当前版本会保留：

- 工作表名称、顺序和可见性
- 单元格空值、文本、数字、布尔值、错误值及公式
- 单元格数字格式，例如日期格式和文本格式
- 工作簿的 1900/1904 日期基准
- 使用区域内的行高、列宽及隐藏状态

长编号会按文本保存，避免科学计数法或精度损失。公式会在工作簿下次由 Excel 打开时重新计算。

当前版本不会保留字体、填充、边框、对齐、批注、合并单元格、条件格式、数据验证、图片、图表、Excel 表格、名称、宏等高级对象或样式。因此，它适合数据和关键格式迁移，不等同于完整复制工作簿。

## 工作原理

1. 父进程通过 Excel COM 以只读方式打开源工作簿，并禁用宏及外部链接更新。
2. 单元格数据和关键格式批量写入临时 SQLite 数据库。
3. 父进程关闭 Excel，再启动独立 Python 子进程。
4. 子进程使用 `openpyxl` 重建 `.xlsx`，成功后自动删除临时数据库。

批量转换是顺序执行，不会同时启动多个 Excel 实例。成功时返回退出码 `0`；失败时返回非零退出码并将错误信息写入标准错误流。

## 开发与构建

从源码安装：

```powershell
git clone https://github.com/minionszyw/x2x.git
cd x2x
python -m pip install -e .
```

构建并检查发布包：

```powershell
python -m pip install build twine
python -m build
python -m twine check dist\*
```

## 许可证

本项目采用 [Apache License 2.0](LICENSE)。
