Dokumentace API pro rozhraní databáze

Toto rozhraní API je bezpečné z hlediska podprocesů (používá schéma vícenásobné čtečky, zamykání jednoduchého zapisovače). K tomuto rozhraní API můžete přistupovat takto:

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

Pokud jste v modulu Calibre, který je součástí hlavního grafického rozhraní Calibre, získáte k němu namísto toho přístup takto:

db = self.gui.current_db.new_api

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

Mezipaměť souboru metadata.db z knihovny calibre uchovávaná v paměti. Tato třída zároveň slouží jako vláknově bezpečné API pro přístup k databázi. Mezipaměť v paměti je kvůli maximálnímu výkonu udržována v normální formě.

SQLITE se používá pouze jako robustní způsob čtení ze souboru metadata.db a zápisu do něj. Veškerá logika čtení, řazení, vyhledávání a ukládání tabulek do mezipaměti je implementována znovu. Bylo to nutné kvůli maximálnímu výkonu a flexibilitě.

class EventType(*values)

book_created = 4

Při vytvoření nového záznamu knihy v databázi, kde jediným argumentem je id knihy

book_edited = 8

Při úpravě formátu knihy, s argumenty: (book_id, fmt)

books_removed = 5

Při odebrání knih z databáze, kde jediným argumentem je seznam id knih

format_added = 2

Při přidání formátu ke knize, s argumenty: (book_id, format)

formats_removed = 3

Při odebrání formátů z knihy, s argumenty: (mapování id knihy na sadu formátů odebraných z knihy)

indexing_progress_changed = 9

Při změně průběhu indexování

items_removed = 7

Při odebrání položek, jako jsou štítky nebo autoři, z některých knih. Argumenty: (field_name, id dotčených knih, id odebraných položek)

items_renamed = 6

Při přejmenování položek, jako jsou štítky nebo autoři, v některých nebo všech knihách. Argumenty: (field_name, id dotčených knih, mapování starého id položky na nové id položky)

links_changed = 11

Při změně odkazů přidružených k položkám, s argumenty: (field_name, item_ids)

metadata_changed = 1

Při změně některých metadat u některých knih, s argumenty: (název změněného pole, sada id dotčených knih)

notes_changed = 10

Při změně poznámek přidružených k položkám, s argumenty: (field_name, item_ids)

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

Přidá zadané knihy do knihovny. Parametr books by měl být iterovatelný přes dvojice, přičemž každá dvojice má tvar (mi, format_map), kde mi je objekt Metadata a format_map je slovník ve tvaru {fmt: path_or_stream}, například {'EPUB': '/path/to/file.epub'}.

Vrátí dvojici seznamů: ids, duplicates. ids obsahuje id knih pro všechny nově vytvořené knihy v databázi. duplicates obsahuje (mi, format_map) pro všechny knihy, které už v databázi existují podle jednoduché heuristiky detekce duplicit používané metodou has_book().

add_custom_book_data(name, val_map, delete_first=False)

Přidá data pro name, kde val_map je mapování book_ids na hodnoty. Pokud je delete_first True, všechna dříve uložená data pro name budou odstraněna.

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

Přidá dodatečné datové soubory

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

Přidá formát k zadané knize. Vrátí True, pokud byl formát úspěšně přidán.

Parametry:

• replace – Pokud je True, nahradí existující formát, jinak v případě, že formát už existuje, vrátí False.

• run_hooks – Pokud je True, před přidáním formátu i po něm se nad formátem spustí moduly typu souboru.

• dbapi – Pouze interní použití.

add_listener(event_callback_function, check_already_added=False)

Zaregistruje callback funkci, která bude volána po provedení určitých akcí nad touto databází. Funkce musí přijímat tři argumenty: (EventType, library_id, event_type_specific_data)

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

Přidá zadaný zdroj, aby na něj mohly odkazovat poznámky, a vrátí jeho hash obsahu

all_annotation_styles()

Vrátí n-tici všech vestavěných stylů anotací.

all_annotation_types()

Vrátí n-tici všech typů anotací v databázi.

all_annotation_users()

Vrátí n-tici všech dvojic (user_type, jméno uživatele), které mají anotace.

all_annotations(restrict_to_user=None, limit=None, annotation_type=None, annotation_style=None, ignore_removed=False, restrict_to_book_ids=None)

