简介

Aspose.PDF FOSS 用于 Python 是一个用于在 Python 代码中处理 PDF 文档的新开源库。它在 MIT 许可证下发布，完全使用 Python 实现——PDF 解析器、写入器、页面光栅化器和加密例程都包含在该包中，所需的依赖仅限于 cryptography 和 asn1crypto。可选的扩展提供基于 Pillow 的图像支持、基于 Brotli 的 WOFF2 字体解码，以及基于 HarfBuzz 的复杂文字排版。

该库围绕 Document 类组织，该类可以从路径、字节或二进制流加载 PDF，并通过 document.pages 暴露其页面，document.pages 是一个支持迭代、索引和切片的 PageCollection。从这里开始，API 包括向页面添加文本和图像、读取和修改注释、创建和填充 AcroForm 字段、加密和解密文档以及提取文本和附件——这些操作是构建新 PDF 或处理现有 PDF 所需的。

此版本面向需要在 Python 代码库中进行 PDF 处理且不想使用商业许可证的开发者：报告和发票生成、文档摄取流水线、表单填写自动化，以及需要将 PDF 页面渲染为图像或提取文本用于下游索引的服务。该项目目前处于 alpha 阶段，因此 API 和功能覆盖可能在首次正式发布前发生变化。要求使用 Python 3.11 或更高版本。

包含内容

文档创建与加载

PdfDocument() 创建一个空的 PDF；PdfDocument(source, password=..., limits=...) 从路径、原始字节或二进制流加载已有的 PDF，并等同于调用 PdfDocument().load_from(source, ...)。两者在文件缺失、非 PDF 数据或缺少密码时都会抛出异常，而不是返回空文档。PdfDocument 是上下文管理器，因此在 with 块退出时会自动释放资源。

from aspose_pdf import Document

with Document() as document:
    page = document.pages.add()
    page.add_text("Generated by Aspose.PDF FOSS", x=72, y=720, font_size=14)
    document.save("report.pdf")

with Document("report.pdf") as document:
    print(f"Pages: {document.page_count}")
    print(f"PDF version: {document.version}")

添加文本和图像

Page.add_text 在 x/y 位置放置 Standard‑14 或嵌入的 Unicode 文本，使用给定的 font_size；font 参数可以是 FontDescriptor、原始字体字节，或指向 TrueType/OpenType 字体的路径，用于超出 Standard‑14 编码的 Unicode。Page.add_image 在页面上以指定的位置和尺寸放置原始、JPEG 或 PNG 图像 XObject。

from aspose_pdf import Document

with Document() as document:
    page = document.pages.add()
    page.add_text(
        "Quarterly Summary",
        x=72,
        y=740,
        font_size=16,
    )
    page.add_image(
        "chart.png",
        x=72,
        y=420,
        width=300,
        height=200,
    )
    document.save("summary.pdf")

注释

每个 Page 通过 page.annotations（一种 AnnotationCollection）公开其注释。add(subtype, rect, contents, title, appearance_normal, properties) 创建并插入一种标准子类型的注释，例如 Square、Circle、Line、Highlight 或 FreeText，并返回一个 Annotation。对返回的注释调用 generate_appearance() 可根据其几何形状和属性合成外观流。

from aspose_pdf import Document

with Document() as document:
    page = document.pages.add()
    annotation = page.annotations.add(
        "Square",
        (100, 600, 300, 680),
        "Needs review",
        properties={"C": [1, 0, 0]},
    )
    annotation.generate_appearance()
    document.save("annotated.pdf")

表单字段

document.form 返回文档的 Form，它直接创建 AcroForm 字段：add_text_field()、add_checkbox()、add_radio_group()、add_list_box()、add_combo_box() 和 add_push_button() 每个都接受字段名称、一个 Page 或页面索引以及放置矩形，返回一个 Field。设置 field.value 可更新字段的值，form.flatten() 将每个字段的外观烘焙为静态页面内容。

from aspose_pdf import Document

with Document() as document:
    page = document.pages.add()
    form = document.form
    field = form.add_text_field(
        "customer_name",
        page,
        (72, 700, 300, 720),
    )
    field.value = "Jane Doe"
    form.flatten()
    document.save("form.pdf")

加密

Document.encrypt(user_password, owner_password, permissions) 使用用户密码、所有者密码和权限位掩码保护文档，并返回相同的 Document 以便链式调用。Document.decrypt(password) 逆转该操作，is_encrypted 属性报告当前状态。再次加载加密文档时需要将 password= 传递给构造函数或 load_from()。

from aspose_pdf import Document

with Document("report.pdf") as document:
    document.encrypt(user_password="user-pass", owner_password="owner-pass", permissions=0)
    document.save("encrypted.pdf")

with Document("encrypted.pdf", password="user-pass") as document:
    print(f"Encrypted: {document.is_encrypted}")

文本提取

PdfExtractor 绑定到带有 bind_pdf() 的源，然后 extract_text() 遍历文档的页面。get_text() 一次性返回所有提取的文本，而 has_next_page_text() 和 get_next_page_text() 则逐页迭代结果。PdfExtractor 也是一个上下文管理器。

from aspose_pdf import PdfExtractor

with PdfExtractor() as extractor:
    extractor.bind_pdf("report.pdf")
    extractor.extract_text()
    while extractor.has_next_page_text():
        print(extractor.get_next_page_text())

快速入门

git clone https://github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python.git
cd Aspose-PDF-FOSS-for-Python
pip install -e .
from aspose_pdf import Document

with Document() as document:
    page = document.pages.add()
    page.add_text(
        "Hello from Aspose.PDF FOSS!",
        x=72,
        y=720,
        font_size=18,
    )
    document.save("hello.pdf")

with Document("hello.pdf") as document:
    print(f"Pages: {document.page_count}")
    print(f"PDF version: {document.version}")

支持的格式

格式扩展名读取写入
PDF.pdf✓✓
PNG.png—✓
TIFF.tiff—✓

PDF 是该库的核心输入和输出格式，通过 Document/load_from() 读取，并通过 Document.save 写入。PNG 和 TIFF 是由 Page.render、Page.save_as_image 和 Document.save_page_as_image 生成的页面渲染输出。

开源与许可

Aspose.PDF FOSS 用于 Python 在 MIT 许可证下分发，完整源码可在 github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python 获取。该许可证允许商业使用、修改和重新分发，无需另行协议。

入门

相关资源