Find #pymupdf on Discord

Tools

中文

该类是一个实用方法和属性的集合，主要用于内存管理。为了简化和加速其使用，当PyMuPDF被导入时，它会自动实例化为名为 TOOLS 的对象。

方法 / 属性	描述
Tools.gen_id()	生成唯一的标识符
Tools.store_shrink()	缩小存储缓存 [3]
Tools.mupdf_warnings()	返回累积的MuPDF警告
Tools.mupdf_display_errors()	控制是否将MuPDF错误作为消息显示
Tools.mupdf_display_warnings()	控制是否将MuPDF警告作为消息显示
Tools.reset_mupdf_warnings()	清空MuPDF警告/错误消息缓冲区
Tools.set_aa_level()	设置抗锯齿值
Tools.set_annot_stem()	设置新注释/链接ID的前缀
Tools.set_small_glyph_heights()	使用较小的bbox高度进行搜索和提取
Tools.set_subset_fontnames()	控制子集字体名标签的抑制
Tools.show_aa_level()	返回抗锯齿值
Tools.unset_quad_corrections()	禁用PyMuPDF特有的代码
Tools.fitz_config	PyMuPDF的配置设置
Tools.store_maxsize	最大存储缓存大小
Tools.store_size	当前存储缓存大小

类 API

class Tools

gen_id()

一个方便的方法，返回一个唯一的正整数，每次调用时该整数会增加1。示例用法包括在数据库中创建唯一的键——它的创建速度应比使用时间戳快一个数量级。

备注

MuPDF已在v1.14.0版本中不再支持此功能，因此我们重新实现了一个类似的函数，具有以下区别：

• 它不是MuPDF的全局上下文的一部分，也不是线程安全的（因为我们在PyMuPDF中不支持线程，所以这不是问题）。

• 它被实现为 int 类型。这意味着最大值为 sys.maxsize 。如果这个数字被超过，计数器将从1重新开始。

返回类型:

int

返回:

一个唯一的正整数。

set_annot_stem(stem=None)

• 新增于v1.18.6

设置或查询新注释、字段或链接ID的前缀。

参数:

stem (str) – 如果省略，则返回当前值，默认值为“fitz”。注释、字段/小部件和链接在PDF文档中实际上是同一类型对象(/Annot)的子类型。一个`/Annot`对象可以在页面中具有唯一的标识符。对于每种适用的子类型，PyMuPDF会生成“stem-Annn”、“stem-Wnnn”或“stem-Lnnn”的标识符，其中“nnn”用于强制要求唯一性。

返回类型:

str

返回:

当前值。

set_small_glyph_heights(on=None)

• 新增于v1.18.5

设置或查询文本提取和文本搜索方法中的缩小bbox高度。

参数:

on (bool) – 如果省略或为 None，则返回当前设置。对于其他值，将应用 bool() 函数来设置全局变量。如果为 True，则 Page.search_for() 和 Page.get_text() 方法返回的字符、跨度、行或块的bbox高度将是 字体大小 。如果为 False （PyMuPDF导入时的标准设置），则bbox高度将基于字体属性，并通常等于 行高 。

返回类型:

bool

返回:

True 或 False。

备注

文本提取选项“xml”、“xhtml”和“html”，这些直接封装了MuPDF代码，不受此设置的影响。

set_subset_fontnames(on=None)

• 新增于v1.18.9

控制在文本提取时是否抑制子集字体名称标签。

参数:

on (bool) – 如果省略或为 None ，则返回当前设置。将传入 True 或 False 值会设置全局变量。如果为 True ，选项”dict”、”json”、”rawdict”和”rawjson”将返回 "NOHSJV+Calibri-Light" ，否则将仅返回 "Calibri-Light" （默认值）。该设置会一直生效，直到再次更改。

返回类型:

bool

返回:

True 或 False。

备注

除上述提到的选项外，其他文本提取变体不受此设置的影响。特别是对于”xml”、”xhtml”和”html”选项，这些基于MuPDF代码的选项，会提取字体名称 "Calibri-Light" ，甚至只是 字体家族 名称——例如 Calibri 。

unset_quad_corrections(on=None)

• 新增于v1.18.10

启用/禁用PyMuPDF特有的代码，该代码在遇到 Page.get_text 文本提取中的无效字符四边形时，尝试重建有效的字符四边形。该代码依赖于某些字体属性（升高字形和下降字形），在某些罕见情况下，这些属性不存在，并且在尝试访问时会导致段错误。此方法设置PyMuPDF中的全局参数，抑制此代码的执行。

参数:

on (bool) – 如果省略或为 None ，则返回当前设置。对于其他值，将应用 bool() 函数来设置全局变量。如果为 True ，PyMuPDF将不尝试访问相应的字体属性，而是使用 ascender=0.8 和 descender=-0.2 作为默认值。

返回类型:

bool

返回:

