电子书编辑工具的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

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

遍历名称中的所有链接。 如果 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_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”。

管理容器中的组件文件

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

参数:
  • 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’}

返回为给定文件名推荐的文件夹。 该建议基于大多数相同类型的文件在容器中的位置。 如果不存在特定类型的文件,则假定推荐的文件夹是包含 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_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()[源代码]

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