电子书编辑工具的API文档

电子书编辑工具包括一个“calibre.ebooks.oeb.polish.container.Container”对象，该对象将一本书表示为一组HTML+资源文件，以及可用于在容器上执行操作的各种工具。所有工具都是各种“Calibre.ebooks.oeb.polish.*”模块中模块级函数的形式。

您可以在如下路径获取图书的容器对象：

from calibre.ebooks.oeb.polish.container import get_container
container = get_container('Path to book file', tweak_mode=True)

如果您正在为电子书编辑器编写插件，您将获得正在编辑的图书的当前容器，如下所示：

from calibre.gui2.tweak_book import current_container
container = current_container()
if container is None:
    report_error # No book has been opened yet

容器对象

class calibre.ebooks.oeb.polish.container.Container(rootpath, opfpath, log, clone_data=None)

容器将一本打开的电子书表示为一个充满文件和 OPF 文件的文件夹。 有两个重要的概念：

• 根文件夹。 这是电子书的基础。 所有电子书文件都位于该文件夹或其子文件夹中。

• 名称：这些是书籍文件相对于根文件夹的路径。 它们始终包含 POSIX 分隔符并且不带引号。 它们可以被认为是书中文件的规范标识符。 容器对象上的大多数方法都使用名称。 名称始终采用 NFC Unicode 范式。

• 克隆：容器对象支持高效的磁盘克隆，用于在电子书编辑器中实现检查点。 为了实现此目的，您永远不应该直接访问文件系统上的文件。 相反，使用“raw_data”或“open”来读取/写入书中的组件文件。

当使用此类提供的方法在href和名称之间进行转换时，它们假定所有href都被引用。

abspath_to_name(fullpath, root=None)

将绝对路径转换为相对于“root”的规范名称

参数:

root -- 基础文件夹。 默认情况下使用此容器对象的根。

add_file(name, data, media_type=None, spine_index=None, modify_name_if_needed=False, process_manifest_item=None)

将文件添加到此容器。文件条目自动在OPF清单和书脊中创建（如果文件是文本文档）

add_name_to_manifest(name, process_manifest_item=None)

向具有指定名称的文件的清单中添加条目。返回清单ID。

add_properties(name, *properties)

将指定的属性添加到由名称标识的清单项。

apply_unique_properties(name, *properties)

请确保仅对由名称标识的清单项设置指定的属性。您可以传递None作为名称，以从所有项中移除属性。

book_type = 'oeb'

图书类型(epub用于EPUB文件，azw3用于AZW3文件)

commit(outpath=None, keep_parsed=False)

将所有有害的解析对象提交到文件系统，并在outpath写出电子书文件。

参数:

• output -- 要将保存的电子书文件写入的路径。如果没有，则使用原始书籍文件的路径。

• keep_parsed -- 如果为True，则已提交项的解析表示形式保留在缓存中。

commit_item(name, keep_parsed=False)

将解析后的对象提交到磁盘（它被序列化并写入底层文件）。 如果“keep_parsed”为 True，解析后的表示将保留在缓存中。 另请参阅：“已解析”

dirty(name)

将name对应的已解析对象标记为dirty。 另请参阅：“已解析”。

exists(name)

如果存在与规范名称相对应的文件/文件夹，则为 True。 请注意，此函数受到底层操作系统文件系统的限制，特别是大小写（不）敏感性。 因此，在不区分大小写的文件系统上，即使名称的大小写与底层文件系统文件的大小写不同，也会返回 True。 另请参阅“has_name”

filesize(name)

返回由指定规范名称表示的文件的大小，以字节为单位。 自动处理混乱的解析对象。 另请参阅：“已解析”

generate_item(name, id_prefix=None, media_type=None, unique_href=True)

使用从给定名称派生的HREF将项目添加到清单中。自动保证href和id的唯一性。返回生成的项。

get_file_path_for_processing(name, allow_modification=True)

与open()类似，不同之处在于它返回文件路径，而不是打开的文件对象。

property guide_type_map

指南类型到规范名称的映射

has_name(name)

当且仅当存在与指定名称具有相同规范名称的文件时返回 True。 与“exists”不同，此方法始终区分大小写。

href_to_name(href, base=None)

将 href（相对于 base）转换为名称。 base 必须是名称或 None，在这种情况下使用 self.root。

insert_into_xml(parent, item, index=None)

将项目插入父级(如果索引为无，则追加)，修复缩进。仅适用于自动关闭的项目。

is_dir = False

如果此容器表示解压缩的图书(目录)