True 或 False。

store_shrink(percent)

按当前大小的百分比减少存储缓存。

参数:

percent (int) – 要释放的当前大小的百分比。如果为100或更大，缓存将被清空；如果为零，则不做任何操作。MuPDF的缓存策略是“最近最少使用”，因此最少使用的元素将被优先删除。

返回类型:

int

返回:

新的当前存储大小。根据情况，减少的大小可能大于请求的百分比。

show_aa_level()

• 新增于v1.16.14

返回当前的抗锯齿值。这些值控制图形和文本元素的渲染质量。

返回类型:

dict

返回:

一个字典，初始内容为：{'graphics': 8, 'text': 8, 'graphics_min_line_width': 0.0}。

set_aa_level(level)

• 新增于v1.16.14

设置用于抗锯齿的位数。当前该值适用于图形和文本渲染。未来的MuPDF版本可能会有所不同。

参数:

level (int) – 一个介于0到8之间的整数。范围之外的值会被自动更改为有效值。该值将在当前会话期间或直到再次更改为止保持有效。

reset_mupdf_warnings()

• 新增于v1.16.0

清空MuPDF警告消息缓冲区。

mupdf_display_errors(value=None)

控制是否应将MuPDF错误显示为|PyMuPDF|消息。

参数:

value –

• 如果为 None ，当前设置保持不变。

• 否则更改当前设置为 bool(value) ；如果为 True ，未来的MuPDF错误将作为消息显示。

• 无论此设置如何，MuPDF错误总是会存储在警告存储区中。

• 在导入 PyMuPDF 时，该值默认为 True 。

返回:

当前设置为 True 或 False 。

• 新增于v1.16.8

mupdf_display_warnings(value=None)

控制是否应将MuPDF警告显示为|PyMuPDF|消息。

参数:

value –

• 如果为 None ，当前设置保持不变。

• 否则更改当前设置为 bool(value) ； 如果为 True ，未来的MuPDF警告将作为消息显示。

• 无论此设置如何，MuPDF警告总是会存储在警告存储区中。

• 在导入 PyMuPDF 时，该值默认为 True 。

返回:

当前设置为 True 或 False 。

• 新增于v1.16.8

mupdf_warnings(reset=True)

• 新增于v1.16.0

返回所有存储的MuPDF消息，格式为字符串并带有换行符。

参数:

reset (bool) – (v1.16.7中新功能) 是否自动清空存储区。

fitz_config

一个字典，包含用于配置PyMuPDF和MuPDF的实际值。也请参考安装章节。以下是各个键的概述，每个键描述了某个支持方面的状态。

键	支持的内容
plotter-g	灰度颜色空间渲染
plotter-rgb	RGB颜色空间渲染
plotter-cmyk	CMYK颜色空间渲染
plotter-n	覆印渲染
pdf	PDF文档
xps	XPS文档
svg	SVG文档
cbz	CBZ文档
img	IMG文档
html	HTML文档
epub	EPUB文档
jpx	JPEG2000图像
js	JavaScript
tofu	所有TOFU字体
tofu-cjk	CJK字体子集（中国、日本、韩国）
tofu-cjk-ext	CJK字体扩展
tofu-cjk-lang	CJK字体语言扩展
tofu-emoji	TOFU表情符号字体
tofu-historic	TOFU历史字体
tofu-symbol	TOFU符号字体
tofu-sil	TOFU SIL字体
icc	ICC色彩配置文件
py-memory	使用Python内存管理 [4]
base14	基础14字体（应始终为True）

关于“TOFU”一词的解释，请参阅 此维基百科条目

In [1]: import pymupdf
In [2]: TOOLS.fitz_config
Out[2]:
{'plotter-g': True,
'plotter-rgb': True,
'plotter-cmyk': True,
'plotter-n': True,
'pdf': True,
'xps': True,
'svg': True,
'cbz': True,
'img': True,
'html': True,
'epub': True,
'jpx': True,
'js': True,
'tofu': False,
'tofu-cjk': True,
'tofu-cjk-ext': False,
'tofu-cjk-lang': False,
'tofu-emoji': False,
'tofu-historic': False,
'tofu-symbol': False,
'tofu-sil': False,
'icc': True,
'py-memory': False,
'base14': True}

返回类型:

dict

store_maxsize

存储缓存的最大大小，以字节为单位。 PyMuPDF 默认值为 268’435’456（256 MB），因此您应始终看到这个值。如果该值为零，则允许“无限制”增长。

返回类型:

int

store_size

当前存储缓存的大小，以字节为单位。此值可能会随每次使用 PyMuPDF 函数而变化（通常会增加）。只有当超出 Tools.store_maxsize 时，这个值才会（自动）减少：在这种情况下， MuPDF 将逐出低使用率的对象，直到值重新回到正常范围。

返回类型:

int

英文

