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=<not given>, *values, 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_annotations(restrict_to_user=None, limit=None, annotation_type=None, ignore_removed=False, restrict_to_book_ids=None)[源代码]¶
返回与指定条件匹配的所有注释的多元组。' ignore_removed '控制是否也返回已删除(删除)的注释。删除的注释只是用于合并注释的骨架。
- all_annotations_for_book(book_id)[源代码]¶
将包含指定book_id的所有注释的二元组作为带有键的dict返回:format, user_type, user, annotation。这里,注释是注释数据。
- annotations_map_for_book(book_id, fmt, user_type='local', user='viewer')[源代码]¶
返回注释类型->指定book_id、格式、用户和用户_类型的注释数据的映射。
- 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,如果该项目或字段不存在,则返回空集。
- 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。
- embed_metadata(book_ids, only_fmts=None, report_error=None, report_progress=None)[源代码]¶
将指定book_ids的所有格式的元数据更新为数据库中的当前元数据。
- 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(作为元组)。 如果没有值,或者没有这样的书,或者没有这样的字段,则返回一个空元组。
- 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_metadata(book_id, fmt, allow_cache=True, update_db=False)[源代码]¶
返回指定书籍的指定格式的路径、大小和运行时间。 除非绝对必要,否则不应使用路径,因为直接访问它会破坏此 API 的线程安全保证。 而是使用“copy_format_to”方法。
- 参数:
allow_cache -- 如果使用“True”缓存值,否则文件系统访问速度会很慢。 如果在此 API 之外对文件系统执行访问,则缓存值可能会过期。
update_db -- 如果为“True”,则数据库的 max_size 字段将针对本书进行更新。
- 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_item_id(field, item_name, case_sensitive=False)[源代码]¶
Return the item id for item_name or None if not found. This function is very slow if doing lookups for multiple names use either get_item_ids() or get_item_name_map(). Similarly, case sensitive lookups are faster than case insensitive ones.
- get_item_ids(field, item_names, case_sensitive=False)[源代码]¶
Return a dict mapping item_name to the item id or None
- 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_proxy_metadata(book_id)[源代码]¶
与“get_metadata”类似,不同之处在于它返回一个仅按需从数据库读取值的 ProxyMetadata 对象。 当只需要从返回的元数据对象访问少量字段时,这比 get_metadata 快得多。
- import_note(field, item_id, path_to_html_file, path_is_data=False)[源代码]¶
导入先前导出的注释或任意 HTML 文件作为指定项目的注释
- 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_annotations_for_book(book_id, fmt, annots_list, user_type='local', user='viewer')[源代码]¶
将指定的注释合并到book_id、fm、user_ype和user的现有注释中。
- merge_extra_files(dest_id, src_ids, replace=False)[源代码]¶
将 src_ids 中的额外文件合并到 dest_id 中。 冲突的文件会自动重命名,除非replace=True,在这种情况下它们会被替换。
- multisort(fields, ids_to_sort=None, virtual_fields=None)[源代码]¶
返回已排序图书 ID 的列表。 如果 ids_to_sort 为 None,则返回所有图书 ID。
fields 必须是形式为 (field_name, ascending=True 或 False) 的二元组列表。 最重要的字段是第一个 2 元组。
- 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_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:”,否则会发生不好的事情。
- 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_annotations(fts_engine_query, use_stemming=True, highlight_start=None, highlight_end=None, snippet_size=None, annotation_type=None, restrict_to_book_ids=None, restrict_to_user=None, ignore_removed=False)[源代码]¶
返回与指定全文查询匹配的注释二元组。
- 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_annotations_for_book(book_id, fmt, annots_list, user_type='local', user='viewer')[源代码]¶
为指定的book_id、fdt、user_ype和user设置所有注释。
- 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以清理未使用的资源,请注意,更新注释会自动清理与该注释相关的资源。
- split_if_is_multiple_composite(f, val)[源代码]¶
如果 f 是复合列查找键并且列是 is_multiple,则将 v 拆分为唯一的非空值。 比较区分大小写。 订单不保留。 返回一个 list() 以与代理元数据字段 getter 兼容,例如标签。