PyMuPDF 1.24.4 中文文档（七）（3）-阿里云开发者社区

PyMuPDF 1.24.4 中文文档（七）（2）https://developer.aliyun.com/article/1559545

参数：

simple（bool）– 指示是否需要简单或详细的 TOC。如果为False，则列表的每个项目还包含用于每个大纲条目的 linkDest 详细信息的字典。

返回类型：

list

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

lvl – 层次级别（正整数）。第一个条目始终为 1。连续条目要么相等，要么递增 1，要么以任何数字递减。
title – 标题（str）
page – 基于 1 的源页面编号（int）。如果没有目标或在文档外部，则为-1。
dest – （dict）仅在simple=False时包含。包含如下 TOC 条目的详细信息：

kind：目标类型，参见链接目标类型。
文件：如果 kind 为LINK_GOTOR 或 LINK_LAUNCH，则为文件名。
page：目标页面，基于 0，LINK_GOTOR 或 LINK_GOTO。
to：目标页面上的位置（Point）。
缩放：目标页面上的缩放因子（float）。
xref：项目的xref（如果无 PDF，则为 0）。
颜色：PDF RGB 格式中的项目颜色(red, green, blue)，或省略（如果没有 PDF 则始终省略）。
粗体：如果为粗体项目文本或省略，则为 true。仅适用于 PDF。
斜体：如果为斜体项目文本，则为 true，或省略。仅适用于 PDF。
collapse：如果子项目折叠，则为 true，或省略。仅适用于 PDF。
nameddest：如果 kind=4，则为目标名称。仅适用于 PDF。（1.23.7 新增。）

xref_get_keys(xref)

v1.18.7 新增内容

仅适用于 PDF：返回xref所提供的dictionary对象的 PDF 字典键。

参数：

xref（int）– 项目的xref。(v1.18.10 中更改) 使用-1访问特殊字典“PDF 尾部”。

dictionary对象的 PDF 字典键的返回类型和值。

