pypdf PdfWriter 完全指南页面组装、合并、加密与增量写入的 PDF 生成实战【免费下载链接】pypdfA pure-python PDF library capable of splitting, merging, cropping, and transforming the pages of PDF files项目地址: https://gitcode.com/GitHub_Trending/py/pypdf导读PdfWriter是 pypdf 中负责写PDF 的核心类你可以从零创建新文档、克隆现有 PDF、逐页组装页面、合并/拆分文件并在写出前统一设置书签、表单、加密、元数据与页面标签。本文以 docs/modules/PdfWriter.rst 为骨架结合 pypdf/_writer.py 的源码实现与 tests/test_writer.py 的测试用例完整讲解PdfWriter与ObjectDeletionFlag的每一个公开能力读完即可在自己的脚本里稳定地生成、改造和输出 PDF 文件。一、PdfWriter 是什么根据 pypdf/_writer.py 中的类文档PdfWriter的职责是将其他类产生的页面或初始化时克隆的 PDF写出为一个 PDF 文件典型场景是从PdfReader获取数据。它的核心数据模型包括_objects文档中所有间接对象indirect objects的列表_pages/flattened_pages页面树根节点与拍平后的页面列表_root_objectPDF 目录catalog字典/Pages、/Outlines、/AcroForm、/PageLayout、/PageMode等文档级条目都挂在它下面_info_obj文档信息字典对应 trailer 中的/Info_ID文件标识符对应 trailer 中的/ID见 pypdf/_writer.py 的generate_file_identifiers_encryption/_encrypt_entry加密处理器与加密字典。换句话说PdfWriter内部先以纯 Python 对象组装出一棵完整的 PDF 对象树再在write()时序列化为对象体 xref 交叉引用表 trailer的标准物理文件结构见 pypdf/_writer.py 的_write_pdf_structure、_write_xref_table、_write_trailer。二、快速上手最小写入流程PdfWriter的典型用法是配合PdfReader使用from pypdf import PdfReader, PdfWriter reader PdfReader(input.pdf) writer PdfWriter() for page in reader.pages: writer.add_page(page) with open(output.pdf, wb) as f: writer.write(f)也可以直接克隆整个文档等价于另存为同时保留书签、命名目标等结构writer PdfWriter(clone_frominput.pdf) with open(output.pdf, wb) as f: writer.write(f)write()接受路径字符串、Path或任意支持write/tell的文件对象见 pypdf/_writer.py。它返回(bool, IO)元组其中布尔值表示是否由write()内部创建并关闭了文件。仓库的 tests/test_writer.py 中用传统用法半传统用法新用法等多组用例验证了上述三种写法。注意write()要求目标流为二进制模式否则会发出File ... is not in binary mode的警告见 pypdf/_writer.py。三、构造参数详解PdfWriter.__init__的完整签名见 pypdf/_writer.pyPdfWriter( fileobj, clone_fromNone, incrementalFalse, fullFalse, strictFalse, *, keep_initial_headerFalse, incremental_clone_object_count_limit500_000, incremental_clone_object_id_limit1_000_000, )参数默认值含义fileobj兼容参数与clone_from等价可传PdfReader、路径、文件对象或Noneclone_fromNone克隆源传入PdfReader、路径或文件对象时初始化即克隆整份文档走clone_document_from_readerincrementalFalse增量模式先写入原始文档再把新增/修改的对象追加到文件尾部用于保持已签名文档/表单的签名有效fullTrue时加载全部对象fullTrue时总是等价于增量模式适合加载超大 PDF 时节省内存strictFalse为True时对不符合 PDF 规范的输入抛异常为False时尽量宽容处理并记录警告keep_initial_headerFalse非增量克隆时是否保留源文档的 PDF 头如%PDF-1.7而不是使用默认的%PDF-1.3incremental_clone_object_count_limit500_000增量克隆时允许的最大对象数量超出抛LimitReachedErrorincremental_clone_object_id_limit1_000_000增量克隆时允许的最大对象 ID超出抛LimitReachedError几个关键实现细节均有源码依据克隆判定逻辑_get_clone_from会检查fileobj是否指向一个非空、真实存在的文件只有文件存在且非空时才触发克隆pypdf/_writer.py。默认 PDF 头非克隆、非增量模式下新文档默认写%PDF-1.3并自动创建一个只含/Producer: pypdf的/Info字典pypdf/_writer.py。pdf_header属性可读写建议设置为能覆盖所用特性的最低版本pypdf/_writer.py。增量模式incrementalTrue时会把fileobj解析为PdfReader保存在_readerwrite()时先原样写出原文档字节再调用_write_increment追加增量pypdf/_writer.py、pypdf/_writer.py。增量写入使用xref流/Type /XRef与/Prev指向上一个startxrefpypdf/_writer.py。增量克隆的对象数量/ID 上限由_collect_incremental_clone_object_ids检查源文档 xref 中的对象总数与最大对象 ID防止恶意超大文档导致内存问题pypdf/_writer.py。上下文管理器PdfWriter支持with语句退出时自动把内容写入fileobj__exit__调用self.write(self.fileobj)见 pypdf/_writer.py。# 增量写入示例在保留原文件字节不变的前提下追加一个页面 reader PdfReader(signed.pdf) writer PdfWriter(fileobjreader, incrementalTrue) writer.add_page(reader.pages[0]) with open(signed-updated.pdf, wb) as f: writer.write(f)仓库测试 tests/test_writer.py 还验证了向非二进制文件对象写入时会记录警告。四、页面操作添加、插入与空白页PdfWriter提供四个页面级入口实现均在 pypdf/_writer.py方法作用关键行为add_page(page, excluded_keys())在末尾追加一页返回新加入的PageObjectinsert_page(page, index0, excluded_keys())在指定位置插入一页index支持负数越界时回退为add_pageadd_blank_page(widthNone, heightNone)末尾追加空白页未指定尺寸时沿用最后一页的mediabox无上一页则抛PageSizeNotDefinedErrorinsert_blank_page(width, height, index0)在指定位置插入空白页尺寸缺省时取index处已有页的mediabox索引越界抛IndexError底层的_add_pagepypdf/_writer.py做了几件重要的事克隆页面字典同一页面多次加入时Acrobat 不允许两个间接引用指向同一个页面对象因此会为每份拷贝创建新的页面字典但底层内容对象content stream、资源不重复拷贝维护页面树计数插入后沿/Parent链向上更新每层节点的/Count超过 1000 层递归会抛PyPdfError记录未解析链接通过extract_links收集页面间链接在write()时由_resolve_links统一重定向到合并后的新页面pypdf/_writer.py提升 PDF 版本新页面的pdf_header与当前 writer 的版本取较高者_get_max_pdf_version_header。空白页的尺寸单位是 PDF 默认用户空间单位1/72 英寸例如 A4 应为595 × 842writer.add_blank_page(width595, height842)批量拷贝可用append_pages_from_reader(reader, after_page_appendNone)其中after_page_append回调会在每页追加后被调用签名接收刚加入的 writer 页面pypdf/_writer.py。测试见 tests/test_writer.py。五、合并与拆分merge / appendmerge(position, fileobj, outline_itemNone, pagesNone, import_outlineTrue, excluded_fields())将源文件页面插入到position指定的页码之后append(...)是merge的等价形式但始终追加到文件末尾pypdf/_writer.py、pypdf/_writer.py。参数详解参数说明fileobj路径、文件对象或PdfReader内部通过_create_stream统一转成字节流再解析pypdf/_writer.pyoutline_item字符串时在合并处为该文件生成一个书签条目内部调用add_outline_itempages可选PageRange、(start, stop[, step])元组或页码列表实现只合并源文件的部分页面拆分常用import_outline为False时阻止导入源文档的书签excluded_fields忽略的字段键列表包含/Annots则不导入注释包含/B则不导入文章threads/articlespages参数的类型处理在 pypdf/_writer.pyPageRange会被range(*pages.indices(len(reader.pages)))展开(start, stop, step)元组直接传给range非法类型抛TypeError。合并过程中writer 会逐页add_page/insert_page并记录original_page重写命名目标_merge__process_named_dests过滤并重建书签树_get_filtered_outline/_insert_filtered_outline只保留指向已合并页面的书签避免悬空引用过滤注释_insert_filtered_annotations把/GoTo目标重映射到新页合并/AcroForm的/Fields把已拷贝的表单字段追加到 writer 的 AcroForm按需导入文章线索add_filtered_articles/_add_articles_thread。# 合并示例把 B.pdf 插到 A.pdf 第 2 页之后并只取 B.pdf 的第 1~3 页 writer PdfWriter(clone_fromA.pdf) writer.merge(2, B.pdf, pages(0, 3)) writer.write(merged.pdf) # 拆分示例只保留源文件的第 3~5 页 writer PdfWriter() writer.append(source.pdf, pages(2, 5)) writer.write(slice.pdf)仓库测试覆盖了 outline 导入tests/test_writer.py、内部链接注解保持tests/test_writer.py以及多种 append 组合tests/test_writer.py。更完整的实操说明可参考 docs/user/merging-pdfs.md。六、文档级设置打开方式、布局与视图模式这些设置统一写入_root_object目录字典6.1 打开目标open_destinationopen_destination属性控制文档打开时定位到哪一页对应/OpenAction可接受字符串、Destination或PageObject设为None则删除该条目pypdf/_writer.pywriter.open_destination writer.pages[3] # 打开时定位到第 4 页6.2 页面布局page_layout对应/PageLayout合法值源码_valid_layoutspypdf/_writer.py值含义/NoLayout未显式指定布局/SinglePage每次显示一页/OneColumn单列滚动显示/TwoColumnLeft双列显示奇数页在左/TwoColumnRight双列显示奇数页在右/TwoPageLeft同时显示两页奇数页在左/TwoPageRight同时显示两页奇数页在右writer.page_layout /TwoColumnLeft6.3 页面模式page_mode对应/PageMode合法值源码_valid_modespypdf/_writer.py值含义/UseNone不显示书签/缩略图面板/UseOutlines显示书签outline面板/UseThumbs显示缩略图面板/FullScreen全屏视图/UseOC显示可选内容组OCG面板/UseAttachments显示附件面板writer.page_mode /UseOutlines6.4 查看器偏好create_viewer_preferences()创建并挂载/ViewerPreferences字典返回ViewerPreferences对象供继续设置pypdf/_writer.py详细用法见 docs/user/viewer-preferences.md。七、书签与命名目标7.1 添加书签add_outline_item完整签名pypdf/_writer.pyadd_outline_item( title, # 书签标题 page_number, # 目标页PageObject / IndirectObject / 页码 int / None parentNone, # 父书签实现多级嵌套 beforeNone, # 插入到哪个兄弟书签之前 colorNone, # RGB 元组 (0.0~1.0) 或十六进制字符串 #RRGGBB boldFalse, italicFalse, fitPAGE_FIT, # 目标页的 Fit 方式 is_openTrue, )底层会把(title, page_ref, fit)构造成/GoTo动作再通过add_outline_item_destination挂入书签树pypdf/_writer.py。颜色与加粗/斜体分别写入书签的/C与/F条目_create_outline_itempypdf/_writer.py。# 一级书签 writer.add_outline_item(第一章, page_number0) # 带样式与嵌套的二级书签 parent writer.add_outline_item(附录, page_number10, color#FF0000, boldTrue) writer.add_outline_item(附录 A, page_number10, parentparent, italicTrue)add_outline()尚未实现会抛NotImplementedError请使用add_outline_item。测试覆盖了书签颜色tests/test_writer.py、折叠状态tests/test_writer.py等场景实操文档见 docs/user/handling-outlines.md。7.2 命名目标add_named_destinationadd_named_destination(title, page_number)注册一个命名目标写入/Names树并自动按字典序排序add_named_destination_arraypypdf/_writer.pywriter.add_named_destination(chapter1, page_number0)对应测试见 tests/test_writer.py。八、元数据与文档信息PdfWriter提供两层元数据metadata属性读写文档信息字典trailer 的/Info值为DocumentInformation或普通字典设为None会删除/Infopypdf/_writer.py。注意若 PDF 使用 XMP 元数据流而非信息字典需用xmp_metadata。add_metadata(infos)把字典逐键写入信息字典值统一转为字符串pypdf/_writer.py。xmp_metadata属性读写 XMP 元数据流/Metadata值为XmpInformation或原始字节pypdf/_writer.py。writer.metadata { /Title: 我的报告, /Author: pypdf, /Subject: PdfWriter 示例, }写入元数据的测试见 tests/test_writer.py更完整说明见 docs/user/metadata.md。九、加密encryptencrypt()使用 PDF 标准安全处理器对输出加密pypdf/_writer.pyencrypt( user_password: str, owner_password: str | None None, use_128bit: bool True, permissions_flag: UserAccessPermissions ALL_DOCUMENT_PERMISSIONS, *, algorithm: str | None None, )参数与行为user_password打开并受限读取 PDF 的密码owner_password无限制打开 PDF 的密码缺省等于用户密码use_128bitTrue用 128 位默认False用 40 位permissions_flagUserAccessPermissions位标志。位 3 控制打印、位 4 控制修改内容、位 5/6 控制注释、位 9 控制表单字段、位 10 控制文本与图形提取-1表示授予全部权限见UserAccessPermissions.all()algorithm可取值RC4-40、RC4-128、AES-128、AES-256-R5、AES-256一旦指定use_128bit被忽略。非法值抛ValueError。加密流程源码佐证encrypt()会先generate_file_identifiers()生成文件 ID再Encryption.make(alg, permissions, id)构建加密器并写入加密字典pypdf/_writer.py写出阶段对除加密字典外的每个对象调用_encryption.encrypt_object(obj, idnum, 0)pypdf/_writer.py。writer.encrypt( user_passworduserpwd, owner_passwordownerpwd, algorithmAES-256, )限制incremental模式下调用encrypt()会抛NotImplementedError增量写入暂不支持加密。测试 tests/test_writer.py 验证了加密后明文不残留、用户/所有者密码均可解密且能提取原文。完整指南见 docs/user/encryption-decryption.md。十、表单处理10.1 更新字段值update_page_form_field_values签名pypdf/_writer.pyupdate_page_form_field_values( page, # PageObject | list[PageObject] | NoneNone所有页 fields, # 字典字段名(/T) - 值(/V) flagsFA.FfBits(0), # FieldDictionaryAttributes.FfBits 标志 auto_regenerateTrue, # 是否设置 NeedAppearances flattenFalse, # 是否把外观流合并进页面内容 )fields的值支持三种形式普通字符串设置字段值字符串列表用于多选列表字段/Ch元组(value, font_id, font_size)同时指定字体资源 ID如/F1必须已存在与字号0表示自动。源码对文本/选择框字段通过TextStreamAppearance.from_text_annotation生成外观流pypdf/_writer.py复选框/Btn则直接在/AP外观字典里切换/On//Off状态flattenTrue时把外观流以 XObject 形式合入页面内容_add_apstream_objectpypdf/_writer.py。writer.update_page_form_field_values( writer.pages[0], {姓名: 张三, 城市: [北京, 上海], (备注, /F1, 12): 自动生成外观}, )10.2 NeedAppearances 开关set_need_appearances_writer(stateTrue)设置 AcroForm 的NeedAppearances标志指示阅读器是自动生成字段外观还是使用内嵌外观pypdf/_writer.py。10.3 重新挂接孤儿字段reattach_fields(pageNone)扫描页面的/Annots把未登记到 AcroForm/Fields的/Widget注解重新挂接进字段树返回重挂接的字段列表pypdf/_writer.py。表单完整用法见 docs/user/forms.md测试见 tests/test_writer.py。十一、清理与删除ObjectDeletionFlag11.1 删除标志位ObjectDeletionFlag是定义在 pypdf/_writer.py 的enum.IntFlag可与|组合标志含义NONE不删除TEXT删除文本内容Tj、TJ、、等文本显示操作符LINKS删除链接注解/LinkATTACHMENTS删除附件类注解/FileAttachment、/Sound、/Movie、/ScreenOBJECTS_3D删除 3D 注解/3DALL_ANNOTATIONS删除全部注解XOBJECT_IMAGES删除 XObject 图片/Subtype /ImageINLINE_IMAGES删除内联图片DRAWING_IMAGES删除矢量绘图re、m、l、c、f、S等绘图操作符IMAGES上述三种图片的组合11.2 核心方法remove_objects_from_page(page, to_delete, text_filtersNone)按标志清理单页。text_filters是可选字典含font_ids键字体资源 ID 列表如/F1、/T1_0用于只删除特定字体的文本。源码实现会递归进入/FormXObject 清理子内容_remove_objects_from_page__clean_forms/_remove_objects_from_page__clean并跟踪Tf操作符识别当前字体pypdf/_writer.py。remove_links()等价于对所有页执行ALL_ANNOTATIONS。remove_annotations(subtypes)按子类型删除注解subtypesNone删除全部单个或列表均可pypdf/_writer.py。remove_images(to_deleteImageType.ALL)删除图片to_delete取ImageType.XOBJECT_IMAGES、INLINE_IMAGES、DRAWING_IMAGES或ALLpypdf/_writer.py。remove_text(font_namesNone)删除文本传入字体名列表如Helvetica-Bold时只删除该字体渲染的文本。源码会先递归收集页面资源中/Type /Font的/BaseFont并把带子集前缀的名字如/RRXFFVPalatino-Bold规范化为Palatino-Bold再匹配pypdf/_writer.py。writer.remove_objects_from_page( writer.pages[0], ObjectDeletionFlag.TEXT | ObjectDeletionFlag.XOBJECT_IMAGES, ) writer.remove_text(font_names[Helvetica-Bold]) writer.remove_images(ImageType.INLINE_IMAGES)删除图片后内容流非空的断言见 tests/test_writer.py删除文本的用例见 tests/test_writer.py。十二、标注、链接、JavaScript 与附件add_annotation(page_number, annotation)向指定页添加新注解不能复用已有注解返回被插入的对象可用于后续 popup 关联。page_number可为PageObject或页码注解字典会被_pdf_objectify递归转换为 PDF 对象pypdf/_writer.py。参考 docs/user/adding-pdf-annotations.md。add_uri(page_number, uri, rect, borderNone)在页面的矩形区域内添加 URI 链接。rect为RectangleObject或四元组[xLL, yLL, xUR, yUR]border描述边框缺省不绘制四项时可带虚线数组pypdf/_writer.py。测试见 tests/test_writer.py。writer.add_uri(0, https://example.com, [10, 10, 200, 50])add_js(javascript)为文档添加打开时执行的 JavaScript写入/Names/JavaScriptpypdf/_writer.py例如this.print({bUI:true,bSilent:false,bShrinkToFit:true});。参考 docs/user/add-javascript.md。add_attachment(filename, data)把文件内嵌到 PDF对应规范 7.11.3 节返回EmbeddedFile对象pypdf/_writer.py。参考 docs/user/handle-attachments.md。十三、输出控制write / write_stream 与增量写出write()是主入口底层write_stream()区分两种模式pypdf/_writer.py普通模式依次写对象体 →xref交叉引用表 →trailer含/Size、/Root、可选/Info、/ID、/Encrypt→startxref→%%EOF增量模式先整体复制_reader的原字节再用_write_increment只追加新增/修改的对象、一个/Type /XRef的 xref 流和新的startxref。新增对象由list_objects_in_increment()计算——即新对象或哈希与原始不一致的对象pypdf/_writer.py。writer.write(output.pdf) # 路径 with open(out.pdf, wb) as f: # 文件对象 writer.write(f)close()仅为 API 对齐而存在pypdf/_writer.pyPdfWriter还实现了_repr_mimebundle_可直接在 Jupyter Notebook 中内联展示生成的 PDFpypdf/_writer.py。输出相关的版本头设置与流式处理还可参考 docs/user/pdf-version-support.md 与 docs/user/streaming-data.md。十四、压缩与文件瘦身compress_identical_objects()在写出前合并哈希相同的对象使多页共享的公共对象只保留一份pypdf/_writer.pycompress_identical_objects( remove_duplicatesTrue, # 合并重复对象同名旧参数 remove_identicals 已废弃 remove_unreferencedTrue, # 清理未被引用的孤儿对象旧参数 remove_orphans 已废弃 )实现思路先按hash_value()分组把重复对象替换为首个对象的间接引用再以目录根、/Info、/ID为锚点做可达性分析删除不可达对象。参考 docs/user/file-size.md。十五、页码标签set_page_labelset_page_label(page_index_from, page_index_to, styleNone, prefixNone, start0)为指定页范围设置页码标签对应目录的/PageLabelspypdf/_writer.py页索引从 0 开始page_index_to表示范围的结束索引style取值/D阿拉伯数字、/R大写罗马数字、/r小写罗马数字、/A大写字母26 页后 AA、AB…、/a小写字母prefix为标签前缀如第 或Chapter start为范围内首个标签的数字部分默认 1校验规则style与prefix至少给一个page_index_from 0page_index_to page_index_from且不超页数start若给出需 1。writer.set_page_label(0, 4, style/R, prefixPart ) writer.set_page_label(5, 9, style/D, start1)未分配标签的范围默认使用从 1 开始的十进制标签。相关辅助逻辑nums_insert、nums_clear_range、nums_next位于 pypdf/_page_labels.py。十六、从源码看整体架构与相关模块PdfWriter继承自PdfDocCommon见 pypdf/_writer.py因此pages、metadata、xmp_metadata、open_destination等公共能力与PdfReader共享同一套实现协议层面由 pypdf/_protocols.py 的PdfWriterProtocol约束。相关的 RST API 文档还包括 docs/modules/PdfReader.rst、docs/modules/PdfDocCommon.rst、docs/modules/PageObject.rst。进一步阅读建议合并、拆分实操docs/user/merging-pdfs.md加密解密docs/user/encryption-decryption.md书签docs/user/handling-outlines.md表单docs/user/forms.md元数据docs/user/metadata.md水印与盖章docs/user/add-watermark.md裁剪与变换docs/user/cropping-and-transforming.md测试基线与边界用例tests/test_writer.py总结PdfWriter是 pypdf 面向输出的核心门面其能力可归纳为五层页面层add_page/insert_page/ 空白页 /merge/append/ 页面范围切片内容层注解、URI 链接、JS、附件、水印与外观流结构层书签树、命名目标、页码标签、页面布局与视图模式安全与合规层RC4/AES 加密、权限位、NeedAppearances、表单值更新输出层普通写出、增量写出、对象压缩与%%EOF收尾。所有行为都能在 pypdf/_writer.py 中找到直接实现并由 tests/test_writer.py 的 3700 余行测试持续验证。掌握本文列出的参数、默认值与源码调用链即可自信地把PdfWriter用于批量报告生成、文档归档、签名保真增量更新等生产场景。【免费下载链接】pypdfA pure-python PDF library capable of splitting, merging, cropping, and transforming the pages of PDF files项目地址: https://gitcode.com/GitHub_Trending/py/pypdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考