Metadata-Version: 2.4
Name: x2x-excel
Version: 0.1.2
Summary: 通过 Excel COM、SQLite 和独立子进程重建 xlsx 和 csv 文件
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,csv,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` 或 `.csv`，暂存到 SQLite，再由独立 Python 进程重新构造文件。

## 快速开始

运行环境：

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

安装：

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

转换文件：

```powershell
x2x test.xlsx
```

CSV 使用相同方式：

```powershell
x2x test.csv
```

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

**默认模式会覆盖源文件。** 新文件完整生成后才会替换源文件，但成功覆盖后不保留备份。请先备份重要文件，或使用 `--suffix` 保留源文件。

## 常用命令

保留源文件，在旁边生成 `test_rebuilt.xlsx`：

```powershell
x2x test.xlsx --suffix
```

一次转换多个文件：

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

`.xlsx` 和 `.csv` 可以混合输入：

```powershell
x2x test.xlsx data.csv
```

默认会按输入顺序覆盖这三个源文件。批量保留源文件：

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

该命令会分别生成 `test_rebuilt.xlsx`、`test1_rebuilt.xlsx` 和 `test2_rebuilt.xlsx`。`-s` 是 `--suffix` 的简写。

重建当前目录直属的全部 `.xlsx` 和 `.csv`：

```powershell
x2x all
```

`all` 不递归扫描子目录，并会跳过名称以 `_rebuilt` 结尾的文件。要保留当前目录中的全部源文件：

```powershell
x2x all --suffix
```

该命令按文件名顺序生成同格式的 `_rebuilt.xlsx` 或 `_rebuilt.csv` 文件。`all` 不能与显式文件路径同时使用。

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

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

查看帮助：

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

### 输出文件已存在

默认模式会覆盖源文件；`--suffix` 模式也会覆盖已存在的 `<源文件名>_rebuilt.<原格式>`。覆盖发生在新文件完整生成之后，但程序不会自动创建备份。

## 保留范围

重建 `.xlsx` 时会保留：

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

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

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

重建 `.csv` 时会保留单元格数据和公式文本，不保留工作表样式、行列尺寸或其他 Excel 专属元数据。输出固定使用逗号分隔、CRLF 换行和带 BOM 的 UTF-8 编码，以便 Excel 正确识别中文。

## 工作原理

1. 父进程通过 Excel COM 以只读方式打开源文件，并禁用宏及外部链接更新。
2. 单元格数据和关键格式批量写入临时 SQLite 数据库。
3. 父进程关闭 Excel，再启动独立 Python 子进程。
4. 子进程使用 `openpyxl` 重建 `.xlsx`，或使用标准库重建 `.csv`；完整保存后原子替换目标文件，并自动删除临时数据库。

批量转换是顺序执行，不会同时启动多个 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)。
