英语日语

在 Discord 上找到 #pymupdf

文档

此类表示一个文档。可以从文件或内存构造。

此类存在别名 open，即 pymupdf.Document(...) 和 pymupdf.open(...) 的功能完全相同。

有关嵌入文件的详细信息，请参阅附录 3。

注意

从 v1.17.0 开始，支持针对仅限 EPUB 文件的新页面寻址机制。此类文档在内部按章节组织，因此可以通过其所谓的“位置”最有效地查找页面。位置是一个元组 (chapter, pno)，包含章节号和该章节内的页码。这两个数字都是从零开始的。

尽管仍然可以通过其（绝对）页码定位页面，但这样做可能意味着必须先对整个 EPUB 文档进行布局，然后才能寻址页面。如果文档非常大，这可能会对性能产生显著影响。使用页面的 (chapter, pno) 可以避免这种情况发生。

为了保持 API 的一致性，PyMuPDF 支持针对所有文件类型的页面 location 语法 – 没有此功能的文档只有一个章节。Document.load_page() 和等效的索引访问现在也支持 location 参数。

有多种方法可用于在页码和位置之间进行转换、确定章节数、每个章节的页数、计算下一页和上一页的位置以及文档的最后一页位置。

方法 / 属性	简要说明
Document.add_layer()	仅限 PDF：创建新的可选内容配置
Document.add_ocg()	仅限 PDF：添加新的可选内容组
Document.authenticate()	获得对加密文档的访问权限
Document.bake()	仅限 PDF：将注释 / 字段设为永久内容
Document.can_save_incrementally()	检查是否可以增量保存
Document.chapter_page_count()	章节中的页数
Document.close()	关闭文档
Document.convert_to_pdf()	将 PDF 版本写入内存
Document.copy_page()	仅限 PDF：复制页面引用
Document.del_toc_item()	仅限 PDF：删除单个 TOC 项
Document.delete_page()	仅限 PDF：删除页面
Document.delete_pages()	仅限 PDF：删除多个页面
Document.embfile_add()	仅限 PDF：从缓冲区添加新的嵌入文件
Document.embfile_count()	仅限 PDF：嵌入文件数
Document.embfile_del()	仅限 PDF：删除嵌入文件条目
Document.embfile_get()	仅限 PDF：提取嵌入文件缓冲区
Document.embfile_info()	仅限 PDF：嵌入文件的元数据
Document.embfile_names()	仅限 PDF：嵌入文件列表
Document.embfile_upd()	仅限 PDF：更改嵌入文件
Document.extract_font()	仅限 PDF：按 xref 提取字体
Document.extract_image()	仅限 PDF：按 xref 提取嵌入图像
Document.ez_save()	仅限 PDF：使用不同默认值的 Document.save()
Document.find_bookmark()	在布局文档后检索页面位置
Document.fullcopy_page()	仅限 PDF：复制页面
Document.get_layer()	仅限 PDF：ON、OFF、RBGroups 中的 OCG 列表
Document.get_layers()	仅限 PDF：可选内容配置列表
Document.get_oc()	仅限 PDF：获取图像 / 表单 xobject 的 OCG /OCMD xref
Document.get_ocgs()	仅限 PDF：所有可选内容组的信息
Document.get_ocmd()	仅限 PDF：检索 OCMD 的定义
Document.get_page_fonts()	仅限 PDF：页面引用的字体列表
Document.get_page_images()	仅限 PDF：页面引用的图像列表
Document.get_page_labels()	仅限 PDF：页面标签定义列表
Document.get_page_numbers()	仅限 PDF：获取具有给定标签的页码
Document.get_page_pixmap()	按页码创建页面的 pixmap
Document.get_page_text()	按页码提取页面文本
Document.get_page_xobjects()	仅限 PDF：页面引用的 XObject 列表
Document.get_sigflags()	仅限 PDF：确定签名状态
Document.get_toc()	提取目录
Document.get_xml_metadata()	仅限 PDF：读取 XML 元数据
Document.has_annots()	仅限 PDF：检查 PDF 是否包含任何注释
Document.has_links()	仅限 PDF：检查 PDF 是否包含任何链接
Document.insert_page()	仅限 PDF：插入新页面
Document.insert_pdf()	仅限 PDF：从另一个 PDF 插入页面
Document.insert_file()	仅限 PDF：从任意文档插入页面
Document.journal_can_do()	仅限 PDF：哪些日志记录操作是可能的
Document.journal_enable()	仅限 PDF：为文档启用日志记录
Document.journal_load()	仅限 PDF：从文件加载日志
Document.journal_op_name()	仅限 PDF：返回日志记录步骤的名称
Document.journal_position()	仅限 PDF：返回日志记录状态
Document.journal_redo()	仅限 PDF：重做当前操作
Document.journal_save()	仅限 PDF：将日志保存到文件
Document.journal_start_op()	仅限 PDF：开始一个“操作”并命名
Document.journal_stop_op()	仅限 PDF：结束当前操作
Document.journal_undo()	仅限 PDF：撤消当前操作
Document.layer_ui_configs()	仅限 PDF：可选内容意图列表
Document.layout()	重新分页文档（如果支持）
Document.load_page()	读取页面
Document.make_bookmark()	在可重排文档中创建页面指针
Document.move_page()	仅限 PDF：将页面移动到文档中的不同位置
Document.need_appearances()	仅限 PDF：获取/设置 /NeedAppearances 属性
Document.new_page()	仅限 PDF：插入新的空白页面
Document.next_location()	返回下一页的 (chapter, pno)
Document.outline_xref()	仅限 PDF：获取 TOC 项的 xref
Document.page_cropbox()	仅限 PDF：未旋转的页面矩形
Document.page_xref()	仅限 PDF：页码的 xref
Document.pages()	页面范围的迭代器
Document.pdf_catalog()	仅限 PDF：目录（根）的 xref
Document.pdf_trailer()	仅限 PDF：trailer 源
Document.prev_location()	返回前一页的 (chapter, pno)
Document.recolor()	仅限 PDF：对所有页面执行 Page.recolor()
Document.reload_page()	仅限 PDF：提供页面的新副本
Document.resolve_names()	仅限 PDF：将目标名称转换为 Python 字典
Document.save()	仅限 PDF：保存文档
Document.saveIncr()	仅限 PDF：增量保存文档
Document.scrub()	仅限 PDF：移除敏感数据
Document.search_page_for()	在页面上搜索字符串
Document.select()	仅限 PDF：选择页面的子集
Document.set_layer_ui_config()	仅限 PDF：临时设置 OCG 可见性
Document.set_layer()	仅限 PDF：批量更改 OCG 状态
Document.set_markinfo()	仅限 PDF：设置 MarkInfo 值
Document.set_metadata()	仅限 PDF：设置元数据
Document.set_oc()	仅限 PDF：将 OCG/OCMD 附加到图像 / 表单 xobject
Document.set_ocmd()	仅限 PDF：创建或更新 OCMD
Document.set_page_labels()	仅限 PDF：添加/更新页面标签定义
Document.set_pagemode()	仅限 PDF：设置 PageMode
Document.set_pagelayout()	仅限 PDF：设置 PageLayout
Document.set_toc_item()	仅限 PDF：更改单个 TOC 项
Document.set_toc()	仅限 PDF：设置目录 (TOC)
Document.set_xml_metadata()	仅限 PDF：创建或更新文档 XML 元数据
Document.subset_fonts()	仅限 PDF：创建字体子集
Document.switch_layer()	仅限 PDF：激活 OC 配置
Document.tobytes()	仅限 PDF：将文档写入内存
Document.xref_copy()	仅限 PDF：将 PDF 字典复制到另一个 xref
Document.xref_get_key()	仅限 PDF：获取字典键的值
Document.xref_get_keys()	仅限 PDF：列出 xref 处对象的键
Document.xref_object()	仅限 PDF：获取 xref 的定义源
Document.xref_set_key()	仅限 PDF：设置字典键的值
Document.xref_stream_raw()	仅限 PDF：xref 处的原始流源
Document.xref_xml_metadata()	仅限 PDF：XML 元数据的 xref
Document.chapter_count	章节数
Document.FormFonts	仅限 PDF：全局小部件字体列表
Document.is_closed	文档已关闭？
Document.is_dirty	仅限 PDF：文档是否已更改？
Document.is_encrypted	文档（仍然）已加密？
Document.is_fast_webaccess	PDF 是否已线性化？
Document.is_form_pdf	这是 Form PDF 吗？
Document.is_pdf	这是 PDF 吗？
Document.is_reflowable	这是可重排文档吗？
Document.is_repaired	仅限 PDF：此 PDF 在打开期间是否已修复？
Document.last_location	最后一页的 (chapter, pno)
Document.metadata	元数据
Document.markinfo	PDF MarkInfo 值
Document.name	文档文件名
Document.needs_pass	需要密码才能访问数据？
Document.outline	第一个 Outline 项
Document.page_count	页数
Document.permissions	访问文档的权限
Document.pagemode	PDF PageMode 值
Document.pagelayout	PDF PageLayout 值
Document.version_count	PDF 版本计数

类 API

class Document

__init__(self, filename=None, stream=None, *, filetype=None, rect=None, width=0, height=0, fontsize=11)

创建一个 Document 对象。

• 使用默认参数，将创建一个新的空 PDF 文档。

• 如果指定了 stream，则从内存创建文档。

• 如果 stream 为 None，则从 filename 指定的文件创建文档。

参数：

• filename (str,pathlib) – 包含文件路径的 UTF-8 字符串或 pathlib.Path 对象。文档类型始终根据文件内容确定。filetype 参数可用于确保检测到的类型符合预期，或者强制将任何文件视为纯文本。

• stream (bytes,bytearray,BytesIO) – 包含文件数据的内存区域。文档类型始终根据数据内容检测。filetype 参数会被忽略，除非数据内容无法检测到。仅在这种情况下，使用 filetype="txt" 会将数据视为纯文本内容。

• filetype (str) –

  指定文档类型的字符串。可以是任何看起来像文件名的东西（例如“x.pdf”），在这种情况下 MuPDF 会使用扩展名来确定类型，也可以是 mime 类型，例如 application/pdf。只使用“pdf”或“.pdf”等字符串也可以。对于支持的文档类型，可以省略此参数。

  如果只打开文件名/路径，则会用它来确保检测到的类型符合预期。如果不匹配，则会引发异常。使用 filetype="txt" 会将任何文件视为纯文本内容。

  从内存打开时，除未检测到的数据内容外，此参数将被忽略。仅在这种情况下，使用 filetype="txt" 会将数据视为纯文本内容。

• rect (rect_like) – 指定所需页面大小的矩形。此参数仅对具有可变页面布局（“可重排”文档）的文档有意义，例如电子书或 HTML，否则将被忽略。如果指定，它必须是一个非空、有限的矩形，其左上角坐标为 (0, 0)。结合参数 fontsize，每个页面将相应地进行布局，从而也确定页数。

• width (float) – 可与 height 一起用作 rect 的替代方案，以指定布局信息。

• height (float) – 可与 width 一起用作 rect 的替代方案，以指定布局信息。

• fontsize (float) – 可重排文档类型的默认 fontsize。如果未指定参数 rect 或 width 和 height，则此参数将被忽略。将用于计算页面布局。

引发：

• TypeError – 如果任何参数的 type 不符合要求。

• FileNotFoundError – 如果找不到文件/路径。重新实现为 RuntimeError 的子类。

• EmptyFileError – 如果文件/路径为空或内存中的 bytes 对象长度为零。它是 FileDataError 和 RuntimeError 的子类。

• ValueError – 如果显式指定了未知文件类型。

• FileDataError – 如果文档对于给定类型具有无效结构 – 或者根本不是文件（例如文件夹）。它是 RuntimeError 的子类。

返回：

文档对象。如果无法创建文档，则会按上述顺序引发异常。请注意，如果您检查 RuntimeError，PyMuPDF 特定的异常（FileNotFoundError、EmptyFileError 和 FileDataError）将被拦截。

如有问题，您可以在内部消息存储中查看更多详细信息：print(pymupdf.TOOLS.mupdf_warnings())（此调用会清空该存储，但您也可以阻止此操作 – 请参阅 Tools.mupdf_warnings()）。

可能的形式概述，注意：open 是 Document 的同义词。

>>> # from a file
>>> doc = pymupdf.open("some.xps")
>>> # handle wrong extension
>>> doc = pymupdf.open("some.file", filetype="xps")  # assert expected type
>>> doc = pymupdf.open("some.file", filetype="txt")  # treat as plain text
>>>
>>> # from memory
>>> doc = pymupdf.open(stream=mem_area)  # works for any supported type
>>> doc = pymupdf.open(stream=unknown-type, filetype="txt")  # treat as plain text
>>>
>>> # new empty PDF
>>> doc = pymupdf.open()
>>> doc = pymupdf.open(None)
>>> doc = pymupdf.open("")

注意

具有错误（但支持）文件扩展名的光栅图像不是问题。当实际访问文件内容时，MuPDF 将确定正确的图像类型并进行处理，不会报错。

Document 类也可以用作上下文管理器。退出内容管理器时，文档将自动关闭。

>>> import pymupdf
>>> with pymupdf.open(...) as doc:
        for page in doc: print("page %i" % page.number)
page 0
page 1
page 2
page 3
>>> doc.is_closed
True
>>>

get_oc(xref)

• v1.18.4 新增

返回附加到图像或表单 xobject 的 OCG 或 OCMD 的交叉引用编号。

参数：

xref (int) – 图像或表单 xobject 的 xref。有效的此类交叉引用编号由 Document.get_page_images() 或 Document.get_page_xobjects() 返回。对于无效编号，将引发异常。

返回类型：

int

返回：

可选内容对象的交叉引用编号，如果没有则为零。

set_oc(xref, ocxref)

