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

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

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

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

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

class EventType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

book_created = 4¶: Коли у базі даних буде створено новий запис книги із ідентифікатором книги, як єдиним аргументом

book_edited = 8¶: Коли буде змінено формат книги з аргументами: (ідентифікатор_книги, формат)

books_removed = 5¶: Коли книги буде вилучено з бази даних із списком ідентифікаторів книг, як єдиним аргументом

format_added = 2¶: Коли до запису книги буде додано формат із аргументами: (ідентифікатор_книги, форма)

formats_removed = 3¶: Коли формати буде вилучено з запису книги з аргументами: (відображення ідентифікатора книги на формати, які вилучено з запису книги)

indexing_progress_changed = 9¶: Коли змінюється поступ індексування

items_removed = 7¶: Коли з деяких книг вилучають записи, подібні до міток або записів авторів. Аргументи: (назва_поля, ідентифікатори книг, ідентифікатори записів, які вилучають)

items_renamed = 6¶: Коли у деяких або усіх книгах перейменовують записи, подібні до міток або записів авторів. Аргументи: (назва_поля, ідентифікатори книг, відображення старого ідентифікатора запису на новий ідентифікатор запису)

metadata_changed = 1¶: Коли змінюють деякі метадані у деяких книгах з аргументами: (назва зміненого поля, набір ідентифікаторів книг)

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_extra_files(book_id, map_of_relpath_to_stream_or_path, replace=True, auto_rename=False)[source]¶: Додати додаткові файли даних

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

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

Параметри:

replace – Якщо True, замінити наявний формат, інакше, якщо формат вже існує, повернути False.
run_hooks – Якщо True, додатки форматів типів файлів опрацьовують формат до і після додавання.
dbapi – Лише для внутрішнього використання.

add_listener(event_callback_function, check_already_added=False)[source]¶: Зареєструвати функцію зворотного виклику, яку буде викликано після певних дій над цією базою даних. Функція має приймати три аргументи: (EventType, ідентифікатор_бібліотеки, специфічні_дані_типу_події)

add_notes_resource(path_or_stream_or_data, name: str, mtime: float = None) → int[source]¶: Додати вказаний ресурс, щоб на нього можна було посилатися з нотаток і повернути хеш його вмісту

all_annotation_types()[source]¶: Повертає кортеж усіх типів анотацій у базі даних.

all_annotation_users()[source]¶: Повертає кортеж усіх (тип_користувача, ім’я_користувача), які містять анотації.

all_annotations(restrict_to_user=None, limit=None, annotation_type=None, ignore_removed=False, restrict_to_book_ids=None)[source]¶: Повертає кортеж усіх анотацій, які відповідають вказаному критерію. ігнорувати_вилучені керує тим, чи слід також повертати дані вилучених (витертих) анотацій. Вилучені анотації є лише каркасом, який використовують для об’єднання анотацій.

all_annotations_for_book(book_id)[source]¶: Повертає кортеж, що містить усі анотації для вказаного ідентифікатор_книги як словник із такими ключами: format, user_type, user, annotation. Тут annotation є даними анотації.

all_book_ids(type=<class '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]¶: Заморожений набір усіх назв полів (слід використовувати лише для полів багато-одне і багато-багато)

annotation_count_for_book(book_id)[source]¶: Повертає кількість анотацій для вказаної книги, які є у базі даних.

annotations_map_for_book(book_id, fmt, user_type='local', user='viewer')[source]¶: Повертає карту «тип анотації -> дані анотації» для вказаних ідентифікатор_книги, формат, користувач і тип_користувача.

author_data(author_ids=None)[source]¶

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

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

author_sort_from_authors(authors, key_func=<function make_change_case_func.<locals>.change_case>)[source]¶: За вказаними списком авторів повертає рядок author_sort для авторів, надаючи перевагу упрядковуванню за авторами, пов’язаному з автором, над обчисленим рядком.

books_for_field(name, item_id)[source]¶

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

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

books_in_virtual_library(vl, search_restriction=None, virtual_fields=None)[source]¶: Повертає набір книг у вказаній віртуальній бібліотеці

compress_covers(book_ids, jpeg_quality=100, progress_callback=None)[source]¶

Стиснути зображення обкладинок вказаних книг. Якість стискання 100 означає виконання стискання без втрати даних. Усі інші значення призводитимуть до втрати якості зображення.

Зворотний виклик поступу буде виконано із використанням ідентифікатора книги та старого і нового розмірів для кожної обробленої книги. Якщо станеться помилка, розміром новин буде рядок із повідомленням про помилку.

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, as_pixmap=False)[source]¶

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

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

Параметри:

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

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

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

delete_annotations(annot_ids)[source]¶: Вилучити анотації з вказаними ідентифікаторами.

delete_custom_book_data(name, book_ids=())[source]¶: Вилучити дані за вказаною назвою. Типово вилучає усі дані. Якщо вам потрібно вилучити дані лише для деяких ідентифікаторів книг, передайте список ідентифікаторів книг.

delete_trash_entry(book_id, category)[source]¶: Вилучити запис зі смітника. Тут категоріями є «b» для книг і «f» для форматів.

