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参数值，转换后的对象定义将被压缩，这可能导致文件大小显著减小。
  

警告

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

注意

文件大小减小

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

1. 实质上的“有损”文件大小减小必须放弃某些与图像相关的东西，比如（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 中更改) 以支持扩展的加密支持。

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