• v1.18.4 新增

如果 xref 代表图像或表单 xobject，则设置或移除可选内容对象的交叉引用编号 ocxref。

参数：

• xref (int) – 图像或表单 xobject 的 xref [5]。有效的此类交叉引用编号由 Document.get_page_images() 或 Document.get_page_xobjects() 返回。对于无效编号，将引发异常。

• ocxref (int) – OCG / OCMD 的 xref 编号。如果非零，无效引用将引发异常。如果为零，则移除所有 OC 引用。

get_layers()

• v1.18.3 新增

显示可选图层配置。始终存在一个标准配置，该标准配置不包含在响应中。

>>> for item in doc.get_layers(): print(item)
{'number': 0, 'name': 'my-config', 'creator': ''}
>>> # use 'number' as config identifier in add_ocg

add_layer(name, creator=None, on=None)

• v1.18.3 新增

添加可选内容配置。图层作为可选内容组的 ON / OFF 状态集合，允许在同一文档的不同视图之间快速切换可见性。

参数：

• name (str) – 任意名称。

• creator (str) – （可选）创建软件。

• on (sequ) – OCG 的序列 xref 编号，当激活此图层时应设置为 ON。此处未列出的所有 OCG 都将设置为 OFF。

switch_layer(number, as_default=False)

• v1.18.3 新增

切换到由可选图层的配置编号定义的文档视图。这是临时的，除非设置为默认值。

参数：

• number (int) – 配置编号，由 Document.layer_configs() 返回。

• as_default (bool) – 将此设为默认配置。

激活已识别图层中定义的 OCG 的 ON / OFF 状态。如果 as_default=True，则此外还会合并所有图层（包括标准图层），并将结果写回标准图层，并且所有可选图层都将被删除。

add_ocg(name, config=-1, on=True, intent='View', usage='Artwork')

• v1.18.3 新增

添加可选内容组。OCG 是确定对象可见性最重要的信息单元。对于 PDF 文件，为了被视为包含可选内容，至少必须存在一个 OCG。

参数：

• name (str) – 任意名称。将在支持的 PDF 阅读器中显示。

• config (int) – 图层配置编号。默认值 -1 为标准配置。

• on (bool) – 指向此 OCG 的对象的标准可见性状态。

• intent (str,list) – 声明可见性意图的字符串或字符串列表。有两个 PDF 标准值可供选择：“View”和“Design”。默认值为“View”。请注意拼写正确。

• usage (str) – 另一个影响 OCG 可见性的因素。这将成为 OCG /Usage 键的一部分。有两个 PDF 标准值可供选择：“Artwork”和“Technical”。默认值为“Artwork”。仅在需要时更改。

返回：

创建的 OCG 的 xref。在支持对象中用作 oc 参数的条目。

注意

可以创建具有相同参数的多个 OCG。这不会导致问题。Document.save() 的垃圾选项 3 将删除任何重复项。

set_ocmd(xref=0, ocgs=None, policy='AnyOn', ve=None)

• v1.18.4 新增

创建或更新 OCMD，即可选内容成员字典。

参数：

• xref (int) – 要更新的 OCMD 的 xref，或对于新的 OCMD 为 0。

• ocgs (list) – 现有 OCG PDF 对象的 xref 编号序列。

• policy (str) – “AnyOn”（默认）、“AnyOff”、“AllOn”、“AllOff”之一（混合或小写）。

• ve (list) – “可见性表达式”。这是一个任意嵌套的其他列表的列表 – 参见下面的解释。如果需要制定更复杂的条件，可作为组合 ocgs / policy 的替代方案使用。

返回类型：

int

返回：

OCMD 的 xref。在支持对象中用作 oc=xref 参数，并分别在 Document.set_oc() 或 Annot.set_oc() 中使用。

注意

与 OCG 类似，OCMD 具有 ON 或 OFF 的可见性状态，并且可以像 OCG 一样使用。与 OCG 不同的是，OCMD 状态是通过评估一个或多个 OCG 的状态（通过特殊形式的布尔表达式）来确定的。如果表达式评估为 true，则 OCMD 状态为 ON；如果为 false，则为 OFF。

有两种方法来制定 OCMD 可见性：

1. 使用 ocgs 和 policy 的组合：policy 值的解释如下：

• AnyOn –（默认）如果至少一个 OCG 为 ON，则为 true。

• AnyOff – 如果至少一个 OCG 为 OFF，则为 true。

• AllOn – 如果所有 OCG 都为 ON，则为 true。

• AllOff – 如果所有 OCG 都为 OFF，则为 true。

假设您希望两个 PDF 对象精确地同时显示一个（如果一个为 ON，则另一个必须为 OFF）：

解决方案：对象 1 使用 OCG，对象 2 使用 OCMD。通过 set_ocmd(ocgs=[xref], policy="AllOff") 创建 OCMD，其中 xref 是 OCG 的。

2. 使用可见性表达式 ve：这是一个包含两个或更多项的列表。第一项是逻辑关键字：字符串 “and”、“or” 或 “not” 之一。第二项以及所有后续项必须是整数或另一个列表。整数必须是 OCG 的 xref 编号。列表再次必须至少有两个项，并且以布尔关键字之一开头。这种语法有点笨拙，但功能强大：

• 每个列表必须以逻辑关键字开头。

• 如果关键字是 “not”，则列表必须正好有两个项。如果是 “and” 或 “or”，可以跟随任意数量的其他项。

• 跟随逻辑关键字的项可以是整数或再次是一个列表。整数必须是 OCG 的 xref。列表必须符合前面的规则。

示例：

• set_ocmd(ve=["or", 4, ["not", 5], ["and", 6, 7]])。如果以下条件为 true，则结果为 ON：“4 为 ON，或 5 为 OFF，或 6 和 7 都为 ON”。

• set_ocmd(ve=["not", xref])。这与在 1 中创建的 OCMD 示例具有相同的效果。

有关更多详细信息和示例，请参见 Adobe PDF 参考手册 的第 224 页。另请查看此处的示例脚本。

可见性表达式 /VE 是 PDF 规范版本 1.6 的一部分。因此，并非所有 PDF 查看器/阅读器都可能已经支持此功能，因此在这些情况下将以某种标准方式做出反应。

get_ocmd(xref)

• v1.18.4 新增

检索 OCMD 的定义。

参数：

xref (int) – OCMD 的 xref。

返回类型：

dict

返回：

一个字典，包含键 xref、ocgs、policy 和 ve。

get_layer(config=-1)

• v1.18.3 新增

指定配置中按状态列出的可选内容组。这是一个字典，其中包含出现在 /ON、/OFF 数组或某些单选按钮组（/RBGroups）中的 OCG 的交叉引用编号列表。

参数：

config (int) – 配置图层（默认为标准配置图层）。

>>> pprint(doc.get_layer())
{'off': [8, 9, 10], 'on': [5, 6, 7], 'rbgroups': [[7, 10]]}
>>>

set_layer(config, *, on=None, off=None, basestate=None, rbgroups=None, locked=None)

• v1.18.3 新增

• v1.22.5 中的更改：支持 locked OCG 列表。

可选内容组的批量状态更改。永久设置 OCG 的状态。

参数：

• config (int) – 所需的配置图层，默认选择 -1。

• on (list) – 要设置为 ON 的 OCG 的 xref 列表。替换先前的值。空列表将导致不再有 OCG 被设置为 ON。如果使用 basestate="ON"，则应指定此参数。

• off (list) – 要设置为 OFF 的 OCG 的 xref 列表。替换先前的值。空列表将导致不再有 OCG 被设置为 OFF。如果使用 basestate="OFF"，则应指定此参数。

• basestate (str) – 未在 on 或 off 中提及的 OCG 的状态。可能的值为“ON”、“OFF”或“Unchanged”。可以是大写或小写。

• rbgroups (list) – 列表的列表。替换先前的值。每个子列表应包含两个或更多 OCG xref。同一子列表中的 OCG 像单选按钮组中的按钮一样处理：将一个设置为 ON 会自动将所有其他组成员设置为 OFF。

• locked (list) – 无法通过用户界面更改的 OCG xref 编号列表。

值 None 不会更改相应的 PDF 数组。

>>> doc.set_layer(-1, basestate="OFF")  # only changes the base state
>>> pprint(doc.get_layer())
{'basestate': 'OFF', 'off': [8, 9, 10], 'on': [5, 6, 7], 'rbgroups': [[7, 10]]}

get_ocgs()

• v1.18.3 新增

所有可选内容组的详细信息。这是一个字典，其键是 OCG 的 xref。

>>> pprint(doc.get_ocgs())
{13: {'on': True,
      'intent': ['View', 'Design'],
      'name': 'Circle',
      'usage': 'Artwork'},
14: {'on': True,
      'intent': ['View', 'Design'],
      'name': 'Square',
      'usage': 'Artwork'},
15: {'on': False, 'intent': ['View'], 'name': 'Square', 'usage': 'Artwork'}}
>>>

layer_ui_configs()

• v1.18.3 新增

显示可通过支持的 PDF 查看器用户界面修改的可选内容的可见性状态。

• 仅报告当前选定图层配置中包含的项目。

• 字典键的含义如下：

  • depth: 项目在 /Order 数组中的嵌套级别。

  • locked: 如果无法通过用户界面更改，则为 true。

  • number: 运行序列号。

  • on: 项目状态。

  • text: 原始 OCG 的文本字符串或名称字段。

  • type: “label”（由文本字符串设置）、“checkbox”（由单个 OCG 设置）或“radiobox”（由一组连接的 OCG 设置）之一。

set_layer_ui_config(number, action=0)

• v1.18.3 新增

修改内容组的 OC 可见性状态。这类似于支持的 PDF 查看器提供的功能。

请注意，可见性不是与 OCG 一起存储的属性。它甚至不是 PDF 文档中必须存在的信息。相反，当前可见性是使用某些支持的 PDF 消费软件的用户界面临时设置的。此方法提供了相同类型的功能。

要进行永久性更改，请使用 Document.set_layer()。

参数：

• number (int,str) – 列表 Document.layer_configs() 中项目的序列号，或是这些项目之一的“text”。

• action (int) – PDF_OC_ON = 设置为 ON（默认），PDF_OC_TOGGLE = 切换 ON/OFF，PDF_OC_OFF = 设置为 OFF。

authenticate(password)

使用字符串 password 解密文档。如果成功，即可访问文档数据。对于 PDF 文档，“所有者”和“用户”具有不同的权限，因此这些授权级别可能存在不同的密码。该方法将自动为提供的密码建立相应的（所有者或用户）访问权限。

参数：

password (str) – 所有者或用户密码。

返回类型：

int

返回：

如果成功，则为正值；否则为零（字符串与任一密码都不匹配）。如果为正，则指示器 Document.is_encrypted 设置为 False。正返回值包含以下详细信息：

• 1 => 已认证，但 PDF 既没有所有者密码也没有用户密码。

• 2 => 使用用户密码认证。

• 4 => 使用所有者密码认证。

• 6 => 已认证且两个密码相同 – 这可能是一种罕见情况。

注意

文档可能受所有者保护，但不受用户密码保护。可通过 doc.authenticate("") == 2 检测此情况。这允许在不认证的情况下打开和读取文档，但根据 Document.permissions 值，其他操作可能被禁止。在这种情况下，PyMuPDF（与 MuPDF 类似）会忽略这些限制。因此，与任何 PDF 查看器不同，即使相应的权限标志 PDF_PERM_COPY、PDF_PERM_MODIFY、PDF_PERM_ANNOTATE 等被关闭，您仍然可以例如提取文本以及添加或修改内容！在适用情况下构建符合法律规定的应用程序是您的责任。

get_page_numbers(label, only_one=False)

• v 1.18.6 新增

仅限 PDF：返回具有指定标签的页码列表 – 请注意，标签在 PDF 中可能不是唯一的。这意味着需要顺序搜索所有页码来比较它们的标签。

注意

实现细节 – 为此目的，页面未加载。

参数：

• label (str) – 要查找的标签，例如“vii”（罗马数字 7）。

• only_one (bool) – 首次匹配后停止。例如，如果已知标签是唯一的，或者页面很多等，则很有用。默认设置将检查每个页码。

返回类型：

list

返回：

具有此标签的页码列表。如果未找到，未定义标签等，则为空。

get_page_labels()

• v1.18.7 新增

仅限 PDF：提取页面标签定义列表。通常用于在将其输入 Document.set_page_labels() 之前进行修改。

返回：

如 Document.set_page_labels() 中定义的字典列表。

set_page_labels(labels)

• v1.18.6 中的新功能

仅限 PDF：添加或更新 PDF 的页面标签定义。

参数：

labels (列表) –

一个字典列表。每个字典定义了一个标签构建规则和一个从 0 开始的“开始”页码。该开始页是标签定义有效的第一个页面。每个字典最多包含 4 个项目，格式如下：{'startpage': int, 'prefix': str, 'style': str, 'firstpagenum': int} 并包含以下项目。

• startpage：（整型）应用标签规则的第一个页码（从 0 开始）。此键必须存在。该规则将应用于所有后续页面，直到文档末尾或被具有下一个更大页码的规则取代。

• prefix：（str）用于开始标签的任意字符串，例如“A-”。默认为“”。

• style：（str）编号样式。可用样式包括“D”（十进制）、“r”/“R”（罗马数字，小写/大写）和“a”/“A”（字母编号，小写/大写：“a”到“z”，然后“aa”到“zz”，以此类推）。默认为“”。如果为“”，则不进行编号，该范围内的页面将收到由prefix值组成的相同标签。如果也省略 prefix，则标签将为空“”。

• firstpagenum：（整型）从此值开始编号。默认为 1，较小的值将被忽略。

例如

