Документация API интерфейса базы данных

Это потокобезопасный API (используется схема блокировки чтения-записи). Получить доступ к API можно так:

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

Из плагина, являющегося частью основного графического интерфейса calibre, доступ осуществляется так:

db = self.gui.current_db.new_api
class calibre.db.cache.Cache(backend)[исходный код]

Кэш в памяти файла metadata.db из библиотеки calibre. Этот класс также служит потокобезопасным API для доступа к базе данных. Кэш в памяти поддерживается в нормальной форме для максимальной производительности.

SQLITE используется просто как способ надежного чтения и записи из metadata.db. Переработана вся логика чтения/сортировки/поиска/кеширования таблиц. Это было необходимо для максимальной производительности и гибкости.

class EventType(value)

Перечисление.

add_books(books, add_duplicates=True, apply_import_tags=True, preserve_uuid=False, run_hooks=True, dbapi=None)[исходный код]

Добавьте указанные книги в библиотеку. Книги должны быть повторяемыми из 2-х кортежей, каждый из 2-х кортежей в форме (mi, format_map), где mi - объект метаданных, а format_map - словарь в форме {fmt: path_or_stream}, например: {'EPUB': '/path/to/file.epub'}.

Возвращает пару списков: ids, duplicates. „ids“ содержит идентификаторы всех новосозданных книг в базе данных. duplicates содержит (mi, format_map) для книг уже существующих в базе данных, руководствуясь простой эвристикой обнаружения дубликатов, используемой has_book().

add_custom_book_data(name, val_map, delete_first=False)[исходный код]

Добавить данные для имени, где val_map - это отображение идентификаторов книг в значения. Если delete_first имеет значение True, все ранее сохраненные данные для имени будут удалены.

add_format(book_id, fmt, stream_or_path, replace=True, run_hooks=True, dbapi=None)[исходный код]

Добавить формат в указанную книгу. Вернёт True, если формат был добавлен успешно.

Параметры
  • replace – If True replace existing format, otherwise if the format already exists, return False.

  • run_hooks – If True, file type plugins are run on the format before and after being added.

  • dbapi – Для внутреннего пользования

add_listener(event_callback_function)[исходный код]

Регистрирует функцию обратного вызова, которая будет вызываться после выполнения определённых действий с этой базой данных. Функция должна принимать три аргумента: (EventType, library_id, event_type_specific_data)

all_book_ids(type=<class 'frozenset'>)[исходный код]

Замороженный набор всех известных идентификаторов книг.

all_field_for(field, book_ids, default_value=None)[исходный код]

То же, что field_for, за исключением того, что работает с несколькими книгами одновременно

all_field_ids(name)[исходный код]

Замороженный набор идентификаторов для всех значений в поле name.

all_field_names(field)[исходный код]

Замороженный набор имен всех полей (следует использовать только для полей „много-один“ и „много-много“)

author_data(author_ids=None)[исходный код]

Вернуть данные об авторе в виде словаря с ключами: имя, сортировка, ссылка

Если авторов с указанными идентификаторами не найдено, возвращается пустой словарь. Если 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.

Возвращаемое значение - это набор идентификаторов книг или пустой набор, если элемент или поле не существует.

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. Возвращает False, если обложки не существует или если dest - тот же файл, что и текущая обложка. 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)[исходный код]

Вернуть обложку или None. По умолчанию возвращает обложку в виде байтовой строки.

ВНИМАНИЕ: использование as_path скопирует обложку во временный файл и вернет путь к временному файлу. Вы должны удалить временный файл, когда закончите работать с ним.

Параметры
  • as_file – Если True, вернуть изображение как объект открытого файла (SpooledTemporaryFile)

  • as_image – Если True вернуть изображение как объект QImage

  • 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=())[исходный код]

Удалить данные для имени. По умолчанию удаляются все данные. Если вы хотите удалить данные только для некоторых идентификаторов книг, передайте список идентификаторов книг.

embed_metadata(book_ids, only_fmts=None, report_error=None, report_progress=None)[исходный код]

Обновить метаданные во всех форматах указанных book_ids до текущих метаданных в базе данных.

fast_field_for(field_obj, book_id, default_value=None)[исходный код]

То же, что field_for, только исключает дополнительный поиск для получения объекта поля

field_for(name, book_id, default_value=None)[исходный код]

Вернуть значение поля name для книги, идентифицированной с помощью book_id. Если такой книги не существует, или она не имеет определенного значения для поля name или такое поле не существует, то возвращается default_value.

default_value не используется для заголовка, title_sort, авторов, author_sort и series_index. Это потому, что они всегда имеют значения в базе данных. default_value используется для всех настраиваемых столбцов.

Возвращаемое значение для полей is_multiple всегда является кортежем, даже если значения не найдены (другими словами, default_value игнорируется). Исключение составляют идентификаторы, для которых возвращаемое значение всегда dict. Возвращаемые кортежи всегда находятся в ссылочном порядке (в порядкеих создания).

