插件API文档¶

定义了各种抽象的基类，它们的子类可以创建功能强大的插件。这些有用的类包括：

插件 ¶

class calibre.customize.Plugin(plugin_path)[源代码]¶

一个 calibre 插件。重要的成员包括：

self.installation_type：存储插件的安装方式。

self.plugin_path：存储包含以下内容的 ZIP 文件的路径
如果它是内置插件，则此插件或无

self.site_customization: 存储一个用户输入的自定义字符串
由用户。

在子类中应当重写的方法：

初始化

定制_帮助

有用的方法：

临时文件

__输入__

加载资源

supported_platforms = []¶: 该插件适用的平台列表。例如：['windows', 'osx', 'linux']

name = 'Trivial Plugin'¶: 该插件的名称。您必须将其设置为 Trivial Plugin 以外的其他内容才能正常工作。

version = (1, 0, 0)¶: 此插件的版本为三-元组（主要、次要、修订版）

description = '不做修改'¶: 描述此插件功能的短字符串

author = '未知'¶: 这个插件的作者

priority = 1¶: 当一种文件类型存在多个插件时，插件将按优先级降序运行。优先级较高的插件将首先运行。可能的最高优先级是“sys.maxsize”。默认优先级为 1。

minimum_calibre_version = (0, 4, 118)¶: 该插件需要的最早版本的 calibre

installation_type = None¶: 这个插件的安装方式

can_be_disabled = True¶: 如果为 False，用户将无法禁用此插件。小心使用。

type = '基本'¶: 该插件的类型。用于在 GUI 中对插件进行分类

initialize()[源代码]¶

当 calibre 插件初始化时调用一次。每次添加新插件时，插件都会重新初始化。另请注意，如果插件在工作进程中运行，例如用于添加书籍，则将为每个新工作进程初始化该插件。

在此执行任何特定于插件的初始化，例如从插件 ZIP 文件中提取资源。 ZIP 文件的路径可用作“self.plugin_path”。

请注意，“self.site_customization”此时**不**可用。

config_widget()[源代码]¶

在插件中实现此方法和“save_settings”以使用自定义配置对话框，而不是依赖于基于简单字符串的默认自定义。

此方法如果实现，必须返回一个 QWidget。该小部件可以有一个可选方法 validate()，该方法不带任何参数，并在用户单击“确定”后立即调用。当且仅当该方法返回 True 时才会应用更改。

如果由于某种原因此时无法执行配置，请返回两个字符串（消息、详细信息）的元组，这些将作为警告对话框显示给用户，并且进程将中止。

save_settings(config_widget)[源代码]¶

使用 config_widget 保存用户指定的设置。

参数:: config_widget -- config_widget 返回的小部件。

do_user_config(parent=None)[源代码]¶: 此方法显示该插件的配置对话框。如果用户单击“确定”，则返回 True，否则返回 False。更改会自动应用。

load_resources(names)[源代码]¶

如果此插件位于 ZIP 文件（用户添加的插件）中，则此方法将允许您从 ZIP 文件加载资源。

例如加载图像：

pixmap = QPixmap()
pixmap.loadFromData(self.load_resources(['images/icon.png'])['images/icon.png'])
icon = QIcon(pixmap)

参数:: names -- ZIP 文件中资源的路径列表，使用 / 作为分隔符
返回:: 形式为“{name: file_contents}”的字典。 ZIP 文件中未找到的任何名称都不会出现在字典中。

customization_help(gui=False)[源代码]¶

返回一个字符串，提供有关如何自定义此插件的帮助。默认情况下会引发“NotImplementedError”，这表明该插件不需要自定义。

如果您在子类中重新实现此方法，系统将要求用户输入一个字符串作为此插件的自定义。自定义字符串将以“self.site_customization”形式提供。

站点自定义可以是任何内容，例如用户计算机上所需二进制文件的路径。

参数:: gui -- 如果 True 返回 HTML 帮助，否则返回纯文本帮助。

temporary_file(suffix)[源代码]¶

返回一个类似文件的对象，它是文件系统上的临时文件。即使关闭后，该文件仍然可用，并且仅在解释器关闭时才会被删除。使用返回对象的“name”成员来访问创建的临时文件的完整路径。

参数:: suffix -- 临时文件将具有的后缀。

cli_main(args)[源代码]¶: 此方法是插件命令行界面的主要入口点。当用户执行以下操作时调用它：calibre-debug -r“插件名称”。传递的任何参数都存在于 args 变量中。

文件类型插件 ¶

class calibre.customize.FileTypePlugin(plugin_path)[源代码]¶

基类：Plugin

与一组特定文件类型关联的插件。

file_types = {}¶: 应运行此插件的文件类型集。对所有文件类型使用“*”。例如：{'lit', 'mobi', 'prc'}

on_import = False¶: 如果为 True，则在将书籍添加到数据库时运行此插件

on_postimport = False¶: 如果为 True，则在将书籍添加到数据库后运行此插件。在这种情况下，将调用插件的 post import 和 post add 方法。

on_postconvert = False¶: 如果为 True，则该插件将在书籍转换后运行。在这种情况下，调用插件的 post convert 方法。

on_postdelete = False¶: 如果为 True，则在从数据库中删除书籍文件后运行此插件。在这种情况下，将调用插件的 post delete 方法。

on_preprocess = False¶: 如果为 True，则该插件将在转换之前运行