[{'startpage': 6, 'prefix': 'A-', 'style': 'D', 'firstpagenum': 10},
 {'startpage': 10, 'prefix': '', 'style': 'D', 'firstpagenum': 1}]

将为第 6、7 页及之后直至文档末尾的页面生成标签“A-10”、“A-11”、“A-12”、“A-13”、“1”、“2”、“3”等。第 0 至 5 页的标签将为空“”。

make_bookmark(loc)

• v.1.17.3 新增

在可重排文档中返回页面指针。在重新布局文档后，此方法的结果可用于查找页面的新位置。

注意

不要与目录（TOC）中的项目混淆。

参数：

loc (列表,元组) – 页面位置。必须是有效的 (chapter, pno)。

返回类型：

指针

返回：

指针格式的长整型值。用于在重新布局文档后查找页面的新位置。请勿修改或重新赋值。

find_bookmark(bookmark)

• v.1.17.3 新增

返回文档重新布局后的新页面位置。

参数：

bookmark (指针) – 由 Document.make_bookmark() 创建。

返回类型：

元组

返回：

页面的新 (chapter, pno)。

chapter_page_count(chapter)

• v.1.17.0 新增

返回章节的页数。

参数：

chapter (整型) – 从 0 开始的章节号。

返回类型：

int

返回：

章节中的页数。仅适用于支持章节的文档类型（目前是 EPUB）。

next_location(page_id)

• v.1.17.0 新增

返回下一页的位置。

参数：

page_id (元组) – 当前页面 ID。必须是一个识别现有页面的元组 (chapter, pno)。

返回：

下一页的元组，即 (chapter, pno + 1) 或 (chapter + 1, 0)，或者如果参数是最后一页，则返回空元组 ()。仅适用于支持章节的文档类型（目前是 EPUB）。

prev_location(page_id)

• v.1.17.0 新增

返回前一页的位置指示符。

参数：

page_id (元组) – 当前页面 ID。必须是一个识别现有页面的元组 (chapter, pno)。

返回：

前一页的元组，即 (chapter, pno - 1) 或前一章节的最后一页，或者如果参数是第一页，则返回空元组 ()。仅适用于支持章节的文档类型（目前是 EPUB）。

load_page(page_id=0)

• v1.17.0 中更改：对于支持所谓“章节结构”的文档类型（如 EPUB），页面也可以通过章节号和相对页码的组合来加载，而不是通过绝对页码。这应该会显著加快对大型文档的访问速度。

创建一个 Page 对象用于进一步处理（如渲染、文本搜索等）。

参数：

page_id (整型,元组) –

（v1.17.0 中更改）

一个从 0 开始的页码，或者一个元组 (chapter, pno)。对于整型，任何 -∞ < page_id < page_count 都是可接受的。当 page_id 为负数时，将为其加上 page_count。例如：要加载最后一页，可以使用 doc.load_page(-1)。之后 page.number 将等于 doc.page_count - 1。

对于元组，chapter 必须在 Document.chapter_count 范围内，pno 必须在该章节的 Document.chapter_page_count() 范围内。这两个值都从 0 开始。使用这种表示法，Page.number 将等于给定的元组。仅适用于支持章节的文档类型（目前是 EPUB）。

返回类型：

Page

注意

文档也遵循 Python 序列协议，页码作为索引：doc.load_page(n) == doc[n]。

仅对于绝对页码，像 “for page in doc: …” 和 “for page in reversed(doc): …” 这样的表达式将依次生成文档的页面。请参阅 Document.pages()，它允许像切片一样处理页面。

您还可以使用新的基于章节的页面标识方式的索引表示法：使用 page = doc[(5, 2)] 来加载第六章的第三页。

为了保持 API 的一致性，对于不支持章节结构（如 PDF）的文档类型，Document.chapter_count 为 1，并且也可以通过元组 (0, pno) 来加载页面。有关性能改进的评论，请参阅此[3]脚注。

recolor(components=1)

仅限 PDF：更改所有页面中所有对象类型（文本、图像和矢量图形）的颜色分量数。

参数：

components (整型) – 期望的颜色空间，由颜色分量数量指示：1 = DeviceGRAY（设备灰度），3 = DeviceRGB（设备 RGB），4 = DeviceCMYK（设备 CMYK）。

典型的用例是 1 (DeviceGRAY)，它将 PDF 转换为灰度。

reload_page(page)

• v1.16.10 新增

仅限 PDF：在完成并更新所有待处理的更改后，提供页面的新副本。

参数：

page (Page) – 页面对象。

返回类型：

Page

返回：

同一页面的新副本。所有待处理的更新（例如注释或控件的更新）都将完成，并加载页面的新副本。

注意

在典型用例中，在添加或更改注释/控件后，应该获取页面的 Pixmap。为了强制将所有这些更改反映在页面结构中，此方法会重新加载一个新副本，同时保持对象层级结构“文档 -> 页面 -> 注释/控件”完整。

resolve_names()

仅限 PDF：将目标名称转换为 Python 字典。

返回：

具有以下结构的字典

• key: (str) 名称。

• value: (dict) 具有以下结构

  • “page”：目标页码（从 0 开始）。如果未找到页码，则为 -1。

  • “to”：页面上的目标点 (x, y)。当前采用 PDF 坐标，即点 (0,0) 是页面的左下角。

  • “zoom”：（float）缩放因子。

  • “dest”：（str）仅当页面上的目标位置未以“/XYZ”形式提供或未找到页码时存在。

示例：

{
    '__bookmark_1': {'page': 0, 'to': (0.0, 541.0), 'zoom': 0.0},
    '__bookmark_2': {'page': 0, 'to': (0.0, 481.45), 'zoom': 0.0},
}

或

{
    '21154a7c20684ceb91f9c9adc3b677c40': {'page': -1, 'dest': '/XYZ 15.75 1486 0'},
    ...
}

目录中键“/Dests”和“/Names/Dests”下找到的所有名称都将包含在内。

• v1.23.6 新增

page_cropbox(pno)

• v1.17.7 新增

仅限 PDF：返回未旋转的页面矩形 – 不加载页面（通过 Document.load_page()）。这用于需要最佳性能的内部目的。

参数：

pno (整型) – 从 0 开始的页码。

返回：

页面的 Rect，类似于 Page.rect()，但忽略任何旋转。

page_xref(pno)

• v1.17.7 新增

仅限 PDF：返回页面的 xref – 不加载页面（通过 Document.load_page()）。这用于需要最佳性能的内部目的。

参数：

pno (整型) – 从 0 开始的页码。

返回：

页面的 xref，类似于 Page.xref。

pages(start=None[, stop=None[, step=None]])

• v1.16.4 新增

页面范围的生成器。参数的含义与内置函数 range() 相同。旨在用于 “for page in doc.pages(start, stop, step): …” 形式的表达式。

参数：

• start (整型) – 从此页码开始迭代。默认为零，允许的值范围为 -∞ < start < page_count。当此值为负时，在开始迭代之前会加上 page_count。

• stop (整型) – 在此页码停止迭代。默认为 page_count，可能的值范围为 -∞ < stop <= page_count。较大的值将被静默替换为默认值。负值将按倒序循环发出页面。与内置函数 range() 一样，这是不返回的第一个页面。

• step (整型) – 步进值。如果 start < stop，默认为 1；如果 start > stop，默认为 -1。不允许为零。

返回：

文档页面的生成器迭代器。一些示例

• “doc.pages()” 发出所有页面。

• “doc.pages(4, 9, 2)” 发出页面 4, 6, 8。

• “doc.pages(0, None, 2)” 发出所有页码为偶数的页面。

• “doc.pages(-2)” 发出最后两页。

• “doc.pages(-1, -1)” 发出所有页面，按倒序排列。

• “doc.pages(-1, -10)” 始终按倒序发出 10 个页面，从最后一页开始 – 如果文档页数少于 10 页，则重复。因此，对于 4 页的文档，将发出以下页码：3, 2, 1, 0, 3, 2, 1, 0, 3。

convert_to_pdf(from_page=-1, to_page=-1, rotate=0)

创建当前文档的 PDF 版本并写入内存。支持所有文档类型。参数的含义与 insert_pdf() 相同。本质上，您可以将转换限制在页面子集内，指定页面旋转，以及反转页面顺序。

参数：

• from_page (整型) – 第一个要复制的页面（从 0 开始）。默认为第一页。

• to_page (整型) – 最后一个要复制的页面（从 0 开始）。默认为最后一页。

• rotate (整型) – 旋转角度。默认为 0（不旋转）。应为 n * 90，其中 n 为整型（不进行检查）。

返回类型：

字节

返回：

一个包含 PDF 文件图像的 Python bytes 对象。它通过内部使用 tobytes(garbage=4, deflate=True) 创建。请参阅 tobytes()。您可以直接将其输出到磁盘或作为 PDF 打开。这里有一些示例

>>> # convert an XPS file to PDF
>>> xps = pymupdf.open("some.xps")
>>> pdfbytes = xps.convert_to_pdf()
>>>
>>> # either do this -->
>>> pdf = pymupdf.open("pdf", pdfbytes)
>>> pdf.save("some.pdf")
>>>
>>> # or this -->
>>> pdfout = open("some.pdf", "wb")
>>> pdfout.tobytes(pdfbytes)
>>> pdfout.close()

>>> # copy image files to PDF pages
>>> # each page will have image dimensions
>>> doc = pymupdf.open()                     # new PDF
>>> imglist = [ ... image file names ...] # e.g. a directory listing
>>> for img in imglist:
        imgdoc=pymupdf.open(img)           # open image as a document
        pdfbytes=imgdoc.convert_to_pdf()  # make a 1-page PDF of it
        imgpdf=pymupdf.open("pdf", pdfbytes)
        doc.insert_pdf(imgpdf)             # insert the image PDF
>>> doc.save("allmyimages.pdf")

注意

此方法使用与 mutool convert CLI 相同的逻辑。在大多数情况下效果非常好 – 但是，请注意以下限制。

• 图像文件：完美，未检测到问题。但是，图像透明度会被忽略。如果您需要透明度（例如用于水印），请改用 Page.insert_image()。否则，建议使用此方法，因为它具有更好的性能。

• XPS：外观非常好。链接正常工作，大纲（书签）会丢失，但可以轻松恢复 [2]。

• EPUB, CBZ, FB2：与 XPS 类似。

• SVG：中等。大致可与 svglib 相媲美。

get_toc(simple=True)

从文档的大纲链创建目录（TOC）。

参数：

simple (布尔型) – 指示是否需要简单或详细的 TOC。如果为 False，列表中的每个项目还包含一个字典，其中包含每个大纲条目的 linkDest 详细信息。

返回类型：

list

返回：

一个列表的列表。每个条目的形式为 [lvl, title, page, dest]。其条目具有以下含义

• lvl – 层级级别（正数 整型）。第一个条目始终为 1。同一行中的条目要么相等，要么增加 1，要么减少任意数量。

• title – 标题 (str)

• page – 基于 1 的源页码 (整型)。如果无目标或在文档外部，则为 -1。

• dest – (字典) 仅当 simple=False 时包含。包含 TOC 项目的详细信息，如下所示

  • kind：目标类型，请参阅 链接目标类型。

  • file：如果类型为 LINK_GOTOR 或 LINK_LAUNCH，则为文件名。

  • page：目标页码，从 0 开始，仅适用于 LINK_GOTOR 或 LINK_GOTO。

  • to：目标页面上的位置 (Point)。

  • zoom：（float）目标页面上的缩放因子。

  • xref：项目的 xref（如果不是 PDF 则为 0）。

  • color：PDF RGB 格式的项目颜色 (red, green, blue)，或省略（如果不是 PDF 则始终省略）。

  • bold：如果项目文本为粗体，则为 True，否则省略。仅限 PDF。

  • italic：如果项目文本为斜体，则为 True，否则省略。仅限 PDF。

  • collapse：如果子项目已折叠，则为 True，否则省略。仅限 PDF。

  • nameddest：如果 kind=4，则为目标名称。仅限 PDF。（v1.23.7 新增。）

xref_get_keys(xref)

• v1.18.7 新增

仅限 PDF：返回由其 xref 号码提供的 dictionary 对象的 PDF 字典键。

参数：

xref (整型) – xref。（v1.18.10 中更改）使用 -1 访问特殊字典“PDF trailer”。

返回：

对象 xref 中存在的字典键的元组。示例

>>> from pprint import pprint
>>> import pymupdf
>>> doc=pymupdf.open("pymupdf.pdf")
>>> xref = doc.page_xref(0)  # xref of page 0
>>> pprint(doc.xref_get_keys(xref))  # primary level keys of a page
('Type', 'Contents', 'Resources', 'MediaBox', 'Parent')
>>> pprint(doc.xref_get_keys(-1))  # primary level keys of the trailer
('Type', 'Index', 'Size', 'W', 'Root', 'Info', 'ID', 'Length', 'Filter')
>>>

xref_get_key(xref, key)

• v1.18.7 新增

仅限 PDF：返回由其 xref 号码提供的 dictionary 对象的 PDF 字典键的类型和值。

参数：

• xref (整型) – xref。v1.18.10 中更改：使用 -1 访问特殊字典“PDF trailer”。

• key (str) – 期望的 PDF 键。必须完全匹配（区分大小写）Document.xref_get_keys() 中包含的键之一。

返回类型：

元组

返回：

一个字符串元组 (type, value)，其中 type 是“xref”、“array”、“dict”、“int”、“float”、“null”、“bool”、“name”、“string”或“unknown”（不应发生）之一。独立于“type”，键的值始终被格式化为字符串 – 参见下面的示例 – 并且（几乎总是）忠实反映了 PDF 中存储的内容。在大多数情况下，值字符串的格式也提供了关于键类型的线索

• “name”始终以斜杠“/”开头。

• “xref”始终以“ 0 R”结尾。

• “array”始终用中括号“[…]”括起来。

