PyMuPDF 1.24.4 中文文档（七）（4）

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

返回类型：

字节

返回：

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

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 的。

参数：

• docsrc (Document) – 一个已打开的 PDF Document，不能是当前文档。但是，它可以引用相同的底层文件。
  
• from_page (int) – docsrc 中的第一页页码。默认为零。
  
• to_page (int) – 复制的docsrc中的最后一页页码。默认为最后一页。
  
• start_at (int) – 复制的第一页，将成为目标中的页码 start_at。默认值 -1 将页面范围追加到末尾。如果为零，则页面范围将插入到当前第一页之前。
  
• rotate (int) – 所有复制的页面将以提供的值旋转（度，90 的整数倍）。
  
• links (bool) – 选择是否包括链接（内部和外部）在复制中。默认为True。命名链接(LINK_NAMED)和指向超出复制页面范围的内部链接总是被排除在外。
  
• annots (bool) – (v1.16.1 新增) 选择是否在复制中包括注释。表单字段永远不会被复制 – 请参见下文。
  
• show_progress (int) – (v1.17.7 新增) 指定大于零的间隔大小以在sys.stdout上看到进度消息。在每个间隔之后，将打印类似Inserted 30 of 47 pages.的消息。
  
• final (int) – (v1.18.0 新增) 控制此方法后是否应删除已复制对象的列表，默认True。对于从同一源 PDF 中进行的多次插入中的最后一次，将其设置为 0。这可以节省目标文件大小，并显著加快执行速度。
  

注意

1. 这是一种基于页面的方法。因此，源文档的文档级信息将被忽略。示例包括可选内容、嵌入文件、StructureElem、AcroForm、目录、页面标签、元数据、命名目标（和其他命名条目）等。因此，具体地说，表单字段（小部件）永远不能被复制 – 尽管它们似乎只出现在页面上。查看Document.bake()以转换源文档，如果您至少需要保留小部件外观。
   
2. 如果from_page > to_page，页面将以相反的顺序复制。如果0 <= from_page == to_page，那么将复制一页。
   
3. docsrc TOC 条目不会被复制。然而，很容易为生成的文档恢复目录。查看下面的示例以及examples目录中的程序join.py：它可以连接 PDF 文档，并同时拼接目录的各个部分。
   

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

• v1.22.0 新增

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

参数：

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

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

仅限 PDF：插入空白页。

参数：

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

返回类型：

Page

返回：

创建的页面对象。

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

仅适用于 PDF：插入一个新页面并插入一些文本。这是一个方便函数，结合了 Document.new_page() 和（部分）Page.insert_text() 的功能。

参数：

pno（int）–

页面号（基于 0）之前要插入的位置。必须在 range(-1, doc.page_count + 1) 内。特殊值 -1 和 doc.page_count 在文档的最后一页之后插入。

自 v1.14.12 版本更改

此参数现在是位置参数。

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

返回类型：

int

返回：

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

delete_page(pno=-1)

仅适用于 PDF：按 0-based 页面号删除页面，范围为 -∞ < pno < page_count - 1。

• 自 v1.18.14 版本更改：支持 Python 的 del 语句。

参数：

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

delete_pages(*args, **kwds)

• 自 v1.18.13 版本更改：删除页面时具有更大的灵活性。
  
• 自 v1.18.14 版本更改：支持 Python 的 del 语句。
  

仅适用于 PDF：按 0-based 页面号删除多个页面。

格式 1： 使用关键字。表示旧格式。删除一段连续的页面。

• “from_page”: 要删除的第一页。如果省略，为零。
  
• “to_page”: 要删除的最后一页。如果省略，将删除文档中的最后一页。必须不小于 “from_page”。
  

格式 2： 作为位置参数的两个页面号。与格式 1 类似处理。

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

格式 4： 一种 list、tuple 或 range() 类型的位置参数，包含要删除的页面号。此序列的项目可以按任何顺序排列，并且可以包含重复项。

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

注意

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

还将删除剩余页面上指向已删除页面的任何链接。对于包含许多页面的文档，此操作可能需要较长的响应时间。

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

• doc.delete_pages(500, 519)
  
• doc.delete_pages(from_page=500, to_page=519)
  
• doc.delete_pages((500, 501, 502, ... , 519))
  
• doc.delete_pages(range(500, 520))
  
• del doc[500:520]
  
• del doc[(500, 501, 502, ... , 519)]
  
• del doc[range(500, 520)]
  

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

通常情况下，该方法的性能取决于剩余页面的数量，而不是删除页面的数量：在上述示例中，删除除了那 20 页之外的所有页面，需要的时间要少得多。

copy_page(pno, to=-1)

仅适用于 PDF：在文档内部复制页面引用。

参数：

• pno（int）- 要复制的页面。必须在0 <= pno < page_count范围内。
  
• to（int）- 要复制的页面号。默认情况下插入在最后一页之后。
  

注释

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

fullcopy_page(pno, to=-1)

• 新版本 v1.14.17 中新增

