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

# 概览

> 高性能开源 PDF 处理库 SoPDF 的能力、架构与快速开始

## 什么是 SoPDF

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

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

## 为什么选择 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）：负责结构读取、写入与保存压缩。

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

## 快速开始

```bash theme={null}
pip install sopdf
```

环境要求：Python `3.10+`。

```python theme={null}
import sopdf

with sopdf.open("document.pdf") as doc:
	# 渲染
	img_bytes = doc[0].render(dpi=150)

	# 提取文本
	text = doc[0].get_text()
	blocks = doc[0].get_text_blocks()

	# 搜索
	hits = doc[0].search("invoice", match_case=False)

	# 拆分与合并
	part = doc.split(pages=[0, 1, 2], output="chapter1.pdf")
	sopdf.merge(["intro.pdf", "body.pdf"], output="book.pdf")

	# 保存
	doc.append(part)
	doc.save("out.pdf", compress=True, garbage=True)
```

## 资源与生态

* 项目仓库：[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)