> ## Documentation Index
> Fetch the complete documentation index at: https://docs.somark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 概览

> 安装 SoPDF，使用 Python 处理 PDF，并查阅函数、对象和异常。

## 什么是 SoPDF

**SoPDF** 是一个面向 Python 的开源 PDF 处理库，覆盖从渲染、文本提取到结构编辑的完整流程。你可以用它构建文档解析、检索、拆分合并、批处理等生产级能力。

函数、对象和调用示例见 [API 文档](https://docs.somark.ai/open-source-tools/sopdf/examples.md)。

> [!NOTE]
>
> SoPDF 使用 Apache 2.0 许可证。你可以在个人项目、商业产品和开源项目中直接使用。

## 快速开始

在空目录中安装 SoPDF（需要 Python 3.10 或更高版本），并下载一份单页测试 PDF。[W3C 测试 PDF](https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf)

```bash theme={null}
python -m pip install sopdf
curl -fL https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf -o document.pdf
```

将下面的代码保存为 `quickstart.py`，然后运行 `python quickstart.py`。`doc[0]` 取第一页，页索引从 `0` 开始。

```python theme={null}
from pathlib import Path

import sopdf

with sopdf.open("document.pdf") as doc:
    page = doc[0]
    Path("page-1.png").write_bytes(page.render(dpi=150))
    text = page.get_text().strip()
    Path("page-1.txt").write_text(text, encoding="utf-8")
    print(text)
```

运行后，目录中会生成渲染图 `page-1.png` 和文本文件 `page-1.txt`，终端会打印 `Dummy PDF file`。

## 为什么选择 SoPDF

* 高性能：在官方基准中，相比 PyMuPDF，SoPDF 在多个核心场景下表现更快（如渲染最高约 `2.82x`、纯文本提取约 `2.74x`、全文搜索约 `3.17x`）。
* 能力完整：同时支持渲染、文本提取、搜索、拆分、合并、压缩保存、元数据与目录读取等。
* API 直观：面向日常工程场景设计，学习成本低。
* 许可友好：Apache 2.0，便于企业与开源社区使用和分发。

## 核心能力

| 能力 | 说明 |
| - | - |
| 打开文档 | 支持从文件路径、字节流、内存流打开 PDF |
| 页面渲染 | 支持渲染为 PNG/JPEG，支持批量与并行渲染 |
| 文本处理 | 支持纯文本提取、带坐标文本块提取、关键词搜索 |
| 文档编辑 | 支持拆分、合并、页面旋转、压缩保存 |
| 工程能力 | 支持加密 PDF 读取与保存、损坏 PDF 自动修复 |
| 文档信息 | 支持元数据读写与文档目录（TOC）读取 |

## 技术架构

SoPDF 采用双引擎协同架构：

* `pypdfium2`（Google PDFium）：负责渲染、文本提取与搜索。
* `pikepdf`（libqpdf）：负责结构读取、写入与保存压缩。

通过脏标记与热重载机制，写操作后可自动同步到读路径，避免你手动维护双引擎状态。

## 资源与生态

* 项目仓库：[SoMarkAI/SoPDF](https://github.com/SoMarkAI/SoPDF)
* PyPI 包：[sopdf](https://pypi.org/project/sopdf/)
* 示例代码：仓库 `examples/` 目录
* 性能基准：仓库 `tests/benchmark/` 目录

## 开源协议

[Apache License 2.0](https://github.com/SoMarkAI/SoPDF/blob/main/LICENSE)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.