field_ids_for(name, book_id)[исходный код]

Вернуть идентификаторы (в виде кортежа) для значений, которые поле name имеет в книге, идентифицированной с помощью book_id. Если значений нет, или такой книги, или такого поля нет, возвращается пустой кортеж.

find_identical_books(mi, search_restriction='', book_ids=None)[исходный код]

Находит книги, у которых есть надмножество авторов в mi и одинаковое название (нечеткое совпадение названия). См. Также data_for_find_identical_books().

format(book_id, fmt, as_file=False, as_path=False, preserve_filename=False)[исходный код]

Вернуть формат электронной книги в виде байтовой строки или None, если формат не существует или у нас нет разрешения на запись в файл электронной книги.

Параметры
  • as_file – If True the e-book format is returned as a file object. Note that the file object is a SpooledTemporaryFile, so if what you want to do is copy the format to another file, use copy_format_to() instead for performance.

  • as_path – Копирует файл формата во временный файл и возвращает путь к временному файлу.

  • preserve_filename – Если True и возвращает путь, имя файла такое же, как и в библиотеке. Обратите внимание, что использование этого означает, что повторные вызовы дают один и тот же временный файл (который каждый раз создается заново)

format_abspath(book_id, fmt)[исходный код]

Вернуть абсолютный путь к файлу электронной книги формата format. Вам почти никогда не следует использовать это, так как это нарушает обещание потоковой безопасности этого API. Вместо этого используйте copy_format_to().

В настоящее время используется только в calibredb list, viewer, edit book, compare_format to original format, open with, массовое редактирование метаданных и каталоги (через get_data_as_dict ()).

Я не верю, что кто-либо, кроме средства просмотра, открывающего и редактирующего книгу, выполняет какие-либо операции ввода-вывода записи файлов с результатами этого вызова.

format_hash(book_id, fmt)[исходный код]

Вернуть хэш указанного формата для указанной книги. Тип хэша зависит от серверной части, но обычно это SHA-256.

format_metadata(book_id, fmt, allow_cache=True, update_db=False)[исходный код]

Вернуть путь, размер и время для указанного формата для указанной книги. Вы не должны использовать path, если в этом нет крайней необходимости, поскольку прямой доступ к нему нарушает гарантии потоковой безопасности этого API. Вместо этого используйте метод copy_format_to().

Параметры
  • allow_cache – Если используются кэшированные значения True, в противном случае выполняется медленный доступ к файловой системе. Значения кеша могли быть устаревшими, если доступ к файловой системе выполнялся вне этого API.

  • update_db – Если True поле max_size базы данных обновляется для этой книги.

formats(book_id, verify_formats=True)[исходный код]

Вернуть кортеж всех форматов для указанной книги. Если verify_formats имеет значение True, проверяет, существуют ли файлы на диске.

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, передайте список идентификаторов книг, если вам нужны только некоторые данные. Возвращает карту значений book_id. Если определенное значение не может быть декодировано, для него используется значение по умолчанию.

get_id_map(field)[исходный код]

Вернуть сопоставление номеров идентификаторов со значениями для указанного поля. Поле должно быть полем «многие-один» или «многие-многие», в противном случае возникает ошибка ValueError.

get_ids_for_custom_book_data(name)[исходный код]

Вернуть набор идентификаторов книг, в названии которых есть данные.

get_item_id(field, item_name)[исходный код]

Вернуть идентификатор элемента для item_name (без учета регистра)

get_item_ids(field, item_names)[исходный код]

Вернуть идентификатор элемента для item_name (без учета регистра)

get_item_name(field, item_id)[исходный код]

Вернуть имя элемента для элемента, указанного в item_id в указанном поле. См. также get_id_map().

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 – If True, returns a mapping of book_id to current series_index value instead.

get_proxy_metadata(book_id)[исходный код]

Например get_metadata(), за исключением того, что он возвращает объект ProxyMetadata, который только считывает значения из базы данных по запросу. Это намного быстрее, чем get_metadata, когда необходимо получить доступ только к небольшому количеству полей из возвращенного объекта метаданных.

get_usage_count_by_id(field)[исходный код]

Вернуть отображение идентификатора в счетчик использования для всех значений указанного поля, которое должно быть полем «много-один» или «много-много»

has_book(mi)[исходный код]

Верните True, если база данных содержит запись с тем же заголовком, что и переданный объект Metadata. При сравнении регистр не учитывается. См. также data_for_has_book().

has_format(book_id, fmt)[исходный код]

Вернуть True, если формат существует на диске

has_id(book_id)[исходный код]

Вернёт True, если указанный book_id существует в БД

init()[исходный код]

Инициализировать этот кеш данными из серверной части.

multisort(fields, ids_to_sort=None, virtual_fields=None)[исходный код]

Вернуть список отсортированных идентификаторов книг. Если ids_to_sort - None, возвращаются идентификаторы всех книг.

