文档#

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

这个类有一个别名 open，即 pymupdf.Document(...) 和 pymupdf.open(...) 完全执行相同的操作。

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

注意

从 v1.17.0 开始，支持仅针对 EPUB 文件 的新页面定位机制。该文档类型内部按章节组织，使得可以通过其所谓的“位置”最有效地找到页面。位置是一个元组 (chapter, pno)，由章节号和在该章节中的页面号码组成。两个号码都是以零为基础。

虽然仍然可以通过其（绝对）编号定位页面，但这样做可能意味着在可以访问该页面之前必须先布局整个EPUB文档。如果文档非常大，这可能会对性能产生重大影响。使用页面的 (chapter, pno) 可以防止这种情况发生。

为了保持一致的API，PyMuPDF支持页面位置语法用于所有文件类型 – 没有此功能的文档仅有一个章节。Document.load_page()及其等效的索引访问现在也支持位置参数。

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

方法 / 属性	简短描述
`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：删除单个目录项
`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：打开、关闭、RBGroups中的OCG列表
`Document.get_layers()`	仅限PDF: 可选内容配置列表
`Document.get_oc()`	仅限PDF: 获取图像/表单x对象的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()`	通过页码创建页面的位图
`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()`	返回下一页的 (章节, 页码)
`Document.outline_xref()`	仅限PDF: `xref` 一个目录项
`Document.page_cropbox()`	仅限PDF：未旋转的页面矩形
`Document.page_xref()`	仅限PDF：`xref` 的页面编号
`Document.pages()`	在页面范围内迭代
`Document.pdf_catalog()`	仅限PDF: `xref` 的目录 (根)
`Document.pdf_trailer()`	仅限PDF：尾部源
`Document.prev_location()`	返回前一页的 (章节, 页码)
`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附加到图像/表单x对象
`Document.set_ocmd()`	仅限PDF：创建或更新一个 `OCMD`
`Document.set_page_labels()`	仅限PDF：添加/更新页面标签定义
`Document.set_pagemode()`	仅限PDF：设置页面模式
`Document.set_pagelayout()`	仅限PDF：设置页面布局
`Document.set_toc_item()`	仅限PDF：更改单个目录项
`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: `xref` 的XML元数据
`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`	这是一个表单PDF吗？
`Document.is_pdf`	这是一份PDF吗？
`Document.is_reflowable`	这是一份可重排的文档吗？
`Document.is_repaired`	仅限PDF：这个PDF在打开时是否被修复？
`Document.last_location`	最后一页的章节和页码
`Document.metadata`	元数据
`Document.markinfo`	PDF 标记信息值
`Document.name`	文档的文件名
`Document.needs_pass`	需要密码来访问数据吗？
`Document.outline`	第一个大纲项目
`Document.page_count`	页数
`Document.permissions`	访问文档的权限
`Document.pagemode`	PDF 页模式值
`Document.pagelayout`	PDF 页面布局值
`Document.version_count`	版本的PDF数量

类 API

class Document#

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

在 v1.14.13 中更改：支持 io.BytesIO 用于内存文档。
在v1.19.6中更改：更清晰、更简短且更一致的异常消息。如果未指定，则始终假定文件类型为“pdf”。空文件和内存区域将始终引发异常。

创建一个文档对象。

使用默认参数，将创建一个新的空PDF文档。
如果 stream 被提供，则文档是从内存中创建的，如果不是PDF，则 filename 或 filetype 必须指明其类型。
如果 stream 为 None，则会从 filename 指定的文件创建文档。其类型由扩展名推断。可以通过 filetype. 进行覆写。

Parameters:

filename (str,pathlib) – 一个包含文件路径的 UTF-8 字符串或 pathlib 对象。文档类型由文件名扩展名推断。如果缺少或不匹配支持的类型，则假定为 PDF 文档。对于内存文档，此参数可以替代 filetype，请见下文。
流 (字节,字节数组,BytesIO) – 一个包含支持文档的内存区域。如果不是PDF，则其类型必须通过filename或filetype指定。
filetype (str) – 一个字符串，指定文档的类型。这个可以是任何看起来像文件名的东西（例如“x.pdf”），在这种情况下MuPDF使用扩展名来确定类型，或者像application/pdf这样的mime类型。仅使用像“pdf”或“.pdf”的字符串也可以。对于PDF文档可以省略，否则必须匹配a supported document type。
rect (rect_like) – 一个矩形，指定所需的页面大小。该参数仅对具有可变页面布局（“可重排”文档）的文档有意义，例如电子书或HTML，其他情况下将被忽略。如果指定，它必须是一个非空的、有穷的矩形，左上角坐标为 (0, 0)。与参数 fontsize 一起，每页将相应地布局，从而也确定页数。
宽度 (浮动) – 可与高度一起使用，作为矩形的替代，以指定布局信息。
高度 (浮点数) – 可与宽度一起使用，作为矩形的替代，来指定布局信息。
fontsize (float) – 默认的 fontsize 用于可重新流动的文档类型。如果未指定参数 rect、width 或 height，则此参数将被忽略。将用于计算页面布局。

Raises:

类型错误 – 如果任何参数的类型不符合。
FileNotFoundError – 如果文件 / 路径无法找到。作为RuntimeError的子类重新实现。
EmptyFileError – 如果文件 / 路径为空或者 bytes 对象在内存中的长度为零。是 FileDataError 和 RuntimeError 的子类。
ValueError – 如果明确指定了未知的文件类型。
FileDataError – 如果文档对于给定类型具有无效结构，或者根本不是文件（例如，一个文件夹）。是RuntimeError的子类。

Returns:

一个文档对象。如果无法创建文档，则会在上述序列中引发异常。请注意，特定于 PyMuPDF 的异常 FileNotFoundError、EmptyFileError 和 FileDataError 如果检查 RuntimeError 会被拦截。

如有问题，您可以在内部消息存储中查看更多详细信息：print(pymupdf.TOOLS.mupdf_warnings())（此调用将清空，但您也可以防止这种情况 - 请参阅 Tools.mupdf_warnings()）。

注意

并不是所有文档类型在打开时都会检查有效格式。例如，光栅图像将在后期引发异常，当尝试访问内容时。其他类型（特别是非二进制内容的类型）也可能成功打开（有时甚至被访问）– 有时即使内容格式无效：

HTM, HTML, XHTML: 始终开启，metadata["format"] 是 “HTML5”，即 “XHTML”。
XML, FB2: 始终打开，metadata["format"] 是 “FictionBook2”。

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

>>> # from a file
>>> doc = pymupdf.open("some.xps")
>>> # handle wrong extension
>>> doc = pymupdf.open("some.file", filetype="xps")
>>>
>>> # from memory, filetype is required if not a PDF
>>> doc = pymupdf.open("xps", mem_area)
>>> doc = pymupdf.open(None, mem_area, "xps")
>>> doc = pymupdf.open(stream=mem_area, filetype="xps")
>>>
>>> # new empty PDF
>>> doc = pymupdf.open()
>>> doc = pymupdf.open(None)
>>> doc = pymupdf.open("")

注意

带有错误（但支持）文件扩展名的栅格图像 没有问题。MuPDF将在实际访问文件内容时确定正确的图像类型，并将毫无怨言地处理它。因此 pymupdf.open("file.jpg") 即使对于PNG图像也可以正常工作。

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 的交叉引用编号。

Parameters:: xref (int) – 图像或表单 xobject 的 xref。有效的交叉引用编号由 Document.get_page_images() 或 Document.get_page_xobjects() 返回。对于无效的编号，将引发异常。
Return type:: 整型
Returns:: 可选内容对象的交叉引用编号，如果没有则为零。

set_oc(xref, ocxref)#

v1.18.4 中的新功能

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

Parameters:

xref (int) – 图像或表单 xobject 的 xref [5]。有效的交叉引用编号由 Document.get_page_images() 返回，或 Document.get_page_xobjects()。对于无效的编号，将引发异常。
ocxref (int) – 一个xref编号的OCG / OCMD。如果不为零，则无效引用会引发异常。如果为零，则移除任何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 状态集合，并允许在同一文档的不同视图之间快速切换可见性。

Parameters:

name (str) – 任意名称。
创建者 (str) – （可选）创建软件。
开启 (序列) – 一系列的 OCG xref 编号，当该图层被激活时应设置为开启。所有未列出的 OCG 将被设置为关闭。

switch_layer(number, as_default=False)#

v1.18.3中的新内容

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

Parameters:

number (int) – 由 Document.layer_configs() 返回的配置编号。
as_default (bool) – 将其设为默认配置。

激活在识别的层中定义的 OCG 的开/关状态。如果 as_default=True，那么所有层，包括标准层，也会被合并，并且结果会被写回到标准层，并且 所有可选层会被删除。

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

v1.18.3中的新内容

添加一个可选内容组。OCG是决定对象可见性的最重要信息单元。对于PDF，必须存在至少一个OCG，才能被视为具有可选内容。

Parameters:

名称 (字符串) – 任意名称。将在支持的PDF查看器中显示。
config (int) – 层配置编号。默认值 -1 是标准配置。
开 (布尔值) – 指向此 OCG 的对象的标准可见性状态。
意图 (字符串,列表) – 一个字符串或字符串列表，声明可见性意图。可选择两个PDF标准值：“查看”和“设计”。默认值是“查看”。正确的拼写很重要。
用法 (str) – 另一个影响OCG可见性的因素。这将成为OCG的 /Usage 键的一部分。有两个PDF标准值可供选择：“Artwork”和“Technical”。默认值为“Artwork”。请仅在需要时更改。

Returns:

xref 创建的 OCG。作为支持对象中 oc 参数的入口。

注意

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

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

v1.18.4 中的新功能

创建或更新一个 OCMD, 可选内容会员字典.

Parameters:

xref (int) – 更新的 OCMD 的 xref，或 0 表示一个新的 OCMD。
ocgs (list) – 一系列现有的 OCG PDF 对象的 xref 编号。
策略 (字符串) – 选项包括“AnyOn”（默认）、“AnyOff”、“AllOn”、“AllOff”（可以混合或使用小写字母）。
ve (list) – 一个“可见性表达式”。这是一系列任意嵌套的其他列表 – 见下面的解释。如果你需要 formulare 更复杂的条件，请作为 ocgs / policy 组合的替代方案使用。

Return type:

整型

Returns:

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

注意

像OCG一样，OCMD具有开启或关闭的可见性状态，并且可以像OCG一样使用。与OCG相反，OCMD状态是通过特殊形式的布尔表达式评估一个或多个OCG的状态来确定的。如果表达式评估为真，则OCMD状态为开启，若为假则为关闭。

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

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

AnyOn – （默认）如果至少有一个 OCG 处于开启状态，则为真。

AnyOff – 如果至少有一个 OCG 关闭，则为真。

AllOn – 如果所有 OCGs 都开启，则为真。

AllOff – 如果所有 OCGs 都关闭则为真。

假设您希望两个PDF对象一次只显示一个（如果一个是打开的，则另一个必须是关闭的）：

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

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

每个列表必须以一个逻辑关键字开始。

如果关键字是 “not”，那么列表必须恰好有两个项目。如果它是 “and” 或 “or”，可以跟随任何数量的其他项目。

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

示例：

set_ocmd(ve=["or", 4, ["not", 5], ["and", 6, 7]]). 这将输出 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的定义。

Parameters:: xref (int) – OCMD 的 xref。
Return type:: 字典
Returns:: 一个字典，具有键 xref、ocgs、policy 和 ve。

get_layer(config=-1)#

v1.18.3中的新内容

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

Parameters:: 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 中更改：支持锁定的 OCG 列表。

可选内容组的大规模状态更改。 永久性 地设置 OCG 的状态。

Parameters:

config (int) – 期望的配置层，选择 -1 代表默认配置。
on (list) – 要设置为 ON 的 OCGs 的 xref 列表。将替换先前的值。一个空列表将导致没有 OCG 再被设置为 ON。如果使用了 basestate="ON"，则应该指定。
关闭 (列表) – OCG的xref列表设置为关闭。替换之前的值。空列表将导致没有OCG再被设置为关闭。如果使用basestate="OFF"，则应该指定此项。
basestate (str) – OCGs的状态没有在on或off中提及。可能的值为“ON”、“OFF”或“Unchanged”。大小写均可。
rbgroups (list) – 一个由列表组成的列表。替换之前的值。每个子列表应包含两个或更多的 OCG xrefs。相同子列表中的 OCG 被处理为单选按钮组中的按钮：将一个设为开启会自动将所有其他组成员设为关闭。
锁定 (列表) – 一个无法通过用户界面更改的 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查看器的用户界面修改的可选内容的可见性状态。

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

The meaning of the dictionary keys is as follows:

深度： 项目在 /Order 数组中的嵌套级别

locked: 如果无法通过用户界面更改则为真

number: 运行序列号

在：项目状态

文本： 源OCG的文本字符串或名称字段

类型： “label”（由文本字符串设置）、“checkbox”（由单个 OCG 设置）或 “radiobox”（由一组连接的 OCG 设置）

set_layer_ui_config(number, action=0)#

v1.18.3中的新内容

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

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

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

Parameters:

number (int,str) – 在列表 Document.layer_configs() 中项的序列号或这些项中的“文本”。
action (int) – PDF_OC_ON = 设置为开启（默认）， PDF_OC_TOGGLE = 切换开/关， PDF_OC_OFF = 设置为关闭。

authenticate(password)#

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

Parameters:

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

Return type:

整型

Returns:

如果成功则返回正值，否则返回零（字符串与两个密码都不匹配）。如果为正值，则指示器 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)#

版本 1.18.6 新增功能

仅限PDF：返回具有指定标签的页面编号列表 - 请注意，标签在PDF中可能不是唯一的。这意味着需要对所有页面编号进行顺序搜索以比较它们的标签。

注意

实现细节 - 页面为了这个目的不会加载。

Parameters:

标签 (str) – 要查找的标签，例如“vii”（罗马数字7）。
only_one (bool) – 在第一次命中后停止。比如当标签知道是唯一时，或者有很多页面等，这很有用。默认将检查每个页面编号。

Return type:

列表

Returns:

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

get_page_labels()#

v1.18.7 新增功能

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

Returns:: 一个字典列表，如Document.set_page_labels()中定义。

set_page_labels(labels)#

v1.18.6 中的新功能

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

Parameters:

labels (list) –

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

startpage: (int) 应用标签规则的第一页码（以0为基数）。该键必须存在。该规则应用于所有后续页面，直到文档结束或被下一个更大页码的规则替代。
prefix: (str) 用于启动标签的任意字符串，例如“A-”。默认为“”。
style: (str) 编号样式。可用的有“D”（十进制）、“r”/“R”（罗马数字，小写/大写）和“a”/“A”（小写/大写字母编号：“a”到“z”，然后是“aa”到“zz”等）。默认为“”。如果为“”，则不会进行编号，且该范围内的页面将收到由prefix值组成的相同标签。如果前缀也被省略，则标签将为“”。
firstpagenum: (int) 从该值开始编号。默认为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。

Parameters:: loc (list,tuple) – 页面位置。必须是有效的 (chapter, pno)。
Return type:: 指针
Returns:: 指针格式的长整型。用于在重新布局文档后查找页面的新位置。请勿触碰或重新分配。

find_bookmark(bookmark)#

在 v.1.17.3 中的新功能

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

Parameters:: 书签 (指针) – 由 Document.make_bookmark() 创建。
Return type:: 元组
Returns:: 页面的新 (chapter, pno)。

chapter_page_count(chapter)#

v.1.17.0中的新功能

返回章节的页数。

Parameters:: 章节 (int) – 从0开始的章节编号。
Return type:: 整型
Returns:: 章节中的页数。仅与支持章节的文档类型相关（当前为EPUB）。

next_location(page_id)#

v.1.17.0中的新功能

返回以下页面的位置。

Parameters:: page_id (tuple) – 当前页面的 ID。这个必须是一个元组 (chapter, pno)，用于标识现有页面。
Returns:: 下面页面的元组，即(chapter, pno + 1)或(chapter + 1, 0)，或者如果参数是最后一页则为空元组()。仅与支持章节的文档类型相关（目前为EPUB）。

prev_location(page_id)#

v.1.17.0中的新功能

返回前一页面的定位器。

Parameters:: page_id (元组) – 当前页面 id。这必须是一个元组 (chapter, pno)，用于标识一个现有页面。
Returns:: 上一页的元组，即 (chapter, pno - 1) 或者前一章的最后一页，或者如果参数是第一页则为空元组 ()。仅对支持章的文档类型相关（目前为 EPUB）。

load_page(page_id=0)#

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

创建一个页面对象以便进一步处理（如渲染、文本搜索等）。

Parameters:

page_id (int,tuple) –

(在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）。

Return type:

页面

注意

文档还遵循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] 脚注。

reload_page(page)#

v1.16.10的新特性

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

Parameters:

页面 (页面) – 页面对象。

Return type:

页面

Returns:

同一页面的新副本。所有待处理的更新（例如对注释或小部件的更新）将被完成，且将加载页面的新副本。

注意

在典型的使用情况下，应该在注释/小部件添加或更改后获取页面Pixmap。为了强制在页面结构中反映所有这些更改，该方法重新加载新副本，同时保持对象层次结构“文档 -> 页面 -> 注释/小部件”不变。

resolve_names()#

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

Returns:

具有以下布局的字典：

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())。此功能用于需要最佳性能的内部目的。

Parameters:: pno (int) – 从0开始的页面编号。
Returns:: 页面的矩形像 Page.rect()，但忽略任何旋转。

page_xref(pno)#

v1.17.7中的新功能

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

Parameters:: pno (int) – 基于0的页面编号。
Returns:: xref 页面的引用，如 Page.xref。

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

v1.16.4中的新功能

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

Parameters:

start (int) – 使用此页面编号开始迭代。默认值为零，允许的值为 -∞ < start < page_count。当这是负数时，page_count 在开始迭代之前被添加。
stop (int) – 在此页面编号停止迭代。默认值为 page_count，可能的值为 -∞ < stop <= page_count。更大的值将被默默替换为默认值。负值将循环以反向顺序发出页面。与内置的 range() 一样，这是不返回的第一页。
步长 (int) – 步进值。如果 start < stop，默认为 1；如果 start > stop，默认为 -1。不允许为零。

Returns:

一个生成器迭代器遍历文档的页面。一些示例：

”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, 2, 1, 0, 3。

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

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

Parameters:

from_page (int) – 要复制的第一页（基于0）。默认为第一页。
to_page (int) – 最后一个要复制的页面（基于0）。默认最后一个页面。
rotate (int) – 旋转角度。默认值为 0（无旋转）。应为 n * 90，其中 n 为整数（未检查）。

Return type:

字节

Returns:

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

>>> # 将 XPS 文件转换为 PDF
>>> xps = pymupdf.open("some.xps")
>>> pdfbytes = xps.convert_to_pdf()
>>>
>>> # 这样做 -->
>>> pdf = pymupdf.open("pdf", pdfbytes)
>>> pdf.save("some.pdf")
>>>
>>> # 或者这样做 -->
>>> pdfout = open("some.pdf", "wb")
>>> pdfout.tobytes(pdfbytes)
>>> pdfout.close()

>>> # 将图像文件复制到 PDF 页面
>>> # 每一页将具有图像尺寸
>>> doc = pymupdf.open()                     # 新 PDF
>>> imglist = [ ... 图像 文件 名称 ...] # 例如，一个目录列表
>>> for img in imglist:
        imgdoc=pymupdf.open(img)           # 将图像作为文档打开
        pdfbytes=imgdoc.convert_to_pdf()  # 制作一个 1 页 PDF
        imgpdf=pymupdf.open("pdf", pdfbytes)
        doc.insert_pdf(imgpdf)             # 插入图像 PDF
>>> doc.save("allmyimages.pdf")

注意

该方法使用与mutool convert命令行相同的逻辑。这在大多数情况下效果很好—然而，请注意以下限制。

图像文件：完美，未检测到问题。然而，图像透明度被忽略。如果您需要该功能（如用于水印），请使用 Page.insert_image()。否则，建议使用此方法，因为它的性能更佳。
XPS：外观非常好。链接正常工作，目录（书签）丢失，但可以很容易恢复 [2]。
EPUB, CBZ, FB2: 类似于 XPS。
SVG：中等。大致可与 svglib 相媲美。

get_toc(simple=True)#

根据文档的提纲链创建目录。

Parameters:

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

Return type:

列表

Returns:

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

lvl – 层级级别（正整数 int）。第一个条目总是 1。同一行中的条目要么相等，要么增加 1，或者减少任何数。
title – 标题 (str)
page – 基于 1 的源页面编号 (int)。 -1 如果没有目标或在文档之外。
dest – (dict) 仅在 simple=False 时包括。包含 TOC 项的详细信息如下：
- kind: 目标类型，参见链接目标类型。
- file: 如果类型为 LINK_GOTOR 或 LINK_LAUNCH，则为文件名。
- page: 目标页面，基于 0，仅 LINK_GOTOR 或 LINK_GOTO。
- to: 目标页面上的位置 (点)。
- 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。（1.23.7 中新增。）

xref_get_keys(xref)#

v1.18.7 新增功能

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

Parameters:

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

Returns:

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

>>> from pprint import pprint
>>> import pymupdf
>>> doc=pymupdf.open("pymupdf.pdf")
>>> xref = doc.page_xref(0)  # 页面 0 的 xref
>>> pprint(doc.xref_get_keys(xref))  # 页面的主键
('Type', 'Contents', 'Resources', 'MediaBox', 'Parent')
>>> pprint(doc.xref_get_keys(-1))  # 牵引的主键
('Type', 'Index', 'Size', 'W', 'Root', 'Info', 'ID', 'Length', 'Filter')
>>>

xref_get_key(xref, key)#

v1.18.7 新增功能

仅限PDF：根据其xref返回dictionary对象的PDF字典键的返回类型和值。

Parameters:

xref (int) – xref。在 v1.18.10 中更改：使用 -1 来访问特殊字典“PDF trailer”。
key (str) – 所需的 PDF 键。必须完全匹配（区分大小写）Document.xref_get_keys()中包含的某个键。

Return type:

元组

Returns:

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

“name”总是以“/”斜杠开始。
一个“xref”总是以“ 0 R”结尾。
“数组”总是被包含在“[…]”括号中。
“dict”总是包含在“<<…>>”括号中。
一个“bool”，或“null”始终等于“true”，“false”，或“null”。
“float”和“int”通过它们的字符串格式表示——因此并不总是可以区分。

一个“字符串”被转换为UTF-8，因此可能与PDF中存储的内容有所不同。例如，PDF键“Author”在文件中可能有一个值“”，但该方法将返回 ('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”，则移除关键字“physically”。

仅限PDF：设置（添加、更新、删除）dictionary对象的PDF键值，依据其xref。

注意

这是一个专家函数：如果您不知道自己在做什么，将会有很高的风险使得（部分）PDF无法使用。请务必查阅 Adobe PDF References 关于对象规格格式（第18页）以及像页面对象这样的特殊字典类型的结构。

Parameters:

xref (int) – xref。在 v1.18.13 中更改：要更新 PDF 预览，指定 -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所必需的。
array – 像 "[a b c d e f]" 这样的字符串。方括号是必需的。数组项必须至少用一个空格分隔（而不是像Python那样用逗号）。一个空数组 "[]" 是可能的，并且 等效于 移除键。数组项可以是任何PDF对象，如字典、xref、其他数组等。与Python一样，数组项可以是不同类型。
字典 – 一个类似于 "<< ... >>" 的字符串。方括号是必需的，并且必须包含有效的 PDF 字典定义。空字典 "<<>>" 是可能的，并且等价于移除该键。
int – 一个格式化为字符串的整数。
float – 一个格式化为 字符串 的浮点数。科学计数法（带有指数）在 PDF 中 不允许。
null – 字符串 "null"。这相当于Python的 None，并导致该键被忽略 – 但是不一定被移除，响应地，在进行垃圾回收时会被移除。在 v1.19.4 中更改： 如果该键不是路径层次结构（即不包含斜杠 “/”），那么它将被完全移除。
bool – 字符串 "true" 或 "false" 之一。
name – 一个有效的 PDF 名称，前面带有斜杠，如： "/PageLayout"。请参阅 Adobe PDF References 第 16 页。
字符串 – 一个有效的PDF字符串。所有PDF字符串必须用括号括起来。将空字符串表示为 "()"。根据其内容，可能的括号有
- “(…)” 用于仅包含 ASCII 的文本。保留的 PDF 字符必须使用反斜杠转义，非 ASCII 字符必须以三位数的反斜杠转义八进制形式提供 - 包括前导零。示例：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: 颜色空间 = csRGB, clip: rect_like = None, alpha: bool = False, annots: bool = True)#

从页面 pno 创建一个像素图（基于零）。调用 Page.get_pixmap()。

除 pno 外，所有参数都是 仅关键字。

Parameters:: pno (int) – 页码，基于0 -∞ < pno < page_count。
Return type:: 位图

get_page_xobjects(pno)#

v1.16.13中的新功能
在 v1.18.11 中更改

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

Parameters:

pno (int) – 页面编号，基于0， -∞ < pno < page_count.

Return type:

列表

Returns:

一个（非图像）的 XObjects 列表。这些对象通常代表从其他 PDF 嵌入（而不是复制）的页面。例如，Page.show_pdf_page() 将创建这种类型的对象。该列表中的一个项具有以下布局： (xref, name, invoker, bbox)，其中

xref （int）是 XObject 的 xref。
name （str）是引用 XObject 的符号名称。
invoker （int）是调用 XObject 的 xref，如果页面直接调用它则为零。
bbox （Rect）是 XObject 在页面上的边界框 以未变换坐标表示。要获得实际的、未旋转的页面坐标，请与页面的变换矩阵 Page.transformation_matrix 相乘。 在 v.18.11 中更改： bbox 现在格式化为 Rect。

get_page_images(pno, full=False)#

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

Parameters:

pno (int) – 页码，基于0， -∞ < pno < page_count.
full (bool) – 是否也包括引用者的 xref（如果这是页面，则为零）。

Return type:

列表

Returns:

该页面引用的图像列表。每个项目看起来像

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

其中

xref (int) 是图像对象编号

smask (int) 是其软掩码图像的对象编号

width (int) 是图像宽度

height (int) 是图像高度

bpc (int) 表示每个组件的位数（通常为8）

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

alt_colorspace (str) 是根据colorspace的值而定的任何替代颜色空间

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

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

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

注意

一般来说，这不是实际显示的图像列表。此方法仅解析几个PDF对象以收集对嵌入图像的引用。它并不分析页面的内容，所有实际图像显示命令都在其中定义。要获取此信息，请使用Page.get_image_info()。还请查看字典输出结构部分中的讨论。

get_page_fonts(pno, full=False)#

仅限PDF：返回页面引用的所有字体（直接或间接）的列表。

Parameters:

pno (int) – 页码，基于0， -∞ < pno < page_count.
full (bool) – 是否也包含引用者的 xref。如果 True，返回的项将多出一个条目。如果您需要知道页面是否直接引用该字体，请使用此选项。在这种情况下，最后一个条目是 0。如果字体是通过页面的 /XObject 引用的，您将在这里找到它的 xref。

Return type:

列表

Returns:

该页面引用的字体列表。每个条目看起来像

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

在哪里

xref (int) 是字体对象编号（如果PDF直接使用内置字体，则可能为零）

ext (str) 字体文件扩展名（例如“ttf”，见字体文件扩展名）

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

basefont (str) 是基本字体名称，

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

编码 (字符串) 如果与其内置编码不同，则为字体的字符编码 (Adobe PDF 参考文献, 第 254 页):

引用者 (int 可选) 引用者的 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创建者可能例如指定了一些全局列表，而每个页面只部分使用。

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

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

Parameters:: pno (int) – 页码，基于0的，任何值 -∞ < pno < page_count.

有关其他参数，请参阅页面方法。

Return type:: 字符串

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

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

Parameters:

rect (rect_like) – 所需的页面大小。必须是有限的，不能为空，并且从点 (0, 0) 开始。
宽度 (浮点数) – 将其与高度一起使用作为矩形的替代。
height (float) – 与 width 一起使用作为 rect 的替代。
fontsize (float) – 所需的默认字体大小。

select(s)#

仅限PDF：仅保留文档中在列表中出现的页码。空序列或超出 range(doc.page_count) 的元素将导致 ValueError。有关更多详细信息，请参阅本章底部的说明。

Parameters:: s (sequence) – 包含的页码序列（见在PyMuPDF中使用Python序列作为参数），页码从零开始。序列之外的页将被删除（从内存中）并在文档重新打开之前不可用。 页码可以多次出现并且可以是任意顺序： 生成的文档将准确反映指定的序列。

注意

序列中的页码不需要是唯一的，也不需要按特定顺序。这使得该方法成为一个多功能工具，例如仅选择偶数页或奇数页或满足其他某些标准等。
在技术层面上，这个方法将始终创建一个新的 pagetree。
当处理只有几页时，方法 copy_page()、 move_page()、 delete_page() 更容易使用。实际上，当文档有很多页时，它们的速度也快得多 – 至少快了一个数量级。

set_metadata(m)#

仅限PDF: 设置或更新文档的元数据，如m中所指定，这是一个Python字典。

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

(在 v1.18.4 中更改) 空值或“无”不再被写入，而是被完全省略。

get_xml_metadata()#

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

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

set_xml_metadata(xml)#

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

Parameters:: xml (str) – 新的 XML 元数据。应该是 XML 语法，但该方法不会进行检查，任何字符串都是可以接受的。

set_pagelayout(value)#

v1.22.2中的新功能

仅限PDF: 设置 /PageLayout。

Parameters:: value (str) – 字符串之一 “SinglePage”, “OneColumn”, “TwoColumnLeft”, “TwoColumnRight”, “TwoPageLeft”, “TwoPageRight”。支持小写。

set_pagemode(value)#

v1.22.2中的新功能

仅限PDF：设置 /PageMode。

Parameters:: value (str) – 字符串之一 “UseNone”, “UseOutlines”, “UseThumbs”, “FullScreen”, “UseOC”, “UseAttachments”。支持小写。

set_markinfo(value)#

v1.22.2 新特性

仅限PDF：设置/MarkInfo值。

Parameters:: value (dict) – 一个类似于这个的字典: {"Marked": False, "UserProperties": False, "Suspects": False}. 这个字典包含有关标记PDF规范使用的信息。有关详细信息，请参见PDF specifications。

set_toc(toc, collapse=1)#

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

步骤 1 删除所有现有的书签。
步骤 2 从 toc 中包含的条目创建一个新的目录。

Parameters:

目录 (序列) –
一个包含所有书签条目的列表/元组，这些条目应形成新的目录。get_toc()的输出变体都是可接受的。要完全移除目录，请指定一个空序列或None。每个条目必须是具有以下格式的列表。
- [lvl, title, page [, dest]] 其中
  - lvl 是条目的层级 (int > 0)，第一个条目必须为 1，且至多比前一个条目大 1。
  - title (str) 是要显示的标题。假定为 UTF-8 编码（仅对多字节代码点相关）。
  - page (int) 是目标页面号码（注意：基于 1）。如果为正数，必须在有效范围内。如果没有目标或目标是外部的，将其设置为 -1。
  - dest （可选）是一个字典或数字。如果是数字，它将被解释为该条目在页面上应指向的期望高度（以点为单位）。使用字典（如get_toc(False)输出的那一个）可以详细控制书签的属性，详情请参见Document.get_toc()。
collapse (int) – (在 v1.16.9 中新增) 控制大纲条目应该最初显示为折叠的层级。默认值 1 仅显示级别 1，较高的级别必须使用 PDF 查看器展开。要展开所有内容，指定一个较大的整数、0 或 None。

Return type:

整型

Returns:

插入的项数，或删除的项数。

在 v1.23.8 中更改：目标 'to' 坐标现在应该与 get_toc() 返回的坐标处于相同的坐标系统（内部现在使用 page.cropbox 和 page.rotation_matrix 进行转换）。因此，例如 set_toc(get_toc()) 现在会返回未更改的目标 'to' 坐标。

outline_xref(idx)#

v1.17.7中的新功能

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

Parameters:: idx (int) – 列表 Document.get_toc() 中项目的索引。
Returns:: xref。

del_toc_item(idx)#

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

仅限PDF：删除此目录项。这是一种高速方法，禁用了相关项目，但保持了整体目录结构不变。从物理上讲，该项目仍然存在于目录树中，但显示为灰色，且不再指向任何目的地。

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

Parameters:: idx (int) – 列表中项目的索引 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：更改由其索引识别的目录项。更改项目标题、目标、外观 (颜色、粗体、斜体) 或折叠子项 – 或完全删除该项目。

如果您只需要对选定条目进行特定更改并想要避免替换完整的目录，请使用此方法。当处理大型目录时，这尤其有益。

Parameters:

idx (int) – 列表中由 Document.get_toc() 创建的条目的索引。
dest_dict (dict) – 新目的地。一个像doc.get_toc(False)最后一个条目的字典。建议使用此作为模板。给定时，所有其他参数将被忽略 – 除了标题。
kind (int) – 链接类型，参见链接目标类型。如果LINK_NONE，则所有剩余参数将被忽略，并且 TOC 项目将被删除 – 与Document.del_toc_item()相同。如果为 None，则只有标题会被修改，其余参数将被忽略。所有其他值将导致使用后续参数生成一个新的目标字典。
pno (int) – 以1为基础的页码，即值为 1 <= pno <= doc.page_count。LINK_GOTO所需。
uri (str) – URL文本。LINK_URI是必需的。
标题 (str) – 所需的新标题。如果不更改，则为None。
到 (point_like) – （可选）指向目标页面上的一个坐标。与 LINK_GOTO 相关。如果省略，将选择页面顶部附近的一个点。
filename (str) – LINK_GOTOR 和 LINK_LAUNCH所必需。
zoom (float) – 在显示目标页面时使用此缩放因子。

示例用法： 更改SWIG手册的目录以实现此目的：

折叠所有顶层以下的内容，并以红色、粗体和斜体显示有关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”。

所有页面将看起来相同，但将不再具有注释或相应字段。可见的部分将根据需要转换为标准文本、矢量图形或图像。

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

请考虑到注释是复杂的对象，可能包含其视觉外观“底下”的更多数据。例子包括“文本”和“文件附件”注释。当使用此方法“嵌入”注释/小部件时，所有这些底层信息（附加文件、评论、关联的弹出注释等）将会丢失，并将在下次垃圾收集时被移除。

例如，可以使用此功能的方法 Document.insert_pdf()（不支持复制小部件）或 Page.show_pdf_page()（不支持注释和小部件），当源页面在目标中应完全相同时。

Parameters:

annots (bool) – 转换注释。
小部件 (布尔值) – 转换字段 / 小部件。执行后，文档将不再是“表单 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产品中类似的“清理”功能的启发。该过程可通过多种选项进行配置。

Parameters:

attached_files (bool) – 搜索‘FileAttachment’ 注释并移除文件内容。
clean_pages (bool) – 从页面绘制源中移除任何注释。如果此选项设置为 False，则对于 hidden_text 和 redactions 也会执行此操作。
embedded_files (bool) – 移除嵌入的文件。
hidden_text (bool) – 移除 OCR 识别的文本和不可见文本 [7].
javascript (bool) – 移除 JavaScript 源代码。
元数据 (布尔值) – 移除 PDF 标准元数据。
编辑 (bool) – 应用编辑注释。
redact_images (int) – 如果应用编辑，如何处理图像。可选值为 0（忽略）、1（遮盖重叠部分）或 2（移除）。
remove_links (bool) – 移除所有链接。
reset_fields (bool) – 将所有表单字段重置为默认值。
reset_responses (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: 以当前状态保存文档。

Parameters:

outfile (str,Path,fp) – 文件路径，pathlib.Path 或文件对象用于保存。文件对象必须在之前通过 open(...) 或 io.BytesIO() 创建。选择 io.BytesIO() 类似于 Document.tobytes() 下面，这等于一个内部创建的 io.BytesIO() 的 getvalue() 输出。
垃圾 (int) –
执行垃圾回收。正值排除“增量”。
- 0 = 无
- 1 = 移除未使用（无引用）对象。
- 2 = 在1的基础上，压缩 xref 表。
- 3 = 在2的基础上，合并重复对象。
- 4 = 在3的基础上，检查 stream 对象是否重复。这可能会很慢，因为这类数据通常很大。
clean (bool) – 清理和净化内容流 [1]。对应于“mutool clean -sc”。
deflate (bool) – 压缩未压缩流。
deflate_images (bool) – (在 v1.18.3 中新增) 对未压缩的图像流进行压缩 [4].
deflate_fonts (bool) – (在v1.18.3中新增加) 压缩未压缩的字体文件流 [4].
增量 (布尔值) – 仅保存对PDF的更改。排除“垃圾”和“线性”。只能在 outfile 是字符串或 pathlib.Path 并且等于 Document.name 时使用。不能用于已解密或已修复的文件以及某些其他情况。为了确保，请检查 Document.can_save_incrementally()。如果为假，则需要保存到新文件。
ascii (bool) – 将二进制数据转换为ASCII。
expand (int) –
解压对象。生成可以被某些其他程序更好读取的版本，并将导致文件增大。
- 0 = 无
- 1 = 图像
- 2 = 字体
- 255 = 全部
线性 (布尔值) – 保存文档的线性化版本。此选项创建一种文件格式，以提高Internet访问的性能。排除了“增量”和“use_objstms”。
pretty (bool) – 美化文档源以提高可读性。PDF对象将被重新格式化，以类似于Document.xref_object()的默认输出呈现。
no_new_id (bool) – 阻止更新文件的 /ID 字段。如果文件根本没有这样的字段，也阻止创建一个新的。默认值是 False，因此每次保存都会导致文件标识的更新。
权限 (int) – (v1.16.0 新增) 设置所需的权限级别。有关可能的值，请参见文档权限。默认是授予所有权限。
加密 (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 参数值，转换后的对象定义将被压缩，这可能导致文件大小显著减少。

警告

该方法不会检查是否已经存在同名文件，因此不会询问确认，并会覆盖该文件。作为程序员，处理此问题是你的责任。

注意

文件大小减小

“有损”文件大小减小本质上必须在图像方面放弃某些东西，例如 (a) 删除所有图像 (b) 用它们的灰度版本替换图像 (c) 降低图像分辨率。在PyMuPDF Utilities “replace-image” folder中找到示例。

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()中的完全相同。章节常见问题包含了将此方法用作pdfrw的预处理器的示例。

(在v1.16.0中更改) 以支持扩展加密。

Return type:: 字节
Returns:: 一个包含完整文档的字节对象。

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, show_progress=0, final=1)#

在 v1.19.3 中更改 - 作为对问题 #537 的修复，表单字段始终被排除。

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

Parameters:

docsrc (文档) – 一个已打开的 PDF 文档，不能是当前文档。然而，它可以指向相同的基础文件。
from_page (int) – docsrc中的第一页号码。默认为零。
to_page (int) – 要复制的docsrc中的最后一页页码。默认值为最后一页。
start_at (int) – 第一个复制的页面，将成为目标中的页面编号 start_at。默认值为 -1 将页面范围附加到末尾。如果为零，页面范围将插入到当前第一页之前。
rotate (int) – 所有复制的页面将按提供的值旋转（度数，90的整数倍）。
链接 (布尔值) – 选择是否应在复制中包含（内部和外部）链接。默认是 True。命名的 链接 (LINK_NAMED) 和指向复制页面范围外的内部链接始终被排除。
annots (bool) – (在v1.16.1中新增) 选择是否在复制中包含注释。表单 字段绝不能被复制 – 见下文。
show_progress (int) – (新于 v1.17.7) 指定一个大于零的间隔大小，以便在 sys.stdout 上查看进度消息。每个间隔后，将打印类似于 Inserted 30 of 47 pages. 的消息。
final (int) – (新于 v1.18.0) 控制在此方法之后是否应该丢弃已经复制的对象列表，默认值 True。在多次从同一源 PDF 插入中，将其设置为 0，除非是最后一个。这可以节省目标文件大小，并显著加快执行速度。

注意

这是一个基于页面的方法。因此，源文档的文档级信息被忽略。例子包括可选内容、嵌入文件、StructureElem、AcroForm、目录、页面标签、元数据、命名目标（和其他命名条目）以及其他一些内容。因此，具体地说，表单字段（小部件）永远无法被复制——尽管它们似乎只在页面上出现。如果需要保留至少小部件的外观，请查看Document.bake()以转换源文档。
如果 from_page > to_page，页面将以反向顺序复制。如果 0 <= from_page == to_page，那么将复制一页。
docsrc TOC 条目 将不会被复制。然而，恢复结果文档的目录是很简单的。请查看下面的示例以及 join.py 程序在 examples 目录中的内容：它可以连接 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的简单方法。

Parameters:: infile (多个) – 要插入的输入文档。可以是创建文档或位图时有效的文件名规范。

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

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

Parameters:

pno (int) – 插入新页面的页码。必须在 1 < pno <= page_count 之间。特殊值 -1 和 doc.page_count 将插入到最后一页之后。
width (float) – 页面宽度。
height (float) – 页面高度。

Return type:

页面

Returns:

创建的页面对象。

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

仅限PDF：插入新页面并插入一些文本。便利函数，结合了 Document.new_page() 和 (部分) Page.insert_text()。

Parameters:

pno (int) –

页码（从0开始），在 前面插入 。必须在 range(-1, doc.page_count + 1) 的范围内。特殊值 -1 和 doc.page_count 在最后一页之后插入。

在 v1.14.12 中更改: 现在这是一个位置参数

有关其他参数，请查阅上述方法。

Return type:: 整型
Returns:: Page.insert_text() 的结果（成功插入的行数）。

delete_page(pno=-1)#

仅限PDF：删除由其基于0的编号给出的页面 -∞ < pno < page_count - 1。

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

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

delete_pages(*args, **kwds)#

在 v1.18.13 中更改：在指定要删除的页面时更具灵活性。
在 v1.18.14 中更改：支持 Python 的 del 语句。

仅限PDF：删除作为基于0的数字给出的多个页面。

Format 1: Use keywords. Represents the old format. A contiguous range of pages is removed.

“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 观看器显示为灰色。整体目录结构保持不变。

它还将删除指向已删除页面的所有链接。对于包含许多页面的文档，此操作可能会有较长的响应时间。

以下示例将删除页面 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 References，上述操作大约需要0.6秒，因为剩余的1290页必须清除无效链接。

一般来说，这个方法的性能取决于剩余页面的数量 – 而不是已删除页面的数量：在上面的例子中，删除所有页面，除了那20个页面，将需要更少的时间。

copy_page(pno, to=-1)#

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

Parameters:

pno (int) – 要复制的页面。必须在范围内 0 <= pno < page_count.
到 (int) – 要复制的页码，复制将在此页码之前进行。默认值是在最后一页之后插入。

注意

只会创建一个新的引用到页面对象 - 而不是一个新的页面对象，所有复制的页面将具有相同的属性值，包括 Page.xref。这意味着对这些副本中的任何一个所做的更改将在所有副本上显示。

fullcopy_page(pno, to=-1)#

v1.14.17 中的新特性

仅限PDF：复制页面的完整副本（重复）。

Parameters:

pno (int) – 要复制的页面。必须在范围内 0 <= pno < page_count.
到 (int) – 要复制的页面编号，默认是在最后一页之后插入。

注意

与 copy_page() 相比，这种方法创建一个新的页面对象（具有新的 xref），可以独立于原始对象进行更改。
任何弹出窗口和“IRT”（“响应于”）注释不会被复制以避免潜在的不正确情况。

move_page(pno, to=-1)#

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

Parameters:

pno (int) – 要移动的页面。必须在范围内 0 <= pno < page_count。
到 (int) – 要插入已移动页面的页码。默认情况下，移动在最后一页之后。

need_appearances(value=None)#

v1.17.4的新功能

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

Parameters:

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

Return type:

布尔值

Returns:

无：不是一个表单PDF，或属性未定义。
真/假：属性的值（可以是刚设置的或现有的用于查询）。如果没有表单PDF，则没有影响。

get_sigflags()#

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

Return type:

整型

Returns:

-1：不是一个表单 PDF / 没有记录的签名字段 / 找不到 SigFlags。
1：至少存在一个签名字段。
3：包含可能在文件以改变其先前内容的方式保存（写入）时失效的签名，与增量更新相对。

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

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

仅限PDF：嵌入新文件。除名称外，所有字符串参数都可以是unicode（在之前的版本中，仅ASCII正常工作）。文件内容将被压缩（在有利的情况下）。

Parameters:

name (str) – 条目的标识符，不能已经存在。
缓冲区 (字节,字节数组,BytesIO) –
文件内容。

(在v1.14.13中更改) io.BytesIO 现在也被支持。
filename (str) – 可选的文件名。仅用于文档，如果 None，将设置为 name。
ufilename (str) – 可选的unicode文件名。仅供文档使用，如果是 None，将设置为 filename。
描述 (字符串) – 可选描述。仅用于文档，如果为 None 则将设置为名称。

Return type:

整型

Returns:

(在 v1.18.13 中更改) 该方法现在返回插入文件的 xref。此外，文件对象现在将根据当前日期时间自动添加 PDF 键 /CreationDate 和 /ModDate。

embfile_count()#

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

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

embfile_get(item)#

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

Parameters:: 项 (整数,字符串) – 条目的索引或名称。一个整数必须在 range(embfile_count()) 内。
Return type:: 字节

embfile_del(item)#

在 v1.14.16 中更改：现在也可以通过索引删除项目。

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

Parameters:: 项目 (整型/字符串) – 条目的索引或名称。

警告

在指定条目名称时，此函数将仅 删除第一个项目。请注意，未使用 PyMuPDF 创建的 PDF 可能包含重复名称。因此，您可能想要采取适当的预防措施。

embfile_info(item)#

在 v1.18.13 中更改

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

Parameters:

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

Return type:

字典

Returns:

一个包含以下键的字典：

name – (str) 此条目的存储名称
filename – (str) 文件名
ufilename – (unicode) 文件名
description – (str) 描述
size – (int) 原始文件大小
length – (int) 压缩文件长度
creationDate – (str) 项目创建的日期时间，格式为 PDF
modDate – (str) 最后更改的日期时间，格式为 PDF
collection – (int) 如果有，相关PDF投资组合项目的 xref，否则为零。
checksum – (str) 存储文件内容的哈希码，以十六进制字符串表示。应根据 PDF 规范为 MD5，但要准备好看到其他哈希算法。

embfile_names()#

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

Return type:: 列表

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

仅限PDF：根据其条目编号或名称更改嵌入文件。所有参数都是可选的。让它们保持默认值将导致没有操作。

Parameters:

item (int/str) – 条目的索引或名称。整数必须在 range(embfile_count()) 中。
缓冲区 (字节,字节数组,BytesIO) –
新的文件内容。

(在 v1.14.13 中更改) io.BytesIO 现在也受到支持。
filename (str) – 新的文件名。
ufilename (str) – 新的unicode文件名。
desc (str) – 新的描述。

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

Return type:: 整型
Returns:: 文件对象的xref。其 /ModDate PDF键将自动更新为当前的日期和时间。

close()#: 释放与文档相关的对象和空间分配。如果是从文件创建的，还会关闭 filename（将控制权交还给操作系统）。明确关闭文档等同于删除它， del doc，或将其分配给其他内容，例如 doc = None。

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

在 v1.16.8 中的新功能
在v1.18.10中更改

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

Parameters:

xref (int) – 对象的 xref。在 v1.18.10 中更改：一个值为 -1 返回 PDF trailer 源。
compressed (bool) – 是否生成不带换行或空格的紧凑输出。
ascii (bool) – 是否对二进制数据进行ASCII编码。

Return type:

字符串

Returns:

对象定义源。

pdf_catalog()#

在 v1.16.8 中的新功能

仅限PDF：返回xref编号的PDF目录（或根）对象。将该编号与Document.xref_object()一起使用，以查看其来源。

pdf_trailer(compressed=False)#

在 v1.16.8 中的新功能

仅限PDF：返回PDF的尾部源，通常位于PDF文件的末尾。这是 Document.xref_object()，其 xref 参数为 -1。

xref_stream(xref)#

在 v1.16.8 中的新功能

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

Parameters:: xref (int) – xref 编号。
Return type:: 字节
Returns:: 对象的（解压缩）流。

xref_stream_raw(xref)#

在 v1.16.8 中的新功能

仅限PDF：返回xref流对象的未修改（特别是未解压缩）内容。否则等同于Document.xref_stream()。

Return type:: 字节
Returns:: 对象的（原始、未修改的）流。

update_object(xref, obj_str, page=None)#

在 v1.16.8 中的新功能

仅限PDF：用提供的字符串替换xref的对象定义。如果xref也是新的，那么这个指令将完成对象定义。如果还提供了一个页面对象，它的链接和注释将在之后重新加载。

Parameters:

xref (int) – xref 编号。
obj_str (str) – 包含有效PDF对象定义的字符串。
页面 (页面) – 一个页面对象。如果提供，则表示该页面的注释应该被刷新（重新加载）以反映链接和/或注释所产生的更改。

Return type:

整型

Returns:

成功返回零，否则将抛出异常。

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”），以便于使用。

Parameters:

xref (int) – xref 编号。
stream (bytes|bytearray|BytesIO) –
流的新内容。

(在 v1.14.13 中更改：) io.BytesIO 对象现在也受到支持。
new (bool) – 已弃用并被忽略。将在v1.20.0之后的某个时间被移除。
compress (bool) – 是否压缩插入的流。如果 True（默认），流将使用 /FlateDecode 压缩（如果有利），否则流将按原样插入。

Raises:

值错误 – 如果 xref 不代表一个 PDF dict。一个空字典 <<>> 是被接受的。因此，如果您刚创建了 xref 并想要给它一个流，首先执行 doc.update_object(xref, "<<>>")，然后使用此方法插入流数据。

该方法主要（但不是唯一）用于操作包含PDF操作符语法的流（参见Adobe PDF References的第643页），如页面内容流的情况。

如果你更新内容流，请考虑使用保存参数 clean=True 以确保PDF操作符源和对象结构之间的一致性。

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

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

v1.19.5中的新功能

仅限PDF：使target xref成为source的精确副本。如果source是一个stream，那么这些数据也会被复制。

Parameters:

source (int) – 源 xref。它必须是一个现有的字典对象。
target (int) – 目标 xref。必须是一个已存在的 dictionary 对象。如果 xref 刚刚被创建，请确保将其初始化为具有最小规范的 PDF 字典 <<>>。
keep (list) – 在准备复制过程中，target 中不应被移除的顶级键的可选列表。

注意

这个方法与Python的 dict 方法 copy() 有很多相似之处。
两个xref编号必须代表现有的字典。
在从 source 复制数据之前，所有 target 字典的键都会被删除。您可以在 keep 列表中指定例外。如果 source 中有同名键，其值仍然会替换目标。
如果 source 是一个 stream 对象，那么这些数据也将被复制过来，并且 target 将被转换为一个流对象。
一个典型的用例是替换或移除现有图像，而无需使用编辑注释。示例脚本可以在这里看到。

extract_image(xref)#

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

Parameters:

xref (int) – xref 的图像对象。如果这个值不在 range(1, doc.xref_length()) 中，或者对象不是图像或者发生其他错误，将返回 None，并且不会引发异常。

Return type:

字典

Returns:

具有以下键的字典

ext (str) 图像类型（例如 ‘jpeg’），可用作图像文件扩展名
smask (int) xref 模板图像（/SMask）的编号或零
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）。

Parameters:

xref (int) – 要提取的字体的PDF对象编号。
info_only (bool) – 仅返回字体信息，而不是缓冲区。用于仅获取信息的目的，避免分配大缓冲区。
named (bool) – 如果为真，则返回一个包含以下键的字典：‘name’（字体基本名称），‘ext’（字体文件扩展名），‘type’（字体类型），‘content’（字体文件内容）。

Return type:

元组,字典

Returns:

一个元组 (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 Fonts 和 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()

警告

从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：检查文档中是否存在链接或注释。

Returns:: 真 / 假。与字段不同，字段也存储在PDF文档的中心位置，链接/注释的存在只能通过解析每一页来检测。这些方法已进行了优化，以高效地完成此操作，并会立即返回，如果某一页的答案为真。然而，对于有数千页的PDF，如果没有找到链接或注释，答案可能需要一些时间[6]。

subset_fonts(verbose=False, fallback=False)#

仅限PDF：调查文本在文档中使用的合适字体。如果某种字体被支持并且可以减小尺寸，则该字体会被替换为其字符子集的版本。

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

Parameters:

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：返回当前操作的数字和总操作次数。

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

journal_op_name(step)#

v1.19.0中的新功能

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

journal_can_do()#

v1.19.0中的新功能

仅限PDF：显示从当前日志位置是否可以进行前向（“重做”）和/或后向（“撤销”）执行。

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

journal_undo()#

v1.19.0中的新功能

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

journal_redo()#

v1.19.0中的新功能

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

journal_save(filename)#

v1.19.0中的新功能

仅限PDF：将期刊保存到文件中。

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

journal_load(filename)#

v1.19.0中的新功能

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

Parameters:: filename (str,fp) – 期刊的文件名 (str) 或以“rb”模式打开的文件对象 (或一个 io.BytesIO() 对象)。

save_snapshot()#

v1.19.0中的新功能

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

这是一个没有任何使用限制的普通PDF文档。如果没有以任何方式更改，它可以与其期刊一起使用以撤销/重做操作或继续更新。

outline#

包含文档的第一个大纲项目（或 无）。可以作为遍历所有大纲项的起点。访问此属性时，如果文档是加密的且未经身份验证，将引发 AttributeError。

Type:: 大纲

is_closed#

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

Type:: 布尔值

is_dirty#

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

Type:: 布尔值

is_pdf#

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

Type:: 布尔值

is_form_pdf#

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

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

Type:: 布尔值，整数

is_reflowable#

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

Type:: 布尔值

is_repaired#

v1.18.2中的新功能

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

Type:: 布尔值

is_fast_webaccess#

v1.22.2 新特性

如果 PDF 是线性化格式则 为 true。 对于非 PDF 文档则为 false。

Type:: 布尔值

markinfo#

v1.22.2 新特性

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

Type:: 字典

pagemode#

v1.22.2 新特性

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

Type:: 字符串

pagelayout#

v1.22.2 新特性

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

Type:: 字符串

version_count#

v1.22.2 新特性

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

Type:: 整型

needs_pass#

指示文档是否受到密码保护以防止访问。此指示符保持不变 – 即使在文档已被验证后。如果为真，则不允许增量保存。

Type:: 布尔值

is_encrypted#

该指标最初等于 Document.needs_pass。在成功认证后，它被设置为 False 以反映情况。

Type:: 布尔值

permissions#

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

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

Type:: 整型

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’）。
加密要么包含 None（无加密），要么是一个指定加密方法的字符串（例如‘标准 V4 R4 128位 RC4’）。请注意，即使needs_pass=False，也可以指定加密方法。在这种情况下，可能并未授予所有权限。有关详细信息，请检查 Document.permissions。
如果日期字段包含有效数据（这完全不一定是情况！），它们是PDF特定时间戳格式“D:”中的字符串，其中
- 是12位字符的ISO时间戳 YYYYMMDDhhmmss (YYYY - 年, MM - 月, DD - 日, hh - 时, mm - 分, ss - 秒), 并且
- 是一个时区值（相对于GMT的时间间隔），包含一个符号（‘+’或‘-’）、小时（hh）和分钟（‘mm’，注意撇号！）。
一个巴拉圭的值可能看起来像 D:20150415131602-04’00’，它对应于2015年4月15日下午1:16:02的当地时间亚松森。

Type:: 字典

name#

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

Type:: 字符串

page_count#

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

Type:: 整型

chapter_count#

在v1.17.0中的新功能

包含文档中的章节数量。始终至少为 1。仅适用于具有章节支持的文档类型（目前为 EPUB）。其他文档将返回 1。

Type:: 整型

last_location#

v1.17.0中的新功能

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

Type:: 整型

FormFonts#

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

Type:: 列表

注意

对于改变 PDF 结构的方法（insert_pdf()、select()、copy_page()、delete_page() 等），请注意程序中的对象或属性可能会失效或变为孤立。例如，Page 对象及其子对象（链接、注释、小部件）、保存旧页数的变量、内容表等。请记得保持这些变量的最新状态或删除孤立的对象。另请参阅 Ensuring Consistency of Important Objects in 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)

脚注

Do you have any feedback on this page?

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

文档#

set_metadata() 示例#

set_toc() 演示#

insert_pdf() 示例#

其他示例#

`set_metadata()` 示例#

`set_toc()` 演示#

`insert_pdf()` 示例#