>>> 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 (int) – xref。在 v1.18.10 中更改： 使用 -1 来访问特殊字典 “PDF 尾页”。
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” 可能在文件中具有值 “”，但该方法将返回 ('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 新增，v 1.18.13 中更改
在 v1.19.4 中更改：如果设置为 “null”，则“物理”删除一个键。

仅限于 PDF：为其 xref 指定的 dictionary 对象的键设置（添加，更新，删除）其值。

注意

这是一个专家功能：如果您不知道自己在做什么，可能会导致（部分）PDF 无法使用。请参阅 Adobe PDF References，了解对象规范格式（第 18 页）和特殊字典类型（如页面对象）的结构。

参数：

xref (int) – xref。在 v1.18.13 中更改： 要更新 PDF 尾页，指定 -1。
key (str) – 所需的 PDF 键（无前导 “/”）。必须不为空。任何有效的 PDF 键 – 无论已存在于对象中（将被覆盖） – 或新键。可以使用类似 "Resources/ExtGState" 的 PDF 路径表示法，这会将键 "/ExtGState" 的值设置为 "/Resources" 的子对象。
value (str) – 键的值。必须是非空字符串，并且根据所需的 PDF 对象类型必须遵守以下规则。有一些语法检查，但 没有类型检查 和 PDF 方面的 语义检查。大小写很重要！
xref – 必须提供为 "nnn 0 R"，带有 PDF 的有效 xref 编号 nnn。后缀 “0 R” 是 PDF 应用程序能够识别 xref 的必要标识符。
array – 像"[a b c d e f]"这样的字符串。括号是必需的。数组项必须至少用一个空格分隔（不像 Python 中的逗号）。空数组"[]"是可能的，并且等效于移除该键。数组项可以是任何 PDF 对象，如字典、xrefs、其他数组等。与 Python 类似，数组项可以是不同类型的。
dict – 像"<< ... >>"这样的字符串。括号是必需的，必须包含有效的 PDF 字典定义。空字典"<<>>"是可能的，并且等效于移除该键。
int – 作为字符串格式化的整数。
float – 作为字符串格式化的浮点数。PDF 不允许使用科学计数法（带有指数）。
null – 字符串"null"。这是 PDF 中类似于 Python 的None，会导致键被忽略 – 不过不一定在保存时移除，或在垃圾收集时移除。*在 v1.19.4 中更改：*如果键不是路径层次结构（即不包含斜杠“/”），则将完全删除该键。
bool – 字符串之一"true"或"false"。
name – 带有前导斜杠的有效 PDF 名称，例如"/PageLayout"。参见 Adobe PDF 参考手册第 16 页。
string – 有效的 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页（从零开始）创建一个位图。调用Page.get_pixmap()。

除了pno之外的所有参数都是仅限关键字的。

参数：

pno (int) – 页面编号，在-∞ < pno < page_count中为基于零的。

返回类型：

Pixmap

get_page_xobjects(pno)

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

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

参数：

pno (int) – 页面编号，从 0 开始，-∞ < pno < page_count。

返回类型：

列表

一个（非图像）XObject 列表。这些对象通常代表从其他 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：返回页面直接或间接引用的所有图像列表。

参数：

pno（int） - 页面编号，从 0 开始，-∞ < pno < page_count。
full（bool） - 是否还包括引用者的xref（如果这是页面，则为零）。

返回类型：

列表

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

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

在哪里

xref（int）是图像对象编号。

smask（int）是其软蒙版图像的对象编号。

width和height（ints）是图像的尺寸。

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

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

alt. colorspace（str）是依赖于colorspace值的任何备选颜色空间。

name（str）是引用图像的符号名称。

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

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

注意

一般而言，这不是实际显示的图像列表。此方法仅解析几个 PDF 对象以收集对嵌入图像的引用。它不分析页面的contents，其中定义了所有实际图像显示命令。要获取此信息，请使用Page.get_image_info()。还请参阅 textpage.html#textpagedict 部分中的字典输出结构讨论。

get_page_fonts(pno, full=False)

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

参数：

pno（int） - 页面编号，从 0 开始，-∞ < pno < page_count。
full（bool） - 是否还包括引用者的xref。如果True，返回的条目将再多一个条目。如果需要知道页面是否直接引用字体，请使用此选项。在这种情况下，最后一个条目为 0。如果字体由页面的/XObject 引用，则在这里找到其xref。

返回类型：

列表

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

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

在哪里

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

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

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

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

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

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

referencer (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()。

参数：

pno (int) – 页面号码，从零开始，任何值 -∞ < pno < page_count。

对于其他参数，请参阅页面方法。

返回类型：

str

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

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

参数：

rect (rect_like) – 所需的页面尺寸。必须是有限的，不为空，并从点 (0, 0) 开始。
width (float) – 与 height 一起使用，作为 rect 的替代。
height (float) – 与 width 一起使用，作为 rect 的替代。
fontsize (float) – 所需的默认字体大小。

select(s)

仅适用于 PDF：保留文档中指定页码的页面。空序列或超出 range(doc.page_count) 范围的元素将引发 ValueError。更多详细信息请参见本章末尾或本章说明。

参数：

s (sequence) – 页面号码序列（从零开始），要包含的页面。不在序列中的页面将被删除（从内存中），并在文档重新打开之前不可用。**页面号码可以多次出现且顺序任意：**生成的文档将完全按指定的序列排列。

注意

序列中的页面号码不需要唯一，也不需要特定顺序。这使得该方法成为一个多功能实用工具，例如仅选择偶数页或奇数页，或满足其他某些条件等。
在技术层面上，该方法始终会创建一个新的 pagetree。
当处理少量页面时，方法 copy_page()、move_page()、delete_page() 更易于使用。事实上，它们也快得多-当文档有许多页面时，至少快一个数量级。

set_metadata(m)

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

参数：

m (dict) – 与 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 (dict) – 一个像这样的字典：{"Marked": False, "UserProperties": False, "Suspects": False}。该字典包含有关标记 PDF 约定使用情况的信息。详情请参阅 PDF 规范。

set_toc(toc, collapse=1)

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

第一步删除所有现有的书签。
第二步从 toc 中包含的条目创建新的目录。

参数：

toc (sequence) –包含所有书签条目的列表/元组，这些条目应形成新的目录。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。

返回类型：

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。这主要用于内部目的。

参数 int idx：列表Document.get_toc()中项目的索引。

xref。

del_toc_item(idx)

从 v1.17.7 开始新增
从 v1.18.14 开始更改：不再删除项目的文本，而是显示为灰色。

仅 PDF：删除此 TOC 项。这是一种高速方法，禁用了相应的项目，但保留了整体的 TOC 结构。在物理上，项目仍然存在于 TOC 树中，但以灰色显示，并且不再指向任何目标。

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

参数：

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：更改由其索引标识的 TOC 条目。更改条目的标题、目标、外观（颜色、粗体、斜体）或折叠子项，或者完全删除该项。

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

参数：

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 操作必需的参数。
title (str) – 所需的新标题。如果不更改，则为 None。
to (point_like) – （可选）指向目标页面上的坐标。对 LINK_GOTO 操作相关。如果省略，则选择靠近页面顶部的点。
filename (str) – LINK_GOTOR 和 LINK_LAUNCH 操作所需的文件名。
zoom (float) – 在显示目标页面时使用的缩放因子。

示例用法： 更改 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 转换的一个可行替代方法。

请考虑注释是复杂对象，可能由更多“底层”数据组成。例如，“Text”和“FileAttachment”注释。使用此方法“烘烤”注释/小部件时，所有这些底层信息（附加文件、评论、相关弹出式注释等）将在下次垃圾收集时丢失并被删除。

比如，用于 Document.insert_pdf() 方法（不支持复制小部件）或 Page.show_pdf_page() 方法（不支持注释和小部件），源页面在目标页面中应该完全一样时使用此功能。

参数：

annots (bool) – 转换注释。
widgets (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 产品中类似“Sanitize”功能的启发。该过程可通过多个选项进行配置。

参数：

attached_files (bool) – 查找“FileAttachment”注释并删除文件内容。
clean_pages (bool) – 从页面绘画源中删除任何注释。如果此选项设置为 False，那么对于 hidden_text 和 redactions 也会执行相同操作。
embedded_files (bool) – 删除嵌入文件。
hidden_text (bool) – 删除 OCR 文本和不可见文本[7]。
javascript (bool) – 删除 JavaScript 源代码。
metadata (bool) – 删除 PDF 标准元数据。
redactions (bool) – 应用删除注释。
redact_images (int) – 如果应用删除操作，处理图像的方法。可选值为 0（忽略）、1（覆盖重叠区域）或 2（删除）。
remove_links (bool) – 删除所有链接。
reset_fields (bool) – 将所有表单字段重置为默认值。
reset_responses (bool) – 从所有注释中删除所有响应。
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() 下的 getvalue() 输出，这相当于内部创建的 io.BytesIO() 的 getvalue()。
garbage (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 新增) 压缩未压缩的图像流。
deflate_fonts (bool) – (自 v1.18.3 新增) 压缩未压缩的字体文件流。
incremental (bool) – 仅保存 PDF 的更改。排除“垃圾”和“线性”。只能在outfile是字符串或pathlib.Path且等于Document.name时使用。不能用于已解密或修复的文件以及其他一些情况。请确认 Document.can_save_incrementally() 如果为假，则需要保存到新文件。
ascii (bool) – 将二进制数据转换为 ASCII。
expand (int) –解压对象。生成可以被其他程序更好读取的版本，从而导致更大的文件。

0 = 无
1 = 图像
2 = 字体
255 = 全部

linear (bool) – 保存文档的线性化版本。此选项创建了一个针对 Internet 访问性能改进的文件格式。排除“增量”选项。
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参数值，转换后的对象定义将被压缩，这可能导致文件大小显著减小。

警告

该方法不检查是否已存在同名文件，因此不会请求确认并覆盖文件。这是程序员处理的责任。

注意

文件大小减小

实质上的“有损”文件大小减小必须放弃某些与图像相关的东西，比如（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)