Документація з програмного інтерфейсу для роботи з базою даних

Цей програмний інтерфейс безпечний щодо потоків виконання (використовує схему із декількома потоками читання і одним потоком запису із блокуванням). Доступ до програмного інтерфейсу можна отримати так:

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)[source]

Кеш у пам’яті файла metadata.db з бібліотеки calibre. Цей клас також слугує безпечним для потоків обробки програмним інтерфейсом для доступу до бази даних. Кеш у пам’яті підтримується у нормальній формі для збільшення швидкодії.

SQLITE просто використовується як стійкий спосіб читання і запису metadata.db. Усю логіку читання, упорядковування, пошуку та кешування таблиць реалізовано окремо. Так зроблено для забезпечення максимальної швидкодії і гнучкості.

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

Додати вказані книги до бібліотеки. Books має бути ітерованим списком з двоелементних кортежів, кожен кортеж має бути записано у формі (mi, format_map), де mi — об’єкт Metadata, а format_map — словник у формі form {формат: шлях_або_потік}. Приклад: {'EPUB': '/шлях/до/файла.epub'}.

Повертає пару списків: ids, duplicates. ids містить ідентифікатори усіх новостворених записів книг у базі даних. duplicates містить записи (mi, format_map) для усіх книг, які вже є у базі даних, на основі простої евристики виявлення дублікатів, що використовується у has_book().

add_custom_book_data(name, val_map, delete_first=False)[source]

Додати дані для вказаної назви, де val_map — прив’язка book_id до значень. Якщо delete_first має значення True, усі раніше збережені для вказаної назви дані буде вилучено.

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

Додати запис формату до вказаного запису книги. Повертає True, якщо запис формату було успішно додано.

Параметри:
  • replace – Якщо True, замінити наявний формат, інакше, якщо формат вже існує, повернути False.
  • run_hooks – Якщо True, додатки форматів типів файлів опрацьовують формат до і після додавання.
  • dbapi – Лише для внутрішнього використання.
all_book_ids(type=<type 'frozenset'>)[source]

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

all_field_for(field, book_ids, default_value=None)[source]

Те саме, що і field_for, але одночасно обробляється декілька книг

all_field_ids(name)[source]

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

all_field_names(field)[source]

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

author_data(author_ids=None)[source]

Повернути дані щодо авторів у форматі словника з такими ключами: name, sort, link

Якщо авторів із вказаними ідентифікаторами немає, буде повернуто порожній словник. Якщо author_ids має значення None, буде повернуто дані для усіх авторів.

author_sort_from_authors(authors, key_func=<function lower>)[source]

За вказаними списком авторів повертає рядок author_sort для авторів, надаючи перевагу упрядковуванню за авторами, пов’язаному з автором, над обчисленим рядком.

books_for_field(name, item_id)[source]

Повертає усі книги, пов’язані із записом, вказаними за допомогою item_id, де запис належить полю name.

Повернуте значення є набором ідентифікаторів книг або порожньою множиною, якщо запису або поля не існує.

books_in_virtual_library(vl, search_restriction=None)[source]

Повертає набір книг у вказаній віртуальній бібліотеці

copy_cover_to(book_id, dest, use_hardlink=False, report_file_size=None)[source]

Копіювати зображення обкладинки до файлоподібного об’єкта dest. Повертає False, якщо зображення обкладинки не існує, або dest є тим самим файлом, що і поточне зображення обкладинки. dest також може бути шляхом. У випадку шляху зображення обкладинки буде скопійовано тоді і лише тоді, коли шлях відрізняється від поточного шляху (із врахуванням регістру символів).

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

Копіювати формат fmt до файлоподібного об’єкта dest. Якщо вказаного формату не існує, повідомляє про помилку NoSuchFormat. dest може бути шляхом. Якщо dest є шляхом (до файла), формат буде скопійовано до нього тоді і лише тоді, коли шлях відрізняється від поточного шляху (із врахуванням регістру символів).