• “dict”始终用双尖括号“<<…>>”括起来。

• “bool”（布尔型）或“null”（空）始终等于“true”、“false”或“null”。

• “float”（浮点型）和“int”（整型）由其字符串格式表示 – 因此并非总是可以区分。

• “string”被转换为 UTF-8，因此可能与 PDF 中存储的内容有所不同。例如，PDF 键“Author”在文件中可能有一个值“<FEFF004A006F0072006A00200058002E0020004D0063004B00690065>”，但此方法将返回 ('string', 'Jorj X. McKie')。

  >>> for key in doc.xref_get_keys(xref):
          print(key, "=" , doc.xref_get_key(xref, key))
  Type = ('name', '/Page')
  Contents = ('xref', '1297 0 R')
  Resources = ('xref', '1296 0 R')
  MediaBox = ('array', '[0 0 612 792]')
  Parent = ('xref', '1301 0 R')
  >>> #
  >>> # Now same thing for the PDF trailer.
  >>> # It has no xref, so -1 must be used instead.
  >>> #
  >>> for key in doc.xref_get_keys(-1):
          print(key, "=", doc.xref_get_key(-1, key))
  Type = ('name', '/XRef')
  Index = ('array', '[0 8802]')
  Size = ('int', '8802')
  W = ('array', '[1 3 1]')
  Root = ('xref', '8799 0 R')
  Info = ('xref', '8800 0 R')
  ID = ('array', '[<DC9D56A6277EFFD82084E64F9441E18C><DC9D56A6277EFFD82084E64F9441E18C>]')
  Length = ('int', '21111')
  Filter = ('name', '/FlateDecode')
  >>>
  

xref_set_key(xref, key, value)

• v1.18.7 新增，v1.18.13 中更改

• v1.19.4 中更改：如果设置为“null”，则“物理上”删除键。

仅限 PDF：设置（添加、更新、删除）由其 xref 号码给定的 dictionary 对象的 PDF 键值。

注意

这是一个专家功能：如果您不确定自己的操作，使 PDF（部分）无法使用存在很高的风险。请务必查阅 Adobe PDF References，了解对象规范格式（第 18 页）以及页面对象等特殊字典类型的结构。

参数：

• xref (整型) – xref。v1.18.13 中更改：要更新 PDF trailer，请指定 -1。

• key (str) – 期望的 PDF 键（不带前导“/”）。不能为空。任何有效的 PDF 键 – 无论对象中是否已存在（将被覆盖） – 还是新键。可以使用 PDF 路径表示法，例如 "Resources/ExtGState" – 这将设置键 "/ExtGState" 的值作为 "/Resources" 的子对象。

• value (str) – 键的值。它必须是非空字符串，并且根据期望的 PDF 对象类型，必须遵守以下规则。进行了一些语法检查，但没有类型检查，也没有检查其在 PDF 层面是否合理，即没有语义检查。区分大小写非常重要！

• xref – 必须以 "nnn 0 R" 的格式提供，其中 nnn 是 PDF 中有效的 xref 号码。需要后缀“0 R”才能被 PDF 应用程序识别为 xref。

• 数组 – 像 "[a b c d e f]" 这样的字符串。必须包含中括号。数组项目必须用至少一个空格分隔（不像 Python 中使用逗号）。空数组 "[]" 是可能的，并且等同于删除该键。数组项目可以是任何 PDF 对象，如字典、xref、其他数组等。与 Python 中一样，数组项目可以是不同类型的。

• 字典 – 像 "<< ... >>" 这样的字符串。必须包含双尖括号，并且必须包含有效的 PDF 字典定义。空字典 "<<>>" 是可能的，并且等同于删除该键。

• 整型 – 格式化为字符串的整型。

• 浮点型 – 格式化为字符串的浮点型。PDF 不允许科学计数法（带指数）。

• 空值 – 字符串 "null"。这是 PDF 中等同于 Python 的 None 的值，并会导致该键被忽略 – 但不一定会被移除，或者在进行垃圾回收时移除。v1.19.4 中更改：如果该键不是路径层级（即不包含斜杠“/”），则将被完全移除。

• 布尔型 – 字符串 "true" 或 "false" 之一。

• 名称 – 带前导斜杠的有效 PDF 名称，例如："/PageLayout"。请参阅 Adobe PDF References 第 16 页。

• 字符串 – 有效的 PDF 字符串。所有 PDF 字符串都必须用括号括起来。空字符串表示为 "()"。根据其内容，可能的括号有

  • “(…)”用于纯 ASCII 文本。保留的 PDF 字符必须用反斜杠转义，非 ASCII 字符必须提供为 3 位反斜杠转义的八进制数 – 包括前导零。示例：12 = 0x0C 必须编码为 014。

  • “<…>”用于十六进制编码文本。每个字符必须由两个十六进制数字表示（小写或大写）。

  • 如有疑问，我们强烈建议使用 get_pdf_str()！此函数会自动生成正确的括号、转义和总体格式。例如，它会进行如下转换

    >>> # because of the € symbol, the following yields UTF-16BE BOM
    >>> pymupdf.get_pdf_str("Pay in $ or €.")
    '<feff00500061007900200069006e002000240020006f0072002020ac002e>'
    >>> # escapes for brackets and non-ASCII
    >>> pymupdf.get_pdf_str("Prices in EUR (USD also accepted). Areas are in m².")
    '(Prices in EUR \\(USD also accepted\\). Areas are in m\\262.)'
    

get_page_pixmap(pno: int, *, matrix: matrix_like = Identity, dpi=None, colorspace: Colorspace = csRGB, clip: rect_like = None, alpha: bool = False, annots: bool = True)

从页面 pno（从 0 开始）创建像素图。调用 Page.get_pixmap()。

除 pno 外，所有参数均为仅限关键字参数。

参数：

pno (整型) – 页码，从 0 开始，范围在 -∞ < pno < page_count 内。

返回类型：

Pixmap

get_page_xobjects(pno)

• v1.16.13 新增

• v1.18.11 中更改

仅限 PDF：返回页面引用的所有 XObject 列表。

参数：

pno (整型) – 页码，从 0 开始，范围在 -∞ < pno < page_count 内。

返回类型：

list

返回：

一个非图像 XObject 列表。这些对象通常表示从其他 PDF 嵌入（非复制）的页面。例如，Page.show_pdf_page() 会创建此类对象。此列表中的项目具有以下结构：(xref, name, invoker, bbox)，其中

• xref (整型) 是 XObject 的 xref。

• name (str) 是引用 XObject 的符号名称。

• invoker (整型) 调用 XObject 的 xref，如果页面直接调用它，则为零。

• bbox (Rect) XObject 在页面上的位置的边界框，处于未变换坐标系中。要获取实际的、未旋转的页面坐标，请乘以页面的变换矩阵 Page.transformation_matrix。v.18.11 中更改： bbox 现在格式化为 Rect。

get_page_images(pno, full=False)

仅限 PDF：返回页面直接或间接引用的所有图像列表。

参数：

• pno (整型) – 页码，从 0 开始，范围在 -∞ < pno < page_count 内。

• full (布尔型) – 是否同时包含引用者的 xref（如果是当前页面，则为零）。

返回类型：

list

返回：

此页面引用的图像列表。每个项目如下所示

(xref, smask, width, height, bpc, colorspace, alt_colorspace, name, filter, referencer)

• xref (整型) 是图像对象编号

• smask (整型) 是其软掩码图像的对象编号

• width (整型) 是图像宽度

• height (整型) 是图像高度

• bpc (整型) 表示每个分量的位数（通常为 8）

• colorspace (str) 命名颜色空间的字符串（例如 DeviceRGB）

• alt_colorspace (str) 是根据 colorspace 的值而定的备用颜色空间

• name (str) 是图像被引用的符号名称

• filter (str) 是图像的解码过滤器（Adobe PDF References，第 22 页）。

• referencer (整型) 引用者的 xref。如果页面直接引用，则为零。仅当 full=True 时存在。

注意

通常，这并不是实际显示的图像列表。此方法仅解析一些 PDF 对象以收集对嵌入图像的引用。它不会分析页面的 contents，所有实际图像显示命令都在其中定义。要获取此信息，请使用 Page.get_image_info()。另请参阅章节 Dictionary Outputs 的结构 中的讨论。

get_page_fonts(pno, full=False)

仅限 PDF：返回页面对象定义直接或间接引用的所有字体列表。

参数：

• pno (整型) – 页码，从 0 开始，范围在 -∞ < pno < page_count 内。

• full (布尔型) – 是否同时包含引用者的 xref。如果为 True，则返回的项目会多一个条目。如果您需要知道页面是否直接引用了字体，请使用此选项。在这种情况下，最后一个条目为 0。如果字体由页面的 /XObject 引用，您将在此处找到其 xref。

返回类型：

list

返回：

页面对象定义引用的字体列表。每个条目如下所示

(xref, ext, type, basefont, name, encoding, referencer)

• xref (整型) 是字体对象编号（如果 PDF 直接使用内置字体之一，可能为零）

• ext (str) 字体文件扩展名（例如“ttf”，请参阅 字体文件扩展名）

• type (str) 是字体类型（如“Type1”或“TrueType”等）

• basefont (str) 是基础字体名称，

• name (str) 是字体被引用的符号名称

• encoding (str) 字体的字符编码，如果与内置编码不同（Adobe PDF References，第 254 页）

• referencer (整型 可选) 引用者的 xref。如果页面直接引用，则为零；否则为 XObject 的 xref。仅当 full=True 时存在。

示例

>>> pprint(doc.get_page_fonts(0, full=False))
[(12, 'ttf', 'TrueType', 'FNUUTH+Calibri-Bold', 'R8', ''),
 (13, 'ttf', 'TrueType', 'DOKBTG+Calibri', 'R10', ''),
 (14, 'ttf', 'TrueType', 'NOHSJV+Calibri-Light', 'R12', ''),
 (15, 'ttf', 'TrueType', 'NZNDCL+CourierNewPSMT', 'R14', ''),
 (16, 'ttf', 'Type0', 'MNCSJY+SymbolMT', 'R17', 'Identity-H'),
 (17, 'cff', 'Type1', 'UAEUYH+Helvetica', 'R20', 'WinAnsiEncoding'),
 (18, 'ttf', 'Type0', 'ECPLRU+Calibri', 'R23', 'Identity-H'),
 (19, 'ttf', 'Type0', 'TONAYT+CourierNewPSMT', 'R27', 'Identity-H')]

注意

• 此列表没有重复条目：xref、name 和 referencer 的组合是唯一的。

• 通常，这是此页面实际使用的字体的真超集。PDF 创建者可能指定了一个全局列表，每个页面仅部分使用其中的字体。

• 请注意，Page.get_text()（或 TextPage 方法）的一些变体返回的字体名称与此处显示的基础字体名称可能不（完全）相等。任何差异的原因包括

  • 此方法始终显示任何子集前缀（模式 ABCDEF+），而文本提取默认不这样做。

  • 文本提取使用基础库访问字体名称，其长度上限为 31 字节，并且通常通过查询字体文件二进制数据来访问名称。而 get_page_fonts() 方法则查看 PDF 定义源。

  • 文本提取以完全相同的方式适用于所有支持的文档类型 – 不仅限于 PDF。因此，它们不包含 PDF 特有信息。

get_page_text(pno, output='text', flags=3, textpage=None, sort=False)

提取给定页码 pno（从 0 开始）的页面的文本。调用 Page.get_text()。

参数：

pno (整型) – 页码，从 0 开始，任意值 -∞ < pno < page_count。

其他参数请参考页面方法。

返回类型：

str

layout(rect=None, width=0, height=0, fontsize=11)

根据给定的页面尺寸和字体大小重新分页（“重排”）文档。这仅影响某些文档类型，如电子书和 HTML。如果不支持则忽略。支持的文档在属性 is_reflowable 中为 True。

参数：

• rect (rect_like) – 期望的页面尺寸。必须有限、非空且从点 (0, 0) 开始。

• width (浮点型) – 与 height 一起使用，作为 rect 的替代方案。

• height (浮点型) – 与 width 一起使用，作为 rect 的替代方案。

• fontsize (浮点型) – 期望的默认字体大小。

select(s)

仅限 PDF：仅保留列表中出现的页码对应的页面。空序列或 range(doc.page_count) 之外的元素将导致 ValueError。更多详细信息请参见本章底部或此处备注。

参数：

s (序列) – 要包含的页码（从 0 开始）的序列（请参阅 在 PyMuPDF 中使用 Python 序列作为参数）。不在序列中的页面将被删除（从内存中），并且在重新打开文档之前将不可用。页码可以多次出现且顺序任意：生成的文档将完全按照指定的序列反映。

注意

• 序列中的页码无需唯一，也无需按特定顺序排列。这使得该方法成为一个多功能实用工具，例如仅选择偶数页或奇数页，或满足其他某些条件等。

• 在技术层面，此方法将始终创建一个新的 pagetree。

• 当仅处理少量页面时，方法 copy_page()、move_page()、delete_page() 更易于使用。事实上，当文档有很多页面时，它们也快得多 – 至少一个数量级。

set_metadata(m)

仅限 PDF：设置或更新文档的元数据，如 Python 字典 m 中指定。

参数：

m (字典) – 一个字典，包含与 metadata（见下文）相同的键。所有键都是可选的。PDF 的格式和加密方法无法设置或更改，将被忽略。如果任何值不应包含数据，请不要指定其键或将其值设置为 None。如果您使用 {}，所有元数据信息将被清除为字符串 “none”。如果您只想选择性地更改某些值，请修改 doc.metadata 的副本并将其用作参数。如果指定为 UTF-8 编码，则允许任意 unicode 值。

（v1.18.4 中更改）空值或“none”不再写入，而是完全省略。

get_xml_metadata()

