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

原文：https://pymupdf.readthedocs.io/en/latest/

存档

原文：pymupdf.readthedocs.io/en/latest/archive-class.html

• v1.21.0 版新增内容

此类表示文件夹和容器文件（如 ZIP 和 TAR 存档）的泛化。存档允许像它们都是一个文件夹层次结构树的一部分一样访问任意文件夹集合、ZIP/TAR 文件和单个二进制数据元素。

在 PyMuPDF 中，存档目前仅被 Story 对象使用，用于指定查找字体、图像和其他资源的位置。

类 API

class Archive

__init__(self[, content[, path]])

创建一个新的存档。如果没有参数，则创建一个空存档。

如果提供，content可以是以下之一：

• 另一个存档：将该存档作为新存档的子存档。
  
• 一个字符串：这必须是本地文件夹或文件的名称。同时支持pathlib.Path对象。

• 一个文件夹将被转换为子存档，因此可以通过它们的名称访问其文件（以及任何子文件夹）。
• 
  
• 以"rb"模式读取一个文件，这些二进制数据（一个bytes对象）将被视为单一成员子存档。在这种情况下，path参数是强制性的，并且应该是可以找到/检索此项的成员名称。

• 一个zipfile.ZipFile或tarfile.TarFile对象：将被添加为子存档。
  
• 一个 Python 二进制对象（bytes，bytearray，io.BytesIO）：这将添加一个单一成员子存档。在这种情况下，path参数是强制性的，并且应该是可以找到/检索此项的成员名称。
  
• 一个元组(data, name)：这将添加一个成员名称为name的单一成员子存档。data可以是 Python 二进制对象或本地文件名（在这种情况下，其二进制文件内容将被使用）。如果需要指定path，请使用此格式。
  
• 一个 Python 序列：这是一种方便的格式，用于指定上述任何组合。
  

如果提供，path必须是一个字符串。

• 如果content是二进制数据或文件名，则此参数是强制性的，并且必须是数据可被找到的名称。
  
• 否则，此参数是可选的。它可用于模拟文件夹名称或挂载点，在此子存档的元素下可以找到。例如，此规范 Archive((data, "name"), "path") 意味着 data 将通过元素名称 "path/name" 找到。其他子存档也是如此：要检索 ZIP 子存档的成员，它们的名称必须以 "path/" 为前缀。此参数的主要目的可能是区分重复名称。
  

注意

如果存档中存在重复的条目名称，则始终会找到/检索到该名称的最后一个条目。在创建存档或向存档追加更多数据时（参见 Archive.add()），不会检查重复项。使用 path 参数可以防止这种情况发生。

add(content[, path])

添加一个子存档。参数的含义与上述解释完全相同。当然，在这里 content 参数是不可选的。

has_entry(name)

检查条目是否存在于任何子存档中。

参数：

name (str) – 条目的完全限定名称。因此，必须包括添加了条目的子存档的任何 path 前缀。

返回：

True 或 False。

read_entry(name)

检索条目的数据。

参数：

name (str) – 条目的完全限定名称。因此，必须包括添加了条目的子存档的任何 path 前缀。

返回：

条目的二进制数据 (bytes)。如果未找到，将会引发异常。

entry_list

存档的子存档列表。每个列表项都是具有以下键的字典：

• entries – 此子存档中顶层条目名称的列表。
  
• fmt – 子存档的格式。这是字符串之一：“dir”（文件夹），“zip”（ZIP 存档），“tar”（TAR 存档），或“tree”用于单个二进制条目或文件内容。
  
• path – 此子存档添加时path参数的值。
  

示例：

>>> from pprint import pprint
>>> import pymupdf
>>> dir1 = "fitz-32"  # a folder name
>>> dir2 = "fitz-64"  # a folder name
>>> img = ("nur-ruhig.jpg", "img")  # an image file
>>> members = (dir1, img, dir2)  # we want to append these in one go
>>> arch = pymupdf.Archive()
>>> arch.add(members, path="mypath")
>>> pprint(arch.entry_list)
[{'entries': ['310', '37', '38', '39'], 'fmt': 'dir', 'path': 'mypath'},
{'entries': ['img'], 'fmt': 'tree', 'path': 'mypath'},
{'entries': ['310', '311', '37', '38', '39', 'pypy'],
'fmt': 'dir',
'path': 'mypath'}]
>>> 