cover(book_id, as_file=False, as_image=False, as_path=False)[source]

Повертає зображення обкладинки або None. Типово, повертає обкладинку як байтовий рядок.

ПОПЕРЕДЖЕННЯ: використання as_path призведе до копіювання зображення обкладинки до тимчасового файла і повернення шляху до цього тимчасового файла. Вам слід вилучити тимчасовий файл, коли ви завершите роботу з ним.

Параметри:
  • as_file – Якщо True, повернути зображення як відкритий об’єкт файла (SpooledTemporaryFile)
  • as_image – Якщо True, повернути зображення як об’єкт QImage.
  • as_path – Якщо True, повернути зображення як шлях, що вказує на тимчасовий файл.
data_for_find_identical_books()[source]

Повертає дані, якими можна скористатися для реалізації find_identical_books() у робочому процесі без доступу до бази даних. Див. db.utils, щоб ознайомитися із реалізацією.

data_for_has_book()[source]

Повертає дані, придатні до використання у has_book(). Можна скористатися для реалізації has_book() у процесі обробки без доступу до бази даних.

delete_custom_book_data(name, book_ids=())[source]

Вилучити дані за вказаною назвою. Типово вилучає усі дані. Якщо вам потрібно вилучити дані лише для деяких ідентифікаторів книг, передайте список ідентифікаторів книг.

embed_metadata(book_ids, only_fmts=None, report_error=None, report_progress=None)[source]

Оновити метадані в усіх форматах вказаних book_id до поточних метаданих у базі даних.

fast_field_for(field_obj, book_id, default_value=None)[source]

Те саме, що і field_for, але з униканням додаткового пошуку для отримання об’єкта поля.

field_for(name, book_id, default_value=None)[source]

Повертає значення поля name для книги, яку вказано за допомогою ідентифікатора book_id. Якщо такої книги не існує, у поля name немає певного значення, або таке поле не існує, буде повернуто default_value.

default_value не використовується для полів title, title_sort, authors, author_sort та series_index. Так зроблено, оскільки ці поля завжди мають значення у базі даних. default_value використовується для усіх нетипових стовпчиків.

Повернутим значення для полів is_multiple завжди будуть кортежі, навіть якщо значень не буде знайдено (іншими словами, default_value буде проігноровано). Виключенням є ідентифікатори, для яких повернуте значення завжди буде словником. Кортежі, які буде повернуто, завжди упорядковуються за посиланнями, тобто порядком їхнього створення.

field_ids_for(name, book_id)[source]

Повертає ідентифікатори (у форматі кортежу) для значень, які поле name містить для книги, що визначається ідентифікатором book_id. Якщо значень немає, або немає такої книги, або немає такого поля, буде повернуто порожній кортеж.

find_identical_books(mi, search_restriction=u'', book_ids=None)[source]

Знаходить книги, набір авторів яких містить mi, і які мають ту саму назву title (відповідність title встановлюється неточно). Див. також data_for_find_identical_books().

format(book_id, fmt, as_file=False, as_path=False, preserve_filename=False)[source]

Повертає дані формату електронної книги у форматі байтового рядка або «None», якщо формату не існує або у вашого користувача немає права доступу до запису файла електронної книги.

Параметри:
  • as_file – Якщо має значення True, дані формату електронної книги повертаються як файловий об’єкт. Зауважте, що файлових об’єкт належатиме до типу SpooledTemporaryFile. Отже, якщо ви хочете скопіювати формат до іншого файла, скористайтеся замість цієї функції функцією copy_format_to() з міркувань швидкодії.
  • as_path – Копіює файл формату до тимчасового файла і повертає шлях до тимчасового файла.
  • preserve_filename – Якщо має значення True і повертаємо шлях, назва файла збігається з використаною у бібліотеці назвою. Зауважте, що використання цього параметра означає, що повторні виклики даватимуть той самий тимчасовий файл (який лише кожного разу створюватиметься повторно).
format_abspath(book_id, fmt)[source]

