插件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 = (7, 20, 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 = (7, 20, 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 的结果将被忽略

is_configured()[源代码]

如果您的插件需要先配置才能使用,则返回 False。 例如,它可能需要用户名/密码/API 密钥。

customization_help()[源代码]

返回一个字符串,提供有关如何自定义此插件的帮助。 默认情况下会引发“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={})[源代码]

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

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

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

identify(log, result_queue, abort, title=None, authors=None, identifiers={}, 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={}, 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 中对插件进行分类

can_be_disabled = False

如果为 False,用户将无法禁用此插件。 小心使用。

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 中对插件进行分类

can_be_disabled = False

如果为 False,用户将无法禁用此插件。 小心使用。

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

从给定对象创建一个新的字符串对象。如果指定了编码或错误,则对象必须公开将使用给定编码和错误处理程序解码的数据缓冲区。否则,返回返回object.__str__()(如果已定义)或repr(对象)的结果。编码默认为sys.getdefaultencoding()。错误默认为“严格”。

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 = ['lrf', 'rtf', 'pdf', 'txt']

支持格式的有序列表

VENDOR_ID = 0

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

{
 integer_vendor_id : { product_id : [list of BCDs], ... },
 ...
}
PRODUCT_ID = 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'

设备图标

UserAnnotation

Annotation 的别名

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_devicesset_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 的实例

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)[源代码]
获取安装设备上的可用总空间:
  1. 主内存

  2. 存储卡A

  3. 存储卡B

返回:

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

free_space(end_session=True)[源代码]
获取挂载点上的可用空间:
  1. 主内存

  2. 存储卡 A

  3. 存储卡 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”调用的结果。

classmethod config_widget()[源代码]

应该返回一个 QWidget。 QWidget 包含设备界面的设置

classmethod save_settings(settings_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) 与插件对话时将使用该名称。

该方法可以在GUI线程上调用。 实现此方法的驱动程序必须是线程安全的。

start_plugin()[源代码]

调用此方法来启动插件。 该插件应该开始接受设备连接,但它确实这样做了。 如果插件已经接受连接,则不执行任何操作。

该方法可以在GUI线程上调用。 实现此方法的驱动程序必须是线程安全的。

stop_plugin()[源代码]

调用此方法来停止插件。 该插件不应再接受连接,并且应在其自身后面进行清理。 这个方法很可能应该调用 shutdown。 如果插件已经不接受连接,则不执行任何操作。

该方法可以在GUI线程上调用。 实现此方法的驱动程序必须是线程安全的。

get_option(opt_string, default=None)[源代码]

返回 opt_string 指示的选项的值。 该方法可以在插件未启动时调用。 如果选项不存在,则返回 None。

该方法可以在GUI线程上调用。 实现此方法的驱动程序必须是线程安全的。

set_option(opt_string, opt_value)[源代码]

设置 opt_string 指示的选项的值。 该方法可以在插件未启动时调用。

该方法可以在GUI线程上调用。 实现此方法的驱动程序必须是线程安全的。

is_running()[源代码]

如果插件启动则返回 True,否则返回 false

该方法可以在GUI线程上调用。 实现此方法的驱动程序必须是线程安全的。

synchronize_with_db(db, book_id, book_metadata, first_call)[源代码]

当设备上的书籍与 calibre 数据库中的书籍匹配时在书籍匹配期间调用。 该方法负责将数据从设备同步到 calibre 的数据库(如果需要)。

该方法必须返回一个二值元组。 第一个值是一组 calibre 书籍 ID,如果 calibre 的数据库已更改,如果数据库未更改,则为“无”。 如果第一个值是空集,则设备上书籍的元数据将使用 calibre 的元数据进行更新并返回给设备,但不会对该书籍进行 GUI 刷新。 当口径数据正确但必须发送到设备时,这非常有用。

第二个值本身就是一个 2 值元组。 元组中的第一个值指定是否应将书籍格式发送到设备。 目的是允许验证设备上的书与书的口径相同。 如果不发送书籍,则该值必须为 None,否则返回设备上的基本文件名(类似 foobar.epub 的字符串)。 请务必在名称中包含扩展名。 设备子系统将为所有返回值非 None 的书籍构造一个 send_books 作业。 注意:除了稍后检索扩展名之外,在设备使用模板生成文件名的情况下(大多数设备都会这样做),该名称将被忽略。 返回元组中的第二个值指示格式是否是未来的。 如果是则返回 True,否则返回 False。 calibre 将向用户显示一个对话框,列出所有未来日期的书籍。

极其重要:该方法在 GUI 线程上调用。 对于设备管理器的线程来说,它必须是线程安全的。

book_id:数据库中书籍的 calibre id。 book_metadata:来自设备的书籍的元数据对象。 first_call:如果这是同步期间的第一次调用,则为 True,否则为 False

class calibre.devices.interface.BookList(oncard, prefix, settings)[源代码]

基类:list

书籍清单。 每个 Book 对象必须具有字段

  1. 书名

  2. 作者

  3. 大小(书籍文件大小)

  4. 日期时间(UTC 时间元组)

  5. 路径(设备上书籍的路径)

  6. 缩略图(可以为 None)缩略图是带有图像数据的 str/bytes 对象,或者它应该有一个属性 image_path 来存储图像的绝对(平台本机)路径

  7. 标签(字符串列表,可以为空)。

supports_collections()[源代码]

如果设备支持此图书列表的集合,则返回 True。

add_book(book, replace_metadata)[源代码]

将书添加到书单中。 目的是维护任何设备内部元数据。 如果必须同步书单则返回 True

remove_book(book)[源代码]

从书单中删除一本书。 同时更正任何设备元数据

get_collections(collection_attributes)[源代码]

返回从 collection_attributes 创建的集合的字典。 字典中的每个条目的形式为集合名称:[书籍列表]

书籍列表按书名排序,但从系列创建的集合除外,在这种情况下使用 series_index。

参数:

collection_attributes -- Book 对象的属性列表

基于USB大容量存储的设备

此类设备的基类是“calibre.devices.usbms.driver.USBMS”。 该类又从其基类继承了一些功能,如下所述。 典型的基于 USBMS 的驱动程序如下所示:

from calibre.devices.usbms.driver import USBMS

class PDNOVEL(USBMS):
    name = 'Pandigital Novel device interface'
    gui_name = 'PD Novel'
    description = _('Communicate with the Pandigital Novel')
    author = 'Kovid Goyal'
    supported_platforms = ['windows', 'linux', 'osx']
    FORMATS = ['epub', 'pdf']

    VENDOR_ID   = [0x18d1]
    PRODUCT_ID  = [0xb004]
    BCD         = [0x224]

    THUMBNAIL_HEIGHT = 144

    EBOOK_DIR_MAIN = 'eBooks'
    SUPPORTS_SUB_DIRS = False

    def upload_cover(self, path, filename, metadata):
        coverdata = getattr(metadata, 'thumbnail', None)
        if coverdata and coverdata[2]:
            with open('%s.jpg' % os.path.join(path, filename), 'wb') as coverfile:
                coverfile.write(coverdata[2])
class calibre.devices.usbms.device.Device(plugin_path)[源代码]

基类:DeviceConfig, DevicePlugin

此类为将自身导出为 USB 大容量存储设备的设备的所有驱动程序提供通用逻辑。 提供在所有平台上安装/弹出 USBMS 设备的实现。

VENDOR_ID = 0

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

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

一个整数或一个整数列表

BCD = None

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

WINDOWS_MAIN_MEM = None

Windows PnP id 字符串中标识设备主内存的字符串 这可以是 None、字符串、字符串列表或已编译的正则表达式

WINDOWS_CARD_A_MEM = None

标识 Windows PnP id 字符串中设备的第一张卡的字符串 这可以是 None、字符串、字符串列表或已编译的正则表达式

WINDOWS_CARD_B_MEM = None

标识 Windows PnP id 字符串中设备的第二张卡的字符串 这可以是 None、字符串、字符串列表或已编译的正则表达式

OSX_MAIN_MEM_VOL_PAT = None

新驱动程序检测使用它来区分主内存和存储卡。 应该是与 macOS 分配的主内存挂载点匹配的正则表达式

BACKLOADING_ERROR_MESSAGE = None
MAX_PATH_LEN = 250

设备上创建的路径的最大长度

NEWS_IN_FOLDER = True

将新闻放在自己的文件夹中

reset(key='-1', log_packets=False, report_progress=None, detected_device=None)[源代码]
参数:
  • key -- 解锁设备的密钥

  • log_packets -- 如果为 true,则记录传入/传出设备的数据包流

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

  • detected_device -- 来自设备扫描仪的设备信息

set_progress_reporter(report_progress)[源代码]

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

参数:

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

card_prefix(end_session=True)[源代码]

返回卡上路径前缀的 2 元素列表。 如果不存在任何内存卡,则不会为内存卡的前缀设置“无”。 例如。 ('/place', '/place2') (无, 'place2') ('place', 无) (无, 无)

total_space(end_session=True)[源代码]
获取安装设备上的可用总空间:
  1. 主内存

  2. 存储卡A

  3. 存储卡B

返回:

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

free_space(end_session=True)[源代码]
获取挂载点上的可用空间:
  1. 主内存

  2. 存储卡 A

  3. 存储卡 B

返回:

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

windows_sort_drives(drives)[源代码]

调用以消除不根据“WINDOWS_CARD_NAME”区分主内存和存储卡的设备的歧义。 例如:EB600

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

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()[源代码]

如果用户拉动设备而不先弹出它,则调用。

sanitize_callback(path)[源代码]

允许各个设备驱动程序覆盖“create_upload_path”使用的路径清理的回调。

filename_callback(default, mi)[源代码]

允许驱动程序更改“create_upload_path”设置的默认文件名的回调。

sanitize_path_components(components)[源代码]

对要上传到设备的文件的路径组件执行任何设备特定的清理

get_annotations(path_map)[源代码]

将设备上找到的文件的path_map解析为annotation_map

add_annotation_to_library(db, db_id, annotation)[源代码]

向 calibre 书库添加注释

class calibre.devices.usbms.cli.CLI[源代码]
class calibre.devices.usbms.driver.USBMS(plugin_path)[源代码]

基类:CLI, Device

所有 USBMS 设备的基类。 实现发送/获取/更新元数据/缓存元数据等的逻辑。

description = '与一个电子书阅读器通信。'

描述此插件功能的短字符串

author = 'John Schember'

这个插件的作者

supported_platforms = ['windows', 'osx', 'linux']

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

booklist_class

BookList 的别名

book_class

Book 的别名

FORMATS = []

支持格式的有序列表

CAN_SET_METADATA = []

是否可以通过操作界面设置书籍的元数据。

get_device_information(end_session=True)[源代码]

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

返回:

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

set_driveinfo_name(location_code, name)[源代码]

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

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

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”。

upload_cover(path, filename, metadata, filepath)[源代码]

将书籍封面上传到设备。 默认实现不执行任何操作。

参数:
  • path -- 关联书籍所在文件夹的完整路径。

  • filename -- 不带扩展名的图书文件的名称。

  • metadata -- 属于本书的元数据。 使用metadata.thumbnail作为封面

  • filepath -- 电子书文件的完整路径

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)[源代码]