Vrátí n-tici všech anotací odpovídajících zadaným kritériím. ignore_removed určuje, zda se vrátí také odebrané (odstraněné) anotace. Odebrané anotace jsou jen kostra používaná ke slučování anotací.

all_annotations_for_book(book_id)

Vrátí n-tici obsahující všechny anotace pro zadané book_id jako slovník s klíči: format, user_type, user, annotation. Zde annotation představuje data anotace.

all_book_ids(type=<class 'frozenset'>)

Neměnná množina všech známých id knih.

all_field_for(field, book_ids, default_value=None)

Stejné jako field_for, s tím rozdílem, že pracuje s více knihami najednou.

all_field_ids(name)

Neměnná množina id pro všechny hodnoty v poli name.

all_field_names(field)

Neměnná množina názvů všech polí (měla by se používat pouze pro pole many-one a many-many)

annotation_count_for_book(book_id)

Vrátí počet anotací pro zadanou knihu dostupných v databázi.

annotations_map_for_book(book_id, fmt, user_type='local', user='viewer')

Vrátí mapování typu anotace -> data anotace pro zadané book_id, format, user a user_type.

author_data(author_ids=None) → dict[int, dict[str, str]]

Vrátí data autorů jako slovník s klíči: name, sort, link

Pokud nejsou nalezeni žádní autoři se zadanými id, vrátí se prázdný slovník. Pokud je author_ids None, vrátí se data pro všechny autory.

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

Pro zadaný seznam autorů vrátí řetězec author_sort pro autory, přičemž před vypočítaným řetězcem upřednostní řazení autora přiřazené k autorovi.

author_sorts(author_ids=None) → dict[int, str]

Vrátí hodnoty řazení autora pro zadané autory.

Pokud nejsou nalezeni žádní autoři se zadanými id, vrátí se prázdný slovník. Pokud je author_ids None, vrátí se data pro všechny autory.

books_for_field(name, item_id)

Vrátí všechny knihy přidružené k položce určené pomocí item_id, kde položka patří do pole name.

Vrácená hodnota je množina id knih nebo prázdná množina, pokud položka nebo pole neexistuje.

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

Vrátí množinu knih v zadané virtuální knihovně.

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

Zkomprimuje obrázky obálek pro zadané knihy. Kvalita komprese 100 provede bezeztrátovou kompresi, jinak se použije ztrátová komprese.

Callback průběhu bude volán s book_id a starou a novou velikostí pro každou zpracovanou knihu. Pokud dojde k chybě, nová velikost bude řetězec s podrobnostmi o chybě.

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

Zkopíruje obálku do objektu podobného souboru dest. Vrátí False, pokud neexistuje žádná obálka nebo pokud dest je stejný soubor jako aktuální obálka. dest může být také cesta; v takovém případě se do ní obálka zkopíruje právě tehdy, když se cesta liší od aktuální cesty, při zohlednění rozlišování velikosti písmen.

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

Zkopíruje formát fmt do objektu podobného souboru dest. Pokud zadaný formát neexistuje, vyvolá chybu NoSuchFormat. dest může být také cesta k souboru; v takovém případě se do ní formát zkopíruje právě tehdy, když se cesta liší od aktuální cesty, při zohlednění rozlišování velikosti písmen.

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

Vrátí obrázek obálky nebo None. Ve výchozím nastavení vrátí obálku jako bytestring.

VAROVÁNÍ: Použití as_path zkopíruje obálku do dočasného souboru a vrátí cestu k tomuto dočasnému souboru. Po dokončení práce byste měli dočasný soubor odstranit.

Parametry:

• as_file – Pokud je True, vrátí obrázek jako otevřený souborový objekt (SpooledTemporaryFile)

• as_image – Pokud je True, vrátí obrázek jako objekt QImage

• as_pixmap – Pokud je True, vrátí obrázek jako objekt QPixmap

• as_path – Pokud je True, vrátí obrázek jako cestu ukazující na dočasný soubor

data_for_find_identical_books()

Vrátí data, která lze použít k implementaci find_identical_books() ve worker procesu bez přístupu k db. Implementaci najdete v db.utils.

data_for_has_book()

Vrátí data vhodná k použití v has_book(). Lze je použít pro implementaci has_book() ve worker procesu bez přístupu k db.

