API 文档

sopdf.open(
    path: str | pathlib.Path | None = None,
    password: str | None = None,
    *,
    stream: bytes | None = None,
) -> Document

# 从文件路径打开
doc = sopdf.open("report.pdf")

# 打开加密文档
doc = sopdf.open("secure.pdf", password="hunter2")

# 从内存字节打开
with open("report.pdf", "rb") as f:
    doc = sopdf.open(stream=f.read())

# 推荐：使用上下文管理器自动释放资源
with sopdf.open("report.pdf") as doc:
    print(doc.page_count)

sopdf.merge(
    inputs: list[str | pathlib.Path],
    output: str | pathlib.Path,
) -> None

sopdf.merge(
    ["intro.pdf", "body.pdf", "appendix.pdf"],
    output="book.pdf",
)

sopdf.render_pages(
    pages: list[Page],
    *,
    dpi: int = 72,
    format: str = "png",
    alpha: bool = False,
    parallel: bool = False,
) -> list[bytes]

with sopdf.open("report.pdf") as doc:
    # 顺序渲染
    images = sopdf.render_pages(doc.pages, dpi=150)

    # 多进程并行渲染（大文档推荐）
    images = sopdf.render_pages(doc.pages, dpi=300, parallel=True)

sopdf.render_pages_to_files(
    pages: list[Page],
    output_dir: str | pathlib.Path,
    *,
    dpi: int = 72,
    format: str = "png",
    alpha: bool = False,
    parallel: bool = False,
) -> None

with sopdf.open("report.pdf") as doc:
    sopdf.render_pages_to_files(doc.pages, "output/", dpi=150, parallel=True)
# 生成 output/page_0.png, output/page_1.png, ...

doc.page_count -> int

len(doc) -> int

doc.metadata -> Metadata

# 读取
print(doc.metadata.title)
print(doc.metadata.creation_datetime)  # Python datetime 对象

# 写入（懒加载 pikepdf，标记文档为脏）
doc.metadata.title  = "Annual Report 2025"
doc.metadata.author = "Kevin Qiu"
doc.save("updated.pdf")

doc.outline -> Outline

for item in doc.outline.items:
    print(f"[p{item.page + 1}] {item.title}")

flat = doc.outline.to_list()  # 与 PyMuPDF get_toc() 格式兼容的扁平列表

doc.is_encrypted -> bool

doc.pages -> _PageList

doc[index: int] -> Page
doc.load_page(index: int) -> Page

first_page = doc[0]
last_page  = doc[-1]
third_page = doc.load_page(2)

for page in doc:
    print(page.number)

doc.split(
    pages: list[int],
    output: str | pathlib.Path | None = None,
) -> Document

# 提取前 3 页并保存
chapter = doc.split(pages=[0, 1, 2], output="chapter1.pdf")

# 仅在内存中提取，不写磁盘
excerpt = doc.split(pages=[4, 5, 6])

doc.split_each(output_dir: str | pathlib.Path) -> None

doc.split_each("pages/")
# 生成 pages/page_0.pdf, pages/page_1.pdf, ...

doc.append(other: Document) -> None

with sopdf.open("part1.pdf") as doc_a, sopdf.open("part2.pdf") as doc_b:
    doc_a.append(doc_b)
    doc_a.save("combined.pdf")

doc.save(
    path: str | pathlib.Path,
    *,
    compress: bool = True,
    garbage: bool = False,
    linearize: bool = False,
) -> None

# 普通保存（压缩默认开启）
doc.save("output.pdf")

# 最大压缩
doc.save("output.pdf", compress=True, garbage=True)

# 去除加密（以正确密码打开后保存）
doc.save("unlocked.pdf")

doc.to_bytes(compress: bool = True) -> bytes

pdf_bytes = doc.to_bytes()

# 在 Flask 中作为响应直接返回
from flask import Response
return Response(doc.to_bytes(), mimetype="application/pdf")

doc.close() -> None

with sopdf.open("file.pdf") as doc:
    ...
# 退出 with 块时自动调用 close()

page.number -> int

page.rect -> Rect