删除设备上路径中的书籍。

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'))。

classmethod normalize_path(path)[源代码]

带有平台本机路径分隔符的返回路径

用户界面操作

如果您要在 ZIP 文件中添加自己的插件,则应该对 InterfaceActionBase 和 InterfaceAction 进行子类化。 InterfaceActionBase 子类的 load_actual_plugin 方法必须返回 InterfaceBase 子类的实例化对象。

class calibre.gui2.actions.InterfaceAction(parent, site_customization)[源代码]

基类:QObject

代表可以在图形用户界面中执行的“操作”的插件。 工具栏和上下文菜单中的所有项目都是由这些插件实现的。

请注意,此类是这些插件的基类,但是,要将插件与 calibre 的插件系统集成,您必须创建一个引用实际插件的包装类。 有关示例,请参阅“calibre.customize.builtins”模块。

如果两个“InterfaceAction”对象具有相同的名称,则优先级较高的对象优先。

子类应该实现 genesislibrary_changedlocation_selectedshutting_downinitialization_completetag_browser_context_action 方法。

初始化后,该插件可以通过“gui”成员访问主 calibre GUI。 您可以通过名称访问其他插件,例如:

self.gui.iactions['Save To Disk']

要访问实际的插件,请使用“interface_action_base_plugin”属性,该属性仅在插件初始化后才可用。 如果您想使用插件类中的方法,例如 do_user_config(),则很有用。