Повертає абсолютний шлях до файла електронної книги формату format. Цим майже ніколи не варто користуватися, оскільки використання шкодить захисту потоків виконання цього програмного інтерфейсу. Замість цієї функції, скористайтеся copy_format_to().

У поточній версії використовується лише у списку calibredb, засобі перегляду, засобі редагування, compare_format для порівняння з початковим форматом, засобі відкриття файла за допомогою іншої програми, засобі пакетного редагування метаданих та у каталогах (через get_data_as_dict()).

Окрім засобів перегляду, відкриття за допомогою іншої програми та редагування книги, як здається авторові програми, жодна інша частина не виконує будь-яких дій із запису файла вхідних-вихідних даних із результатами цього виклику.

format_hash(book_id, fmt)[source]

Повертає хеш-суму вказаного формату вказаної книги. Тип модуля обробки для отримання сум може бути різним, але, зазвичай, це SHA-256.

format_metadata(book_id, fmt, allow_cache=True, update_db=False)[source]

Повертає шлях, розмір і mtime для вказаного формату вказаної книги. Вам не варто використовувати шлях, окрім безвихідних випадків, оскільки доступ до нього безпосередньо шкодить захисту виконання у потоках, який гарантується цим програмним інтерфейсом. Замість цієї функції, скористайтеся методом copy_format_to().

Параметри:
  • allow_cache – Якщо має значення True, використовуються кешовані значення. У інших випадках використовується повільний доступ до файлової системи. Кешовані значення можуть втрачати актуальність, якщо доступ до файлової системи здійснюється поза цим програмним інтерфейсом.
  • update_db – Якщо має значення True, поле бази даних max_size для цієї книги оновлено.
formats(book_id, verify_formats=True)[source]

Повертає кортеж усіх форматів для вказаної книги. Якщо verify_formats має значення True, перевіряє наявність файлів на диску.

get_categories(sort=u'name', book_ids=None, already_fixed=None, first_letter_sort=False)[source]

Для внутрішньої реалізації панелі перегляду міток

get_custom_book_data(name, book_ids=(), default=None)[source]

Отримати дані для назви name. Типово, повертає дані для усіх book_ids. Передайте функції список ідентифікаторів книг, якщо вам потрібна лише якась частина даних. Повертає прив’язку book_id до значень. Якщо певне значення не вдасться декодувати, використовує типове значення.

get_id_map(field)[source]

Повертає прив’язку номерів ідентифікаторів до значень для вказаного поля. Поле має бути полем багато-одне або багато-багато, інакше буде надіслано повідомлення ValueError.

get_ids_for_custom_book_data(name)[source]

Повернути набір ідентифікаторів книг, для яких для вказаної назви є дані.

get_item_id(field, item_name)[source]

Повертає ідентифікатор запису для item_name (без врахування регістру)

get_item_ids(field, item_names)[source]

Повертає ідентифікатор запису для item_name (без врахування регістру)

get_item_name(field, item_id)[source]

Повертає назву запису для запису, вказаного за item_id, у вказаному полі. Див. також get_id_map().

get_metadata(book_id, get_cover=False, get_user_categories=True, cover_as_data=False)[source]

Повертає метадані для книги, заданої 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=u'series', current_indices=False)[source]

Повертає наступний індекс циклу для вказаного циклу, беручи до уваги різноманітні налаштування, які керують створенням наступного номера у книжковому циклі.

Параметри:
  • field – Поле, яке подібне до поля циклу (типово, вбудований стовпчик циклу)
  • current_indices – Якщо має значення True, повертає прив’язку book_id до поточного значення series_index.
get_proxy_metadata(book_id)[source]

Подібний до get_metadata(), але повертає об’єкт ProxyMetadata, який лише читає значення з бази даних на вимогу. Так виходить набагато швидше за get_metadata, якщо потрібен доступ лише до невеликої кількості полів із повернутого об’єкта метаданих.

get_usage_count_by_id(field)[source]