embed_metadata(book_ids, only_fmts=None, report_error=None, report_progress=None)[source]¶: Оновити метадані в усіх форматах вказаних book_id до поточних метаданих у базі даних.

expire_old_trash()[source]¶: Вилучити надто старі записи зі смітника

export_note(field, item_id) → str[source]¶: Експортувати нотатку як окремий документ HTML з вбудованими зображеннями у форматі адрес data:

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. Якщо значень немає, або немає такої книги, або немає такого поля, буде повернуто порожній кортеж.

field_supports_notes(field=None) → bool[source]¶: Повертає True тоді і лише тоді, коли для вказаного поля передбачено підтримку нотаток. Якщо поле має значення None повертає фіксований список усіх полів, для яких передбачено підтримку нотаток.

find_identical_books(mi, search_restriction='', 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_all_items_that_have_notes(field_name=None) → set[int] | dict[str, set[int]][source]¶: Повертає усі ідентифікатори записів для записів, з якими пов’язано нотатки у вказаному полі або усіх полях, якщо значенням field_name є None

get_all_link_maps_for_book(book_id)[source]¶

Повертає усі посилання для усіх полів, які використано у книзі, на яку вказує ідентифікатор_книги. Якщо книги з вказаним ідентифікатором не існує, метод повертає {}.

Приклад: нехай запис автора A містить посилання X, а запис автора B містить посилання Y, мітка S містить посилання F, а мітка T містить посилання G. Якщо книга 1 має автора A і мітку T, цей метод поверне {„authors“:{„A“:“X“}, „tags“:{„T“, „G“}}. Якщо автором книги 2 не є ні A, ні B, і вона не має міток, цей метод поверне {}.

Параметри:: book_id – ідентифікатор потрібної книги.
Повертає:: {поле: {значення_поля, значення_посилання}, … для усіх полів, які містять значення_поля і непорожнє значення посилання для цієї книги

get_categories(sort='name', book_ids=None, already_fixed=None, first_letter_sort=False, uncollapsed_categories=None)[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, case_sensitive=False)[source]¶: Повертає ідентифікатор запису для назви запису або None, якщо нічого не буде знайдено. Ця функція працює дуже повільно, якщо її використовують для декількох назв. Користуйтеся get_item_ids() або get_item_name_map(). Так само, пошук із врахуванням регістру символів є швидшим за пошук без його врахування.

get_item_ids(field, item_names, case_sensitive=False)[source]¶: Повертає словник із прив’язкою item_name до ідентифікатора запису або None

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

get_item_name_map(field, normalize_func=None)[source]¶: Повертає прив’язку значень запису до ідентифікаторів

get_link_map(for_field)[source]¶

Повернути словник посилань для наданого поля.

Параметри:: for_field – пошукова назва поля, для якого потрібна карта посилань
Повертає:: {значення_поля:значення_посилання, …} для непорожніх посилань

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='series', current_indices=False)[source]¶

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

Параметри:

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

get_notes_resource(resource_hash) → dict | None[source]¶: Повертає словник, що містить дані і назву ресурсу або None, якщо ресурс із вказаним хешем не було знайдено

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, лише якщо вказане значення ід_книги існує у базі даних

import_note(field, item_id, path_to_html_file, path_is_data=False)[source]¶: Імпортує попередньо експортовану нотатку або довільний файл HTML як нотатку для вказаного запису

init()[source]¶: Ініціалізувати цей кеш даними від модуля обробки.

items_with_notes_in_book(book_id: int) → dict[str, dict[int, str]][source]¶: Повертає словник прив’язки полів до записів, які мають пов’язані нотатки для відповідного поля для вказаної книги

link_for(field, item_id)[source]¶: Повертає посилання, якщо таке існує, для вказаного запису або None, якщо посилання не буде знайдено

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

Отримати відомості щодо додаткових файлів у каталозі книги.

Параметри:

book_id – ідентифікатор книги у базі даних
pattern – взірець назв файлів, які слід шукати. Порожній взірець означає «усі додаткові файли». У взірцях слід використовувати роздільник «/». Скористайтеся сталою DATA_FILE_PATTERN для встановлення відповідності файлів у каталозі даних.

Повертає:

Кортеж усіх додаткових файлів, що відповідають вказаному взірцю. Кожен елемент кортежу з записом ExtraFile(відн_шлях, шлях_до_файла, статистика), де «відн_шлях» є відносним шляхом до каталогу книги із роздільником /. «статистика» є результатом виклику os.stat() для файла.

merge_annotations_for_book(book_id, fmt, annots_list, user_type='local', user='viewer')[source]¶: Об’єднати вказані анотації до наявних анотацій для вказаних ідентифікатор_книги, формат, тип_користувача і користувач.

merge_extra_files(dest_id, src_ids, replace=False)[source]¶: Об’єднати додаткові файли з src_ids до dest_id. Файли з конфліктом назв буде автоматично перейменовано, якщо не вказано replace=True. Якщо ж вказано цей параметр, файли буде замінено.

move_book_from_trash(book_id)[source]¶: Відновити книгу із каталогу смітника

move_format_from_trash(book_id, fmt)[source]¶: Відновити формат із каталогу смітника

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

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

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

notes_data_for(field, item_id) → str[source]¶: Повертає усі дані нотаток як словник або None, якщо жодної нотатки не існує

notes_for(field, item_id) → str[source]¶: Повертає документ нотаток або порожній рядок, якщо документ не знайдено

notes_resources_used_by(field, item_id)[source]¶: Повертає набір хешів ресурсів усіх ресурсів, які використано нотаткою, для вказаного запису

pref(name, default=None, namespace=None)[source]¶: Повертає значення вказаного налаштування або значення, вказане як default, якщо налаштування не встановлено.

read_backup(book_id)[source]¶: Повертає резервну копію метаданих OPF для книги у форматі рядка байтів або None, якщо така резервна копія вже існує.

remove_books(book_ids, permanent=False)[source]¶: Вилучити книги, вказані за допомогою параметра book_ids з бази даних і вилучити відповідні файли форматів. Якщо значенням permanent є False, файли форматів надсилатимуться до окремої теки смітника бібліотеки.

remove_extra_files(book_id: int, relpaths: Iterable[str], permanent=False) → dict[str, Exception | None][source]¶: Вилучити вказані зайві файли, до теки Смітника або остаточно.

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_extra_files(book_id, map_of_relpath_to_new_relpath, replace=False)[source]¶: Перейменування додаткових файлів даних

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, annotations=())[source]¶: Відновити запис книги у базі даних для книги, яка вже існує у файловій системі.