поля должны быть списком из двух кортежей формы (field_name, ascending = True или False). Наиболее значимое поле - первое в кортеже из двух элементов.

pref(name, default=None, namespace=None)[исходный код]

Вернуть значение для указанного предпочтения или значение, указанное как по умолчанию, если предпочтение не установлено.

read_backup(book_id)[исходный код]

Вернуть резервную копию метаданных OPF для книги в виде байтовой строки или None, если такой резервной копии не существует

remove_books(book_ids, permanent=False)[исходный код]

Удалить записи книг, указанных в book_ids, из базы данных и удалить их файлы. Если для параметра permanent установлено значение False, файлы помещаются в корзину.

remove_formats(formats_map, db_only=False)[исходный код]

Remove the specified formats from the specified books.

Параметры
  • formats_map – Сопоставить book_id со списком форматов, которые нужно удалить из книги.

  • db_only – Если True, удалить только запись для формата из базы данных, не удалять файл формата из файловой системы.

remove_items(field, item_ids, restrict_to_book_ids=None)[исходный код]

Удалить все элементы в указанном поле с указанными идентификаторами. Возвращает набор идентификаторов затронутых книг. restrict_to_book_ids - необязательный набор идентификаторов книг. Если указано, элементы будут удалены только из этих книг.

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 – Необязательный набор идентификаторов книг, для которых должно быть выполнено переименование, по умолчанию для всех книг.

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, которые могут возникнуть при обновлении кеша поиска при наличии составных столбцов. Обновление кеша поиска содержит эксклюзивную блокировку, но поиск в составном столбце включает чтение значений полей через 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)[исходный код]

Искать в базе данных указанный запрос, возвращая набор совпадающих идентификаторов книг.

Параметры
  • restriction – Ограничение, добавляемое (AND) к указанному запросу. Обратите внимание, что ограничения кэшируются, поэтому поиск «a» AND «b» будет медленнее, чем «a» с ограничением «b».

  • virtual_fields – Используется внутри (виртуальные поля, такие как on_device, для поиска).

  • book_ids – Если не None, то набор идентификаторов книг, по которым будет выполняться поиск книг вместо поиска по всем книгам.

set_conversion_options(options, fmt='PIPE')[исходный код]

параметры должны быть картой в форме {book_id: conversion_options}

set_cover(book_id_data_map)[исходный код]

Установить обложку для этой книги. данные могут быть QImage, QPixmap, файловым объектом или байтовой строкой. Также может быть None - любая существующая обложка будет удалена

set_field(name, book_id_to_val_map, allow_case_change=True, do_path_update=True)[исходный код]

Установить значения поля, указанного в name. Возвращает набор всех идентификаторов книг, на которые повлияло изменение.

Параметры
  • book_id_to_val_map – Сопоставление book_ids значениям, которые следует применить.

  • allow_case_change – Если True, регистр полей много-один или много-много будет изменен. Например, если у книги есть тег tag1, а вы установили тег для другой книги как Tag1, тогда обе книги будут иметь тег Tag1, если allow_case_change - True, иначе они оба будут иметь тег tag1.

  • do_path_update – Используется внутри, вы никогда не должны его менять.

set_metadata(book_id, mi, ignore_errors=False, force_changes=False, set_title=True, set_authors=True, allow_case_change=False)[исходный код]

Установить метаданные для книги id из объекта Metadata mi

Установка force_changes = True заставит set_metadata обновлять поля, даже если mi содержит пустые значения. В этом случае None отличается от empty. Если mi.XXX равно „None“, XXX не заменяется, в противном случае - нет. Теги, идентификаторы и атрибуты обложки - это особые случаи. Теги и идентификаторы не могут быть установлены на „None“, поэтому они всегда будут заменены, если force_changes истинно. Вы должны убедиться, что mi содержит те значения, которые вы хотите, чтобы книга имела. Обложки всегда меняются, если предоставляется новая обложка, но никогда не удаляются. Также обратите внимание, что force_changes не влияет на установку заголовка или авторов.

set_pref(name, val, namespace=None)[исходный код]

Установите указанное предпочтение на указанное значение. См. Также: meth:pref.

tags_older_than(tag, delta=None, must_have_tag=None, must_have_authors=None)[исходный код]

Возвратить идентификаторы всех книг с тегом tag, которые старше указанного времени. сравнение тегов производится без учета регистра.

Параметры
  • delta – Объект timedelta или None. Если None, то возвращаются все идентификаторы с тегом.

  • must_have_tag – Если нет, то список совпадений будет ограничен книгами с этим тегом.

  • must_have_authors – Список авторов. Если нет, то список совпадений будет ограничен книгами, имеющими этих авторов (без учета регистра).

user_categories_for_books(book_ids, proxy_metadata_map=None)[исходный код]

Вернуть категории пользователей для указанных книг. proxy_metadata_map не является обязательным и полезен для повышения производительности в контекстах, где уже существует объект ProxyMetadata для книг. Это должно быть отображение book_ids на соответствующие им объекты ProxyMetadata.