快速开始¶
安装¶
可选font package包含Noto Sans/Serif JP，用于渲染缺少嵌入字体的日文PDF，也可在
日文／汉字insert_text和insert_textbox中自动subset。中文本地字形和Hangul需要
显式传入匹配的font：
release CI 会在architecture匹配的runner上安装每个native platform wheel，并验证PDF
创建、保存、重新打开、抽取、render和immutable Pixmap storage。该gate覆盖全部五个
abi3-py310和五个CPython 3.14t artifact；sdist与PyEmscripten wheel各有独立的
environment-specific gate。
打开、检查、保存¶
import pylopdf
doc = pylopdf.open("input.pdf") # 也可使用 pylopdf.open(stream=pdf_bytes)
print(doc.page_count) # 也支持 len(doc)
print(doc.metadata["title"])
doc.set_metadata({"title": "报告", "author": "Alice"})
doc.save("out.pdf")
data = doc.tobytes()
doc.save("small.pdf", garbage=True, deflate=True, object_streams=True)
doc.save("locked.pdf", user_pw="secret", permissions=pylopdf.Permissions.PRINT)
使用password=打开加密PDF，也可稍后调用doc.authenticate()。
通常，pylopdf.peek_metadata(path)无需完整解析PDF文档即可读取元数据和页数，适合扫描
大型文件集。max_file_size=可在解析前按大小拒绝path或byte input；为了向后兼容，
默认不设上限。若受限修复了最终classic startxref，repaired与
doc.is_repaired为True，并发出PylopdfWarning；保存会规范化xref数据。
处理不受信任的文件时，请传入limits=pylopdf.DocumentLimits.web()，以限制文件、
结构、解压、rendering／extraction用PDF snapshot和已解释文本。重型处理前可检查
doc.complexity，受控拒绝会抛出
LimitError。各项预算请参阅安全。
页面、文本与搜索¶
page = doc[0] # 从0开始；负数从末尾计数
for page in doc:
print(page.number, page.rect)
text = page.get_text() # 纯文本
words = page.get_text("words") # (x0, y0, x1, y1, word, block, line, word_no)
layout = page.get_text("dict") # blocks → lines → spans（bbox、size、font、flags）
hits = page.search_for("合计") # 不区分大小写，返回 list[Rect]
所有坐标均为左上角原点的显示空间。即使页面旋转，搜索结果、版面信息、绘制和渲染 也使用同一坐标系。
渲染¶
png = doc.render_page(0, dpi=300) # bytes（PNG）
pix = page.get_pixmap(scale=2) # 供NumPy/PIL使用的RGBA8像素
batch = doc.render_pages([0, 1, 2], scale=2, workers=4)
svg = doc.render_page_svg(0)
编辑¶
doc.delete_pages([1, 2])
doc.select([2, 0]) # 保留/重排（重复即复制）
doc.new_page(); doc.copy_page(0, to=1)
merged = pylopdf.Document()
merged.insert_pdf(pylopdf.open("a.pdf"))
merged.insert_pdf(pylopdf.open("b.pdf"), from_page=0, to_page=2, start_at=0)
doc.set_toc([[1, "第1章", 1], [2, "1.1节", 2]])
page.set_rotation(90)
绘制与批注¶
page.insert_image((72, 72, 200, 200), filename="logo.png") # JPEG直通/PNG透明
page.insert_image(page.search_for("已批准")[0], stream=stamp_png)
page.insert_image((300, 72, 500, 200), pixmap=thumbnail, rotate=90) # 直接RGBA并顺时针旋转
page.show_pdf_page(page.rect, letterhead) # 以矢量叠加；也可来自同一文档
page.insert_text((40, 40), "CONFIDENTIAL", fontsize=18, color=(1, 0, 0))
page.insert_text((40, 70), "机密", fontsize=18, fontfile="NotoSansSC-Regular.otf")
page.add_highlight_annot(page.search_for("重要")) # 搜索并高亮
page.add_link_annot(page.search_for("Example")[0], "https://example.com/")