仅限 PDF：获取文档的 XML 元数据。

返回类型：

str

返回：

文档的 XML 元数据。如果不存在或不是 PDF，则为空字符串。

set_xml_metadata(xml)

仅限 PDF：设置或更新文档的 XML 元数据。

参数：

xml (str) – 新的 XML 元数据。应为 XML 语法，但此方法不进行检查，接受任何字符串。

set_pagelayout(value)

• v1.22.2 新增

仅限 PDF：设置 /PageLayout。

参数：

value (str) – 字符串“SinglePage”（单页）、“OneColumn”（单列）、“TwoColumnLeft”（双列左）、“TwoColumnRight”（双列右）、“TwoPageLeft”（双页左）、“TwoPageRight”（双页右）之一。支持小写。

set_pagemode(value)

• v1.22.2 新增

仅限 PDF：设置 /PageMode。

参数：

value (str) – 字符串“UseNone”（不使用）、“UseOutlines”（使用大纲）、“UseThumbs”（使用缩略图）、“FullScreen”（全屏）、“UseOC”（使用可选内容组）、“UseAttachments”（使用附件）之一。支持小写。

set_markinfo(value)

• v1.22.2 新增

仅限 PDF：设置 /MarkInfo 值。

参数：

value (字典) – 类似于此示例的字典：{"Marked": False, "UserProperties": False, "Suspects": False}。此字典包含有关标记 PDF 约定使用情况的信息。详细信息请参阅 PDF 规范。

set_toc(toc, collapse=1)

仅限 PDF：将完整的当前大纲树（目录）替换为作为参数提供的大纲树。成功执行后，可以通过 Document.get_toc() 或通过 Document.outline 像往常一样访问新的大纲树。与其他面向输出的方法一样，更改仅通过 save() 才会永久生效（支持增量保存）。在内部，此方法由以下两个步骤组成。演示请参见下面的示例。

• 步骤 1 删除所有现有书签。

• 步骤 2 从 toc 中包含的条目创建新的 TOC。

参数：

• toc (序列) –

  一个列表/元组，包含所有应构成新目录的所有书签条目。get_toc() 的输出变体是可接受的。要完全删除目录，请指定空序列或 None。每个项目必须是一个具有以下格式的列表。

  • [lvl, title, page [, dest]] 其中

    • lvl 是项目的层级级别（整型 > 0），第一个项目必须为 1，并且最多比前一个大 1。

    • title (str) 是要显示的标题。假定其为 UTF-8 编码（仅与多字节码点相关）。

    • page (整型) 是目标页码（注意：从 1 开始）。如果为正数，则必须在有效范围内。如果无目标或目标为外部，请将其设置为 -1。

    • dest (可选) 是一个字典或数字。如果为数字，则将被解释为该条目应指向页面上的期望高度（以点为单位）。使用字典（如 get_toc(False) 输出的字典）来详细控制书签的属性，有关说明请参见 Document.get_toc()。

• collapse (整型) – （v1.16.9 新增）控制超出哪个层级的大纲条目应在初始时显示为折叠状态。默认值 1 因此将仅显示级别 1，更高级别必须使用 PDF 查看器展开。要展开所有内容，请指定一个大整型、0 或 None。

返回类型：

int

返回：

插入或删除的项目数量。

v1.23.8 中更改：目标 'to' 坐标现在应与 get_toc() 返回的坐标位于同一坐标系中（在内部，它们现在通过 page.cropbox 和 page.rotation_matrix 进行变换）。因此，例如 set_toc(get_toc()) 现在会给出未更改的目标 'to' 坐标。

outline_xref(idx)

• v1.17.7 新增

仅限 PDF：返回大纲项目的 xref。这主要用于内部目的。

参数：

idx (整型) – 项目在 Document.get_toc() 列表中的索引。

返回：

xref.

del_toc_item(idx)

• v1.17.7 新增

• v1.18.14 中更改：不再删除项目的文本，而是将其显示为灰色。

仅限 PDF：删除此 TOC 项目。这是一个高速方法，它会禁用相应的项目，但保持整个 TOC 结构完整。物理上，该项目仍然存在于 TOC 树中，但显示为灰色，并且不再指向任何目标。

这也意味着您可以在需要时使用 Document.set_toc_item() 将项目重新分配给新目标。

参数：

idx (整型) – 项目在 Document.get_toc() 列表中的索引。

set_toc_item(idx, dest_dict=None, kind=None, pno=None, uri=None, title=None, to=None, filename=None, zoom=0)

• v1.17.7 新增

• v1.18.6 中更改

仅限 PDF：更改由其索引标识的 TOC 项目。更改项目的标题、目标、外观（颜色、粗体、斜体）或折叠子项目 – 或者完全删除该项目。

如果您只需要对选定的条目进行特定更改，并且希望避免替换整个 TOC，请使用此方法。这在处理大型目录时特别有用。

参数：

• idx (整型) – 条目在 Document.get_toc() 创建的列表中的索引。

• dest_dict (字典) – 新的目标。一个字典，类似于 doc.get_toc(False) 中项目的最后一个条目。建议使用它作为模板。如果给出，所有其他参数都将被忽略 – 除了 title。

• kind (整型) – 链接类型，请参阅 链接目标类型。如果为 LINK_NONE，则所有剩余参数将被忽略，并且该 TOC 项目将被移除 – 与 Document.del_toc_item() 相同。如果为 None，则仅修改 title，剩余参数将被忽略。所有其他值将导致使用后续参数创建一个新的目标字典。

• pno (整型) – 基于 1 的页码，即值 1 <= pno <= doc.page_count。LINK_GOTO 必需。

• uri (str) – URL 文本。LINK_URI 必需。

• title (str) – 期望的新标题。如果无更改，则为 None。

• to (point_like) – (可选) 指向目标页面上的坐标。与 LINK_GOTO 相关。如果省略，则选择靠近页面顶部的一个点。

• filename (str) – LINK_GOTOR 和 LINK_LAUNCH 必需。

• zoom (浮点型) – 显示目标页面时使用的缩放因子。

示例用法：修改 SWIG 手册的 TOC 以实现以下效果

折叠顶级以下的所有内容，并以红色、粗体和斜体显示关于 Python 支持的章节

>>> import pymupdf
>>> doc=pymupdf.open("SWIGDocumentation.pdf")
>>> toc = doc.get_toc(False)  # we need the detailed TOC
>>> # list of level 1 indices and their titles
>>> lvl1 = [(i, item[1]) for i, item in enumerate(toc) if item[0] == 1]
>>> for i, title in lvl1:
        d = toc[i][3]  # get the destination dict
        d["collapse"] = True  # collapse items underneath
        if "Python" in title:  # show the 'Python' chapter
            d["color"] = (1, 0, 0)  # in red,
            d["bold"] = True  # bold and
            d["italic"] = True  # italic
        doc.set_toc_item(i, dest_dict=d)  # update this toc item
>>> doc.save("NEWSWIG.pdf",garbage=3,deflate=True)

在前面的示例中，我们仅更改了文件中 1240 个 TOC 项目中的 42 个。

bake(*, annots=True, widgets=True)

仅限 PDF：将注释和/或控件转换为页面的永久组成部分。此方法将更改 PDF。如果 widgets 为 True，文档也将不再是“表单 PDF”。

所有页面看起来都一样，但不再包含注释或字段。可见部分将根据需要转换为标准文本、矢量图形或图像。

因此，此方法可能是使用 Document.convert_to_pdf() 进行 PDF 到 PDF 转换的有效替代方案。

请注意，注释是复杂的对象，其视觉外观“下方”可能包含更多数据。例如“文本”和“文件附件”注释。使用此方法“烘焙”注释/控件时，所有这些底层信息（附件文件、评论、关联的弹出注释等）都将丢失，并在下次垃圾回收时被移除。

例如，当源页面在目标中应看起来完全相同时，可以将此功能用于 Page.show_pdf_page()（它不支持注释或控件）。

参数：

• annots (布尔型) – 转换注释。

• widgets (布尔型) – 转换字段/控件。执行后，文档将不再是“表单 PDF”。

can_save_incrementally()

• v1.16.0 新增

检查文档是否可以增量保存。使用此方法来选择正确的选项，避免发生异常。

scrub(attached_files=True, clean_pages=True, embedded_files=True, hidden_text=True, javascript=True, metadata=True, redactions=True, redact_images=0, remove_links=True, reset_fields=True, reset_responses=True, thumbnails=True, xml_metadata=True)

• v1.16.14 新增

仅限 PDF：从 PDF 中移除潜在的敏感数据。此功能受到 Adobe Acrobat 产品中类似“净化（Sanitize）”功能的启发。该过程可通过多种选项进行配置。

参数：

• attached_files (布尔型) – 搜索“文件附件”注释并删除文件内容。

• clean_pages (布尔型) – 移除页面绘制源中的任何注释。如果此选项设置为 False，则也会对 hidden_text 和 redactions 执行此操作。

• embedded_files (布尔型) – 移除嵌入文件。

• hidden_text (布尔型) – 移除 OCR 文本和不可见文本 [7]。

• javascript (布尔型) – 移除 JavaScript 源代码。

• metadata (布尔型) – 移除 PDF 标准元数据。

• redactions (布尔型) – 应用修订注释。

• redact_images (整型) – 应用修订时如何处理图像。为 0（忽略）、1（空白重叠区域）或 2（移除）之一。

• remove_links (布尔型) – 移除所有链接。

• reset_fields (布尔型) – 将所有表单字段重置为其默认值。

• reset_responses (布尔型) – 移除所有注释中的所有回复。

• thumbnails (bool) – 从页面中移除缩略图。

• xml_metadata (bool) – 移除 XML 元数据。

save(outfile, garbage=0, clean=False, deflate=False, deflate_images=False, deflate_fonts=False, incremental=False, ascii=False, expand=0, linear=False, pretty=False, no_new_id=False, encryption=PDF_ENCRYPT_NONE, permissions=-1, owner_pw=None, user_pw=None, use_objstms=0)

• v1.18.7 中已更改

• v1.19.0 中已更改

• v1.24.1 中已更改

仅限 PDF：以其当前状态保存文档。

参数：

• outfile (str,Path,fp) – 要保存到的文件路径、pathlib.Path 或文件对象。文件对象必须之前通过 open(...) 或 io.BytesIO() 创建。选择 io.BytesIO() 类似于下面的 Document.tobytes()，后者等同于内部创建的 io.BytesIO() 的 getvalue() 输出。

• garbage (int) –

  执行垃圾回收。正数值会排除“incremental”。

  • 0 = 不执行

  • 1 = 删除未使用的（未引用的）对象。

  • 2 = 在 1 的基础上，压缩 xref 表。

  • 3 = 在 2 的基础上，合并重复对象。

  • 4 = 在 3 的基础上，检查 stream 对象是否有重复。这可能比较慢，因为此类数据通常很大。

• clean (bool) – 清理和规范化内容流 [1]。对应于 “mutool clean -sc”。

• deflate (bool) – 压缩（deflate）未压缩的流。

• deflate_images (bool) – （v1.18.3 新增）压缩（deflate）未压缩的图像流 [4]。

• deflate_fonts (bool) – （v1.18.3 新增）压缩（deflate）未压缩的字体文件流 [4]。

• incremental (bool) – 仅保存对 PDF 的更改。排除“garbage”和“linear”。仅当 outfile 是字符串或 pathlib.Path 且等于 Document.name 时才能使用。不能用于已解密或已修复的文件，以及其他一些情况。为确保起见，请检查 Document.can_save_incrementally()。如果此项为 false，则需要保存到新文件。

• ascii (bool) – 将二进制数据转换为 ASCII。

• expand (int) –

  解压缩对象。生成可被其他程序更好地读取的版本，会导致文件变大。

  • 0 = 不执行

  • 1 = 图像

  • 2 = 字体

  • 255 = 全部

• linear (bool) – 保存文档的线性化版本。此选项会创建一个文件格式，以提高互联网访问性能。排除“incremental”和“use_objstms”。

• pretty (bool) – 美化文档源以提高可读性。PDF 对象将被重新格式化，使其看起来像 Document.xref_object() 的默认输出。

• no_new_id (bool) – 阻止更新文件的 /ID 字段。如果文件恰好没有任何此类字段，也阻止创建新的字段。默认值为 False，因此每次保存都会更新文件标识。

• permissions (int) – （v1.16.0 新增）设置所需的权限级别。可能的值请参见 文档权限。默认值为授予所有权限。

• encryption (int) – （v1.16.0 新增）设置所需的加密方法。可能的值请参见 PDF 加密方法代码。

• owner_pw (str) – （v1.16.0 新增）设置文档的所有者密码。（v1.18.3 中已更改）如果未提供，则使用提供的用户密码。字符串长度不能超过 40 个字符。

• user_pw (str) – （v1.16.0 新增）设置文档的用户密码。字符串长度不能超过 40 个字符。

• use_objstms (int) – （v1.24.0 新增）压缩选项，将符合条件的 PDF 对象定义转换为存储在其他对象 stream 数据中的信息。根据 deflate 参数的值，转换后的对象定义将被压缩——这可以显著减小文件大小。

警告

该方法不检查是否已存在同名文件，因此不会要求确认并会覆盖文件。作为程序员，您有责任处理此情况。

注意

文件大小减小

1. 使用如 garbage=3|4, deflate=True, use_objstms=True|1 的保存选项。不要更改默认值 expand=False|0, clean=False|0, incremental=False|0, linear=False|0。这是“无损的”文件大小减小。此方法有一个便捷版本，默认设置了这些值，即 Document.ez_save() – 请参见下文。

2. “有损的”文件大小减小本质上必须在图像方面有所牺牲，例如 (a) 删除所有图像 (b) 将图像替换为其灰度版本 (c) 降低图像分辨率。示例请参见 PyMuPDF Utilities 的“replace-image”文件夹。