delete_annotations(annot_ids)

Odstraní anotace se zadanými id.

delete_custom_book_data(name, book_ids=())

Odstraní data pro name. Ve výchozím nastavení odstraní všechna data; pokud chcete odstranit data jen pro některá id knih, předejte seznam id knih.

delete_trash_entry(book_id, category)

Odstraní položku z koše. Parametr category je zde ‚b‘ pro knihy a ‚f‘ pro formáty.

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

Aktualizuje metadata ve všech formátech zadaných book_ids na aktuální metadata v databázi.

expire_old_trash()

Odstraní z koše položky, které jsou příliš staré

export_note(field, item_id) → str

Exportuje poznámku jako jeden dokument HTML s obrázky vloženými jako adresy URL se schématem data:

fast_field_for(field_obj, book_id, default_value=None)

Stejné jako field_for, s tím rozdílem, že se vyhne dodatečnému vyhledání objektu pole.

field_for(name, book_id, default_value=None)

Vrátí hodnotu pole name pro knihu určenou pomocí book_id. Pokud taková kniha neexistuje, nemá pro pole name definovanou hodnotu nebo takové pole neexistuje, vrátí se default_value.

default_value se nepoužívá pro title, title_sort, authors, author_sort a series_index. Důvodem je, že tyto položky mají v db vždy hodnoty. default_value se používá pro všechny vlastní sloupce.

Vrácená hodnota pro pole is_multiple je vždy n-tice, i když nejsou nalezeny žádné hodnoty (jinými slovy, default_value se ignoruje). Výjimkou jsou identifiers, pro které je vrácená hodnota vždy dict. Vrácené n-tice jsou vždy v pořadí vazeb, tedy v pořadí, v jakém byly vytvořeny.

field_ids_for(name, book_id)

Vrátí id (jako n-tici) pro hodnoty, které má pole name u knihy určené pomocí book_id. Pokud nejsou žádné hodnoty, neexistuje taková kniha nebo takové pole, vrátí se prázdná n-tice.

field_supports_notes(field=None) → bool

Vrátí True právě tehdy, když zadané pole podporuje poznámky. Pokud je field None, vrátí frozenset všech polí, která podporují poznámky.

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

Najde knihy, které mají nadmnožinu autorů v mi a stejný název (název se porovnává přibližně). Viz také data_for_find_identical_books().

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

Vrátí formát e-knihy jako bytestring nebo None, pokud formát neexistuje nebo nemáme oprávnění zapisovat do souboru e-knihy.

Parametry:

• as_file – Pokud je True, formát e-knihy se vrátí jako souborový objekt. Všimněte si, že souborový objekt je SpooledTemporaryFile, takže pokud chcete formát zkopírovat do jiného souboru, použijte kvůli výkonu raději copy_format_to().

• as_path – Zkopíruje soubor formátu do dočasného souboru a vrátí cestu k dočasnému souboru.

• preserve_filename – Pokud je True a vrací se cesta, název souboru je stejný jako název použitý v knihovně. Všimněte si, že použití této volby znamená, že opakovaná volání vrátí stejný dočasný soubor, který se pokaždé znovu vytvoří.

format_abspath(book_id, fmt)

Vrátí absolutní cestu k souboru e-knihy ve formátu format. Téměř nikdy byste to neměli používat, protože to porušuje příslib vláknové bezpečnosti tohoto API. Místo toho použijte copy_format_to().

V současnosti se používá pouze v calibredb list, prohlížeči, editoru knih, porovnání compare_format s původním formátem, funkci otevřít pomocí, hromadné úpravě metadat a katalozích (přes get_data_as_dict()).

Kromě prohlížeče, funkce otevřít pomocí a editoru knih se nedomnívám, že by kterákoli z ostatních částí prováděla s výsledky tohoto volání jakýkoli zápisový souborový I/O.

format_hash(book_id, fmt)

Vrátí hash zadaného formátu pro zadanou knihu. Druh hashe závisí na backendu, obvykle jde ale o SHA-256.

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

Vrátí cestu, velikost a mtime pro zadaný formát zadané knihy. path byste neměli používat, pokud to není nezbytně nutné, protože přímý přístup k ní porušuje záruky vláknové bezpečnosti tohoto API. Místo toho použijte metodu copy_format_to().