仅适用于 PDF：制作页面的完整副本（复制）。

参数：

• pno（int）- 要复制的页面。必须在0 <= pno < page_count范围内。
  
• to（int）- 要复制的页面号。默认情况下插入在最后一页之后。
  

注释

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

move_page(pno, to=-1)

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

参数：

• pno（int）- 要移动的页面。必须在0 <= pno < page_count范围内。
  
• to（int）- 要复制的页面前面的页码。默认情况下插入在最后一页之后。
  

need_appearances(value=None)

• 新版本 v1.17.4 中新增

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

参数：

value（bool）- 将属性设置为此值。如果省略或为None，则查询当前值。

返回类型：

布尔值

返回：

• None：不是表单 PDF，或未定义属性。
  
• True / False：属性的值（已设置或现有以进行查询）。如果没有表单 PDF，则没有影响。
  

get_sigflags()

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

返回类型：

int

返回：

• -1：不是表单 PDF/未记录签名字段/未找到SigFlags。
  
• 1：至少存在一个签名字段。
  
• 3：包含可能在文件被保存（写入）时使其前一内容发生变化而无效的签名。
  

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

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

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

参数：

• name (str) – 条目标识符，不得已经存在。
  
• buffer (bytes*,bytearray,*BytesIO) –
  文件内容。
  (在 v1.14.13 中更改) 现在也支持 io.BytesIO。
  
• filename (str) – 可选的文件名。仅供文档使用，如果为 None，将设置为name。
  
• ufilename (str) – 可选的 Unicode 文件名。仅供文档使用，如果为 None，将设置为filename。
  
• desc (str) – 可选的描述。仅供文档使用，如果为 None，将设置为name。
  

返回类型：

int

返回：

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

embfile_count()

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

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

embfile_get(item)

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

参数：

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

返回类型：

字节

embfile_del(item)

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

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

参数：

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

警告

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

embfile_info(item)

• 在 v1.18.13 中更改

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

参数：

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

返回类型：

字典

返回：

具有以下键的字典：

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

embfile_names()

• 在 v1.14.16 中新增

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

返回类型：

列表

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

仅限 PDF：根据其条目编号或名称更改嵌入文件。所有参数均为可选。让它们默认导致无操作。

参数：

• item（int/str）– 条目的索引或名称。整数必须在 range(embfile_count()) 内。
  
• buffer（bytes*,bytearray,*BytesIO）–
  新文件内容。
  （在 v1.14.13 中更改）io.BytesIO 现在也受支持。
  
• filename（str）– 新的文件名。
  
• ufilename（str）– 新的 Unicode 文件名。
  
• desc（str）– 新描述。
  

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

返回类型：

int

返回：

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

close()

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

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

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

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

参数：

• xref（int）– 对象的 xref。在 v1.18.10 中更改： 值为 -1 返回 PDF 尾部源。
  
• compressed（bool）– 是否生成没有换行或空格的紧凑输出。
  
• ascii（bool）– 是否对二进制数据进行 ASCII 编码。
  

返回类型：

str

返回：

对象定义源。

pdf_catalog()

• 新功能在 v1.16.8 中

仅限 PDF：返回 PDF 目录（或根）对象的 xref 编号。使用该编号与 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 流对象的 解压缩 内容。

参数：

xref（int）– xref 编号。

返回类型：

字节

返回：

（解压后的）对象流。

xref_stream_raw(xref)

• 新功能在 v1.16.8 中

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

返回类型：

字节

返回：

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

update_object(xref, obj_str, page=None)

• 新功能在 v1.16.8 中

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

参数：

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

返回类型：

int

返回：

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

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

• 新功能 v.1.16.8
  
• v1.19.2 中更改：添加参数 “compress”
  
• v1.19.6 中更改：不推荐参数 “new”。现在确认对象是 PDF 字典对象。
  

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

参数：

• xref（int） – xref 编号。
  
• stream（bytes|bytearray|BytesIO） –
  流的新内容。
  （v1.14.13 中更改：）io.BytesIO 对象现在也得到支持。
  
• new（bool） – 不推荐 和被忽略。将在 v1.20.0 之后删除。
  
• compress（bool） – 是否压缩插入的流。如果为 True（默认），则使用 /FlateDecode 压缩插入流（如果有利），否则按原样插入流。
  

抛出：

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

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

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

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

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

• 新功能 v1.19.5

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

参数：

• source（int） – 源 xref。必须是现有的 dictionary 对象。
  
• 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）呈现图像。

参数：

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

返回类型：

dict

返回：

具有以下键的字典

• 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 vs. 0.35 MB）：

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

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

• 在 v1.19.4 中更改：如果named == True，则返回一个字典。

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

参数：

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

返回类型：

tuple,dict

返回值：

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

• ("", "", "", b"") – 无效的 xref 或 xref 不是（有效的）字体对象。
  
• （basename，“n/a”，“Type1”，b“”） – basename未嵌入，因此无法提取。例如，这适用于 PDF Base 14 字体和 Type 3 字体。
  

示例：

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

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