ez_save(*args, **kwargs)

• v1.18.11 新增

仅限 PDF：与 Document.save() 相同，但更改了默认值：deflate=True, garbage=3, use_objstms=1。

saveIncr()

仅限 PDF：增量保存文档。这是 doc.save(doc.name, incremental=True, encryption=PDF_ENCRYPT_KEEP) 的便捷缩写。

注意

如果文档包含经过验证的签名，而保存到新文件会使签名失效，则可能需要增量保存。

tobytes(garbage=0, clean=False, deflate=False, deflate_images=False, deflate_fonts=False, ascii=False, expand=0, linear=False, pretty=False, no_new_id=False, encryption=PDF_ENCRYPT_NONE, permissions=-1, owner_pw=None, user_pw=None, use_objstms=0)

• v1.18.7 中已更改

• v1.19.0 中已更改

• v1.24.1 中已更改

仅限 PDF：将文档的当前内容写入字节对象而不是写入文件。显然，您应该注意内存要求。参数的含义与 save() 中的完全相同。FAQ 章包含一个将此方法用作 pdfrw 预处理器的示例。

（v1.16.0 中已更改）以支持扩展的加密。

返回类型：

字节

返回：

包含完整文档的字节对象。

search_page_for(pno, text, quads=False)

在页码“pno”的页面上搜索“text”。功能与对应的 Page.search_for() 完全相同。任何在 -∞ < pno < page_count 范围内的整数都可接受。

insert_pdf(docsrc, *, from_page=-1, to_page=-1, start_at=-1, rotate=-1, links=True, annots=True, widgets=True, join_duplicates=False, show_progress=0, final=1)

仅限 PDF：将 PDF 文档 docsrc 的页面范围 [from_page, to_page]（包括两者）复制到当前文档。插入将从页码 start_at 开始。值 -1 表示默认值。所有这样复制的页面将按指定旋转。链接、注释和控件可以在目标文档中排除，参见下文。所有页码都是基于 0 的。

参数：

• docsrc (Document) – 一个已打开的 PDF Document 对象，它不能是当前文档。但是，它可以指向相同的基础文件。

• from_page (int) – docsrc 中的起始页码。默认为零。

• to_page (int) – docsrc 中要复制的结束页码。默认为最后一页。

• start_at (int) – 第一个复制的页面，在目标文档中将成为页码 start_at。默认值 -1 将页面范围附加到末尾。如果为零，页面范围将插入到当前第一页之前。

• rotate (int) – 所有复制的页面将按提供的值旋转（度，90 的整数倍）。

• links (bool) – 选择是否包含（内部和外部）链接。默认为 True。命名链接（LINK_NAMED）和指向复制页范围外部的内部链接始终被排除。

• annots (bool) – 选择是否包含注释。

• widgets (bool) – 选择是否包含控件。如果为 True，并且至少一个源页面包含表单字段，则目标 PDF 将转换为表单 PDF（如果尚未是）。

• join_duplicates (bool) –

  （v1.25.5 新增）选择如何处理源页面中重复的根字段名称。如果 widgets=False，则忽略此参数。

  默认为 False，这将向目标文档中存在重复的源根字段的名称添加统一字符串。例如，如果目标文档中已存在“name”，则源控件的名称将被更改为“name [text]”，其中“text”是一个适当选择的字符串。

  如果为 True，则源和目标文档中名称重复的根字段将被转换为所谓的“父对象”的“子对象”（该父对象在 PDF 数组中列出所有子控件）。这将有效地使这些子对象成为“同一”控件的实例：例如，如果其中一个子对象被更改，则其所有实例将自动继承此更改——无论它们显示在哪一页上。

• show_progress (int) – （v1.17.7 新增）指定一个大于零的间隔大小，以便在 sys.stdout 上查看进度消息。每隔一段时间后，将打印一条类似 Inserted 30 of 47 pages. 的消息。

• final (int) – （v1.18.0 新增）控制在此方法执行后是否应该丢弃已复制对象的列表，默认为 True。除非是多次插入中最后一次来自同一源 PDF，否则将其设置为 0。这可以显著节省目标文件大小并加快执行速度。

注意

1. 这是一个基于页面的方法。因此，源文档的文档级别信息大部分被忽略。例如，可选内容、嵌入文件、StructureElem、目录、页面标签、元数据、命名目标（以及其他命名条目）等等。

2. 如果 from_page > to_page，页面将按逆序复制。如果 0 <= from_page == to_page，则复制一页。

3. docsrc 的目录条目不会被复制。然而，恢复结果文档的目录很简单。请看下面的示例以及 examples 目录中的程序 join.py：它可以合并 PDF 文档，同时拼接相应的目录部分。

insert_file(infile, from_page=-1, to_page=-1, start_at=-1, rotate=-1, links=True, annots=True, show_progress=0, final=1)

• v1.22.0 新增

仅限 PDF：向当前 PDF 添加任意支持的文档。将“infile”作为文档打开，将其转换为 PDF，然后调用 Document.insert_pdf()。参数与该方法相同。除其他功能外，这还提供了一种简单的方法，将图像作为完整页面附加到输出 PDF。

参数：

infile (multiple) – 要插入的输入文档。可以是创建 Document 或 Pixmap 有效的文件名规范。

new_page(pno=-1, width=595, height=842)

仅限 PDF：插入一个空白页。

参数：

• pno (int) – 新页面应该插入到其前面的页码。必须在 1 < pno <= page_count 范围内。特殊值 -1 和 doc.page_count 插入到最后一页之后。

• width (float) – 页面宽度。

• height (float) – 页面高度。

返回类型：

Page

返回：

创建的页面对象。请注意，插入页面之后页面的页码将在方法执行后发生变化。出于同样的原因，所有现有页面对象将失效。使用它们将导致异常。

insert_page(pno, text=None, fontsize=11, width=595, height=842, fontname='helv', fontfile=None, color=None)

仅限 PDF：插入新页面并插入一些文本。组合了 Document.new_page() 和（部分）Page.insert_text() 的便捷函数。

参数：

pno (int) –

要插入到其前面（基于 0）的页码。必须在 range(-1, doc.page_count + 1) 范围内。特殊值 -1 和 doc.page_count 插入到最后一页之后。

v1.14.12 中已更改

这现在是一个位置参数

对于其他参数，请参考上述方法。

返回类型：

int

返回：

Page.insert_text() 的结果（成功插入的行数）。

delete_page(pno=-1)

仅限 PDF：根据其在 -∞ < pno < page_count - 1 范围内的基于 0 的页码删除页面。

• v1.18.14 中已更改：支持 Python 的 del 语句。

参数：

pno (int) – 要删除的页面。负数从文档末尾向后计数（类似于索引）。默认为最后一页。

delete_pages(*args, **kwds)

• v1.18.13 中已更改：指定要删除的页面更加灵活。

• v1.18.14 中已更改：支持 Python 的 del 语句。

仅限 PDF：删除以基于 0 的页码给定的多个页面。

格式 1：使用关键字。代表旧格式。移除连续的页面范围。

• “from_page”：要删除的起始页。如果省略则为零。

• “to_page”：要删除的结束页。如果省略则为文档的最后一页。必须不小于“from_page”。

格式 2：两个页码作为位置参数。按格式 1 处理。

格式 3：一个位置整数参数。等同于 Page.delete_page()。

格式 4：一个类型为 list、tuple 或 range() 的位置参数，包含页码。此序列中的项可以是任意顺序，并且可能包含重复项。

格式 5：（v1.18.14 新增）现在可以使用 Python 的 del 语句和索引/切片表示法。

注意

（v1.14.17 中已更改，v1.17.7 中已优化）为了维护有效的 PDF 结构，此方法和 delete_page() 也会停用目录中指向已删除页面的条目。此处的“停用”意味着书签将指向空位置，并且支持 PDF 查看器将灰显标题。整体目录结构保持不变。

它还将移除剩余页面中指向已删除页面的任何链接。此操作对于包含许多页面的文档可能会延长响应时间 [6]，如果未找到链接或注释。

以下示例都将删除页面 500 到 519：

• doc.delete_pages(500, 519)

• doc.delete_pages(from_page=500, to_page=519)

• doc.delete_pages((500, 501, 502, ... , 519))

• doc.delete_pages(range(500, 520))

• del doc[500:520]

• del doc[(500, 501, 502, ... , 519)]

• del doc[range(500, 520)]

对于 Adobe PDF 参考手册，上述操作大约需要 0.6 秒，因为剩余的 1290 页必须清理无效链接。

通常，此方法的性能取决于剩余页面的数量——而不是取决于已删除页面的数量：在上述示例中，删除除这 20 页之外的所有页面，所需时间会少得多。

copy_page(pno, to=-1)

仅限 PDF：在文档内复制页面引用。

参数：

• pno (int) – 要复制的页面。必须在 0 <= pno < page_count 范围内。

• to (int) – 要复制到其前面的页码。默认值插入到最后一页之后。

注意

只会创建一个新的页面对象引用——而不是新的页面对象，所有复制的页面将具有相同的属性值，包括 Page.xref。这意味着对其中一个复制页面的任何更改都将反映在所有复制页面上。

fullcopy_page(pno, to=-1)

• v1.14.17 新增

仅限 PDF：完全复制（克隆）一个页面。

参数：

• pno (int) – 要复制的页面。必须在 0 <= pno < page_count 范围内。

• to (int) – 要复制到其前面的页码。默认值插入到最后一页之后。

注意

• 与 copy_page() 不同，此方法创建一个新的页面对象（具有新的 xref），可以独立于原始页面进行更改。

• 任何弹出式和“IRT”（“响应”）注释都不会被复制，以避免潜在的不正确情况。

move_page(pno, to=-1)

仅限 PDF：在文档内移动页面（复制然后删除原始页面）。

参数：

• pno (int) – 要移动的页面。必须在 0 <= pno < page_count 范围内。

• to (int) – 要将移动的页面插入到其前面的页码。默认值移动到最后一页之后。

need_appearances(value=None)

• v1.17.4 新增

仅限 PDF：获取或设置表单 PDF 的 /NeedAppearances 属性。引用：“（可选）一个标志，指定是否为文档中的所有控件注释构建外观流和外观字典……默认值：false。”这可能有助于控制某些阅读器/查看器的行为。

参数：

value (bool) – 将属性设置为此值。如果省略或为 None，则查询当前值。

返回类型：

bool

返回：

• None：不是表单 PDF，或属性未定义。

• True / False：属性的值（无论是刚刚设置的还是查询到的）。如果不是表单 PDF，则无效。

get_sigflags()

仅限 PDF：返回文档是否包含签名域。这是一个可选的 PDF 属性：如果不存在（返回值为 -1），则无法得出结论——PDF 创建者可能只是没有使用它。

返回类型：

int

返回：

• -1：不是表单 PDF / 未记录签名域 / 未找到 SigFlags。

• 1：存在至少一个签名域。

• 3：包含可能失效的签名，如果文件以修改其先前内容的方式保存（写入），而不是增量更新。

embfile_add(name, buffer, filename=None, ufilename=None, desc=None)

• v1.14.16 中已更改：位置参数“name”和“buffer”的顺序已更改，以符合其他函数的调用模式。

仅限 PDF：嵌入新文件。除 name 外的所有字符串参数都可以是 unicode（在以前的版本中，只有 ASCII 能正常工作）。文件内容将被压缩（如果有利的话）。

参数：

• name (str) – 条目标识符，必须不存在。

• buffer (bytes,bytearray,BytesIO) –

  文件内容。

  （v1.14.13 中已更改）现在也支持 io.BytesIO。

• filename (str) – 可选文件名。仅供文档使用，如果为 None，则设置为 name。

• ufilename (str) – 可选 unicode 文件名。仅供文档使用，如果为 None，则设置为 filename。

• desc (str) – 可选描述。仅供文档使用，如果为 None，则设置为 name。

返回类型：

int

返回：

（v1.18.13 中已更改）该方法现在返回插入文件的 xref。此外，文件对象现在将自动获得基于当前日期时间的 PDF 键 /CreationDate 和 /ModDate。

embfile_count()

• v1.14.16 中已更改：这现在是一个方法。在以前的版本中，这是一个属性。

仅限 PDF：返回嵌入文件的数量。

embfile_get(item)

仅限 PDF：按条目号或名称检索嵌入文件的内容。如果文档不是 PDF，或找不到条目，则引发异常。

参数：

item (int,str) – 条目的索引或名称。整数必须在 range(embfile_count()) 范围内。

返回类型：

字节

embfile_del(item)

• v1.14.16 中已更改：现在也可以按索引删除项。

仅限 PDF：从 /EmbeddedFiles 中移除一个条目。和往常一样，嵌入文件内容的物理删除（以及回收文件空间）只会在文档保存到新文件并使用适当的垃圾回收选项时发生。

参数：

item (int/str) – 条目的索引或名称。

警告

指定条目名称时，此函数将只删除第一个具有该名称的项。请注意，非 PyMuPDF 创建的 PDF 可能包含重复名称。因此您可能需要采取适当的预防措施。

embfile_info(item)

• v1.18.13 中已更改

仅限 PDF：按编号或名称检索嵌入文件的信息。

参数：

item (int/str) – 条目的索引或名称。整数必须在 range(embfile_count()) 范围内。

返回类型：

dict

返回：

一个包含以下键的字典：

• name – (str) 此条目存储的名称

• filename – (str) 文件名

• ufilename – (unicode) unicode 文件名

• description – (str) 描述

• size – (int) 原始文件大小

• length – (int) 压缩文件长度

• creationDate – (str) 条目创建的日期时间，PDF 格式

• modDate – (str) 最后修改的日期时间，PDF 格式

• collection – (int) 相关联的 PDF 包条目的 xref，如果存在，否则为零。