Parametry:

• allow_cache – Pokud je True, použijí se hodnoty z mezipaměti, jinak se provede pomalý přístup k souborovému systému. Hodnoty v mezipaměti mohou být zastaralé, pokud byl k souborovému systému proveden přístup mimo toto API.

• update_db – Pokud je True, pole max_size v databázi se pro tuto knihu aktualizuje.

formats(book_id, verify_formats=True)

Vrátí n-tici všech formátů pro zadanou knihu. Pokud je verify_formats True, ověří, že soubory existují na disku.

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

Vrátí všechna item_ids položek, které mají poznámky v zadaném poli, nebo pro všechna pole, pokud je field_name None

get_all_link_maps_for_book(book_id)

Vrátí všechny odkazy pro všechna pole odkazovaná knihou určenou pomocí book_id. Pokud book_id neexistuje, metoda vrátí {}.

Příklad: Předpokládejme, že autor A má odkaz X, autor B má odkaz Y, štítek S má odkaz F a štítek T má odkaz G. Pokud má kniha 1 autora A a štítek T, tato metoda vrátí {‚authors‘:{‚A‘:‘X‘}, ‚tags‘:{‚T‘, ‚G‘}}. Pokud autor knihy 2 není ani A, ani B a kniha nemá žádné štítky, tato metoda vrátí {}.

Parametry:

book_id – příslušné id knihy.

Vrací:

{field: {field_value, link_value}, … pro všechna pole, kde má field_value pro tuto knihu neprázdnou hodnotu odkazu

get_book_path(book_id, sep='/', unsafe=False)

Vrátí relativní cestu knihy pro dané id. Preferujte tuto metodu, protože můžete zvolit oddělovač adresářů; ve výchozím nastavení se použije oddělovač OS. Pokud je unsafe True, povolí vrátit None, pokud book_id není v knihovně.

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

Používá se interně k implementaci Prohlížeče štítků

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

Získá data pro name. Ve výchozím nastavení vrací data pro všechna book_ids; pokud chcete jen některá data, předejte seznam id knih. Vrátí mapování book_id na hodnoty. Pokud konkrétní hodnotu nelze dekódovat, použije pro ni default.

get_id_map(field)

Vrátí mapování čísel id na hodnoty pro zadané pole. Pole musí být many-one nebo many-many, jinak je vyvolána chyba ValueError.

get_ids_for_custom_book_data(name)

Vrátí množinu id knih, pro které má name data.

get_item_id(field, item_name, case_sensitive=False)

Vrátí id položky pro item_name, nebo None, pokud ji nenajde. Tato funkce je velmi pomalá; pokud vyhledáváte více názvů, použijte get_item_ids() nebo get_item_name_map(). Podobně platí, že vyhledávání rozlišující velikost písmen je rychlejší než vyhledávání bez rozlišování velikosti písmen.

get_item_ids(field, item_names, case_sensitive=False)

Vrátí dict mapující item_name na id položky nebo None

get_item_name(field, item_id)

Vrátí název položky pro položku určenou pomocí item_id v zadaném poli. Viz také get_id_map().

get_item_name_map(field, normalize_func=None)

Vrátí mapování hodnot položek na id

get_link_map(for_field)

Vrátí slovník odkazů pro zadané pole.

Parametry:

for_field – lookup název pole, pro které je požadována mapa odkazů

Vrací:

{field_value:link_value, …} pro neprázdné odkazy

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

Vrátí metadata pro knihu určenou pomocí book_id jako objekt calibre.ebooks.metadata.book.base.Metadata. Všimněte si, že seznam formátů se neověřuje. Pokud je get_cover True, vrátí se obálka, buď jako cesta k dočasnému souboru v mi.cover, nebo pokud je cover_as_data True, jako mi.cover_data.

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

Vrátí další index série pro zadanou sérii s přihlédnutím k různým předvolbám, které řídí generování dalšího čísla série.

Parametry:

• field – Pole podobné sérii (výchozí je vestavěný sloupec série)

• current_indices – Pokud je True, místo toho vrátí mapování book_id na aktuální hodnotu series_index.

get_notes_resource(resource_hash) → dict | None

Vrátí dict obsahující data zdroje a název, nebo None, pokud není nalezen žádný zdroj se zadaným hashem

get_pages(book_id: int) → Pages | None

Vrátí informace o počtu stran pro zadanou knihu

get_proxy_metadata(book_id)

Podobné jako get_metadata(), s tím rozdílem, že vrací objekt ProxyMetadata, který čte hodnoty z databáze pouze na vyžádání. Je to mnohem rychlejší než get_metadata, pokud je z vráceného objektu metadat potřeba přistupovat jen k malému počtu polí.

get_usage_count_by_id(field)

Vrátí mapování id na počet použití pro všechny hodnoty zadaného pole, které musí být pole many-one nebo many-many.

has_book(mi)

Vrátí True právě tehdy, když databáze obsahuje záznam se stejným názvem jako předaný objekt Metadata. Porovnání nerozlišuje velikost písmen. Viz také data_for_has_book().

has_format(book_id, fmt)

Vrátí True právě tehdy, když formát existuje na disku.

has_id(book_id)

Vrátí True právě tehdy, když zadané book_id existuje v db.

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

Importuje dříve exportovanou poznámku nebo libovolný soubor HTML jako poznámku pro zadanou položku

init()

Inicializuje tuto mezipaměť daty z backendu.

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

Vrátí dict mapující pole na položky, které mají u zadané knihy přidružené poznámky pro dané pole

link_for(field, item_id)

Vrátí odkaz pro zadanou položku, pokud existuje, nebo None, pokud žádný odkaz nenajde

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

Získá informace o dodatečných souborech v adresáři knihy.

Parametry:

• book_id – databázové id knihy

• pattern – vzor názvů souborů, který se má hledat. Prázdný vzor odpovídá všem dodatečným souborům. Vzory musí používat / jako oddělovač. K nalezení souborů uvnitř adresáře data použijte konstantu DATA_FILE_PATTERN.

Vrací:

N-tice všech dodatečných souborů odpovídajících zadanému vzoru. Každý prvek n-tice je ExtraFile(relpath, file_path, stat_result). relpath je relativní cesta souboru k adresáři knihy s použitím / jako oddělovače. stat_result je výsledek volání os.stat() nad souborem.

mark_for_pages_recount(book_id: int = 0) → None

Označí všechny knihy k přepočítání stran

merge_annotations_for_book(book_id, fmt, annots_list, user_type='local', user='viewer')

Sloučí zadané anotace s existujícími anotacemi pro book_id, fmt, user_type a user.

merge_extra_files(dest_id, src_ids, replace=False)

Sloučí dodatečné soubory ze src_ids do dest_id. Konfliktní soubory se automaticky přejmenují, pokud není replace=True; pokud replace=True, nahradí se.

move_book_from_trash(book_id)

Obnoví knihu z adresáře koše

move_format_from_trash(book_id, fmt)

Obnoví formát z adresáře koše

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

Vrátí seznam seřazených id knih. Pokud je ids_to_sort None, vrátí se všechna id knih.

fields musí být seznam dvojic ve tvaru (field_name, ascending=True nebo False). Nejdůležitější pole je první dvojice.

notes_data_for(field, item_id) → str

Vrátí všechna data poznámky jako dict, nebo None, pokud poznámka neexistuje

notes_for(field, item_id) → str

Vrátí dokument poznámky nebo prázdný řetězec, pokud jej nenajde

notes_resources_used_by(field, item_id)

Vrátí množinu hashů všech zdrojů použitých poznámkou pro zadanou položku

pages_needs_scan(books: Iterable[int] = ()) → set[int]

Vrátí podmnožinu knih (nebo všechny knihy, pokud je vstup prázdný), které jsou označené jako vyžadující skenování kvůli aktualizaci počtu stran

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

Vrátí hodnotu zadané předvolby nebo hodnotu určenou jako default, pokud předvolba není nastavena.

queue_pages_scan(book_id: int = 0, force: bool = False, by_user: bool = True) → None

Zahájí skenování, které aktualizuje počty stran pro všechny knihy vyžadující skenování. Pokud je zadáno book_id, skenuje se jen tato kniha a skenuje se vždy. Pokud je force True, existující hodnota pages se zahodí, pokud existuje, takže se kniha nuceně znovu naskenuje, i když byla existující hodnota aktuální.

read_backup(book_id)

Vrátí zálohu metadat OPF pro knihu jako bytestring nebo None, pokud taková záloha neexistuje.

remove_books(book_ids, permanent=False)

Odstraní z databáze knihy určené pomocí book_ids a odstraní jejich soubory formátů. Pokud je permanent False, soubory formátů se přesunou do adresáře koše po jednotlivých knihovnách.

remove_extra_files(book_id: int, relpaths: Iterable[str], permanent=False) → dict[str, Exception | None]

Odstraní zadané dodatečné soubory buď přesunutím do koše, nebo trvale.

remove_formats(formats_map, db_only=False)

Odstraní zadané formáty ze zadaných knih.

Parametry:

• formats_map – Mapování book_id na seznam formátů, které mají být z knihy odstraněny.

• db_only – Pokud je True, odstraní z db pouze záznam formátu, ale skutečný soubor formátu ze souborového systému neodstraní.

Vrací:

Mapování id knih na množiny formátů skutečně odstraněných ze systému souborů pro příslušné knihy

remove_items(field, item_ids, restrict_to_book_ids=None)

Odstraní všechny položky v zadaném poli se zadanými id. Vrátí množinu dotčených id knih. restrict_to_book_ids je volitelná množina id knih. Pokud je zadána, položky se odstraní pouze z těchto knih.

rename_extra_files(book_id, map_of_relpath_to_new_relpath, replace=False)

Přejmenuje dodatečné datové soubory

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

Přejmenuje položky z pole many-one nebo many-many, například štítky nebo série.

Parametry:

• change_index – Při přejmenování v poli podobném sérii změní také hodnoty series_index.

• restrict_to_book_ids – Volitelná množina id knih, pro které má být přejmenování provedeno; výchozí hodnota jsou všechny knihy.

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

Obnoví v databázi záznam knihy pro knihu, která už existuje v souborovém systému.

restore_original_format(book_id, original_fmt)

Obnoví zadaný formát z dříve uloženého ORIGINAL_FORMAT, pokud existuje. Při úspěchu vrátí True. Po úspěšné obnově se ORIGINAL_FORMAT odstraní.

property safe_read_lock

Bezpečný zámek pro čtení je zámek, který neudělá nic, pokud vlákno už má zámek pro zápis; jinak získá zámek pro čtení. Je to nutné kvůli zabránění DowngradeLockErrors, k nimž může dojít při aktualizaci mezipaměti vyhledávání za přítomnosti složených sloupců. Aktualizace mezipaměti vyhledávání drží exkluzivní zámek, ale vyhledávání ve složeném sloupci zahrnuje čtení hodnot polí přes ProxyMetadata, které se pokouší získat sdílený zámek. Mohou existovat i další scénáře, které toto chování vyvolají.

Tato vlastnost při každém přístupu vrátí nový objekt zámku. Tento objekt zámku není rekurzivní (kvůli výkonu) a smí se používat pouze v příkazu with jako with cache.safe_read_lock:, jinak dojde k nežádoucím následkům.

save_original_format(book_id, fmt)

Uloží kopii zadaného formátu jako ORIGINAL_FORMAT a přepíše případný existující ORIGINAL_FORMAT.

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

Vyhledá v databázi zadaný dotaz a vrátí množinu odpovídajících id knih.

Parametry:

• restriction – Omezení, které je k zadanému dotazu připojeno logickým operátorem AND. Všimněte si, že omezení se ukládají do mezipaměti, proto bude vyhledání a AND b pomalejší než a s omezením b.

• virtual_fields – Používá se interně pro vyhledávání ve virtuálních polích, například on_device.

• book_ids – Pokud není None, množina id knih, ve kterých se bude vyhledávat místo vyhledávání ve všech knihách.

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, annotation_style=None)