由“action_spec”指定的 QAction 会自动创建并以“self.qaction”形式提供。

name = 'Implement me'

插件名称。 如果存在两个同名插件,则优先级较高的插件优先。

priority = 1

插件优先级。 如果存在两个同名插件,则优先级较高的插件优先。

popup_type = 1

将此插件添加到工具栏时的菜单弹出类型

auto_repeat = False

按住快捷键时是否自动重复此操作。

action_spec = ('text', 'icon', None, None)

形式为:(文本、图标路径、工具提示、键盘快捷键)。 图标、工具提示和键盘快捷键可以为“无”。 键盘快捷键必须是字符串、None 或快捷键元组。 如果为“无”,则不会注册与该操作对应的键盘快捷键。 如果传递空元组,则注册快捷方式时没有默认键绑定。

action_shortcut_name = None

如果不是 None,则用于在自定义上述操作规范的键盘快捷键时向用户显示的名称,而不是 action_spec[0]

action_add_menu = False

如果为 True,则会自动创建菜单并将其添加到 self.qaction

action_menu_clone_qaction = False

如果为 True,则将 self.qaction 的克隆添加到 self.qaction 的菜单中。如果您希望此操作的文本与 self.qaction 的文本不同,请将此变量设置为新文本

dont_add_to = frozenset({})

