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

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

记录

原文：pymupdf.readthedocs.io/en/latest/recipes-journalling.html

从版本 1.19.0 开始，可以在更新 PDF 文档时记录日志。

记录是一种允许在 PDF 中回滚或重新应用更改的日志记录机制。类似于现代数据库系统中的 LUW“逻辑工作单元”，可以将一组更新分组成一个“操作”。在 MuPDF 记录中，操作扮演着 LUW 的角色。

注意

与数据库系统中找到的 LUW 实现相比，MuPDF 记录发生在每个文档级别上。不支持跨多个 PDF 同时更新：必须在此处建立自己的逻辑。

必须通过文档方法启用记录。可以为现有或新文档记录。只能通过关闭文件来禁用记录。
一旦启用，每个更改必须发生在一个操作内 —— 否则会引发异常。通过文档方法启动和停止操作。在这两次调用之间发生的更新形成一个 LUW，因此可以集体回滚或重新应用，或者用 MuPDF 术语来说是“撤销”或“重做”。
在任何时候，都可以查询记录状态：记录是否活动，已记录多少操作，是否可能“撤消”或“重做”，日志中的当前位置等。
日志可以保存到或从文件加载。这些是文档方法。
加载日志文件时，会检查与文档的兼容性，并在成功时自动启用日志记录。
对于正在记录日志的现有 PDF，提供了一种特殊的新保存方法：Document.save_snapshot()。这执行特殊的增量保存，包括到目前为止的所有记录更新。如果同时保存其日志（在文档快照之后立即进行），则文档和日志将同步，以便随后可以一起用于撤消或重做操作或继续记录的更新 —— 就像没有中断一样。
快照 PDF 在各方面都是有效的 PDF，完全可用。但是，如果在没有使用其日志文件的情况下以任何方式更改文档，则会发生失同步，日志将变得无法使用。
快照文件的结构类似增量更新。然而，内部记录日志的逻辑要求，保存必须发生到一个新文件中。因此，用户应该开发文件命名约定，以支持原始 PDF（如 original.pdf）与其快照集之间的可识别关系，如 original-snap1.pdf / original-snap1.log、original-snap2.pdf / original-snap2.log 等。

会话示例 1

描述：

制作一个新的 PDF 并启用记录。然后添加一个页面和一些文本行 —— 每个作为单独的操作。
在日志中导航，撤消和重做这些更新，并显示状态和文件结果：

>>> import pymupdf
>>> doc=pymupdf.open()
>>> doc.journal_enable()
>>> # try update without an operation:
>>> page = doc.new_page()
mupdf: No journalling operation started
... omitted lines
RuntimeError: No journalling operation started
>>> doc.journal_start_op("op1")
>>> page = doc.new_page()
>>> doc.journal_stop_op()
>>> doc.journal_start_op("op2")
>>> page.insert_text((100,100), "Line 1")
>>> doc.journal_stop_op()
>>> doc.journal_start_op("op3")
>>> page.insert_text((100,120), "Line 2")
>>> doc.journal_stop_op()
>>> doc.journal_start_op("op4")
>>> page.insert_text((100,140), "Line 3")
>>> doc.journal_stop_op()
>>> # show position in journal
>>> doc.journal_position()
(4, 4)
>>> # 4 operations recorded - positioned at bottom
>>> # what can we do?
>>> doc.journal_can_do()
{'undo': True, 'redo': False}
>>> # currently only undos are possible. Print page content:
>>> print(page.get_text())
Line 1
Line 2
Line 3
>>> # undo last insert:
>>> doc.journal_undo()
>>> # show combined status again:
>>> doc.journal_position();doc.journal_can_do()
(3, 4)
{'undo': True, 'redo': True}
>>> print(page.get_text())
Line 1
Line 2
>>> # our position is now second to last
>>> # last text insertion was reverted
>>> # but we can redo / move forward as well:
>>> doc.journal_redo()
>>> # our combined status:
>>> doc.journal_position();doc.journal_can_do()
(4, 4)
{'undo': True, 'redo': False}
>>> print(page.get_text())
Line 1
Line 2
Line 3
>>> # line 3 has appeared again!

示例会话 2

描述：

类似于之前的情况，但在撤消某些操作后，我们现在添加了不同的更新。这将导致：

永久删除未完成的日志条目

新的更新操作将成为新的最后条目。