Повертає прив’язку ідентифікатора до кількості використань для усіх значень вказаного поля, яке має бути полем багато-одне або багато-багато.

has_book(mi)[source]

Повертає True тоді і лише тоді, коли база даних містить запис із таким самим заголовком, що і у переданому об’єкті Metadata. При порівнянні не враховується регістр символів. Див. також data_for_has_book().

has_format(book_id, fmt)[source]

Повертає True, лише якщо формат існує на диску

has_id(book_id)[source]

Повертає True, лише якщо вказане значення ід_книги існує у базі даних

init()[source]

Ініціалізувати цей кеш даними від модуля обробки.

multisort(fields, ids_to_sort=None, virtual_fields=None)[source]

Повертає список упорядкованих ідентифікаторів книг. Якщо ids_to_sort має значення None, буде повернуто ідентифікатори усіх книг.

fields має бути списком двоелементних кортежів у формі (назва_поля, за_зростанням=True або False). Найбільше значення має перша двоелементна комбінація.

pref(name, default=None)[source]

Повертає значення вказаного налаштування або значення, вказане як default, якщо налаштування не встановлено.

read_backup(book_id)[source]

Повертає резервну копію метаданих OPF для книги у форматі рядка байтів або None, якщо така резервна копія вже існує.

remove_books(book_ids, permanent=False)[source]

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

remove_formats(formats_map, db_only=False)[source]

Вилучити вказані формат із запису вказаних книг.

Параметри:
  • formats_map – Прив’язка book_id до списку форматів книги, які слід вилучити.
  • db_only – Якщо має значення True, вилучити запис щодо формату лише з бази даних, не вилучати файл формату з файлової системи.
remove_items(field, item_ids, restrict_to_book_ids=None)[source]

Вилучити усі записи у вказаному полі з вказаними ідентифікаторами. Повертає список оброблених ідентифікаторів книг. restrict_to_book_ids — необов’язковий набір ідентифікаторів книг. Якщо вказано такий набір, записи вилучатимуться лише із книг цього набору.

rename_items(field, item_id_to_new_name_map, change_index=True, restrict_to_book_ids=None)[source]

Перейменувати записи з поля «багато-один» або «багато-багато», зокрема з полів міток або циклів.

Параметри:
  • change_index – Під час перейменування у полі, подібному до поля циклу, змінити значення series_index.
  • restrict_to_book_ids – Необов’язковий набір ідентифікаторів книг, для яких слід виконати перейменовування. Типово, перейменовування виконується для усіх книг.
restore_book(book_id, mi, last_modified, path, formats)[source]

Відновити запис книги у базі даних для книги, яка вже існує у файловій системі.

restore_original_format(book_id, original_fmt)[source]

Відновити вказаний формат на основі раніше збереженого ORIGINAL_FORMAT, якщо такий існує. Повертає True, якщо дію виконано успішно. Після успішного відновлення ORIGINAL_FORMAT буде вилучено.

safe_read_lock

Безпечною дією з блокування на читання є блокування, яке забороняє дії, якщо якщо потік вже має блокування на запис, інакше отримує блокування на читання. Це необхідно для запобігання DowngradeLockErrors, помилкам, які можуть трапитися під час оновлення кешу пошуку, коли існують складені стовпчики. Оновлення кешу пошуку отримує виключне блокування, але пошук складеного стовпчика включає читання значень полів за допомогою ProxyMetadata, який намагається отримати блокування зі спільним доступом. Можливі і інші сценарії, які призводять до цієї ситуації.

Ця властивість повертає новий об’єкт блокування під час кожного доступу. Цей об’єкт блокування не є рекурсивним (з міркувань швидкодії). Його слід використовувати лише у a з інструкцією with cache.safe_read_lock:, інакше можливі небажані наслідки.

save_original_format(book_id, fmt)[source]

Зберегти копію вказаного формату ORIGINAL_FORMAT, переписати усі наявні записи ORIGINAL_FORMAT.