restore_original_format(book_id, original_fmt)[source]¶: Відновити вказаний формат на основі раніше збереженого ORIGINAL_FORMAT, якщо такий існує. Повертає True, якщо дію виконано успішно. Після успішного відновлення ORIGINAL_FORMAT буде вилучено.

property 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='', virtual_fields=None, book_ids=None)[source]¶

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

Параметри:

restriction – Обмеження яке буде об’єднано логічним «І» із вказаним запитом. Зауважте, що обмеження кешуються, тому пошук «a І b» буде повільнішим за пошук «a» з обмеженням «b».
virtual_fields – Для внутрішнього використання (віртуальні поля, зокрема on_device, для пошуку).
book_ids – Якщо має значення, відмінне від None, пошук виконуватиметься для набору вказаних за допомогою ідентифікаторів книг, а не для усіх книг.

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)[source]¶: Повертає кортеж анотацій, які відповідають вказаному повнотекстовому запиту.

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)[source]¶: Шукає у тексті нотаток за допомогою покажчика повнотекстового пошуку. Якщо запит є порожнім, повертає усі нотатки.

set_annotations_for_book(book_id, fmt, annots_list, user_type='local', user='viewer')[source]¶: Встановити усі анотації для вказаних ідентифікатор_книги, формат, тип_користувача і користувач.

set_conversion_options(options, fmt='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_link_map(field, value_to_link_map, only_set_if_no_existing_link=False)[source]¶

Встановлює посилання для значень пунктів у полі Зауваження: цей метод не змінює значень поза карта_прив“язки_значення_ до_посилання

Параметри:

field – назва фільтра
value_to_link_map – dict(значення_поля:посилання, …). Зауважте, що це значення, а не ідентифікатори полів.

Повертає:

книги, які було змінено встановленням посилання

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_notes_for(field, item_id, doc: str, searchable_text: str = '', resource_hashes=(), remove_unused_resources=False) → int[source]¶: Встановлює документ нотаток. Якщо придатний до пошуку текст відрізняється від документа, вкажіть його як searchable_text. Якщо документ посилається на ресурси, їхні хеші мають бути у resource_hashes. Встановіть для remove_unused_resources значення True, щоб вилучити невикористані ресурси. Зауважте, що оновлення нотатки автоматично і безумовно вилучає ресурси, що стосуються цієї нотатки.

set_pref(name, val, namespace=None)[source]¶: Встановити вказаний рівень пріоритетності. Див. також pref().

split_if_is_multiple_composite(f, val)[source]¶: Якщо f є ключем пошуку складеного стовпчика і стовпчик є is_multiple, поділити v на неповторювані непорожні значення. Порівняння виконуватиметься із врахуванням регістру символів. Порядок не зберігатиметься. Повертає list() для сумісності з отримувачами полів метаданих проксі, наприклад мітками.

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, список відповідників буде обмежено до книг, авторами яких є вказані письменники (без врахування регістру символів).

unretire_note_for(field, item_id) → int[source]¶: Відновлює раніше замасковану нотатку щодо вказаного запису. Нотатки маскують, коли запис вилучають з бази даних.

update_annotations(annot_id_map)[source]¶: Оновити анотації.

user_categories_for_books(book_ids, proxy_metadata_map=None)[source]¶: Повертає категорії користувача для вказаних книг. Параметр proxy_metadata_map є необов’язковим. Він корисний для пришвидшення обробки у контекстах, коли для книг вже існує об’єкт ProxyMetadata. Має повернути прив’язку book_ids до відповідних об’єктів ProxyMetadata.