>>> doc=pymupdf.open()
>>> doc.journal_enable()
>>> doc.journal_start_op("Page insert")
>>> page=doc.new_page()
>>> doc.journal_stop_op()
>>> for i in range(5):
 doc.journal_start_op("insert-%i" % i)
 page.insert_text((100, 100 + 20*i), "text line %i" %i)
 doc.journal_stop_op()

>>> # combined status info:
>>> doc.journal_position();doc.journal_can_do()
(6, 6)
{'undo': True, 'redo': False}

>>> for i in range(3):  # revert last three operations
 doc.journal_undo()
>>> doc.journal_position();doc.journal_can_do()
(3, 6)
{'undo': True, 'redo': True}

>>> # now do a different update:
>>> doc.journal_start_op("Draw some line")
>>> page.draw_line((100,150), (300,150))
Point(300.0, 150.0)
>>> doc.journal_stop_op()
>>> doc.journal_position();doc.journal_can_do()
(4, 4)
{'undo': True, 'redo': False}

>>> # this has changed the journal:
>>> # previous last 3 text line operations were removed, and
>>> # we have only 4 operations: drawing the line is the new last one

对本页面有任何反馈吗？

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

此文档覆盖所有版本，直至 1.24.4。

示例会话 1

描述：

创建一个新的 PDF 并启用日志记录。然后添加一个页面和一些文本行 - 每个都作为单独的操作。
在日志中导航，撤消和重做这些更新，并显示状态和文件结果：

>>> import pymupdf
>>> doc=pymupdf.open()
>>> doc.journal_enable()
>>> # try update without an operation:
>>> page = doc.new_page()
mupdf: No journalling operation started
... omitted lines
RuntimeError: No journalling operation started
>>> doc.journal_start_op("op1")
>>> page = doc.new_page()
>>> doc.journal_stop_op()
>>> doc.journal_start_op("op2")
>>> page.insert_text((100,100), "Line 1")
>>> doc.journal_stop_op()
>>> doc.journal_start_op("op3")
>>> page.insert_text((100,120), "Line 2")
>>> doc.journal_stop_op()
>>> doc.journal_start_op("op4")
>>> page.insert_text((100,140), "Line 3")
>>> doc.journal_stop_op()
>>> # show position in journal
>>> doc.journal_position()
(4, 4)
>>> # 4 operations recorded - positioned at bottom
>>> # what can we do?
>>> doc.journal_can_do()
{'undo': True, 'redo': False}
>>> # currently only undos are possible. Print page content:
>>> print(page.get_text())
Line 1
Line 2
Line 3
>>> # undo last insert:
>>> doc.journal_undo()
>>> # show combined status again:
>>> doc.journal_position();doc.journal_can_do()
(3, 4)
{'undo': True, 'redo': True}
>>> print(page.get_text())
Line 1
Line 2
>>> # our position is now second to last
>>> # last text insertion was reverted
>>> # but we can redo / move forward as well:
>>> doc.journal_redo()
>>> # our combined status:
>>> doc.journal_position();doc.journal_can_do()
(4, 4)
{'undo': True, 'redo': False}
>>> print(page.get_text())
Line 1
Line 2
Line 3
>>> # line 3 has appeared again!

示例会话 2

描述：

类似于之前的情况，但在撤消某些操作后，我们现在添加了不同的更新。这将导致：

永久删除未完成的日志条目

新的更新操作将成为新的最后条目。

>>> doc=pymupdf.open()
>>> doc.journal_enable()
>>> doc.journal_start_op("Page insert")
>>> page=doc.new_page()
>>> doc.journal_stop_op()
>>> for i in range(5):
 doc.journal_start_op("insert-%i" % i)
 page.insert_text((100, 100 + 20*i), "text line %i" %i)
 doc.journal_stop_op()

>>> # combined status info:
>>> doc.journal_position();doc.journal_can_do()
(6, 6)
{'undo': True, 'redo': False}

>>> for i in range(3):  # revert last three operations
 doc.journal_undo()
>>> doc.journal_position();doc.journal_can_do()
(3, 6)
{'undo': True, 'redo': True}

>>> # now do a different update:
>>> doc.journal_start_op("Draw some line")
>>> page.draw_line((100,150), (300,150))
Point(300.0, 150.0)
>>> doc.journal_stop_op()
>>> doc.journal_position();doc.journal_can_do()
(4, 4)
{'undo': True, 'redo': False}

>>> # this has changed the journal:
>>> # previous last 3 text line operations were removed, and
>>> # we have only 4 operations: drawing the line is the new last one

对本页面有任何反馈吗？

此文档覆盖所有版本，直至 1.24.4。

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