iterlinks(name, get_line_numbers=True)

遍历名称中的所有链接。 如果 get_line_numbers 为 True，则产生 (link, line_number, offset) 形式的结果。 其中 line_number 是发生链接的 line_number，offset 是距行开头的字符数。 请注意，如果偏移量不为零，则实际上可以包含多条线。

make_name_unique(name)

确保本书中不存在“name”。 如果存在，则返回不存在的修改版本。

manifest_has_name(name)

如果清单具有与Name对应的条目，则返回True

property manifest_id_map

清单ID到规范名称的映射

manifest_items_of_type(predicate)

媒体类型与谓词匹配的所有清单项的名称。 predicate 可以是一个集合、一个列表、一个字符串或一个带有单个参数的函数，它将使用媒体类型进行调用。

manifest_items_with_property(property_name)

具有指定属性的所有清单项

property manifest_type_map

将清单媒体类型映射到该媒体类型的规范名称列表

property mi

本书的元数据作为 Metadata 对象。 请注意，每次请求此属性时都会动态构造此对象，因此请谨慎使用它。

name_to_abspath(name)

将规范名称转换为操作系统相关的绝对路径

name_to_href(name, base=None)

将名称转换为相对于基准的 href，该基准必须是名称或 None，在这种情况下 self.root 用作基准

property names_that_must_not_be_changed

绝对不能重命名的一组名称。 取决于电子书文件格式。

property names_that_must_not_be_removed

绝不能从容器中删除的一组名称。 取决于电子书文件格式。

property names_that_need_not_be_manifested

清单中允许缺失的名称集。 取决于电子书文件格式。

open(name, mode='rb')

打开名称指向的文件以进行直接读/写。 请注意，如果文件脏了，这将提交该文件并将其从解析缓存中删除。 在再次访问该文件的解析版本之前，您必须完成该文件，否则会发生不好的事情。

property opf

解析后的OPF文件

opf_get_or_create(name)

返回具有指定名称的第一个 XML 元素或在 opf:package 元素下创建它然后返回它的便捷方法，如果它尚不存在。

property opf_version

OPF <package> 元素上设置的版本

property opf_version_parsed

OPF 的 <package> 元素上设置的版本作为整数元组

opf_xpath(expr)

计算 OPF 文件上的 XPath 表达式的便捷方法，具有预定义的 opf: 和 dc: 命名空间前缀。

parsed(name)

返回按名称指定的文件的已解析表示形式。 对于 HTML 和 XML 文件，将返回 lxml 树。 对于 CSS 文件，会返回 css_parser 样式表。 请注意，已解析的对象会被缓存以提高性能。 如果对解析的对象进行任何更改，则必须调用“dirty”，以便容器知道更新缓存。 另请参阅“替换”。

raw_data(name, decode=True, normalize_to_nfc=True)

返回name指定文件对应的原始数据

参数:

• decode -- 如果为 True 并且文件具有基于文本的 MIME 类型，则对其进行解码并返回 unicode 对象而不是原始字节。

• normalize_to_nfc -- 如果为 True，则返回的 unicode 对象将按照 EPUB 和 AZW3 文件格式的要求标准化为 NFC 范式。

relpath(path, base=None)

将绝对路径（带有 os 分隔符）转换为相对于基路径（默认为 self.root）的路径。 相对路径*不是*名称。 为此使用“abspath_to_name”。

remove_from_spine(spine_items, remove_if_no_longer_in_spine=True)

从书脊中删除指定的项目（按规范名称）。 如果“remove_if_no_longer_in_spine”为 True，则这些项目也会从书中删除，而不仅仅是从书脊中删除。

remove_from_xml(item)

从父项中删除项目，修复缩进（仅适用于自闭合项目）

remove_item(name, remove_from_guide=True)

从此容器中移除按名称标识的项目。 这会删除 OPF 清单、指南和书脊以及任何内部缓存中对该项目的所有引用。

rename(current_name, new_name)

将文件从 current_name 重命名为 new_name。 如果文件所在的文件夹发生更改，它会自动重新设置文件内的所有链接的基准。 但请注意，可能引用该文件的其他文件中的链接不会更新。 这是为了性能，此类更新应该批量完成一次。

replace(name, obj)

将 name 对应的已解析对象替换为 obj，它必须是相似的对象，即 HTML/XML 的 lxml 树或 CSS 文件的 css_parser 样式表。

replace_links(name, replace_func)