This class is a collection of utility methods and attributes, mainly around memory management. To simplify and speed up its use, it is automatically instantiated under the name TOOLS when PyMuPDF is imported.

Method / Attribute	Description
Tools.gen_id()	generate a unique identifier
Tools.store_shrink()	shrink the storables cache [1]
Tools.mupdf_warnings()	return the accumulated MuPDF warnings
Tools.mupdf_display_errors()	control whether MuPDF errors are displayed as messages.
Tools.mupdf_display_warnings()	control whether MuPDF warnings are displayed as messages.
Tools.reset_mupdf_warnings()	empty MuPDF warnings/errors message buffer.
Tools.set_aa_level()	set the anti-aliasing values
Tools.set_annot_stem()	set the prefix of new annotation / link ids
Tools.set_small_glyph_heights()	search and extract using small bbox heights
Tools.set_subset_fontnames()	control suppression of subset fontname tags
Tools.show_aa_level()	return the anti-aliasing values
Tools.unset_quad_corrections()	disable PyMuPDF-specific code
Tools.fitz_config	configuration settings of PyMuPDF
Tools.store_maxsize	maximum storables cache size
Tools.store_size	current storables cache size

Class API

Example Session

Example Session

中文

>>> import pymupdf
# 打印最大和当前缓存大小
>>> pymupdf.TOOLS.store_maxsize
268435456
>>> pymupdf.TOOLS.store_size
0
>>> doc = pymupdf.open("demo1.pdf")
# 创建pixmap会将许多对象放入缓存（文本、图像、字体），
# 除了pixmap本身
>>> pix = doc[0].get_pixmap(alpha=False)
>>> pymupdf.TOOLS.store_size
454519
# 释放（至少）50%的存储空间
>>> pymupdf.TOOLS.store_shrink(50)
13471
>>> pymupdf.TOOLS.store_size
13471
# 获取几个唯一的编号
>>> pymupdf.TOOLS.gen_id()
1
>>> pymupdf.TOOLS.gen_id()
2
>>> pymupdf.TOOLS.gen_id()
3
# 关闭文档并查看仍然使用的缓存量
>>> doc.close()
>>> pymupdf.TOOLS.store_size
0

英文

>>> import pymupdf
# print the maximum and current cache sizes
>>> pymupdf.TOOLS.store_maxsize
268435456
>>> pymupdf.TOOLS.store_size
0
>>> doc = pymupdf.open("demo1.pdf")
# pixmap creation puts lots of object in cache (text, images, fonts),
# apart from the pixmap itself
>>> pix = doc[0].get_pixmap(alpha=False)
>>> pymupdf.TOOLS.store_size
454519
# release (at least) 50% of the storage
>>> pymupdf.TOOLS.store_shrink(50)
13471
>>> pymupdf.TOOLS.store_size
13471
# get a few unique numbers
>>> pymupdf.TOOLS.gen_id()
1
>>> pymupdf.TOOLS.gen_id()
2
>>> pymupdf.TOOLS.gen_id()
3
# close document and see how much cache is still in use
>>> doc.close()
>>> pymupdf.TOOLS.store_size
0
>>>

Footnotes

[1]

This memory area is internally used by MuPDF, and it serves as a cache for objects that have already been read and interpreted, thus improving performance. The most bulky object types are images and also fonts. When an application starts up the MuPDF library (in our case this happens as part of import pymupdf), it must specify a maximum size for this area. PyMuPDF’s uses the default value (256 MB) to limit memory consumption. Use the methods here to control or investigate store usage. For example: even after a document has been closed and all related objects have been deleted, the store usage may still not drop down to zero. So you might want to enforce that before opening another document.

[2]

By default PyMuPDF and MuPDF use malloc()/free() for dynamic memory management. One can instead force them to use the Python allocation functions PyMem_New()/PyMem_Del(), by modifying fitz/fitz.i to do #define JM_MEMORY 1 and rebuilding PyMuPDF.

[3]

该内存区域是MuPDF内部使用的，用作已经读取和解释的对象的缓存，从而提高性能。最大的对象类型是图像和字体。当应用程序启动MuPDF库时（在我们的案例中，这发生在 import pymupdf 过程中），它必须指定该区域的最大大小。PyMuPDF使用默认值（256 MB）来限制内存消耗。使用这里的方法可以控制或调查存储使用情况。例如：即使文档已经关闭并且所有相关对象都已删除，存储使用情况仍然可能不会降到零。因此，您可能希望在打开另一个文档之前强制执行此操作。

[4]

默认情况下，PyMuPDF和MuPDF使用 malloc()/free() 进行动态内存管理。可以通过修改 fitz/fitz.i 文件，将 #define JM_MEMORY 1 并重新构建PyMuPDF，强制它们使用Python的分配函数 PyMem_New()/PyMem_Del()。

您对此页面有任何反馈吗？

---

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

This documentation covers all versions up to 1.25.4.