on_postprocess = False¶: 如果为 True，则在转换输出插件生成的最终文件后运行此插件。

type = '文件格式'¶: 该插件的类型。用于在 GUI 中对插件进行分类

run(path_to_ebook)[源代码]¶

运行插件。必须在子类中实现。它应该对电子书执行所需的任何修改，并返回修改后的电子书的绝对路径。如果不需要修改，它应该返回原始电子书的路径。如果遇到错误，它应该引发异常。默认实现只是返回原始电子书的路径。请注意，原始文件的路径（在运行任何文件类型插件之前，可用作 self.original_path_to_file）。

修改后的电子书文件应使用“temporary_file”方法创建。

参数:: path_to_ebook -- 电子书的绝对路径。
返回:: 修改后的电子书的绝对路径。

postimport(book_id, book_format, db)[源代码]¶

称为导入后，即在将书籍文件添加到数据库之后。请注意，这与第一次创建图书记录时调用的“post add”不同。每当新文件添加到图书记录时都会调用此方法。它对于根据新添加的文件的内容修改图书记录非常有用。

参数:

book_id -- 添加的图书的数据库id。
book_format -- 添加的书籍的文件类型。
db -- 图书馆数据库。

postconvert(book_id, book_format, db)[源代码]¶

称为转换后，即转换后输出的书籍文件已添加到数据库中。请注意，它仅在转换后运行，而不是在添加书籍后运行。它对于根据新添加的文件的内容修改图书记录非常有用。

参数:

book_id -- 添加的图书的数据库id。
book_format -- 添加的书籍的文件类型。
db -- 图书馆数据库。

postdelete(book_id, book_format, db)[源代码]¶

称为删除后，即书籍文件从数据库中删除后。请注意，删除图书记录时不会运行它，仅当删除图书中的一种或多种格式时才会运行。它对于根据已删除文件的格式修改图书记录非常有用。

参数:

book_id -- 添加的图书的数据库id。
book_format -- 添加的书籍的文件类型。
db -- 图书馆数据库。

postadd(book_id, fmt_map, db)[源代码]¶

称为后添加，即在将一本书添加到数据库之后。请注意，这与 post import 不同，post import 在将单个书籍文件添加到书籍后调用。仅当第一次创建可能包含多个图书文件的整个图书记录时，才会调用 postadd()。如果您希望在书籍首次添加到 calibre 时修改数据库中的书籍记录，这非常有用。

参数:

book_id -- 添加的图书的数据库id。
fmt_map -- 文件格式到添加文件格式的路径的映射。请注意，这可能指向也可能不指向实际存在的文件，因为有时文件会作为流添加。在这种情况下，它可能是虚拟值或不存在的路径。
db -- 图书馆数据库

元数据插件 ¶

class calibre.customize.MetadataReaderPlugin(*args, **kwargs)[源代码]¶

基类：Plugin

一个实现从一组文件类型读取元数据的插件。

file_types = {}¶: 应运行此插件的文件类型集。例如：set(['lit', 'mobi', 'prc'])

supported_platforms = ['windows', 'osx', 'linux']¶: 该插件适用的平台列表。例如：['windows', 'osx', 'linux']

version = (9, 17, 0)¶: 此插件的版本为三-元组（主要、次要、修订版）

author = 'Kovid Goyal'¶: 这个插件的作者

type = '读取元数据'¶: 该插件的类型。用于在 GUI 中对插件进行分类

get_metadata(stream, type)[源代码]¶

返回流表示的文件的元数据（支持读取的类似文件的对象）。当输入数据有错误时引发异常。

参数:: type -- 文件类型。保证是“file_types”中的条目之一。
返回:: 一个 calibre.ebooks.metadata.book.Metadata 对象

class calibre.customize.MetadataWriterPlugin(*args, **kwargs)[源代码]¶

基类：Plugin

一个实现从一组文件类型读取元数据的插件。

file_types = {}¶: 应运行此插件的文件类型集。例如：set(['lit', 'mobi', 'prc'])

supported_platforms = ['windows', 'osx', 'linux']¶: 该插件适用的平台列表。例如：['windows', 'osx', 'linux']

version = (9, 17, 0)¶: 此插件的版本为三-元组（主要、次要、修订版）

author = 'Kovid Goyal'¶: 这个插件的作者

type = '编辑元数据'¶: 该插件的类型。用于在 GUI 中对插件进行分类

set_metadata(stream, mi, type)[源代码]¶

为流（支持读取的类似文件的对象）表示的文件设置元数据。当输入数据有错误时引发异常。

参数:

type -- 文件类型。保证是“file_types”中的条目之一。
mi -- 一个 calibre.ebooks.metadata.book.Metadata 对象

书目插件 ¶

class calibre.customize.CatalogPlugin(plugin_path)[源代码]¶

基类：Plugin

实现目录生成器的插件。

file_types = {}¶: 应运行此插件的输出文件类型。例如：“epub”或“xml”

type = '生成书目'¶: 该插件的类型。用于在 GUI 中对插件进行分类

cli_options = []¶

特定于此插件的 CLI 解析器选项，声明为 namedtuple Option：