使用replace_func替换名称中的所有链接，它必须是接受URL并返回替换的URL的可调用函数。 如果完成任何实际替换，它还必须具有设置为 True 的“replaced”属性。 创建此类可调用对象的便捷方法是使用“LinkReplacer”和“LinkRebaser”类。

serialize_item(name)

将已解析的对象（由规范名称标识）转换为字节串。 请参阅“已解析”。

set_spine(spine_items)

将spine 设置为spine_items，其中spine_items 是形式为（名称、线性）的可迭代对象。 如果清单中不存在其中一个名称，则会引发错误。

property spine_items

一个迭代器，生成书脊中每个项目的路径。 另请参阅：“spine_iter”和“spine_items”。

property spine_iter

一个迭代器，为书脊中的每个项目生成项目，名称为 is_linear。 item 是 lxml 元素，name 是规范文件名，如果 item 是线性的，则 is_linear 为 True。 另请参阅：“spine_names”和“spine_items”。

property spine_names

一个迭代器，为书脊中的每个项目生成名称和 is_linear 。 另请参阅：“spine_iter”和“spine_items”。

管理容器中的组件文件

calibre.ebooks.oeb.polish.replace.replace_links(container, link_map, frag_map=<function <lambda>>, replace_in_opf=False)

替换容器中文件的链接。 将遍历容器中的所有文件并更改其中指定的链接。

参数:

• link_map -- 旧规范名称到新规范名称的映射。 例如： {'images/old.png': 'images/new.png'}

• frag_map -- 一个可调用函数，它接受两个参数``(name,anchor)``并返回一个新的锚点。 如果您需要更改 HTML 文件中的锚点，这非常有用。 默认情况下，它不执行任何操作。

• replace_in_opf -- 如果为 False，则不会替换 OPF 文件中的链接。

calibre.ebooks.oeb.polish.replace.rename_files(container, file_map)

重命名容器中的文件，自动更新它们的所有链接。

参数:

file_map -- 旧规范名称到新规范名称的映射，例如：{'text/chapter1.html': 'chapter1.html'}。

calibre.ebooks.oeb.polish.replace.get_recommended_folders(container, names)

返回为给定文件名推荐的文件夹。 该建议基于大多数相同类型的文件在容器中的位置。 如果不存在特定类型的文件，则假定推荐的文件夹是包含 OPF 文件的文件夹。

漂亮的打印和自动修复解析错误

calibre.ebooks.oeb.polish.pretty.fix_html(container, raw)

修复以原始字符串表示的 HTML 中的任何解析错误。 使用 HTML5 解析算法完成修复。

calibre.ebooks.oeb.polish.pretty.fix_all_html(container)

修复容器中所有 HTML 文件中的任何解析错误。 使用 HTML5 解析算法完成修复。

calibre.ebooks.oeb.polish.pretty.pretty_html(container, name, raw)

漂亮地打印以原始字符串表示的 HTML

calibre.ebooks.oeb.polish.pretty.pretty_css(container, name, raw)

漂亮地打印以原始字符串表示的 CSS

calibre.ebooks.oeb.polish.pretty.pretty_xml(container, name, raw)

漂亮地打印以原始字符串形式表示的 XML。 如果“name”是 OPF 的名称，则会执行额外的 OPF 特定的美化。

calibre.ebooks.oeb.polish.pretty.pretty_all(container)

漂亮地打印容器中的所有 HTML/CSS/XML 文件

管理书封

calibre.ebooks.oeb.polish.jacket.remove_jacket(container)

除去现有的书皮，如果有。 如果未找到现有的书封，则返回 False。

calibre.ebooks.oeb.polish.jacket.add_or_replace_jacket(container)

从书籍的元数据创建新的封面或替换现有的书籍封面。 如果替换了现有的书皮，则返回 True。

文件的分割和合并

calibre.ebooks.oeb.polish.split.split(container, name, loc_or_xpath, before=True, totals=None)

在 loc_or_xpath 指定的位置分割 name 指定的文件。 拆分会自动迁移受影响文件的所有链接和引用。

参数:

• loc_or_xpath -- 应该是 XPath 表达式，例如 //h:div[@id="split_here"]。 也可以是 loc，在内部用于实现预览面板中的分割。

• before -- 如果为 True，则分割发生在所识别的元素之前，否则发生在其之后。

• totals -- 内部使用

calibre.ebooks.oeb.polish.split.multisplit(container, name, xpath, before=True)

在多个位置拆分指定文件（与指定 XPath 表达式匹配的所有标记）。 另请参阅：“拆分”。 拆分会自动迁移受影响文件的所有链接和引用。

参数:

before -- 如果为 True，则分割发生在所识别的元素之前，否则发生在其之后。

calibre.ebooks.oeb.polish.split.merge(container, category, names, master)

将指定文件合并为单个文件，自动迁移受影响文件的所有链接和引用。 该文件必须全部是 HTML 或 CSS 文件。

参数:

• category -- 对于 HTML 文件必须是 'text' 对于 CSS 文件必须是 'styles'

• names -- 要合并的文件列表

• master -- 合并后的文件中哪个是*主*文件，即合并后保留的文件。

管理封面

calibre.ebooks.oeb.polish.cover.set_cover(container, cover_path, report=None, options=None)

将书籍的封面设置为 cover_path 指向的图像。

参数:

• cover_path -- 图像文件的绝对路径或书中图像的规范名称。 使用书中的图像时，您还必须设置选项，请参见下文。

• report -- 带有单个参数的可选可调用对象。 它将被调用并提供有关正在处理的任务的信息。

• options -- 无或控制封面设置方式的字典。 字典可以包含条目： keep_aspect：True 或 False（保留 EPUB 中封面的宽高比） no_svg：True 或 False（在 EPUB 标题页中使用 SVG 封面包装） 现有： 对或错（“cover_path”指的是书中现有的图像）

calibre.ebooks.oeb.polish.cover.mark_as_cover(container, name)

将指定图像标记为封面图像。

calibre.ebooks.oeb.polish.cover.mark_as_titlepage(container, name, move_to_start=True)

将指定的 HTML 文件标记为 EPUB 的标题页。

参数:

move_to_start -- 如果为 True，则 HTML 文件将移动到书脊的开头

使用 CSS

calibre.ebooks.oeb.polish.fonts.change_font(container, old_name, new_name=None)

将字体系列从 old_name 更改为 new_name。 更改样式表、样式标签和样式属性中所有出现的字体系列。 如果 old_name 引用嵌入字体，则将其删除。 您可以将 new_name 设置为 None 以删除字体系列而不是更改它。

calibre.ebooks.oeb.polish.css.remove_unused_css(container, report=None, remove_unused_classes=False, merge_rules=False, merge_rules_with_identical_properties=False, remove_unreferenced_sheets=False)

从书中删除所有未使用的 CSS 规则。 未使用的 CSS 规则是指与任何实际内容都不匹配的规则。

参数:

• report -- 带有单个参数的可选可调用对象。 调用它时会包含有关正在执行的操作的信息。

• remove_unused_classes -- 如果为 True，则 HTML 中与任何 CSS 规则不匹配的类属性也会被删除。

• merge_rules -- 如果为 True，则合并具有相同选择器的规则。

• merge_rules_with_identical_properties -- 如果为 True，则合并具有相同属性的规则。

• remove_unreferenced_sheets -- 如果为 True，则删除任何内容未引用的样式表

calibre.ebooks.oeb.polish.css.filter_css(container, properties, names=())

从本书中的所有 CSS 规则中删除指定的 CSS 属性。

参数:

• properties -- 要删除的属性集。 例如：{'font-family', 'color'}。

• names -- 要从中删除属性的文件。 默认为书中的所有 HTML 和 CSS 文件。

使用目录

calibre.ebooks.oeb.polish.toc.from_xpaths(container, xpaths, prefer_title=False)

从 XPath 表达式列表生成目录。 列表中的每个表达式对应于生成目录的一个级别。 例如： ['//h:h1', '//h:h2', '//h:h3'] 将从 <h1>, <h2>` 生成三级目录 ` 和 ``<h3> 标签。

calibre.ebooks.oeb.polish.toc.from_links(container)

从书中的链接生成目录。

calibre.ebooks.oeb.polish.toc.from_files(container)

从书中的文件生成目录。

calibre.ebooks.oeb.polish.toc.create_inline_toc(container, title=None)

从现有 NCX 目录创建内联 (HTML) 目录。

参数:

title -- 此目录的标题。

书籍编辑工具

class calibre.gui2.tweak_book.plugin.Tool

基类：object

编辑图书插件中各个工具的基类。 有用的成员包括：

• “self.plugin”：对该工具所属的“calibre.customize.Plugin”对象的引用。

• self. boss

• self. gui

必须在子类中重写的方法：

• 创建动作

• 注册快捷方式

name = None

将其设置为一个唯一的名称，它将用作密钥

allowed_in_toolbar = True

如果为 True，用户可以选择将此工具放置在插件工具栏中

allowed_in_menu = True

如果为 True，则用户可以选择将此工具放置在插件菜单中

