API文档之数据库接口

此API是线程安全的(它使用多个读取器、单个写入器锁定方案)。您可以通过如下方式访问该API接口：

from calibre.library import db
db = db('Path to calibre library folder').new_api

如果您使用的Calibre插件是主Calibre图形用户界面的一部分，则可以通过以下方式访问该插件：

db = self.gui.current_db.new_api

class calibre.db.cache.Cache(backend, library_database_instance=None)

来自 calibre 库的metadata.db 文件的内存缓存。 该类还充当用于访问数据库的线程安全 API。 内存中的缓存以正常形式维护，以获得最佳性能。

SQLITE 只是用作从metadata.db 稳健地读取和写入的一种方式。 所有表读取/排序/搜索/缓存逻辑都被重新实现。 这是获得最大性能和灵活性所必需的。

class EventType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

book_created = 4

当数据库中创建新的图书记录时，图书 id 作为唯一参数

book_edited = 8

编辑书籍格式时, 使用参数: (book_id, fmt)

books_removed = 5

当书籍从数据库中删除时，书籍 ID 列表作为唯一参数

format_added = 2

当为书籍添加一种格式时, 使用参数: (book_id, fmt)

formats_removed = 3

当从书中删除格式时，带有参数：（将图书 ID 映射到从书中删除的格式集）

indexing_progress_changed = 9

当索引进度发生变化时

items_removed = 7

当标签或作者等项目从某些书籍中删除时。 参数：（字段名称、受影响的图书 ID、已删除项目的 ID）

items_renamed = 6

当某些或所有书籍中的标签或作者等项目被重命名时。 参数：（字段名称、受影响的图书 ID、旧项目 ID 到新项目 ID 的映射）

metadata_changed = 1

当某些书籍的某些元数据发生更改时，带有参数：（更改字段的名称，受影响的书籍 ID 集）

add_books(books, add_duplicates=True, apply_import_tags=True, preserve_uuid=False, run_hooks=True, dbapi=None)