Vrátí n-tici anotací odpovídajících zadanému fulltextovému dotazu.

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)

Prohledá text poznámek pomocí indexu FTS. Pokud je dotaz prázdný, vrátí všechny poznámky.

set_annotations_for_book(book_id, fmt, annots_list, user_type='local', user='viewer')

Nastaví všechny anotace pro zadané book_id, fmt, user_type a user.

set_conversion_options(options, fmt='PIPE')

options musí být mapování ve tvaru {book_id:conversion_options}

set_cover(book_id_data_map)

Nastaví obálku pro tuto knihu. Data mohou být QImage, QPixmap, souborový objekt nebo bytestring. Mohou být také None, v takovém případě se odstraní případná existující obálka.

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

Nastaví hodnoty pole určeného pomocí name. Vrátí množinu všech id knih, kterých se změna dotkla.

Parametry:

• book_id_to_val_map – Mapování book_ids na hodnoty, které se mají použít.

• allow_case_change – Pokud je True, změní se velikost písmen polí many-one nebo many-many. Pokud má například jedna kniha štítek tag1 a jiné knize nastavíte štítek Tag1, budou mít obě knihy štítek Tag1, pokud je allow_case_change True; jinak budou mít obě štítek tag1.

• do_path_update – Používá se interně, nikdy byste ho neměli měnit.