不得添加此操作的位置集。 请参阅“all_locations”以获取可能位置的列表

dont_remove_from = frozenset({})

不得删除此操作的一组位置。 请参阅“all_locations”以获取可能位置的列表

action_type = 'global'

操作类型 “当前”表示作用于当前视图 “全局”表示操作不作用于当前视图,而是作用于整个 calibre

accepts_drops = False

如果为 True,则此 InterfaceAction 将有机会与拖放事件进行交互。 有关详细信息,请参阅方法“accept_enter_event”、“accept_drag_move_event”、“drop_event”。

accept_enter_event(event, mime_data)[源代码]

当且仅当此界面操作能够处理拖动事件时,此方法应返回 True。 不要对事件调用接受/忽略,这将由 calibre UI 处理。

accept_drag_move_event(event, mime_data)[源代码]

当且仅当此界面操作能够处理拖动事件时,此方法应返回 True。 不要对事件调用接受/忽略,这将由 calibre UI 处理。

drop_event(event, mime_data)[源代码]

当且仅当该接口操作能够处理放置事件时,此方法应该执行一些有用的操作并返回 True。 不要对事件调用接受/忽略,这将由 calibre UI 处理。 您不应在此函数中执行阻塞/长操作。 相反,发出信号或使用 QTimer.singleShot 并快速返回。 请参阅内置操作的示例。

create_menu_action(menu, unique_name, text, icon=None, shortcut=None, description=None, triggered=None, shortcut_name=None, persist_shortcut=False)[源代码]

轻松向 QMenu 添加操作的便捷方法。 返回创建的 QAction。 此操作有一个额外的属性 calibre_shortcut_unique_name,如果不是 None,则指的是此操作在键盘管理器中注册的唯一名称。