toolbar_button_popup_mode = 'delayed'

工具栏按钮的菜单（如果有）的弹出模式。 可能的值为“延迟”、“即时”、“按钮”

property boss

calibre.gui2.tweak_book.boss.Boss 对象。 用于控制用户界面。

property gui

用户界面的主窗口

property current_container

返回表示正在编辑的书籍的当前“calibre.ebooks.oeb.polish.container.Container”对象。

register_shortcut(qaction, unique_name, default_keys=(), short_text=None, description=None, **extra_data)

注册将触发指定的“qaction”的键盘快捷键。 用户将在编辑器首选项的“键盘快捷键”部分中自动自定义此键盘快捷键。

参数:

• qaction -- 一个 QAction 对象，当用户按下配置的组合键时会触发该对象。

• unique_name -- 此快捷方式/操作的唯一名称。 它将在内部使用，不得与此插件中的任何其他操作共享。

• default_keys -- 默认键盘快捷键列表。 如果未指定，则不会设置默认快捷方式。 如果此处指定的快捷方式与内置快捷方式或用户配置/其他插件的快捷方式冲突，它们将被忽略。 在这种情况下，用户必须通过首选项手动配置快捷方式。 例如：default_keys=('Ctrl+J', 'F9')。

• short_text -- 此操作的可选简短描述。 如果未指定，将使用 QAction 中的文本。

• description -- 此操作的可选较长描述，它将用于此快捷方式的首选项条目中。

create_action(for_toolbar=True)

创建一个 QAction，根据“for_toolbar”将其添加到插件工具栏或插件菜单中。 例如：

def create_action(self, for_toolbar=True):
    ac = QAction(get_icons('myicon.png'), 'Do something')
    if for_toolbar:
        # We want the toolbar button to have a popup menu
        menu = QMenu()
        ac.setMenu(menu)
        menu.addAction('Do something else')
        subaction = menu.addAction('And another')

        # Register a keyboard shortcut for this toolbar action be
        # careful to do this for only one of the toolbar action or
        # the menu action, not both.
        self.register_shortcut(ac, 'some-unique-name', default_keys=('Ctrl+K',))
    return ac

参见

方法“register_shortcut”。

控制编辑器的用户界面

电子书编辑器的用户界面由单个全局 Boss 对象控制。 它有许多有用的方法，可以在插件代码中使用来执行常见任务。

class calibre.gui2.tweak_book.boss.Boss(parent, notify=None)

add_savepoint(msg)

创建一个恢复检查点，名称指定为“msg”

apply_container_update_to_gui(mark_as_modified=True)

更新用户界面的所有组件以反映当前书籍容器中的最新数据。

参数:

mark_as_modified -- 如果为 True，该书将被标记为已修改，因此退出时将提示用户保存它。

close_editor(name)

关闭正在编辑“name”指定文件的编辑器

commit_all_editors_to_container()

将用户对编辑器中打开的文件所做的任何更改提交到容器。 您应该在对当前容器执行任何操作之前调用此方法

property currently_editing

返回当前正在编辑的文件的名称，如果没有正在编辑的文件，则返回 None

edit_file(name, syntax=None, use_template=None)

在编辑器中打开按名称指定的文件

参数:

• syntax -- 文件的媒体类型，例如``'text/html'``。 如果未指定，则从文件扩展名猜测。

• use_template -- 用于初始化打开的编辑器的模板

open_book(path=None, edit_file=None, clear_notify_data=True, open_folder=False, search_text=None)

打开“path”处的电子书进行编辑。 如果电子书的格式不受支持或当前书籍有未保存的更改，则会显示错误。

参数:

edit_file -- 新打开的书籍中要开始编辑的文件的名称。 也可以是姓名列表。

rewind_savepoint()

撤消之前创建的恢复检查点，如果您创建检查点，然后中止操作而不进行任何更改，则非常有用

save_book()

保存这本书。 保存在后台执行

set_modified()

将书标记为已修改

show_current_diff(allow_revert=True, to_container=None)

显示书籍相对于上次检查点状态的更改

参数:

• allow_revert -- 如果为 True，diff 对话框将有一个按钮允许用户恢复所有更改

• to_container -- 与当前容器进行比较的容器对象。 如果没有，则使用先前设置检查点的容器

show_editor(name)

显示正在编辑“name”指定文件的编辑器

sync_preview_to_editor()

将预览面板的位置同步到当前编辑器中的当前光标位置

© 版权 Kovid Goyal。 最后一次更新于 12月 20, 2024。