将指定的书籍添加到图书馆。 Books 应该是一个可迭代的 2 元组，每个 2 元组的形式为“(mi, format_map)”，其中 mi 是元数据对象，format_map 是“{fmt: path_or_stream}”形式的字典，例如： {‘EPUB’: ‘/path/to/file.epub’}`。

返回一对列表：“ids，duplicates”。 ids 包含数据库中所有新创建的图书的图书 ID。 根据“has_book”使用的简单重复检测启发式，“duplicates”包含数据库中已存在的所有书籍的“(mi, format_map)”。

add_custom_book_data(name, val_map, delete_first=False)

添加 name 数据，其中 val_map 是 book_ids 到值的映射。 如果delete_first为True，则所有先前存储的name数据将被删除。

add_extra_files(book_id, map_of_relpath_to_stream_or_path, replace=True, auto_rename=False)

添加额外的数据文件

add_format(book_id, fmt, stream_or_path, replace=True, run_hooks=True, dbapi=None)

为指定的书籍添加格式。 如果格式添加成功，则返回 True。

参数:

• replace – 如果为 True 则替换现有格式，否则如果该格式已存在，则返回 False。

• run_hooks – 如果为 True，则文件类型插件将在添加之前和之后的格式上运行。

• dbapi – 仅内部使用。

add_listener(event_callback_function, check_already_added=False)

注册一个回调函数，该函数将在对此数据库执行某些操作后调用。 该函数必须采用三个参数：(EventType、library_id、event_type_specific_data)

add_notes_resource(path_or_stream_or_data, name: str, mtime: float = None) → int

添加指定的资源，以便它可以被注释引用并返回其内容哈希

all_book_ids(type=<class 'frozenset'>)

所有已知图书 ID 的冻结集。

all_field_for(field, book_ids, default_value=None)

与 field_for 相同，只不过它同时对多本书进行操作

all_field_ids(name)

字段“name”中所有值的冻结 ID 集。

all_field_names(field)

所有字段名称的冻结集（仅应用于多一和多对多字段）

author_data(author_ids=None)

将作者数据作为带有键的字典返回：名称、排序、链接

如果没有找到具有指定 ID 的作者，则返回空字典。 如果author_ids为None，则返回所有作者的数据。

author_sort_from_authors(authors, key_func=<function make_change_case_func.<locals>.change_case>)

给定一个作者列表，返回作者的author_sort字符串，优先选择与作者关联的作者排序而不是计算出的字符串。

books_for_field(name, item_id)

返回与由“item_id”标识的项目关联的所有书籍，其中该项目属于字段“name”。

返回值是一组图书 ID，如果该项目或字段不存在，则返回空集。

books_in_virtual_library(vl, search_restriction=None, virtual_fields=None)

返回指定虚拟书库的图书

compress_covers(book_ids, jpeg_quality=100, progress_callback=None)

压缩指定书籍的封面图像。 压缩质量为 100 将执行无损压缩，否则将执行有损压缩。

将使用 book_id 以及已处理的每本书的旧尺寸和新尺寸来调用进度回调。 如果发生错误，新的大小将是包含错误详细信息的字符串。

copy_cover_to(book_id, dest, use_hardlink=False, report_file_size=None)

将封面复制到文件中，如对象“dest”。 如果不存在封面或 dest 与当前封面是同一文件，则返回 False。 dest 也可以是路径，在这种情况下，当且仅当该路径与当前路径不同时（考虑区分大小写），封面才会被复制到该路径。

copy_format_to(book_id, fmt, dest, use_hardlink=False, report_file_size=None)

将格式“fmt”复制到文件中，如对象“dest”。 如果指定的格式不存在，则会引发“NoSuchFormat”错误。 dest 也可以是路径（到文件），在这种情况下，格式将复制到其中，前提是该路径与当前路径不同（考虑区分大小写）。

cover(book_id, as_file=False, as_image=False, as_path=False, as_pixmap=False)

返回封面图像或无。 默认情况下，以字节字符串形式返回封面。

警告：使用 as_path 会将封面复制到临时文件并返回临时文件的路径。 使用完临时文件后，您应该将其删除。

参数:

• as_file – 如果为 True，则将图像作为打开的文件对象（SpooledTemporaryFile）返回

• as_image – 如果 True 将图像返回为 QImage 对象

• as_pixmap – 如果 True 返回图像作为 QPixmap 对象

• as_path – 如果为 True，则将图像作为指向临时文件的路径返回

data_for_find_identical_books()

返回可用于在工作进程中实现“find_identical_books”的数据，而无需访问数据库。 有关执行，请参阅 db.utils。

data_for_has_book()

返回适合在“has_book”中使用的数据。 这可用于在工作进程中实现“has_book”，而无需访问数据库。

delete_custom_book_data(name, book_ids=())

删除名称数据。 默认情况下删除所有数据，如果只想删除某些图书 ID 的数据，请传入图书 ID 列表。

delete_trash_entry(book_id, category)

从垃圾箱中删除条目。 这里的类别是“b”代表书籍，“f”代表格式。

embed_metadata(book_ids, only_fmts=None, report_error=None, report_progress=None)

将指定book_ids的所有格式的元数据更新为数据库中的当前元数据。

expire_old_trash()

使垃圾箱中太旧的条目过期

export_note(field, item_id) → str

将注释导出为单个 HTML 文档，并嵌入图像作为数据：URL

fast_field_for(field_obj, book_id, default_value=None)

与 field_for 相同，只不过它避免了获取字段对象的额外查找

field_for(name, book_id, default_value=None)

返回由“book_id”标识的书籍的字段“name”的值。 如果不存在这样的书，或者没有为字段“name”定义值，或者不存在这样的字段，则返回“default_value”。

“default_value” 不用于标题、title_sort、作者、author_sort 和 series_index。 这是因为这些在数据库中总是有值。 “default_value” 用于所有自定义列。

is_multiple 字段的返回值始终是元组，即使未找到任何值（换句话说，default_value 被忽略）。 例外情况是返回值始终是字典的标识符。 返回的元组始终按链接顺序排列，即它们的创建顺序。

field_ids_for(name, book_id)

返回由“book_id”标识的书籍上“name”字段的值的 ids（作为元组）。 如果没有值，或者没有这样的书，或者没有这样的字段，则返回一个空元组。

field_supports_notes(field=None) → bool

当且仅当指定字段支持注释时返回 True。 如果字段为“无”，则返回支持注释的所有字段的冻结集。

find_identical_books(mi, search_restriction='', book_ids=None)

查找mi中具有作者超集且标题相同的图书(标题是模糊匹配的)。另请参阅`data_for_find_aligant_books`。

format(book_id, fmt, as_file=False, as_path=False, preserve_filename=False)

以字节串形式返回电子书格式，如果格式不存在，或者我们没有写入电子书文件的权限，则返回“None”。

参数:

• as_file – 如果为 True，则电子书格式作为文件对象返回。 请注意，文件对象是 SpooledTemporaryFile，因此如果您想要将格式复制到另一个文件，请使用“copy_format_to”代替以提高性能。

• as_path – 将格式文件复制到临时文件并返回临时文件的路径

• preserve_filename – 如果为 True 并返回路径，则文件名与库中使用的文件名相同。 请注意，使用此方法意味着重复调用会产生相同的临时文件（每次都会重新创建）

format_abspath(book_id, fmt)

返回格式为“format”的电子书文件的绝对路径。 您几乎不应该使用它，因为它破坏了此 API 的线程安全承诺。 而是使用“copy_format_to”。

目前仅在 calibredb 列表、查看器、编辑书籍、将格式与原始格式进行比较、打开方式、批量元数据编辑和目录（通过 get_data_as_dict()）中使用。

除了查看器、打开方式和编辑书籍之外，我不相信其他任何人会使用此调用的结果执行任何文件写入 I/O。

format_hash(book_id, fmt)

返回指定书籍的指定格式的哈希值。 哈希类型取决于后端，但通常是 SHA-256。

format_metadata(book_id, fmt, allow_cache=True, update_db=False)

返回指定书籍的指定格式的路径、大小和运行时间。 除非绝对必要，否则不应使用路径，因为直接访问它会破坏此 API 的线程安全保证。 而是使用“copy_format_to”方法。

参数:

• allow_cache – 如果使用“True”缓存值，否则文件系统访问速度会很慢。 如果在此 API 之外对文件系统执行访问，则缓存值可能会过期。

• update_db – 如果为“True”，则数据库的 max_size 字段将针对本书进行更新。

formats(book_id, verify_formats=True)

返回指定书籍的所有格式的元组。 如果 verify_formats 为 True，则验证文件是否存在于磁盘上。

get_all_items_that_have_notes(field_name=None) → set[int] | dict[str, set[int]]

如果 field_name 为 None，则返回在指定字段或所有字段中具有注释的项目的所有 item_id

get_all_link_maps_for_book(book_id)

返回由 book_id 标识的书籍引用的所有字段的所有链接。 如果 book_id 不存在，则该方法返回 {}。

示例：假设作者 A 有链接 X，作者 B 有链接 Y，标签 S 有链接 F，标签 T 有链接 G。如果图书 1 有作者 A 和标签 T，则此方法返回 {‘authors’:{‘A’ ：’X’}，’标签’：{‘T’，’G’}}。 如果图书 2 的作者既不是 A 也不是 B，并且没有标签，则此方法返回 {}。

参数:

book_id – 这本书id有问题。

返回:

{字段： {field_value， link_value}， … 对于field_value具有该书的非空链接值的所有字段

get_categories(sort='name', book_ids=None, already_fixed=None, first_letter_sort=False)

在内部使用以实现标签浏览器

get_custom_book_data(name, book_ids=(), default=None)

获取名称数据。默认情况下，会返回所有book_ids的数据，如果您只需要一些数据，请传入书籍 ID 列表。返回book_id到值的映射。如果无法解码特定值，则对其使用 default。

get_id_map(field)

返回id号到指定字段值的映射。字段必须是多-一或多-多字段，否则会引发ValueError。

get_ids_for_custom_book_data(name)

返回名称包含数据的书籍 ID 集。

get_item_id(field, item_name)

返回item_name的项目ID(不区分大小写)，如果未找到，则返回None

get_item_ids(field, item_names)

返回item_name的项目 ID（不区分大小写）

get_item_name(field, item_id)

返回指定字段中由 item_id 指定的项目的项目名称。 另请参阅“get_id_map”。

get_item_name_map(field, normalize_func=None)

返回条目值到 id 的映射

get_link_map(for_field)

返回所提供字段的链接字典。

参数:

for_field – 需要链接映射的字段的查找名称

返回:

{field_value:link_value, …} 用于非空链接

get_metadata(book_id, get_cover=False, get_user_categories=True, cover_as_data=False)

将 book_id 标识的书籍的元数据返回为 calibre.ebooks.metadata.book.base.Metadata 对象。 请注意，格式列表未经验证。 如果 get_cover 为 True，则返回封面，作为 mi.cover 的临时文件的路径，或者如果 cover_as_data 为 True，则返回 mi.cover_data。

get_next_series_num_for(series, field='series', current_indices=False)

返回指定系列的下一个系列索引，同时考虑控制下一个系列号生成的各种首选项。

参数:

• field – 类似系列的字段（默认为内置系列列）

• current_indices – 如果为 True，则返回 book_id 到当前 series_index 值的映射。

get_notes_resource(resource_hash) → dict | None

返回包含资源数据和名称的字典，如果未找到具有指定哈希的资源，则返回 None

get_proxy_metadata(book_id)

与“get_metadata”类似，不同之处在于它返回一个仅按需从数据库读取值的 ProxyMetadata 对象。 当只需要从返回的元数据对象访问少量字段时，这比 get_metadata 快得多。

get_usage_count_by_id(field)

返回指定字段的所有值的 id 到使用计数的映射，该字段必须是多一或多对字段。

has_book(mi)

当且仅当数据库包含与传入的 Metadata 对象具有相同标题的条目时返回 True。 比较不区分大小写。 另请参阅“有书的数据”。

has_format(book_id, fmt)

当且仅当磁盘上存在该格式时返回 True

has_id(book_id)

如果指定的book_id在数据库中存在就返回真

import_note(field, item_id, path_to_html_file, path_is_data=False)

导入先前导出的注释或任意 HTML 文件作为指定项目的注释

init()

使用来自后端的数据初始化此缓存。

items_with_notes_in_book(book_id: int) → dict[str, dict[int, str]]

将字段字典返回到具有指定书籍的该字段的关联注释的项目

link_for(field, item_id)

返回指定项目的链接，如果有；如果未找到链接，则返回“无”

list_extra_files(book_id, use_cache=False, pattern='') → Tuple[ExtraFile, ...]

获取有关书籍目录中额外文件的信息。

参数:

• book_id – 书籍的数据库书籍 ID

• pattern – 要搜索的文件名模式。 空模式匹配所有额外文件。 模式必须使用 / 作为分隔符。 使用 DATA_FILE_PATTERN 常量来匹配数据目录内的文件。

返回:

与指定模式匹配的所有额外文件的元组。 元组的每个元素都是 ExtraFile(relpath, file_path, stat_result)。 其中 relpath 是文件到图书目录的相对路径，使用 / 作为分隔符。 stat_result 是对文件调用 os.stat() 的结果。

merge_extra_files(dest_id, src_ids, replace=False)

将 src_ids 中的额外文件合并到 dest_id 中。 冲突的文件会自动重命名，除非replace=True，在这种情况下它们会被替换。

move_book_from_trash(book_id)

从垃圾目录中取消删除书籍

move_format_from_trash(book_id, fmt)

从垃圾目录中取消删除格式

multisort(fields, ids_to_sort=None, virtual_fields=None)

返回已排序图书 ID 的列表。 如果 ids_to_sort 为 None，则返回所有图书 ID。

fields 必须是形式为 (field_name, ascending=True 或 False) 的二元组列表。 最重要的字段是第一个 2 元组。

notes_data_for(field, item_id) → str

将所有笔记数据作为字典返回，如果笔记不存在则返回 None

notes_for(field, item_id) → str

返回注释文档，如果找不到则返回空字符串

notes_resources_used_by(field, item_id)

返回指定项目的注释所使用的所有资源的资源哈希集

pref(name, default=None, namespace=None)

返回指定首选项的值，如果未设置首选项，则返回指定为“default”的值。

read_backup(book_id)

以字节串形式返回书籍的 OPF 元数据备份，如果不存在此类备份，则返回 None。

remove_books(book_ids, permanent=False)

从数据库中删除 book_ids 指定的书籍并删除其格式文件。 如果“permanent”为 False，则格式文件将放置在每个库的垃圾目录中。

remove_formats(formats_map, db_only=False)

从指定书籍中删除指定格式。

参数:

• formats_map – book_id 到要从书中删除的格式列表的映射。

• db_only – 如果为 True，则仅从数据库中删除该格式的记录，而不从文件系统中删除实际的格式文件。

返回:

书籍 ID 到实际从该书的文件系统中删除的格式集的映射

remove_items(field, item_ids, restrict_to_book_ids=None)

删除指定字段中具有指定 ID 的所有项目。 返回受影响的图书 ID 集。 restrict_to_book_ids 是一组可选的书籍 ID。 如果指定，这些项目只会从这些书中删除。

rename_extra_files(book_id, map_of_relpath_to_new_relpath, replace=False)

重命名附加的数据文件

rename_items(field, item_id_to_new_name_map, change_index=True, restrict_to_book_ids=None)

重命名多-一或多-多对字段中的项目，例如标签或系列。

参数:

• change_index – 在类似系列的字段中重命名时，还要更改 series_index 值。

• restrict_to_book_ids – 要执行重命名的一组可选书籍 ID，默认为所有书籍。

restore_book(book_id, mi, last_modified, path, formats, annotations=())

恢复数据库中已存在于文件系统上的书籍的书籍条目

restore_original_format(book_id, original_fmt)

从之前保存的 ORIGINAL_FORMAT 中恢复指定的格式，如果有。 成功则返回 True。 成功恢复后，ORIGINAL_FORMAT 将被删除。

property safe_read_lock

安全读锁是一种如果线程已经拥有写锁则不执行任何操作的锁，否则它会获取读锁。 这对于防止 DowngradeLockErrors 是必要的，在存在复合列的情况下更新搜索缓存时可能会发生 DowngradeLockErrors。 更新搜索缓存持有独占锁，但搜索复合列涉及通过尝试获取共享锁的 ProxyMetadata 读取字段值。 可能还有其他情况会触发此情况。

此属性在每次访问时返回一个新的锁定对象。 该锁对象不是递归的（为了性能），并且只能在 with 语句中使用“with cache.safe_read_lock:”，否则会发生不好的事情。

save_original_format(book_id, fmt)

将指定格式的副本保存为 ORIGINAL_FORMAT，覆盖任何现有的 ORIGINAL_FORMAT。

search(query, restriction='', virtual_fields=None, book_ids=None)

在数据库中搜索指定的查询，返回一组匹配的图书 ID。

参数:

• restriction – 与指定查询进行 AND 运算的限制。 请注意，限制已被缓存，因此搜索 a AND b 将比搜索带有限制 b 的 a 慢。

• virtual_fields – 内部使用（虚拟字段，例如用于搜索的 on_device）。

• book_ids – 如果不是“无”，则将搜索一组图书 ID，而不是搜索所有图书。

search_notes(fts_engine_query='', use_stemming=True, highlight_start=None, highlight_end=None, snippet_size=None, restrict_to_fields=(), return_text=True, result_type=<class 'tuple'>, process_each_result=None, limit=None)

使用 FTS 索引搜索笔记文本。 如果查询为空，则返回所有注释。

set_conversion_options(options, fmt='PIPE')

options 必须是 {book_id:conversion_options} 形式的映射

set_cover(book_id_data_map)

设置这本书的封面。 数据可以是 QImage、QPixmap、文件对象或字节串。 它也可以是“无”，在这种情况下，任何现有的覆盖物都会被删除。

set_field(name, book_id_to_val_map, allow_case_change=True, do_path_update=True)

设置“name”指定的字段的值。 返回受更改影响的所有图书 ID 的集合。

参数:

• book_id_to_val_map – 将 book_ids 映射到应应用的值。

• allow_case_change – 如果为 True，多对一或多对多字段的大小写将会改变。 例如，如果一本书有标签“tag1”，而您将另一本书的标签设置为“Tag1”，那么如果allow_case_change为True，这两本书都将有标签“Tag1”，否则它们都会有标签“Tag1”。 有标签``tag1``。

• do_path_update – 内部使用，你不应该改变它。

set_link_map(field, value_to_link_map, only_set_if_no_existing_link=False)

设置字段中项目值的链接。 注意：此方法不会更改不在 value_to_link_map 中的值

参数:

• field – 查找名称

• value_to_link_map – 字典（字段值：链接，…）。 请注意，这些是值，而不是字段 ID。

返回:

通过设置链接更改书籍

set_metadata(book_id, mi, ignore_errors=False, force_changes=False, set_title=True, set_authors=True, allow_case_change=False)

从“Metadata”对象“mi”设置书籍“id”的元数据

设置force_changes=True将强制set_metadata更新字段，即使mi包含空值。 在这种情况下，“无”与“空”不同。 如果 mi.XXX 为 None，则不替换 XXX，否则替换。 标签、标识符和封面属性是特殊情况。 标签和标识符不能设置为 None，因此如果 force_changes 为 true，它们将始终被替换。 您必须确保 mi 包含您希望本书具有的值。 如果提供新封面，封面总是会更改，但永远不会被删除。 另请注意，force_changes 对设置标题或作者没有影响。

set_notes_for(field, item_id, doc: str, searchable_text: str = '', resource_hashes=(), remove_unused_resources=False) → int

设置注释文档。 如果可搜索文本与文档不同，请将其指定为 searchable_text。 如果文档引用资源，则它们的哈希值必须存在于 resource_hashes 中。 将remove_unused_resources设置为True以清理未使用的资源，请注意，更新注释会自动清理与该注释相关的资源。

set_pref(name, val, namespace=None)

将指定首选项设置为指定值。 另请参阅“pref”。

split_if_is_multiple_composite(f, val)

如果 f 是复合列查找键并且列是 is_multiple，则将 v 拆分为唯一的非空值。 比较区分大小写。 订单不保留。 返回一个 list() 以与代理元数据字段 getter 兼容，例如标签。

tags_older_than(tag, delta=None, must_have_tag=None, must_have_authors=None)

返回所有具有早于指定时间的标签“tag”的书籍的 ID。 标签比较不区分大小写。

参数:

• delta – timedelta 对象或 None。 如果没有，则返回带有该标签的所有 id。

• must_have_tag – 如果不是“无”，则匹配列表将仅限于具有此标签的书籍

• must_have_authors – 作者名单。 如果不是“无”，则匹配列表将仅限于具有这些作者的书籍（不区分大小写）。

unretire_note_for(field, item_id) → int

取消指定项目之前已停用的注释。 当从数据库中删除项目时，注释将被停用

user_categories_for_books(book_ids, proxy_metadata_map=None)

返回指定书籍的用户类别。 proxy_metadata_map 是可选的，在书籍的 ProxyMetadata 对象已存在的情况下，对于提高性能很有用。 它应该是 book_ids 到其对应的 ProxyMetadata 对象的映射。

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