介绍
document.py，该模块为 Python 的 Document 类定义 Aspose.PDF FOSS，并将其描述为一个“封装原生 PDF 引擎”的类。具体而言，该引擎是 aspose_pdf.engine.simple_pdf.SimplePdf：Document.load_from 构建一个 SimplePdf 实例，所有文档级操作——保存、优化、修复、加密——都委托给它。渲染也是如此：Page.render 和 Document.render_page 都会调用 aspose_pdf.engine.rasterizer。
大多数应用代码根本不需要超出 Document 和 Page 的范围。但 aspose_pdf.engine 是一个普通的、可导入的 Python 包，其下层的多个组件单独使用也很有价值：将页面转换为像素的光栅化器、用于压缩和解压 PDF 内容流的流过滤编解码器，以及实现 PDF 安全处理程序所依赖的 AES-CBC 和 RC4 算法的加密工具。与主包不同，aspose_pdf.engine 子模块不会从顶层 aspose_pdf 重新导出——唯一例外是通过 aspose_pdf.visualization 桥接的 RasterizedPage——因此下面的所有内容都必须使用完整的点路径导入，例如 from aspose_pdf.engine.filters import StreamDecoder。
Aspose.PDF FOSS 针对 Python 是一个 Python 包，aspose-pdf-foss-for-python，在 MIT 许可证下发布，要求 Python 3.11 或更高版本。其顶层模块名称为 aspose_pdf。核心包仅依赖于 cryptography 和 asn1crypto；可选的额外功能添加了基于 Pillow 的图像解码、基于 Brotli 的 WOFF2 字体支持，以及基于 HarfBuzz 的复杂文本布局。
关键特性
使用光栅化引擎渲染页面
Document.render_page(page_index, dpi=..., scale=..., background=..., antialias=...) 及其 Page.render 对应物均返回一个 RasterizedPage——由引擎的光栅化器生成的打包 RGB 光栅。RasterizedPage 暴露 width、height 和原始 pixels 字节，以及用于单像素查找的 get_pixel()、用于内存中编码字节的 to_png()/to_tiff()，并提供 save() 直接写入 .png 或 .tif/.tiff 文件。将对象保存在内存中而非仅写入磁盘，在调用方希望在决定是否保留像素之前检查或转换像素时非常有用。
from aspose_pdf import Document
with Document() as document:
page = document.pages.add()
page.add_text("Rendered by the engine", x=72, y=700, font_size=18)
raster = document.render_page(0, dpi=150)
print(raster.width, raster.height)
corner = raster.get_pixel(0, 0)
print("top-left pixel:", corner)
with open("page-0.png", "wb") as handle:
handle.write(raster.to_png())
raster.save("page-0.tiff")
流过滤器引擎
PDF 内容和对象流使用诸如 FlateDecode 和 LZWDecode 等具名过滤器进行压缩。aspose_pdf.engine.filters.StreamEncoder.encode(data, filters, decode_parms=None) 和 StreamDecoder.decode(data, filters, decode_parms, *, limits=None, max_output_bytes=None) 实现该过滤器链的编码和解码端——即引擎在写入和读取文档流时内部使用的相同编解码器。两者都接受单个过滤器名称或用于链式过滤的列表，且 StreamDecoder.decode() 在遇到未识别的过滤器名称时会抛出 PdfValidationException，而不是悄悄返回错误的字节。
from aspose_pdf.engine.filters import StreamDecoder, StreamEncoder
raw = b"Sample content-stream payload.\n" * 40
compressed = StreamEncoder.encode(raw, "FlateDecode")
restored = StreamDecoder.decode(compressed, "FlateDecode", None)
assert restored == raw
print(f"{len(raw)} bytes -> {len(compressed)} bytes with FlateDecode")
加密引擎
aspose_pdf.engine.encryption.EncryptionUtils 是静态方法实用类，SimplePdf 在每个加密相关操作中调用它：Document.encrypt、decrypt() 和 change_passwords() 在内部都解析为对 EncryptionUtils 的调用。它的方法直接实现 AES-CBC 和 RC4 加密（encrypt_aes_cbc、decrypt_aes_cbc、encrypt_rc4、decrypt_rc4），以及 PDF 标准安全处理器修订版的密钥派生（compute_owner_key_v4、compute_user_key_v4、compute_user_owner_keys_v6），并为新文档所需的随机 16 字节 ID 提供 generate_file_id()。
from aspose_pdf.engine.encryption import EncryptionUtils
key = b"0123456789ABCDEF" # 16 bytes -> AES-128
ciphertext = EncryptionUtils.encrypt_aes_cbc(key, b"Reviewer notes: approved")
plaintext = EncryptionUtils.decrypt_aes_cbc(key, ciphertext)
assert plaintext == b"Reviewer notes: approved"
file_id = EncryptionUtils.generate_file_id()
print(file_id.hex())
快速入门
安装软件包，然后在单个脚本中直接从引擎层渲染页面。
asposefoss/pdf is not yet published — build from source until it ships. See the project README for build instructions.from aspose_pdf import Document
with Document() as document:
page = document.pages.add()
page.add_text("Engine-rendered page", x=72, y=740, font_size=20)
raster = document.render_page(0, dpi=150)
raster.save("engine-render.png")
document.save("engine-quickstart.pdf")
print("Saved engine-quickstart.pdf and engine-render.png")
支持的格式
| 格式 | 扩展名 | 读取 | 写入 |
|---|---|---|---|
| 是 | 是 | ||
| TIFF | tiff | - | 是 |
PDF 读取和写入是 Aspose.PDF FOSS 对于 Python 的核心功能——Document/SimplePdf 引擎在本文的每条代码路径上都加载并写入 PDF 文档。Document.render_page、Page.render 和 RasterizedPage.to_png()/to_tiff() 还可生成 PNG 和 TIFF 光栅输出；这些是页面光栅化输出，而非文档加载格式。
开源与许可
Aspose.PDF FOSS 对于 Python 在 MIT 许可证下发布：没有使用限制、没有运行时费用，也没有商业或个人使用的注册要求。源代码托管在 github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python，该软件包在 PyPI 上发布为 aspose-pdf-foss-for-python。