参数:
  • menu -- 新创建的操作将添加到 QMenu

  • unique_name -- 此操作的唯一名称,必须是全局唯一的,因此请使其尽可能具有描述性。 如果有疑问,请添加 UUID。

  • text -- 操作的文本。

  • icon -- QIcon 或文件名。 文件名将传递给 QIcon.ic() 内置函数,因此您无需传递图像文件夹的完整路径。

  • shortcut -- 一个字符串、字符串列表、None 或 False。 如果为 False,则不会为此操作注册键盘快捷键。 如果为“无”,则注册没有默认键绑定的键盘快捷键。 字符串和字符串列表使用指定的默认键绑定注册快捷方式。

  • description -- 此操作的描述。 用于设置工具提示。

  • triggered -- 连接到所创建操作的触发信号的可调用对象。

  • shortcut_name -- 自定义此操作的键盘快捷键时向用户显示的文本。 默认情况下,它设置为“text”的值。

  • persist_shortcut -- 编辑其他键盘快捷键时,并不总是出现或依赖于库的操作的快捷键可能会消失,除非将 `persist_shortcut` 设置为 True。

load_resources(names)[源代码]

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

例如加载图像:

pixmap = QPixmap()
pixmap.loadFromData(tuple(self.load_resources(['images/icon.png']).values())[0])
icon = QIcon(pixmap)
参数:

names -- ZIP 文件中资源的路径列表,使用 / 作为分隔符

返回:

形式为“{name : file_contents}”的字典。 ZIP 文件中未找到的任何名称都不会出现在字典中。

genesis()[源代码]

设置这个插件。 仅在初始化期间调用一次。 self.gui 可用。 action_spec 指定的操作可作为 self.qaction 使用。

location_selected(loc)[源代码]

每当以 calibre 显示的图书列表发生变化时调用。 当前 loc 的值为:“library、main、card 和 cardb”。

此方法应根据位置启用/禁用此操作及其子操作。

library_about_to_change(olddb, db)[源代码]

每当当前库发生更改时调用。

参数:
  • olddb -- 与之前的库对应的LibraryDatabase。

  • db -- 新书库对应的LibraryDatabase。

library_changed(db)[源代码]

每当当前库发生更改时调用。

参数:

db -- 当前书库对应的LibraryDatabase。

gui_layout_complete()[源代码]

当主 GUI 布局完成时,每个操作调用一次。 如果您的操作需要对布局进行更改,则应该在此处完成,而不是在“initialization_complete”中完成。

initialization_complete()[源代码]

当主 GUI 初始化完成时,每个操作调用一次。

tag_browser_context_action(index)[源代码]

在标签浏览器中显示上下文菜单时调用。 index 是指向右键单击的标签浏览器项的 QModelIndex。 使用index.valid()测试其有效性,并使用index.data(Qt.ItemDataRole.UserRole)获取底层TagTreeItem对象。 此方法生成的任何操作对象都将添加到上下文菜单中。

shutting_down()[源代码]

当主 GUI 正在关闭时,每个插件调用一次。 释放所有使用的资源,但尽量不要长时间阻止关闭。

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

基类:Plugin

supported_platforms = ['windows', 'osx', 'linux']

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

author = 'Kovid Goyal'

这个插件的作者

type = '用户界面操作'

该插件的类型。 用于在 GUI 中对插件进行分类

can_be_disabled = False

如果为 False,用户将无法禁用此插件。 小心使用。

load_actual_plugin(gui)[源代码]

该方法必须返回实际的界面操作插件对象。

首选项插件

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

基类:Plugin

代表“首选项”对话框中显示的小部件的插件。

这个插件只有一个重要的方法“create_widget”。 插件的各个字段控制它在 UI 中的分类方式。

supported_platforms = ['windows', 'osx', 'linux']

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

author = 'Kovid Goyal'

这个插件的作者

type = '首选项'

该插件的类型。 用于在 GUI 中对插件进行分类

can_be_disabled = False

如果为 False,用户将无法禁用此插件。 小心使用。

config_widget = None

包含名为 ConfigWidget 的类(实现 ConfigWidgetInterface)的模块的导入路径。 由“create_widget”使用。

category_order = 100

该插件的“类别”应位于类别列表中的位置。

name_order = 100

在类别中的名称列表中,该插件的“gui_name”应该是

category = None

该插件应该属于的类别

gui_category = None

该插件向用户显示的类别名称

gui_name = None