set_link_map(field, value_to_link_map, only_set_if_no_existing_link=False)

Nastaví odkazy pro hodnoty položek v poli. Poznámka: tato metoda nemění hodnoty, které nejsou ve value_to_link_map

Parametry:

• field – lookup název

• value_to_link_map – dict(field_value:link, …). Upozorňujeme, že jde o hodnoty, ne o id polí.

Vrací:

knihy změněné nastavením odkazu

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

Nastaví metadata pro knihu id z objektu Metadata mi

Nastavení force_changes=True vynutí, aby set_metadata aktualizovalo pole i tehdy, když mi obsahuje prázdné hodnoty. V takovém případě se rozlišuje mezi ‚None‘ a ‚empty‘. Pokud je mi.XXX None, XXX se nenahradí, jinak ano. Atributy tags, identifiers a cover jsou zvláštní případy. Tags a identifiers nelze nastavit na None, takže se vždy nahradí, pokud je force_changes true. Musíte zajistit, aby mi obsahovalo hodnoty, které má kniha mít. Obálky se vždy změní, pokud je poskytnuta nová obálka, ale nikdy se neodstraňují. Všimněte si také, že force_changes nemá žádný vliv na nastavení title nebo authors.

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

Nastaví dokument poznámky. Pokud se prohledávatelný text liší od dokumentu, zadejte ho jako searchable_text. Pokud dokument odkazuje na zdroje, jejich hashe musí být přítomny v resource_hashes. Nastavte remove_unused_resources na True, aby se vyčistily nepoužívané zdroje; upozorňujeme, že aktualizace poznámky stejně automaticky vyčistí zdroje patřící k této poznámce.

set_pages(book_id: int, pages: int = 0, algorithm: int = 0, format: str = '', format_size: int = 0) → None

Nastaví informace o počtu stran pro zadanou knihu

set_pref(name, val, namespace=None)

Nastaví zadanou předvolbu na zadanou hodnotu. Viz také pref().

split_if_is_multiple_composite(f, val)

Pokud je f lookup klíčem složeného sloupce a sloupec je is_multiple, rozdělí v na jedinečné neprázdné hodnoty. Porovnání rozlišuje velikost písmen. Pořadí se nezachovává. Vrátí list() kvůli kompatibilitě s gettery polí ProxyMetadata, například tags.

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

Vrátí id všech knih se štítkem tag, které jsou starší než zadaný čas. Porovnání tag nerozlišuje velikost písmen.

Parametry:

• delta – Objekt timedelta nebo None. Pokud je None, vrátí se všechna id se štítkem.

• must_have_tag – Pokud není None, seznam shod bude omezen na knihy, které mají tento štítek.

• must_have_authors – Seznam autorů. Pokud není None, seznam shod bude omezen na knihy, které mají tyto autory, bez rozlišování velikosti písmen.

unretire_note_for(field, item_id) → int

Obnoví dříve vyřazenou poznámku pro zadanou položku. Poznámky se vyřadí, když je položka odstraněna z databáze

update_annotations(annot_id_map)

Aktualizuje anotace.

user_categories_for_books(book_ids, proxy_metadata_map=None)

Vrátí uživatelské kategorie pro zadané knihy. proxy_metadata_map je volitelné a je užitečné pro zvýšení výkonu v kontextech, kde už pro knihy existuje objekt ProxyMetadata. Mělo by jít o mapování book_ids na odpovídající objekty ProxyMetadata.

© Copyright Kovid Goyal. Naposledy aktualizováno čvc 03, 2026.