从集合导入namedtuple Option=namedtupel（'Option'，'Option，default，dest，help'）cli_options=[选项（'-目录标题'，default='我的目录'，dest='catalog_title'，help=（_（'生成的目录的标题。n默认值：'）+“'”+'%ddefault'+"'"))]在calible.db.cli.cmd_catalog:Option_parser（）中解析的cli_options

initialize()[源代码]¶: 如果插件不是内置插件，请将插件的 .ui 和 .py 文件从 ZIP 文件复制到 $TMPDIR。选项卡将动态生成并添加到 calibre.gui2.dialogs.catalog.py:Catalog 中的“目录选项”对话框

run(path_to_output, opts, db, ids, notification=None)[源代码]¶

运行插件。必须在子类中实现。它应该以 file_types 中指定的格式生成目录，并返回生成的目录文件的绝对路径。如果遇到错误，它应该引发异常。

生成的目录文件应使用“temporary_file”方法创建。

参数:

path_to_output -- 生成的目录文件的绝对路径。
opts -- 关键字参数字典
db -- LibraryDatabase2 对象

元数据下载插件 ¶

class calibre.ebooks.metadata.sources.base.Source(*args, **kwargs)[源代码]¶

基类：Plugin

type = '元数据来源'¶: 该插件的类型。用于在 GUI 中对插件进行分类

author = 'Kovid Goyal'¶: 这个插件的作者

supported_platforms = ['windows', 'osx', 'linux']¶: 该插件适用的平台列表。例如：['windows', 'osx', 'linux']

capabilities = frozenset({})¶: 该插件支持的功能集。有用的功能有：“识别”、“覆盖”

touched_fields = frozenset({})¶: 该插件在识别阶段可能下载的元数据字段列表

has_html_comments = False¶: 如果您的插件返回 HTML 格式的注释，请将此设置为 True

supports_gzip_transfer_encoding = False¶: 将其设置为 True 意味着浏览器对象将指示它支持 gzip 传输编码。这可以加快下载速度，但首先要确保源实际上正确支持 gzip 传输编码

ignore_ssl_errors = False¶: 将其设置为 True 可在连接到此源时忽略 HTTPS 证书错误。

cached_cover_url_is_reliable = True¶: 缓存的封面 URL 有时可能不可靠（即下载可能失败或返回的图像可能是伪造的）。如果此源经常出现这种情况，请设置为 False

options = ()¶: Option 对象的列表。它们将用于自动构建该插件的配置小部件

config_help_message = None¶: 显示在该插件的配置小部件顶部的字符串

can_get_multiple_covers = False¶: 如果为 True，则此源可以为给定查询返回多个封面

auto_trim_covers = False¶: 如果设置为 True，此插件下载的封面将自动修剪。

prefer_results_with_isbn = True¶: 如果设置为 True，并且此源返回查询的多个结果，其中一些有 ISBN，一些没有，则没有 ISBN 的结果将被忽略

uses_camoufox_worker = False¶: If set to True this source uses the Camoufox browser shared by all metadata downloads, see calibre.web.automate.metadata, which is then started before metadata is downloaded, so that it is ready in time. Such sources are also waited for longer after the first result from any source arrives, since downloading with a browser is slow.

is_configured()[源代码]¶: 如果您的插件需要先配置才能使用，则返回 False。例如，它可能需要用户名/密码/API 密钥。

customization_help(gui=False)[源代码]¶

返回一个字符串，提供有关如何自定义此插件的帮助。默认情况下会引发“NotImplementedError”，这表明该插件不需要自定义。

如果您在子类中重新实现此方法，系统将要求用户输入一个字符串作为此插件的自定义。自定义字符串将以“self.site_customization”形式提供。

站点自定义可以是任何内容，例如用户计算机上所需二进制文件的路径。

参数:: gui -- 如果 True 返回 HTML 帮助，否则返回纯文本帮助。

config_widget()[源代码]¶

在插件中实现此方法和“save_settings”以使用自定义配置对话框，而不是依赖于基于简单字符串的默认自定义。

此方法如果实现，必须返回一个 QWidget。该小部件可以有一个可选方法 validate()，该方法不带任何参数，并在用户单击“确定”后立即调用。当且仅当该方法返回 True 时才会应用更改。

如果由于某种原因此时无法执行配置，请返回两个字符串（消息、详细信息）的元组，这些将作为警告对话框显示给用户，并且进程将中止。

save_settings(config_widget)[源代码]¶

使用 config_widget 保存用户指定的设置。

参数:: config_widget -- config_widget 返回的小部件。

get_author_tokens(authors, only_first_author=True)[源代码]¶: 获取作者列表并返回对 AND 搜索查询有用的标记列表。此函数尝试按名字、中间名、姓氏顺序返回标记，假设如果作者姓名中包含逗号，则该名称采用姓氏、其他名称的形式。

get_title_tokens(title, strip_joiners=True, strip_subtitle=False)[源代码]¶: 获取标题并返回对 AND 搜索查询有用的标记列表。不包括连接词（可选）和标点符号。

split_jobs(jobs, num)[源代码]¶: 将作业列表尽可能均匀地拆分为最多 num 个组

test_fields(mi)[源代码]¶: 返回 self.touched_fields 中 mi 对象上为 null 的第一个字段

clean_downloaded_metadata(mi)[源代码]¶: 在将元数据对象放入 result_queue 之前，在插件的识别方法中调用此方法来规范元数据。当然，您可以使用适合您的元数据源的自定义算法。

get_book_url(identifiers)[源代码]¶: 返回 3 元组或 None。 3 元组的形式为：（identifier_type、identifier_value、URL）。 URL 是由该源中的标识符标识的书籍的 URL。 identifier_type、identifier_value指定URL对应的标识符。该 URL 必须可供使用浏览器的人员浏览。它旨在为用户提供一个可点击的链接，以便轻松访问此来源的书籍页面。如果没有找到 URL，则返回 None。此方法必须快速且一致，因此仅当可以根据给定标识符的已知方案构造 URL 时才实施它。

get_book_url_name(idtype, idval, url)[源代码]¶: 从 get_book_url() 的返回值返回一个人类可读的名称。

get_book_urls(identifiers)[源代码]¶: 如果您想返回本书的多个 URL，请重写此方法。返回 3 元组的列表。默认情况下，此方法仅调用 get_book_url。

get_cached_cover_url(identifiers)[源代码]¶

返回由标识符字典标识的书籍的缓存封面 URL，如果不存在此类 URL，则返回 None。

请注意，此方法必须仅返回经过验证的 URL，即不能返回可能导致通用封面图像或未找到错误的 URL。

id_from_url(url)[源代码]¶: 解析 URL 并返回以下形式的元组：（identifier_type，identifier_value）。如果 URL 与元数据源的模式不匹配，则返回 None。

identify_results_keygen(title=None, authors=None, identifiers=None)[源代码]¶

返回一个函数，该函数用于生成一个关键词，该关键词可以根据给定搜索查询（标题、作者、标识符）的相关性对元数据对象进行排序。

这些关键词用于对“identify”调用的结果进行排序。

有关默认算法的详细信息，请参阅“InternalMetadataCompareKeyGen”。如果默认算法不合适，请在您的插件中重新实现此功能。

identify(log, result_queue, abort, title=None, authors=None, identifiers=None, timeout=30)[源代码]¶

通过书名/作者/ISBN/等识别一本书。

如果指定了标识符(s)但未找到匹配项，并且此元数据源未存储所有相关标识符（例如，一本书的所有 ISBN），则此方法应仅使用标题和作者（假设已指定）重试。

如果此元数据源还提供封面，则应缓存封面的 URL，以便后续使用相同 ISBN/特殊标识符调用获取封面 API 时无需再次获取封面 URL。为此，请使用缓存 API。

通过此方法放入 result_queue 的每个元数据对象都必须具有“source_relevance”属性，该属性是一个整数，指示元数据源为此查询返回结果的顺序。该整数将由“compare_identify_results”使用。如果顺序不重要，请将每个结果的顺序设置为零。

确保在将元数据对象放入 result_queue 之前缓存所有封面/ISBN 映射信息。

参数:

log -- 一个日志对象，用它来输出调试信息/错误
result_queue -- 一个结果队列，结果应该放入其中。每个结果都是一个元数据对象
abort -- 如果 abort.is_set() 返回 True，则中止进一步处理并尽快返回
title -- 书名，可以为 None
authors -- 本书的作者列表，可以是 None
identifiers -- 其他标识符的字典，最常见的是 {'isbn':'1234...'}
timeout -- 超时，以秒为单位，网络请求挂起时间不应超过超时。

返回:

如果没有发生错误，则为 None，否则为适合向用户显示的错误的 unicode 表示形式

download_cover(log, result_queue, abort, title=None, authors=None, identifiers=None, timeout=30, get_best_cover=False)[源代码]¶

下载封面并将其放入 result_queue 中。所有参数的含义与“identify”相同。将 (self, cover_data) 放入 result_queue 中。

此方法应尽可能使用缓存的封面 URL 以提高效率。当缓存数据不存在时，大多数插件只需调用识别并使用其结果。

如果参数 get_best_cover 为 True 并且该插件可以获取多个封面，则它应该只获取“最佳”封面。

class calibre.ebooks.metadata.sources.base.InternalMetadataCompareKeyGen(mi, source_plugin, title, authors, identifiers)[源代码]¶

给定搜索查询，生成排序键以比较元数据对象的相关性。这仅用于比较来自同一元数据源的结果，而不用于比较不同源的结果。

排序键确保升序排序是按相关性递减的顺序排序。

算法是：

首选具有至少一个与查询相同的标识符的结果

首选带有缓存封面 URL 的结果

首选已填写所有可用字段的结果

首选与当前用户界面语言相同的结果

首选与查询标题完全匹配的结果

优先选择评论较长的结果（长度超过 10%）

使用元数据源搜索报告的结果的相关性
引擎

转换插件 ¶

class calibre.customize.conversion.InputFormatPlugin(*args)[源代码]¶

基类：Plugin

engineInputFormatPlugins 负责将文档转换为 HTML+OPF+CSS+等。转换结果*必须*采用 UTF-8 编码。主要操作发生在“convert”中。

type = '输入转换'¶: 该插件的类型。用于在 GUI 中对插件进行分类

supported_platforms = ['windows', 'osx', 'linux']¶: 该插件适用的平台列表。例如：['windows', 'osx', 'linux']

file_types = {}¶: 应运行此插件的文件类型集例如：set(['azw', 'mobi', 'prc'])

is_image_collection = False¶: 如果为 True，则此输入插件会生成一组图像，每个 HTML 文件一个。如果输入文件可以是图像集合和非图像集合，则可以在转换方法中动态设置。如果将此设置为 True，则必须实现返回图像列表的 get_images() 方法。

core_usage = 1¶: 该插件使用的 CPU 核心数。值为 -1 表示它使用所有可用核心

for_viewer = False¶: 如果设置为 True，输入插件将执行特殊处理，使其输出适合查看

output_encoding = 'utf-8'¶: 此输入插件创建文件所采用的编码。 None 值表示编码未定义，该值必须单独检测

common_options = {<calibre.customize.conversion.OptionRecommendation object>}¶: 所有输入格式插件共享的选项。不要在子类中重写。请改用“选项”。每个选项都必须是“OptionRecommendation”的实例。

options = {}¶: 自定义此插件行为的选项。每个选项都必须是 :OptionRecommendation 的实例。

recommendations = {}¶: 一组形式为（选项名称、推荐值、推荐级别）的三元组

get_images()[源代码]¶: 如果此输入插件代表图像集合，则返回图像的绝对路径列表。图像列表的顺序与书脊和目录的顺序相同。

convert(stream, options, file_ext, log, accelerators)[源代码]¶

该方法必须在子类中实现。它必须返回创建的 OPF 文件或“OEBBook”实例的路径。所有输出应包含在当前文件夹中。如果此插件在当前文件夹之外创建文件，则必须在此方法返回之前将其删除/标记为删除。

参数:

stream -- 包含输入文件的类似文件的对象。
options -- 自定义转换过程的选项。保证具有与该插件声明的所有选项相对应的属性。此外，它还有一个详细属性，该属性采用从零开始的整数值。数字越大意味着越详细。另一个有用的属性是“input_profile”，它是“calibre.customize.profiles.InputProfile”的实例。
file_ext -- 输入文件的扩展名（不带 .）。它保证是该插件支持的“file_types”之一。
log -- 一个 calibre.utils.logging.Log 对象。所有输出都应使用该对象。
accelerators -- 输入插件可以轻松获取的各种信息的字典，这将加快转换的后续阶段。

postprocess_book(oeb, opts, log)[源代码]¶: 调用以允许输入插件在解析书籍后执行后处理。

specialize(oeb, opts, log, output_fmt)[源代码]¶: 调用以允许输入插件将解析的书籍专门用于特定的输出格式。在 postprocess_book 之后且在解析的书上执行任何转换之前调用。

gui_configuration_widget(parent, get_option_by_name, get_option_help, db, book_id=None)[源代码]¶: 调用以创建用于在 calibre GUI 中配置此插件的小部件。该小部件必须是 PluginWidget 类的实例。有关示例，请参阅内置输入插件。

class calibre.customize.conversion.OutputFormatPlugin(*args)[源代码]¶

基类：Plugin

OutputFormatPlugins 负责将 OEB 文档（OPF+HTML）转换为输出电子书。

可以假定 OEB 文档采用 UTF-8 编码。主要操作发生在“convert”中。

type = '输出转换'¶: 该插件的类型。用于在 GUI 中对插件进行分类

supported_platforms = ['windows', 'osx', 'linux']¶: 该插件适用的平台列表。例如：['windows', 'osx', 'linux']

file_type = None¶: 该插件输出的文件类型（扩展名不带前导句点）

common_options = {<calibre.customize.conversion.OptionRecommendation object>}¶: 所有输入格式插件共享的选项。不要在子类中重写。请改用“选项”。每个选项都必须是“OptionRecommendation”的实例。

options = {}¶: 自定义此插件行为的选项。每个选项都必须是 :OptionRecommendation 的实例。

recommendations = {}¶: 一组形式为（选项名称、推荐值、推荐级别）的三元组

property description¶

str(对象='') -> str str(bytes_or_buffer[, 编码[, 错误]]) -> str

从指定对象创建一个新的字符串对象。如果指定了 encoding 或 error，则该对象必须公开一个数据缓冲区，该缓冲区将使用指定的编码和错误处理程序进行解码。否则，返回 object.__str__()（如果已定义）或 repr(object) 的结果。encoding 默认为 'utf-8'。errors 默认为 'strict'。

convert(oeb_book, output, input_plugin, opts, log)[源代码]¶

将“oeb_book”（它是“calibre.ebooks.oeb.OEBBook”的实例）的内容渲染到输出指定的文件中。

参数:

output -- 类似文件的对象或字符串。如果它是字符串，则它是可能存在或可能不存在的文件夹的路径。输出插件应将其输出写入该文件夹。如果它是类似文件的对象，则输出插件应将其输出写入文件中。
input_plugin -- 在转换传输途径开始时使用的输入插件。
opts -- 转换选项。保证具有与该插件的 OptionRecommendations 相对应的属性。
log -- 记录器。使用它打印调试/信息消息等。

specialize_options(log, opts, input_fmt)[源代码]¶: 可用于更改转换传输途径使用的转换选项的值。

specialize_css_for_output(log, opts, item, stylizer)[源代码]¶

可用于在 CSS 扁平化过程中对 CSS 进行更改。

参数:

item -- 正在处理的项目（HTML 文件）
stylizer -- 包含项目的展平样式的 Stylizer 对象。您可以通过 stylizer.style(element) 获取任何元素的样式。

gui_configuration_widget(parent, get_option_by_name, get_option_help, db, book_id=None)[源代码]¶: 调用以创建用于在 calibre GUI 中配置此插件的小部件。该小部件必须是 PluginWidget 类的实例。有关示例，请参阅内置输出插件。

设备驱动程序 ¶

所有设备驱动程序的基类是“DevicePlugin”。但是，如果您的设备将自身作为 USBMS 驱动器公开给操作系统，则您应该使用 USBMS 类，因为它实现了支持此类设备所需的所有逻辑。

class calibre.devices.interface.DevicePlugin(plugin_path)[源代码]¶

基类：Plugin

定义与电子书阅读器通信的后端应实现的接口。

type = '设备接口'¶: 该插件的类型。用于在 GUI 中对插件进行分类

FORMATS: ClassVar[list[str]] = ['lrf', 'rtf', 'pdf', 'txt']¶: 支持格式的有序列表

VENDOR_ID: ClassVar[int | list[int] | dict[int, dict[int, list[int] | None]]] = 0¶

VENDOR_ID 可以是整数、整数列表或字典。如果它是字典，则它必须是字典的字典，其形式为：

{
 integer_vendor_id : { product_id : [list of BCDs], ... },
 ...
}

PRODUCT_ID: ClassVar[int | list[int]] = 0¶: 一个整数或一个整数列表

BCD = None¶: BCD 可以是 None，不区分基于 BCD 的设备，也可以是该驱动程序支持的所有设备的 BCD 编号的列表。

THUMBNAIL_HEIGHT = 68¶: 设备上缩略图的高度

THUMBNAIL_COMPRESSION_QUALITY = 75¶: 缩略图的压缩质量。将其设置为接近 100 可以获得质量更好、压缩伪影更少的缩略图。当然，缩略图也会变大。

WANTS_UPDATED_THUMBNAILS = False¶: 如果设备支持在sync_booklists期间更新封面缩略图，则将此设置为True。将其设置为 true 将要求 device.py 在书籍匹配期间刷新封面缩略图

CAN_SET_METADATA = ['title', 'authors', 'collections']¶: 是否可以通过操作界面设置书籍的元数据。

CAN_DO_DEVICE_DB_PLUGBOARD = False¶: 设备是否可以处理 device_db 元数据插件板

path_sep = '/'¶: 设备上图书路径的路径分隔符

icon = 'reader.png'¶: 设备图标

class UserAnnotation(type, value)¶

基类：tuple

type¶: 0 号字段的别名

value¶: 1号字段的别名

OPEN_FEEDBACK_MESSAGE = None¶: 如果状态栏中没有“无”，GUI 会将其显示为消息。如果打开需要很长时间，则很有用

VIRTUAL_BOOK_EXTENSIONS = frozenset({})¶: 一组扩展是设备上的“虚拟书籍”，因此无法查看/保存/添加到书库。例如：frozenset(['kobo'])

VIRTUAL_BOOK_EXTENSION_MESSAGE = None¶: 向用户显示虚拟图书扩展的消息。

NUKE_COMMENTS = None¶: 是否删除发送到设备的书籍副本中的评论。如果不是“无”，这应该是注释将被替换的短字符串。

MANAGES_DEVICE_PRESENCE = False¶: 如果为True，则表示该驱动程序完全管理设备检测、弹出等。如果将此设置为 True，则*必须*实现 detector_managed_devices 和 debug_management_device_detection 方法。将此设置为 true 的驱动程序负责检测设备、管理设备黑名单、弹出设备列表等。 calibre 将定期调用 detector_management_devices() 方法，如果返回检测到的设备，calibre 将调用 open()。每次返回设备时都会调用 open()，即使之前对 open() 的调用失败，因此驱动程序必须维护自己的失败设备黑名单。类似地，当弹出时，calibre将调用eject()，然后假设下一次调用Detect_management_devices()返回None，它将调用post_yank_cleanup()。

SLOW_DRIVEINFO = False¶: 如果设置为 True，calibre 将在加载书籍列表后调用 get_driveinfo() 方法来获取驱动器信息。

ASK_TO_ALLOW_CONNECT = False¶: 如果设置为 True，calibre 将在第一次检测到设备时询问用户是否要使用 calibre 管理设备。如果将此设置为 True，则必须实现 get_device_uid() 和 ignore_connected_device() 以及 get_user_blacklisted_devices 和 set_user_blacklisted_devices

user_feedback_after_callback = None¶: 将其设置为 {'title':title, 'msg':msg, 'det_msg':detailed_msg} 形式的字典，以便 calibre 在运行一些回调后向用户弹出一条消息（当前仅 upload_books）。请注意不要向用户发送过多的垃圾邮件。在*每个*回调后都会检查此变量，因此仅在真正需要时才设置它。

classmethod get_open_popup_message()[源代码]¶: GUI 将其显示为非模式弹出窗口。应该是 OpenPopupMessage 的实例

classmethod model_metadata() → tuple[ModelMetadata, ...][源代码]¶: 关于此驱动程序支持的所有实际设备型号的元数据

is_usb_connected(devices_on_system, debug=False, only_presence=False)[源代码]¶

如果此插件处理的设备当前已连接，则返回 True，device_info。

参数:: devices_on_system -- 当前连接的设备列表

detect_managed_devices(devices_on_system, force_refresh=False)[源代码]¶

仅当 MANAGES_DEVICE_PRESENCE 为 True 时调用。

扫描该驱动程序可以处理的设备。如果找到设备，则应返回设备对象。该对象将作为connected_device 传递给open() 方法。如果没有找到设备，则返回 None。返回的对象可以是任何东西，calibre 不使用它，它只传递给 open()。

此方法由 GUI 定期调用，因此请确保它不会占用太多资源。使用缓存以避免重复扫描系统。

参数:

devices_on_system -- 系统上找到的 USB 设备集。
force_refresh -- 如果为 True 并且驱动程序使用缓存来防止重复扫描，则必须刷新缓存。

debug_managed_device_detection(devices_on_system, output)[源代码]¶

仅当 MANAGES_DEVICE_PRESENCE 为 True 时调用。

应该写入有关系统上检测到的设备的信息以输出，这是一个类似文件的对象。

如果检测到并成功打开设备，则应返回 True，否则返回 False。

reset(key='-1', log_packets=False, report_progress=None, detected_device=None)[源代码]¶

参数:

key -- 解锁设备的密钥
log_packets -- 如果为 true，则记录传入/传出设备的数据包流
report_progress -- 针对各种任务以百分比进度（0 到 100 之间的数字）调用的函数。如果以-1调用则表示该任务没有任何进度信息
detected_device -- 来自设备扫描仪的设备信息

can_handle_windows(usbdevice, debug=False)[源代码]¶

对设备执行进一步检查以查看该驱动程序是否能够处理它的可选方法。如果不是，则应返回 False。该方法仅在供应商、产品 ID 和 bcd 匹配后调用，因此它可以执行一些相对耗时的检查。默认实现返回 True。该方法仅在 Windows 上调用。另请参见“can_handle”。

请注意，对于基于 USBMS 的设备，此方法默认委托给“can_handle”。因此，您只需要在 USBMS 的子类中重写“can_handle”即可。

参数:: usbdevice -- 由`calibre.devices.winusb.scan_usb_devices`返回的usbdevice

can_handle(device_info, debug=False)[源代码]¶

can_handle_windows 的 Unix 版本。

参数:: device_info -- 是一个元组（vid、pid、bcd、制造商、产品、序列号）

open(connected_device, library_uuid)[源代码]¶

执行任何设备特定的初始化。在检测到设备之后但在与设备通信的任何其他函数之前调用。例如：对于将自身呈现为 USB 大容量存储设备的设备，此方法将负责安装该设备，或者如果该设备已自动安装，则负责查找其已安装的位置。方法 calibre.devices.usbms.device.Device.open 具有此函数的实现，应该作为 USB 大容量存储设备的一个很好的示例。

此方法可以引发 OpenFeedback 异常以向用户显示消息。

参数:

connected_device -- 我们正在尝试打开的设备。它是（供应商 id、产品 id、bcd、制造商名称、产品名称、设备序列号）的元组。但是，某些设备没有序列号，并且在 Windows 上仅存在前三个字段，其余字段均为“无”。
library_uuid -- 当前 calibre 库的 UUID。如果没有库（例如从命令行使用时），则可以为 None。

eject()[源代码]¶

从操作系统中卸载/弹出设备。这不会检查是否有需要与设备通信的待处理 GUI 作业。

注意：此方法可能无法与其余设备方法在同一线程上调用。

post_yank_cleanup()[源代码]¶: 如果用户拉动设备而不先弹出它，则调用。

set_progress_reporter(report_progress)[源代码]¶

设置报告进度信息的功能。

参数:: report_progress -- 针对各种任务以百分比进度（0 到 100 之间的数字）调用的函数。如果以-1调用则表示该任务没有任何进度信息

get_device_information(end_session=True)[源代码]¶

向设备询问设备信息。请参阅 L{DeviceInfoQuery}。

返回:: （设备名称、设备版本、设备上的软件版本、MIME 类型）元组可以选择包含第五个元素，它是驱动器信息字典。有关示例，请参阅 usbms.driver。

get_driveinfo()[源代码]¶: 返回driveinfo字典。通常从 get_device_information() 调用，但如果加载该驱动程序的驱动信息很慢，则应设置 SLOW_DRIVEINFO。在这种情况下，该方法将在书籍列表加载后由 calibre 调用。请注意，它不是在设备线程上调用的，因此驱动程序应在 books() 方法中缓存驱动器信息，并且该函数应返回缓存的数据。

card_prefix(end_session=True)[源代码]¶: 返回卡上路径前缀的 2 元素列表。如果不存在任何内存卡，则不会为内存卡的前缀设置“无”。例如。 ('/place', '/place2') (无, 'place2') ('place', 无) (无, 无)

total_space(end_session=True)[源代码]¶

获取安装设备上的可用总空间：

主内存
存储卡A
存储卡B

返回:: 一个 3 元素列表，总空间（以字节为单位）为 (1, 2, 3)。如果特定设备没有任何这些位置，则应返回 0。

free_space(end_session=True)[源代码]¶

获取挂载点上的可用空间：

主内存
存储卡 A
存储卡 B

返回:: 一个 3 元素列表，其可用空间以字节为单位 (1, 2, 3)。如果特定设备没有任何这些位置，则应返回 -1。

books(oncard=None, end_session=True)[源代码]¶

返回设备上的电子书列表。

参数:: oncard -- 如果“carda”或“cardb”返回特定存储卡上的电子书列表，否则返回设备主内存中的电子书列表。如果指定了卡片并且卡片上没有书籍，则返回空列表。
返回:: 书单。

upload_books(files, names, on_card=None, end_session=True, metadata=None)[源代码]¶

将图书列表上传到设备。如果设备上已存在文件，则应替换该文件。如果设备上没有足够的可用空间，此方法应该引发“FreeSpaceError”。如果 on_card 不是 None，则 FreeSpaceError 的文本必须包含单词“card”，否则它必须包含单词“memory”。

参数:

files -- 路径列表
names -- 书籍应上传到设备的文件名列表。 len(名称) == len(文件)
metadata -- 如果不是 None，则它是“Metadata”对象的列表。这个想法是使用元数据来确定将书籍放置在设备上的位置。 len(元数据) == len(文件). 除了常规封面（封面路径）之外，还可能存在缩略图属性，应优先使用该属性。缩略图属性的形式为（宽度、高度、cover_data as jpeg）。

返回:

三元素元组的列表。该列表旨在传递给“add_books_to_metadata”。

classmethod add_books_to_metadata(locations, metadata, booklists)[源代码]¶

将位置添加到书单中。此功能不得与设备通信。

参数:

locations -- 调用 L{upload_books} 的结果
metadata -- Metadata 对象列表，与 upload_books 相同。
booklists -- 包含调用结果的元组 (books(oncard=None)、books(oncard='carda')、books(oncard='cardb'))。

delete_books(paths, end_session=True)[源代码]¶: 删除设备上路径中的书籍。

classmethod remove_books_from_metadata(paths, booklists)[源代码]¶

从元数据列表中删除书籍。此功能不得与设备通信。

参数:

paths -- 设备上书籍的路径。
booklists -- 包含调用结果的元组 (books(oncard=None)、books(oncard='carda')、books(oncard='cardb'))。

sync_booklists(booklists, end_session=True)[源代码]¶

更新设备上的元数据。

参数:: booklists -- 包含调用结果的元组 (books(oncard=None)、books(oncard='carda')、books(oncard='cardb'))。

get_file(path, outfile, end_session=True)[源代码]¶

读取设备上“path”处的文件并将其写入输出文件。

参数:: outfile -- 文件对象，如“sys.stdout”或“open”调用的结果。

config_widget()[源代码]¶: 应该返回一个 QWidget。 QWidget 包含设备界面的设置

save_settings(config_widget)[源代码]¶: 应将设置保存到磁盘。获取在`config_widget`中创建的小部件并将所有设置保存到磁盘。

classmethod settings()[源代码]¶: 应该返回一个 opts 对象。 opts 对象应该至少有一个属性“format_map”，它是设备格式的有序列表。

set_plugboards(plugboards, pb_func)[源代码]¶

为驱动程序提供当前的一组插板以及选择特定插板的函数。该方法在 add_books 和sync_booklists 之前立即调用。

pb_func 是具有以下签名的可调用函数：: def pb_func(设备名称、格式、插件板)

您为其提供当前设备名称（类名或 DEVICE_PLUGBOARD_NAME）、您感兴趣的格式（“真实”格式或“device_db”）以及插件板（这些都是由set_plugboard提供的，与您获得此方法的位置相同）。

返回:: 无或单个插件板实例。

set_driveinfo_name(location_code, name)[源代码]¶

将driveinfo 文件中的设备名称设置为“name”。此设置将持续存在，直到重新创建文件或再次更改名称。

非磁盘设备应根据 get_device_information() 方法返回的位置代码来实现此方法。

prepare_addable_books(paths)[源代码]¶

给定一个路径列表，返回另一个路径列表。这些路径指向书籍的可添加版本。

如果准备一本书时出现错误，则该书返回的列表中的位置应为三元组，而不是路径：（original_path、异常实例、traceback）

startup()[源代码]¶: 当 calibre 启动设备时调用。执行任何所需的初始化。请注意，可以实例化该类的多个实例，因此可以多次调用 __init__ ，但只有一个实例会调用此方法。该方法在设备线程上调用，而不是在 GUI 线程上调用。

shutdown()[源代码]¶: 当 calibre 关闭时调用，无论是永久关闭还是准备重新启动。进行任何所需的清理。该方法在设备线程上调用，而不是在 GUI 线程上调用。

get_device_uid()[源代码]¶: 必须返回当前连接设备的唯一 ID（这在成功调用 open() 后立即调用）。如果设置 ASK_TO_ALLOW_CONNECT = True，则必须实现此方法

ignore_connected_device(uid)[源代码]¶: 将来应该忽略 uid（调用 get_device_uid() 的结果）标识的设备。如果设置 ASK_TO_ALLOW_CONNECT = True，则必须实现此方法。请注意，此函数在 open() 之后立即调用，因此如果 open() 缓存某些状态，驱动程序应重置该状态。

get_user_blacklisted_devices()[源代码]¶: 将设备 uid 映射返回到用户要求忽略的所有设备的友好名称。

set_user_blacklisted_devices(devices)[源代码]¶: 设置该驱动程序应忽略的设备 uid 列表。

specialize_global_preferences(device_prefs)[源代码]¶: 如果您的设备想要覆盖特定首选项，请实现此方法。您必须确保所有需要可覆盖首选项的调用站点都使用 device_prefs['something'] 而不是 prefs['something']。您的方法应调用 device_prefs.set_overrides(pref=val, pref=val, ...)。目前用于：元数据管理(prefs['manage_device_metadata'])

set_library_info(library_name, library_uuid, field_metadata)[源代码]¶: 如果您想要有关当前 calibre 库的信息，请实现此方法。该方法在启动时以及连接时 calibre 库发生更改时调用。

is_dynamically_controllable()[源代码]¶

启动插件时由设备管理器调用。如果此方法返回一个字符串，则 a) 它支持设备管理器的动态控制接口，b) 与插件对话时将使用该名称。