对此页面有任何反馈吗？

此软件按原样提供，不附带任何明示或暗示的保证。此软件在许可下分发，并且除非根据该许可的条款明确授权，否则不得复制、修改或分发。有关详细信息，请参阅 artifex.com 的许可信息或联系位于美国加利福尼亚州旧金山市 Mesa 街 39 号 108A 室的 Artifex Software Inc.。

此文档涵盖所有版本直到 1.24.4。

颜色空间

原文：pymupdf.readthedocs.io/en/latest/colorspace.html

表示一个 Pixmap 的颜色空间。

类 API

class Colorspace

__init__(self, n)

构造函数

参数：

n (int) – 标识颜色空间的数字。可能的值为CS_RGB、CS_GRAY和CS_CMYK。

nam

标识颜色空间的名称。例如：pymupdf.csCMYK.name = ‘DeviceCMYK’。

类型：

str

n

定义一个像素的颜色所需的字节数。例如：pymupdf.csCMYK.n == 4。

类型：

int

预定义的颜色空间

为了节省输入，已存在三种可用情况的预定义颜色空间对象。

• csRGB = pymupdf.Colorspace(pymupdf.CS_RGB)
  
• csGRAY = pymupdf.Colorspace(pymupdf.CS_GRAY)
  
• csCMYK = pymupdf.Colorspace(pymupdf.CS_CMYK)
  

对这个页面有任何反馈吗？

此软件按原样提供，不带任何明示或暗示的担保。此软件根据许可分发，并且未经授权不得复制、修改或分发。请参阅artifex.com的许可信息或联系 Artifex Software Inc.，39 Mesa Street，Suite 108A，San Francisco CA 94129，美国获取更多信息。

此文档涵盖了所有版本，直到 1.24.4。

DisplayList

原文：pymupdf.readthedocs.io/en/latest/displaylist.html

DisplayList 是一个包含绘图命令（文本、图像等）的列表。其目的是双重的：

1. 作为减少页面解析的缓存机制
   
2. 作为多线程设置中的数据结构，其中一个线程解析页面，另一个线程呈现页面。PyMuPDF 当前不支持这个方面。
   

显示列表由页面中的对象填充，通常通过执行Page.get_displaylist()来执行。还存在一个独立的构造函数。

通过调用其方法之一 run(), get_pixmap() 或 get_textpage() 来“重放”列表（一次或多次）。

类 API

class DisplayList

__init__(self, mediabox)

创建一个新的显示列表。

参数：

mediabox (矩形) – 页面的矩形。

返回类型：

DisplayList

run(device, matrix, area)

通过设备运行显示列表。设备将用其“命令”（即文本提取或图像创建）填充显示列表。显示列表以后可以多次“读取”页面，而无需重新从文档文件解释它。

您最有可能使用以下专门的运行方法之一 – get_pixmap() 或 get_textpage()。

参数：

• device (设备) – 设备
  
• matrix (矩阵) – 用于应用于显示列表内容的转换矩阵。
  
• area (矩形) – 仅在此区域内可见的部分将在运行设备时被考虑。
  

get_pixmap(matrix=pymupdf.Identity, colorspace=pymupdf.csRGB, alpha=0, clip=None)

通过绘制设备运行显示列表并返回像素图。

参数：

• matrix (矩阵) – 要使用的矩阵。默认为单位矩阵。
  
• colorspace (色彩空间) – 所需的色彩空间。默认为 RGB。
  
• alpha (int) – 确定是否（0，默认）包含透明通道。
  
• clip (irect_like) – 限制渲染到此区域与DisplayList.rect的交集。
  

返回类型：

Pixmap

返回：

显示列表的像素图。

get_textpage(flags)

通过文本设备运行显示列表并返回文本页。

参数：

flags（int）– 控制将哪些信息解析为文本页。PyMuPDF 中的默认值为 3 = TEXT_PRESERVE_LIGATURES | TEXT_PRESERVE_WHITESPACE，即 ligatures 保留，空白字符保留（不转换为空格），且不包括图像。参见 Text Extraction Flags。

返回类型：