该插件向用户显示的名称

icon = None

该插件的图标应该是绝对路径

description = None

用于工具提示等的描述

create_widget(parent=None)[源代码]

创建并返回用于设置这组首选项的实际 Qt 小部件。 小部件必须实现 calibre.gui2.preferences.ConfigWidgetInterface

默认实现使用“config_widget”来实例化小部件。

class calibre.gui2.preferences.ConfigWidgetInterface[源代码]

此类定义“首选项”对话框中显示的所有小部件都必须实现的接口。 请参阅“ConfigWidgetBase”了解实现此接口并定义各种便捷方法的基类。

changed_signal = None

每当用户更改此小部件中的值时,都必须发出此信号

supports_restoring_to_defaults = True

当且仅当执行了 restore_to_defaults 方法时设置为 True。

restore_defaults_desc = '将设置还原为默认值。您必须点击“应用”以实际保存默认设置。'

“恢复默认值”按钮的工具提示

restart_critical = False

如果为 True,首选项对话框将不允许用户设置更多首选项。 仅当“commit”返回 True 时才有效。

genesis(gui)[源代码]

在显示小部件之前调用一次,应执行任何必要的设置。

参数:

gui -- calibre主要图形用户界面

initialize()[源代码]

应该将所有配置值设置为其初始值(存储在配置文件中的值)。 “返回”语句是可选的。 如果不显示对话框,则返回 False。

restore_defaults()[源代码]

应该将所有配置值设置为默认值。

commit()[源代码]

保存所有更改的设置。 如果更改需要重新启动,则返回 True,否则返回 False。 引发“AbortCommit”异常以指示发生错误。 您有责任向用户提供有关错误是什么以及如何纠正错误的反馈。

refresh_gui(gui)[源代码]

提交此小部件后调用一次。 负责使 GUI 重新读取任何更改的设置。 请注意,默认情况下 GUI 无论如何都会重新初始化各种元素,因此大多数小部件不需要使用此方法。

initial_tab_changed()[源代码]

如果在小部件显示之前但初始化之后更改了最初显示的选项卡,则调用。

class calibre.gui2.preferences.ConfigWidgetBase(parent=None)[源代码]

包含用于轻松添加标准配置小部件的代码的基类,如复选框、组合框、文本字段等。 请参阅“注册”方法。

此类自动处理注册设置的更改通知、重置为默认值、gui 对象和配置对象之间的转换等。

如果您的配置小部件继承自此类,但包含未注册的设置,则应覆盖“ConfigWidgetInterface”方法并调用覆盖内的基类方法。

changed_signal

每当用户更改此小部件中的值时,都必须发出此信号

supports_restoring_to_defaults = True

当且仅当执行了 restore_to_defaults 方法时设置为 True。

restart_critical = False

如果为 True,首选项对话框将不允许用户设置更多首选项。 仅当“commit”返回 True 时才有效。

register(name, config_obj, gui_name=None, choices=None, restart_required=False, empty_string_is_None=True, setting=<class 'calibre.gui2.preferences.Setting'>)[源代码]

注册设置。

参数:
  • name -- 设置名称

  • config_obj -- 读取/写入设置的配置对象

  • gui_name -- 提供更改设置界面的 GUI 对象的名称。 默认情况下,假定为``'opt_' + name``。

  • choices -- 如果此设置是基于多项选择(组合框)的设置,则为选项列表。 该列表是两个元素元组的列表,其形式为:[(gui name, value), ...]

  • setting -- 负责管理此设置的类。 默认类处理几乎所有情况,因此很少使用此参数。

initialize()[源代码]

应该将所有配置值设置为其初始值(存储在配置文件中的值)。 “返回”语句是可选的。 如果不显示对话框,则返回 False。

commit(*args)[源代码]

保存所有更改的设置。 如果更改需要重新启动,则返回 True,否则返回 False。 引发“AbortCommit”异常以指示发生错误。 您有责任向用户提供有关错误是什么以及如何纠正错误的反馈。

restore_defaults(*args)[源代码]

应该将所有配置值设置为默认值。