• checksum – (str) 存储文件内容的哈希码，以十六进制字符串形式。根据 PDF 规范应为 MD5，但请准备好看到其他哈希算法。

embfile_names()

仅限 PDF：返回嵌入文件名称列表。名称的顺序等于文档中的物理顺序。

返回类型：

list

embfile_upd(item, buffer=None, filename=None, ufilename=None, desc=None)

仅限 PDF：根据条目号或名称修改嵌入文件。所有参数都是可选的。使用默认值会导致无操作。

参数：

• item (int/str) – 条目的索引或名称。整数必须在 range(embfile_count()) 范围内。

• buffer (bytes,bytearray,BytesIO) –

  新的文件内容。

  （v1.14.13 中已更改）现在也支持 io.BytesIO。

• filename (str) – 新文件名。

• ufilename (str) – 新 unicode 文件名。

• desc (str) – 新描述。

（v1.18.13 中已更改）该方法现在返回文件对象的 xref。

返回类型：

int

返回：

文件对象的 xref。它的 /ModDate PDF 键将自动更新为当前日期时间。

close()

释放与文档关联的对象和空间分配。如果从文件创建的，也会关闭 filename（将控制权释放给操作系统）。显式关闭文档等同于删除文档 del doc，或将其赋值给其他变量，例如 doc = None。

xref_object(xref, compressed=False, ascii=False)

• v1.16.8 新增

• v1.18.10 中已更改

仅限 PDF：返回 PDF 对象的定义源。

参数：

• xref (int) – 对象的 xref。v1.18.10 中已更改：值 -1 返回 PDF trailer 源。

• compressed (bool) – 是否生成没有换行或空格的紧凑输出。

• ascii (bool) – 是否对二进制数据进行 ASCII 编码。

返回类型：

str

返回：

对象定义源。

pdf_catalog()

• v1.16.8 新增

仅限 PDF：返回 PDF catalog（或 root）对象的 xref 号码。使用该号码和 Document.xref_object() 来查看其源。

pdf_trailer(compressed=False)

• v1.16.8 新增

仅限 PDF：返回 PDF 的 trailer 源，通常位于 PDF 文件末尾。这相当于使用 Document.xref_object()，并将 xref 参数设置为 -1。

xref_stream(xref)

• v1.16.8 新增

仅限 PDF：返回 xref 流对象的解压缩内容。

参数：

xref (int) – xref 号码。

返回类型：

字节

返回：

对象的（解压缩）流。

xref_stream_raw(xref)

• v1.16.8 新增

仅限 PDF：返回 xref 流对象的未修改（尤其是未解压缩）内容。否则与 Document.xref_stream() 相同。

返回类型：

字节

返回：

对象的（原始，未修改的）流。

update_object(xref, obj_str, page=None)

• v1.16.8 新增

仅限 PDF：将 xref 的对象定义替换为提供的字符串。xref 也可以是新的，在这种情况下，此指令将完成对象定义。如果也提供了页面对象，其链接和注释将在之后重新加载。

参数：

• xref (int) – xref 号码。

• obj_str (str) – 包含有效 PDF 对象定义的字符串。

• page (Page) – 页面对象。如果提供，表示应该刷新（重新加载）此页面的注释，以反映链接和/或注释所产生的更改。

返回类型：

int

返回：

成功则返回零，否则将引发异常。

update_stream(xref, data, new=False, compress=True)

• v.1.16.8 新增

• v1.19.2 中已更改：添加了参数“compress”

• v1.19.6 中已更改：废弃了参数“new”。现在确认对象是 PDF 字典对象。

替换由 xref 标识的对象的流，该对象必须是 PDF 字典。如果对象不是 stream，它将被转换为流。该函数会在有利的情况下自动执行压缩操作（“deflate”）。

参数：

• xref (int) – xref 号码。

• stream (bytes|bytearray|BytesIO) –

  流的新内容。

  （v1.14.13 中已更改：）现在也支持 io.BytesIO 对象。

• new (bool) – 已废弃并忽略。将在 v1.20.0 后某个时间移除。

• compress (bool) – 是否压缩插入的流。如果为 True（默认值），将使用 /FlateDecode 压缩插入流（如果有利），否则流将按原样插入。

引发：

ValueError – 如果 xref 不代表 PDF dict。接受空字典 <<>>。因此，如果您刚刚创建了 xref 并想为其提供流，请首先执行 doc.update_object(xref, "<<>>")，然后使用此方法插入流数据。

此方法主要（但不限于）用于操作包含 PDF 运算符语法的流（参见 Adobe PDF 参考手册 第 643 页），例如页内容流就是这种情况。

如果您更新内容流，考虑使用 save 参数 clean=True 以确保 PDF 运算符源与对象结构之间的一致性。

示例：假设您不再希望某个图像显示在页面上。这可以通过删除其内容源中的相应引用来实现——确实如此：重新加载页面后，图像将消失。但页面的 resources 对象仍然会显示该图像被页面引用。此保存选项将清理任何此类不匹配。

xref_copy(source, target, *, keep=None)

• v1.19.5 新增

仅限 PDF：使 target xref 成为 source 的精确副本。如果 source 是 stream，则此数据也会被复制。

参数：

• source (int) – 源 xref。它必须是已存在的字典对象。

• target (int) – 目标 xref。必须是已存在的字典对象。如果 xref 刚刚创建，确保将其初始化为具有最小规范 <<>> 的 PDF 字典。

• keep (list) – 可选的顶级键列表，在复制过程准备阶段不应从 target 中移除。

注意

• 此方法与 Python 字典方法的 copy() 非常相似。

• 两个 xref 号码都必须代表已存在的字典。

• 在从 source 复制数据之前，所有 target 字典键都被删除。您可以在 keep 列表中指定例外。然而，如果 source 具有同名键，其值仍将替换 target。

• 如果 source 是 stream 对象，则这些数据也会被复制过去，并且 target 将被转换为流对象。

• 一个典型的用例是在不使用修订注释的情况下替换或移除现有图像。示例脚本可以在 此 PyMuPDF Utilities 示例 中找到。

extract_image(xref)

仅限 PDF：提取文档中存储的图像的数据和元信息。输出可以直接用于存储为图像文件、作为 PIL、Pixmap 创建等的输入。此方法尽可能避免使用 pixmaps，以原始格式（例如 JPEG）呈现图像。

参数：

xref (int) – 图像对象的 xref。如果不在 range(1, doc.xref_length()) 范围内，或者对象不是图像或发生其他错误，则返回 None 且不引发异常。

返回类型：

dict

返回：

一个包含以下键的字典：

• ext (str) 图像类型（例如 ‘jpeg’），可用作图像文件扩展名

• smask (int) 模板（/SMask）图像的 xref 号码或零

• width (int) 图像宽度

• height (int) 图像高度

• colorspace (int) 图像的 colorspace.n 号码。

• cs-name (str) 图像的 colorspace.name。

• xres (int) x 方向分辨率。另请参见 resolution。

• yres (int) y 方向分辨率。另请参见 resolution。

• image (bytes) 图像数据，可用作图像文件内容

>>> d = doc.extract_image(1373)
>>> d
{'ext': 'png', 'smask': 2934, 'width': 5, 'height': 629, 'colorspace': 3, 'xres': 96,
'yres': 96, 'cs-name': 'DeviceRGB',
'image': b'\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x05\ ...'}
>>> imgout = open(f"image.{d['ext']}", "wb")
>>> imgout.write(d["image"])
102
>>> imgout.close()

注意

这与 pix = pymupdf.Pixmap(doc, xref) 后跟 pix.tobytes() 在功能上有重叠。主要区别在于 extract_image，(1) 不总是提供 PNG 图像格式，(2) 对于非 PNG 图像速度快得多，(3) 提取的图像通常占用少得多的磁盘空间，(4) 在错误情况下返回 None（不生成异常）。查看同一 PDF 中的以下示例图像。

• xref 1268 是 PNG – 可比较的执行时间和相同的输出

  In [23]: %timeit pix = pymupdf.Pixmap(doc, 1268);pix.tobytes()
  10.8 ms ± 52.4 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)
  In [24]: len(pix.tobytes())
  Out[24]: 21462
  
  In [25]: %timeit img = doc.extract_image(1268)
  10.8 ms ± 86 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)
  In [26]: len(img["image"])
  Out[26]: 21462
  

• xref 1186 是 JPEG – Document.extract_image() 快很多倍且生成小得多的输出（2.48 MB 对 0.35 MB）

  In [27]: %timeit pix = pymupdf.Pixmap(doc, 1186);pix.tobytes()
  341 ms ± 2.86 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)
  In [28]: len(pix.tobytes())
  Out[28]: 2599433
  
  In [29]: %timeit img = doc.extract_image(1186)
  15.7 µs ± 116 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each)
  In [30]: len(img["image"])
  Out[30]: 371177
  

extract_font(xref, info_only=False, named=None)

• v1.19.4 中已更改：如果 named == True 则返回字典。

仅限 PDF：返回嵌入字体文件的数据及适当的文件扩展名。这可用于将字体存储为外部文件。此方法不抛出异常（除了通过检查 PDF 和有效 xref 外）。

参数：

• xref (int) – 要提取字体的 PDF 对象编号。

• info_only (bool) – 只返回字体信息，不返回缓冲区。用于仅获取信息，避免分配大块缓冲区。

• named (bool) – 如果为 true，则返回一个包含以下键的字典：‘name’（字体基本名称）、‘ext’（字体文件扩展名）、‘type’（字体类型）、‘content’（字体文件内容）。

返回类型：

元组, 字典

返回：

一个元组 (basename, ext, type, content)，其中 ext 是建议的 3 字节文件扩展名（str），basename 是字体的名称（str），type 是字体的类型（例如“Type1”），content 是包含字体文件内容的字节对象（或 b””）。关于可能的扩展名值及其含义，请参见 字体文件扩展名。错误时返回详情：

• ("", "", "", b"") – 无效的 xref 或 xref 不是（有效的）字体对象。

• (basename, "n/a", "Type1", b"") – basename 未嵌入，因此无法提取。例如 PDF Base 14 字体 和 Type 3 字体就是这种情况。

示例

>>> # store font as an external file
>>> name, ext, _, content = doc.extract_font(4711)
>>> # assuming content is not None:
>>> ofile = open(name + "." + ext, "wb")
>>> ofile.write(content)
>>> ofile.close()

警告

basename 从 PDF 中原样返回。因此它可能包含某些字符（如空格），这些字符可能导致它不能作为您的操作系统的文件名。请采取适当措施。

注意

• 返回的 basename 通常不是原始文件名，但它可能有一些相似之处。

• 如果参数 named == True，则返回包含以下键的字典：{'name': 'T1', 'ext': 'n/a', 'type': 'Type3', 'content': b''}。

xref_xml_metadata()

• v1.16.8 新增

仅限 PDF：返回文档 XML 元数据的 xref。

has_links()

has_annots()

• v1.18.7 新增

仅限 PDF：检查文档中是否包含链接或注释。

返回：

True / False。与字段不同（字段也存储在 PDF 文档的中心位置），链接/注释的存在只能通过解析每个页面来检测。这些方法经过优化以高效地执行此操作，如果某页的答案为 True，则会立即返回。然而，对于包含数千页的 PDF，如果未找到链接或注释，答案可能需要一些时间 [6]。

subset_fonts(verbose=False, fallback=False)

仅限 PDF：调查文档中文本使用的适用字体。如果字体受支持且可以减小大小，该字体将替换为其字符子集版本。

在保存文档之前立即使用此方法。

参数：

• verbose (bool) – 向 sysout 写入各种进度信息。这目前仅在 fallback 为 True 时有效。

• fallback (bool) – 如果为 True，则使用废弃的算法，该算法使用 fontTools 库（因此必须安装）。如果使用推荐值 False（默认值），则使用 MuPDF 的原生函数——该函数速度快得多，并且可以对更广泛的字体类型进行子集化。此时不需要 fontTools 库。

使用大型字体（例如亚洲文字的典型情况）创建新 PDF 时，可以获得最大的好处。使用 Story 类或方法 Page.insert_htmlbox() 时，可能会自动包含多种字体——程序员可能对此并不知晓。

在所有这些情况下，实际使用的 unicode 集合通常与所用字体中可用的字形数量相比非常小。使用此方法可以轻松地将嵌入字体二进制文件减小两个数量级——从几兆字节减少到几十千字节。

创建字体子集会留下大量现在未使用的 PDF 对象（“幽灵”对象）。因此，在保存文件时务必进行压缩和垃圾回收。我们建议使用 Document.ez_save()。

显示/隐藏历史

• v1.18.7 新增

• v1.18.9 中已更改

• v1.24.2 中已更改：使用 MuPDF 的原生函数。

journal_enable()

• v1.19.0 新增

仅限 PDF：启用日志记录。在开始记录操作之前使用此方法。

journal_start_op(name)

• v1.19.0 新增

仅限 PDF：开始记录由字符串“name”标识的“操作”。如果未启动操作，则启用了日志记录的 PDF 的更新将失败。

journal_stop_op()

• v1.19.0 新增

仅限 PDF：停止当前操作。操作开始和停止之间的更新属于同一工作单元，将一起撤消/重做。

journal_position()

• v1.19.0 新增

仅限 PDF：返回当前操作的编号和操作总数。

返回：

一个包含当前操作编号和日志中的操作总数的元组 (step, steps)。如果 step 为 0，则位于日志顶部。如果 step 等于 steps，则位于日志底部。使用撤消或重做以外的任何内容更新 PDF 将自动移除当前条目之后的所有日志条目，新的更新将成为日志中新的最后一条条目。与已移除日志条目对应的更新将永久丢失。

journal_op_name(step)

• v1.19.0 新增

仅限 PDF：返回操作编号 step 的名称。