TextPage

返回：

显示列表的文本页。

rect

包含显示列表的媒体框。如果通过 Page.get_displaylist() 创建，则与页面的矩形相等。

类型：

Rect

对此页面有任何反馈吗？

本软件按原样提供，不附带任何明示或暗示的担保。此软件根据许可证分发，未经授权不得复制、修改或分发。请参阅 artifex.com 上的许可信息或联系美国加利福尼亚州旧金山 Mesa Street 39 号 108A 套房的 Artifex Software Inc. 获取更多信息。

此文档涵盖所有版本直到 1.24.4。

文档

原文：pymupdf.readthedocs.io/en/latest/document.html

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

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

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

注意

从 v1.17.0 开始，仅支持EPUB 文件的新页面寻址机制。此文档类型在内部组织为章节，因此可以通过其所谓的“位置”最有效地找到页面。位置是一个由章节号和该章节中的页号组成的元组*(chapter, pno)*，两个数字都是从零开始计数的。

尽管仍然可以通过（绝对）页码定位页面，但这样做可能意味着必须在地址页面之前对完整的 EPUB 文档进行布局。如果文档非常庞大，这可能会对性能产生显著影响。使用页面的*(章节，页号)*可以避免这种情况发生。

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

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

类 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”。空文件和内存区域将始终导致异常。
  

创建一个Document对象。

• 默认参数下，将创建一个新的空白 PDF文档。
  
• 如果提供了stream，则文档将从内存中创建，如果不是 PDF，则filename或filetype必须指示其类型。
  
• 如果stream为None，则文档将从filename指定的文件创建。其类型将根据扩展名推断。可以通过filetype覆盖此行为。
  

参数：

• filename (str*,*pathlib) – 包含文件路径的 UTF-8 字符串或pathlib对象。文档类型将根据文件名扩展名推断。如果不存在或不匹配支持的类型，则假定为 PDF 文档。对于内存文档，可以使用此参数代替filetype，请参见下文。
  
• stream (bytes*,bytearray,*BytesIO) – 包含支持的文档的内存区域。如果不是 PDF，必须通过filename或filetype指定其类型。
  
• filetype (str) – 指定文档类型的字符串。这可以是类似文件名的任何内容（例如“x.pdf”），在这种情况下，MuPDF 使用扩展名确定类型，或者像application/pdf这样的 MIME 类型。只需使用像“pdf”或“.pdf”这样的字符串也可以。对于 PDF 文档，可以省略，否则必须匹配支持的文档类型。
  
• rect (rect_like) – 指定所需页面大小的矩形。此参数仅适用于具有可变页面布局（“可重排”文档），如电子书或 HTML，并且在其他情况下将被忽略。如果指定，它必须是一个非空的有限矩形，其左上坐标为 (0, 0)。与参数 fontsize 一起，每个页面将相应地布局，并因此确定页数。
  
• width (float) – 可与 height 一起用作 rect 的替代，以指定布局信息。
  
• height (float) – 可与 width 一起用作 rect 的替代，以指定布局信息。
  
• fontsize (float) – 可重排文档类型的默认字体大小。如果未指定 rect 或 width 和 height 中的任何一个参数，则此参数将被忽略。将用于计算页面布局。
  

引发：

• TypeError – 如果任何参数的类型不符合规范。
  
• FileNotFoundError – 如果找不到文件/路径。重新实现为RuntimeError的子类。
  
• EmptyFileError – 如果文件/路径为空或内存中的bytes对象长度为零。是FileDataError和RuntimeError的子类。
  
• ValueError – 如果显式指定未知文件类型。
  
• FileDataError – 如果文档对于给定类型具有无效结构 – 或根本不是文件（而是例如文件夹）。是RuntimeError的子类。
  

返回：

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

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

注意

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

• HTM，HTML，XHTML：始终打开，metadata["format"] 为“HTML5”，或“XHTML”。
  
• XML，FB2：始终打开，metadata["format"] 为“FictionBook2”。
  

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

>>> # 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 将确定正确的图像类型。因此，即使对于 PNG 图像，pymupdf.open("file.jpg")也能正常工作。

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 中的新内容

返回图像或表单 X 对象附加的OCG或OCMD的交叉引用号。

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