page.rotation -> int          # 读取当前旋转角度
page.rotation = degrees: int  # 设置旋转角度

page.render(
    *,
    dpi: int = 72,
    format: str = "png",
    alpha: bool = False,
) -> bytes

png_bytes  = page.render(dpi=150)
jpeg_bytes = page.render(dpi=150, format="jpeg")
png_alpha  = page.render(dpi=72, alpha=True)

page.render_to_file(
    path: str | pathlib.Path,
    *,
    dpi: int = 72,
    format: str = "png",
    alpha: bool = False,
) -> None

page.render_to_file("page0.png", dpi=300)
page.render_to_file("page0.jpg", dpi=150, format="jpeg")

page.get_text(
    *,
    rect: Rect | None = None,
) -> str

full_text = page.get_text()

# 仅提取特定区域
region = Rect(0, 0, 300, 100)
header_text = page.get_text(rect=region)

page.get_text_blocks(
    *,
    rect: Rect | None = None,
    format: str = "list",
) -> list

blocks = page.get_text_blocks()
for block in blocks:
    print(block.text, block.rect)

# 以字典格式返回（便于 JSON 序列化）
dicts = page.get_text_blocks(format="dict")

page.search(
    query: str,
    *,
    match_case: bool = False,
) -> list[Rect]

hits = page.search("invoice")
for rect in hits:
    print(f"在 {rect} 处找到匹配")

# 区分大小写
hits = page.search("PDF", match_case=True)

page.search_text_blocks(
    query: str,
    *,
    match_case: bool = False,
) -> list[dict]

results = page.search_text_blocks("total amount")
for r in results:
    print(r["text"])        # 包含关键词的完整段落
    print(r["match_rect"])  # 关键词精确位置

Rect(x0: float, y0: float, x1: float, y1: float)

r = Rect(10, 20, 200, 300)
print(r.width)    # 190.0
print(r.height)   # 280.0

# 判断包含
print(r.contains(Rect(50, 50, 100, 100)))  # True
print(r.contains((50, 50)))                # True（点）

# 交集
a = Rect(0, 0, 100, 100)
b = Rect(50, 50, 150, 150)
print(a.intersect(b))  # Rect(50, 50, 100, 100)

# 解包
x0, y0, x1, y1 = r

TextBlock(text: str, rect: Rect)

blocks = page.get_text_blocks()
for block in blocks:
    print(block.text)
    print(block.rect.width, block.rect.height)
    print(block.to_dict())

with sopdf.open("report.pdf") as doc:
    meta = doc.metadata

    # 读取字段
    print(meta.title)
    print(meta.creation_datetime)  # datetime(2024, 1, 1, 12, 0, tzinfo=...)

    # 写入
    meta.title  = "新标题"
    meta.author = "Kevin Qiu"
    doc.save("updated.pdf")

    # 字典风格读取（向后兼容）
    d = meta.to_dict()
    print(d["title"])
    print(meta["author"])

@dataclass(frozen=True)
class OutlineItem:
    title:    str
    page:     int                          # 0-based；-1 = 无目标页
    level:    int                          # 0 = 顶层
    children: tuple[OutlineItem, ...] = ()

with sopdf.open("textbook.pdf") as doc:
    outline = doc.outline
    print(outline)          # Outline(top_level=2, total=4)
    print(bool(outline))    # True

    # 递归树遍历
    def print_tree(items, indent=0):
        for item in items:
            print("  " * indent + f"[p{item.page + 1}] {item.title}")
            print_tree(item.children, indent + 1)

    print_tree(outline.items)

    # 扁平列表（与 PyMuPDF 兼容）
    for row in outline.to_list():
        print(f"{'  ' * row['level']}{row['title']}  →  p{row['page'] + 1}")

RuntimeError
└── PDFError
    ├── PasswordError
    ├── FileDataError
    └── PageError

import sopdf

try:
    doc = sopdf.open("file.pdf", password="wrong")
except sopdf.PasswordError:
    print("密码错误")
except sopdf.FileDataError:
    print("文件损坏")
except sopdf.PDFError as e:
    print(f"PDF 错误：{e}")