journal_can_do()

• v1.19.0 新增

仅限 PDF：显示当前日志位置是否可以进行前进（“重做”）和/或后退（“撤消”）操作。

返回：

一个字典 {"undo": bool, "redo": bool}。如果对应方法的值为 True，则该方法可用。

journal_undo()

• v1.19.0 新增

仅限 PDF：撤消（undo）日志中的当前步骤。这将移向日志的顶部。

journal_redo()

• v1.19.0 新增

仅限 PDF：重新应用（redo）日志中的当前步骤。这将移向日志的底部。

journal_save(filename)

• v1.19.0 新增

仅限 PDF：将日志保存到文件。

参数：

filename (str,fp) – 文件名字符串或以“wb”模式打开的文件对象（或 io.BytesIO() 对象）。

journal_load(filename)

• v1.19.0 新增

仅限 PDF：从文件加载日志。为文档启用日志记录。如果日志记录已启用，则会引发异常。

参数：

filename (str,fp) – 日志的文件名 (str) 或以“rb”模式打开的文件对象（或 io.BytesIO() 对象）。

save_snapshot()

• v1.19.0 新增

仅限 PDF：保存文档的“快照”。这是一个具有特殊增量保存格式的 PDF 文档，与日志记录兼容，因此没有可用的保存选项。新文档无法保存快照。

这是一个正常的 PDF 文档，没有任何使用限制。如果未对其进行任何更改，则可以将其与日志一起使用以撤消/重做操作或继续更新。

outline

包含文档的第一个 大纲 (Outline) 条目（或 None）。可用作遍历所有大纲项的起点。访问加密但未经验证的文档的此属性将引发 AttributeError。

类型:

Outline

is_closed

如果文档仍打开，则为 False。如果已关闭，则大多数其他属性和方法将被删除/禁用。此外，引用此文档的 页面 (Page) 对象（即使用 Document.load_page() 创建的对象）及其依赖对象将不再可用。出于引用目的，Document.name 仍然存在，并将包含原始文档的文件名（如果适用）。

类型:

bool

is_dirty

如果这是 PDF 文档并包含未保存的更改，则为 True，否则为 False。

类型:

bool

is_pdf

如果这是 PDF 文档，则为 True，否则为 False。

类型:

bool

is_form_pdf

如果这不是 PDF 或没有表单字段，则为 False，否则为根表单字段的数量（没有祖先的字段）。

(在 v1.16.4 中更改) 返回（根）表单字段的总数。

类型:

bool,int

is_reflowable

如果文档具有可变页面布局（如电子书或 HTML），则为 True。在这种情况下，您可以在创建文档时（打开）或通过方法 layout() 设置所需的页面尺寸。

类型:

bool

is_repaired

• v1.18.2 中的新增功能

如果 PDF 在打开时已修复（由于主要的结构问题），则为 True。对于非 PDF 文档始终为 False。如果为真，更多详细信息已存储在 TOOLS.mupdf_warnings() 中，并且 Document.can_save_incrementally() 将返回 False。

类型:

bool

is_fast_webaccess

• v1.22.2 新增

如果 PDF 采用线性化格式，则为 True。对于非 PDF 文档为 False。

类型:

bool

markinfo

• v1.22.2 新增

一个字典，指示 /MarkInfo 的值。如果未指定，则返回空字典。如果不是 PDF，则返回 None。

类型:

dict

pagemode

• v1.22.2 新增

一个字符串，包含 /PageMode 的值。如果未指定，则返回默认值“UseNone”。如果不是 PDF，则返回 None。

类型:

str

pagelayout

• v1.22.2 新增

一个字符串，包含 /PageLayout 的值。如果未指定，则返回默认值“SinglePage”。如果不是 PDF，则返回 None。

类型:

str

version_count

• v1.22.2 新增

一个整数，统计文档中存在的版本数量。如果不是 PDF，则为零；否则为增量保存次数加一。

类型:

int

needs_pass

指示文档是否受密码保护而无法访问。此指示符保持不变 – 即使文档已通过身份验证后也是如此。如果为真，则阻止增量保存。

类型:

bool

is_encrypted

此指示符最初等于 Document.needs_pass。成功通过身份验证后，其被设置为 False 以反映当前情况。

类型:

bool

permissions

• 在 v1.16.0 中更改：现在是一个由位指示符组成的整数。以前是一个字典。

包含访问文档的权限。这是一个整数，在相应的位位置包含布尔值。例如，如果 doc.permissions & pymupdf.PDF_PERM_MODIFY > 0，则可以更改文档。有关详细信息，请参阅文档权限 (Document Permissions)。

类型:

int

metadata

包含文档的元数据，形式为 Python 字典或 None（如果 is_encrypted=True 且 needPass=True）。键包括 format, encryption, title, author, subject, keywords, creator, producer, creationDate, modDate, trapped。所有项的值都是字符串或 None。

除了 format 和 encryption，对于 PDF 文档，键名与 PDF 键 /Creator, /Producer, /CreationDate, /ModDate, /Title, /Author, /Subject, /Trapped 和 /Keywords 分别对应。

• format 包含文档格式（例如 'PDF-1.6', 'XPS', 'EPUB'）。

• encryption 包含 None（无加密）或命名加密方法的字符串（例如 ‘Standard V4 R4 128-bit RC4’）。请注意，即使 needs_pass=False，也可能指定加密方法。在这种情况下，可能并未授予所有权限。有关详细信息，请查看 Document.permissions。

• 如果日期字段包含有效数据（并非必须如此！），它们将是 PDF 特定的时间戳格式“D:<TS><TZ>”的字符串，其中

  • <TS> 是 12 个字符的 ISO 时间戳 YYYYMMDDhhmmss（YYYY - 年，MM - 月，DD - 日，hh - 小时，mm - 分钟，ss - 秒），以及

  • <TZ> 是一个时区值（相对于 GMT 的时间间隔），包含符号（'+' 或 '-'）、小时 (hh) 和分钟 (‘mm’，注意撇号！)。

• 因此，巴拉圭的值可能看起来像 D:20150415131602-04’00’，它对应于亚松森当地时间 2015 年 4 月 15 日下午 1:16:02 的时间戳。

类型:

dict

name

包含创建 Document 时使用的 filename 或 filetype 值。

类型:

str

page_count

包含文档的页数。对于没有页面的文档可能返回 0。函数 len(doc) 也将返回此结果。

类型:

int

chapter_count

• v1.17.0 中的新增功能

包含文档中的章节数。始终至少为 1。仅与支持章节的文档类型（目前为 EPUB）相关。其他文档将返回 1。

类型:

int

last_location

• v1.17.0 中的新增功能

包含文档最后一页的 (章节, 页码)。仅与支持章节的文档类型（目前为 EPUB）相关。如果文档没有页面，其他文档将返回 (0, page_count - 1) 和 (0, -1)。

类型:

int

FormFonts

一个列表，包含在 /AcroForm 对象中定义的表单字段字体名称。如果不是 PDF，则为 None。

类型:

list

注意

对于更改 PDF 结构的方法（insert_pdf()、select()、copy_page()、delete_page() 等），请注意程序中的对象或属性可能已失效或成为孤立对象。例如 页面 (Page) 对象及其子对象（链接、注释、控件）、保存旧页数的变量、目录等。请记住保持这些变量最新或删除孤立对象。另请参阅确保 PyMuPDF 中重要对象的一致性。

set_metadata() 示例

清除元数据信息。如果出于隐私/数据保护考虑这样做，请确保将文档另存为新文件，并设置 garbage > 0。只有这样，旧的 /Info 对象才会物理地从文件中删除。在这种情况下，您可能还需要清除一些 PDF 编辑器插入的任何 XML 元数据。

>>> import pymupdf
>>> doc=pymupdf.open("pymupdf.pdf")
>>> doc.metadata             # look at what we currently have
{'producer': 'rst2pdf, reportlab', 'format': 'PDF 1.4', 'encryption': None, 'author':
'Jorj X. McKie', 'modDate': "D:20160611145816-04'00'", 'keywords': 'PDF, XPS, EPUB, CBZ',
'title': 'The PyMuPDF Documentation', 'creationDate': "D:20160611145816-04'00'",
'creator': 'sphinx', 'subject': 'PyMuPDF 1.9.1'}
>>> doc.set_metadata({})      # clear all fields
>>> doc.metadata             # look again to show what happened
{'producer': 'none', 'format': 'PDF 1.4', 'encryption': None, 'author': 'none',
'modDate': 'none', 'keywords': 'none', 'title': 'none', 'creationDate': 'none',
'creator': 'none', 'subject': 'none'}
>>> doc.del_xml_metadata()    # clear any XML metadata
>>> doc.save("anonymous.pdf", garbage = 4)       # save anonymized doc

set_toc() 演示

这展示了如何修改或添加目录。还可以看看示例目录中的 import.py 和 export.py。

>>> import pymupdf
>>> doc = pymupdf.open("test.pdf")
>>> toc = doc.get_toc()
>>> for t in toc: print(t)                           # show what we have
[1, 'The PyMuPDF Documentation', 1]
[2, 'Introduction', 1]
[3, 'Note on the Name fitz', 1]
[3, 'License', 1]
>>> toc[1][1] += " modified by set_toc"               # modify something
>>> doc.set_toc(toc)                                  # replace outline tree
3                                                    # number of bookmarks inserted
>>> for t in doc.get_toc(): print(t)                  # demonstrate it worked
[1, 'The PyMuPDF Documentation', 1]
[2, 'Introduction modified by set_toc', 1]            # <<< this has changed
[3, 'Note on the Name fitz', 1]
[3, 'License', 1]

insert_pdf() 示例

(1) 合并两个文档，包括它们的目录

>>> doc1 = pymupdf.open("file1.pdf")          # must be a PDF
>>> doc2 = pymupdf.open("file2.pdf")          # must be a PDF
>>> pages1 = len(doc1)                     # save doc1's page count
>>> toc1 = doc1.get_toc(False)     # save TOC 1
>>> toc2 = doc2.get_toc(False)     # save TOC 2
>>> doc1.insert_pdf(doc2)                   # doc2 at end of doc1
>>> for t in toc2:                         # increase toc2 page numbers
        t[2] += pages1                     # by old len(doc1)
>>> doc1.set_toc(toc1 + toc2)               # now result has total TOC

显然，在更一般的情况下也可以找到类似的方法。只需确保同一行中的层级不会增加超过一级。在 toc2 段落前后插入占位书签可以解决此类问题。示例目录中的脚本 join.py 中有一个现成的 GUI (wxPython) 解决方案。

(2) 更多示例

>>> # insert 5 pages of doc2, where its page 21 becomes page 15 in doc1
>>> doc1.insert_pdf(doc2, from_page=21, to_page=25, start_at=15)

>>> # same example, but pages are rotated and copied in reverse order
>>> doc1.insert_pdf(doc2, from_page=25, to_page=21, start_at=15, rotate=90)

>>> # put copied pages in front of doc1
>>> doc1.insert_pdf(doc2, from_page=21, to_page=25, start_at=0)

其他示例

将 PDF 中所有按页面引用的图像提取为单独的 PNG 文件:

for i in range(doc.page_count):
    imglist = doc.get_page_images(i)
    for img in imglist:
        xref = img[0]                  # xref number
        pix = pymupdf.Pixmap(doc, xref)   # make pixmap from image
        if pix.n - pix.alpha < 4:      # can be saved as PNG
            pix.save("p%s-%s.png" % (i, xref))
        else:                          # CMYK: must convert first
            pix0 = pymupdf.Pixmap(pymupdf.csRGB, pix)
            pix0.save("p%s-%s.png" % (i, xref))
            pix0 = None                # free Pixmap resources
        pix = None                     # free Pixmap resources

旋转 PDF 的所有页面

>>> for page in doc: page.set_rotation(90)

脚注

[1]

内容流描述了页面上显示什么（例如文本或图像）、在何处以及如何显示。PDF 使用一种类似于 PostScript 的专门迷你语言来实现这一点（参见 Adobe PDF References 第 643 页），该语言在加载页面时被解释。

[2]

但是，您可以使用 Document.get_toc() 和 Page.get_links()（这些方法适用于所有文档类型）并将此信息复制到输出 PDF。请参阅演示 convert.py。

[3]

对于适用的文档类型（EPUB），通过其绝对页码加载页面可能导致在访问该页面之前对文档的大部分进行布局。为了避免这种性能影响，请优先使用基于章节的访问。使用便捷方法和属性 Document.next_location()、Document.prev_location() 和 Document.last_location 以保持较高的编码效率。

[4] (1,2)

这些参数导致流类别的单独处理：将其与 expand 一起使用，将解压缩限制为图像/字体文件以外的流。

[5]

“Form XObjects” 的示例由 Page.show_pdf_page() 创建。

[6]

对于 False，必须扫描整个文档。这两种方法都不加载页面，而只扫描对象定义。这使得它们比应用级循环（总响应时间大约等于加载所有页面的时间）快至少 10 倍。对于 Adobe PDF References（756 页）和 Pandas 文档（超过 3070 页）——两者都没有注释——该方法返回 False 大约需要 11 毫秒。因此，响应时间可能只有远远超过这个数量级时才会变得显著。

[7]

这仅在某些条件下有效。例如，如果普通文本被其上面的某个图像覆盖，则这是无法检测到的，并且相应的文本不会被移除。白色背景上的白色文本等情况也是如此。

---

本软件按“原样”提供，不附带任何明示或暗示的担保。本软件根据许可协议分发，除非该许可协议的条款明确授权，否则不得复制、修改或分发。有关许可信息，请参阅 artifex.com 或联系 Artifex Software Inc., 39 Mesa Street, Suite 108A, San Francisco CA 94129, United States 获取更多信息。

本文档涵盖所有版本，最高至 1.26.0。