search(query, restriction=u'', virtual_fields=None, book_ids=None)[source]

Виконати пошук у базі даних за вказаним запитом. Повертає набір ідентифікаторів відповідних до критерію пошуку книг.

Параметри:
  • restriction – Обмеження яке буде об’єднано логічним «І» із вказаним запитом. Зауважте, що обмеження кешуються, тому пошук «a І b» буде повільнішим за пошук «a» з обмеженням «b».
  • virtual_fields – Для внутрішнього використання (віртуальні поля, зокрема on_device, для пошуку).
  • book_ids – Якщо має значення, відмінне від None, пошук виконуватиметься для набору вказаних за допомогою ідентифікаторів книг, а не для усіх книг.
set_conversion_options(options, fmt=u'PIPE')[source]

параметри мають бути картою у формі {ід_книги:параметри_перетворення}

set_cover(book_id_data_map)[source]

Встановити зображення обкладинки для цієї книги. Значенням data може бути QImage, QPixmap, об’єкт файла або рядок байтів. Також можливе значення None, яке означає, що слід вилучити будь-яке наявне зображення обкладинки.

set_field(name, book_id_to_val_map, allow_case_change=True, do_path_update=True)[source]

Встановлює значення для поля, вказаного за допомогою name. Повертає набір усіх ідентифікаторів книг, на які впливає зміна.

Параметри:
  • book_id_to_val_map – Прив’язка book_ids до значень, які слід застосувати.
  • allow_case_change – Якщо має значення True, регістр символів у полях багато-одне або багато-багато буде змінено. Наприклад, якщо у книги була мітка мітка1 і ви встановили для іншої книги мітку Мітка1, обидві книги отримають мітку Мітка1, якщо allow_case_change має значення True, і мітку мітка1 у іншому випадку.
  • do_path_update – Використовується для внутрішніх потреб програми. Вам не варто змінювати цей параметр.
set_metadata(book_id, mi, ignore_errors=False, force_changes=False, set_title=True, set_authors=True, allow_case_change=False)[source]

Встановлює метадані для книги з ідентифікатором id на основі об’єкта Metadata mi

Встановлення значення force_changes=True наказує set_metadata оновити поля у примусовому порядку, навіть якщо mi містить порожні значення. У цьому випадку None відрізняється від empty. Якщо mi.XXX має значення None, XXX не буде замінено, а якщо ні, буде. Мітки, ідентифікатори і атрибути зображення є особливими випадками. Для міток та ідентифікаторів не можна встановлювати значення None, отже їх буде завжди замінено, якщо force_changes має значення True. Вам слід забезпечити наявність у mi значень, які повинна мати книга. Зображення обкладинок замінюються завжди, якщо надано нове зображення обкладинки, але ніколи не вилучаються. Також зауважте, що force_changes не впливає на встановлення назви книги або авторів.

set_pref(name, val)[source]

Встановити вказаний рівень пріоритетності. Див. також pref().

tags_older_than(tag, delta=None, must_have_tag=None, must_have_authors=None)[source]

Повертає ідентифікатори усіх книг, які мають мітку tag і які є старішими за вказаний час. При порівнянні міток регістр символів не враховується.

Параметри:
  • delta – Об’єкт timedelta або None. Якщо має значення None, буде повернуто усі ідентифікатори з вказаною міткою.
  • must_have_tag – Якщо встановлено значення None, список відповідників буде обмежено до книг, які мають вказану мітку.
  • must_have_authors – Список авторів. Якщо не None, список відповідників буде обмежено до книг, авторами яких є вказані письменники (без врахування регістру символів).
user_categories_for_books(book_ids, proxy_metadata_map=None)[source]

Повертає категорії користувача для вказаних книг. Параметр proxy_metadata_map є необов’язковим. Він корисний для пришвидшення обробки у контекстах, коли для книг вже існує об’єкт ProxyMetadata. Має повернути прив’язку book_ids до відповідних об’єктів ProxyMetadata.