API-dokumentation för databasgränssnittet

Denna API är trådsäker (använder en flerläsare-, singelskrivar-utelåsningsschema). Du kan komma åt denna API så här:

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

Om du är i en calibre-insticksmodul som är del av calibres huvudanvändargränssnitt, får du tillgång till det så här istället:

db = self.gui.current_db.new_api
class calibre.db.cache.Cache(backend)[source]

En iminnescache av metadata.db filen från calibre-biblioteket. Denna klass fungerar också som en trådsäker API för komma åt databasen. Iminnecachen hanteras på normalt sätt för högsta prestanda.

SQLITE används helt enkelt som ett stabilt sätt att läsa och skriva från metadata.db.

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

Lägg till de angivna böckerna i biblioteket. Böcker bör vara en uppräknelig mängd i multipel av 2, varje multipel av 2 med formen (mi, format_map) där mi är ett metadataobjekt och format_map är en ordlista med formen {fmt: path_or_stream}, till exempel: {'EPUB': '/path/to/file.epub'}.

Återger ett listpar: ids, duplicates. id innehållande bokens identiteter för all nyligen skapade böcker i databasen. ”duplikat” innehåller (mi, format_map) for alla böcker som redan finns i databasen genom enkel heuristisk duplikationsdetektering använd av has_book().

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

Lägg till data för namn där val_map är en karta över book_ids till värden. Om delete_first är True kommer alla tidigare lagrade data för namn tas bort.

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

Lägg till ett format i den angivna boken. Återge True om formatet har lagts till.

Parametrar:
  • replace – Om True ersätt befintligt format, annars om formatet redan finns, återges False
  • run_hooks – Om True, körs filtyp insticksmodul på formatet innan och efter det tilläggs.
  • dbapi – Bara för internt bruk.
all_book_ids(type=<type 'frozenset'>)[source]

Frusen uppsättning av alla kända bokidentiteter.

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

Samma som field_for, förutom att den opererar på flera böcker på samma gång

all_field_ids(name)[source]

Frusen uppsättning av identiteter för alla värden i fältet ”namn”.

all_field_names(field)[source]

Frusen uppsättning av alla fältnamn (bör bara användas för många till en och många till många fält)

author_data(author_ids=None)[source]

Återger författardata som ordlista med nycklar: namn, sort, länk

Om inga författare med angivna identiteter hittas återges en tom ordlista. Om author_ids är None, återges data för alla författare.

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

Given en lista med författare, återge author_sort sträng för författare, framför författarsortering associerad med författare över bearbetade strängen.

books_for_field(name, item_id)[source]

Återger alla böcker associerade med posten identifierad av item_id, där posten tillhör fältet name.

Återgett värde är en mängd av bokidentiteter eller den tomma mängden om posten eller fältet inte finns.

books_in_virtual_library(vl, search_restriction=None)[source]

Returnera uppsättning av böcker som angavs i virtuellt bibliotek

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

Kopiera omslag till filen som objektet dest. Återger False om inget omslag finns eller dest är samma fil som det aktuella omslaget. dest kan också vara en sökväg i vilket fall omslaget kopieras till det om och endast om sökvägen är en annan än den aktuella sökvägen (med små bokstäver i beräkningen).

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

Kopiera formatet fmt till det fillika objektet dest. Om den angivna formatet inte existerar, kasta NoSuchFormat-fel. dest kan också vara en sökväg (till en fil), i vilket fall formatet kopieras till den, om och endast om sökvägen är (skiftlägeskänsligt eller på annat sätt) annorlunda än den aktuella sökvägen.

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

Återge omslagsbild eller inget. Som standard, återges omslag som en byte sträng.

VARNING: Använda as_path kommer att kopiera omslaget till en temporär fil och återge sökvägen till temporära filen. Du bör ta bort temporära filen när du är klar med den.

Parametrar:
  • as_file – Om True återger bilden som ett öppet filobjekt (en SpooledTemporaryFile)
  • as_image – Om True återger bilden som ett Q-bildobjekt
  • as_path – Om True återger bilden som en sökväg till en temporärfil
data_for_find_identical_books()[source]

Återge uppgifter som kan användas för att implementera find_identical_books() i en arbetsprocess utan tillgång till db. Se db.utils för en implementering

data_for_has_book()[source]

Återger data som är lämpliga för användning i :meth:’has_book`. Detta kan användas för en implementering av has_book() i en arbetsprocess utan tillgång till db.

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

Ta bort uppgifter om namn. Som standard raderas all data, om du bara vill ta bort data för vissa bok identifierare, passera i en lista med bokidentifierare.

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

Uppdatera metadata i alla format av de angivna bok_ids till aktuell metadata i databasen.

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

Samma som field_for, förutom att den undviker extra uppslag för att få fältobjektet

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

Återge värdet av fältet name för boken som identifieras av book_id. Om ingen sådan bok existerar eller inte har något definierat värde för fältet name eller inget sådant fält finns, så återges default_value.

default_value används inte för title, title_sort, authors, author_sort och series_index. Detta för dessa alltid har värden i databasen default_value används för anpassade kolumner.

Det återgivna värdet för is_multiple fält är alltid tupler, även om inga värden finns (med andra ord, default_value ignoreras). Undantaget är identifierare som det återgav värdet alltid är en ’dict’. De återgivna tuplerna är alltid i länkordning, det vill säga i vilken ordning de skapades.

field_ids_for(name, book_id)[source]

Återge id:ar (som en tupel) för de värden som fältet namn har på boken som identifieras av book_id. Om det inte finns några värden, eller ingen sådan bok, eller något sådant fält, återges en tom tupel tillbaka.

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

Hittar böcker som har en övermängd av författarna i mi och samma titel (titeln är oklart matchad). Se även :meth:’data_for_find_identical_books`.

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

Återge e-bokformat som en oktettsträng eller None om formatet inte finns, eller att vi inte har behörighet att skriva till e-bokfilen.

Parametrar:
  • as_file – Om det är sant återges e-bokformatet som ett filobjekt. Observera att filobjektet är en SpooledTemporaryFile, så om vad du vill göra är att kopiera formatet till en annan fil, använd copy_format_to() istället för prestanda.
  • as_path – Kopierar formatet filen till en temp fil och återger sökvägen till temp filen
  • preserve_filename – Om True och återges en sökväg, filnamnet är samma som den som används i biblioteket. Observera att detta innebär att upprepade anrop ger samma temp fil (som återskapas varje gång)
format_abspath(book_id, fmt)[source]

Återge absolut sökväg till e-bokfilen i formatet format. Du bör nästan aldrig använda det, eftersom det bryter trådsäkerhetsgarantin i detta API. Använd istället, copy_format_to().

Används för närvarande endast i calibredb-listan, visaren, redigera bok, compare_format till originalformat, öppna med, redigera massmetadata och katalogerna (via get_data_as_dict ()).

Bortsett från visaren, öppna med och redigera boken, tror jag inte någon av de andra gör någon filskrivnings-I/O med resultaten av detta anrop.

format_hash(book_id, fmt)[source]

Återge hash för det angivna formatet för den angivna boken. Den typ av hash är algoritmberoende, men är oftast SHA-256.

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

Återge sökväg, storlek och mtime för det specifika formatet för den specifika boken. Du bör inte använda sökväg annat om du absolut måste, eftersom direkt tillgång av den förstör trådsäkerhetsgarantin av denna API. Istället använd copy_format_to() metoden.

Parametrar:
  • allow_cache – Om True, används cachade värden, annars sker en långsam filsystem tillgång. Cache-värden kan vara utdaterade om tillgång sker till filsystem utanför detta API.
  • update_db – Om ”True” är max_size-fältet av databasen uppdaterad för denna bok.
formats(book_id, verify_formats=True)[source]

Återge tupel av alla format för den specifika boken. Om verify_formats är True verifieras att filer existerar på disken.

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

Används internt för att implementera Taggbläddraren

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

Hämta data för namn. Som standard återges data för alla book_ids, förse med en lista med bokidentifierare om du bara vill ha några data. Återger en översikt av book_id till värden. Om en speciellt värde inte kan identifieras, används istället standardvärde för den.

get_id_map(field)[source]

Återge en översik av id nummer till värden för specifika fält. Fältet måste vara en många-en eller många-många fält, annars genereras ett ValueError.

get_ids_for_custom_book_data(name)[source]

Återge en uppsättning bok id för vilket namn har data.

get_item_id(field, item_name)[source]

Återge posten id för item_name (skiftlägesokänslig)

get_item_ids(field, item_names)[source]

Återge posten id för item_name (skiftlägesokänslig)

get_item_name(field, item_id)[source]

Återge postnamnet för posten som anges av item_id i specificerat fält. Se också get_id_map().

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

Återge metadata för boken identifierat av book_id som ett calibre.ebooks.metadata.book.base.Metadata objekt. Observera att listan av format inte är verifierad. Om get_cover är True, kommer omslag att återges, antingen som en sökväg till temporärfilen mi.cover eller om cover_as_data är Sant som mi.cover_data.

get_next_series_num_for(series, field=u'series', current_indices=False)[source]

Återge nästa serieindex för den specifika serien, med beaktning av olika inställningar som styr generering av nästa serienummer.

Parametrar:
  • field – Serielikt fält (som standard för inbyggda seriekolumnen)
  • current_indices – Om True, återger en översikt av book_id till aktuell serie_index-värde istället.
get_proxy_metadata(book_id)[source]

Liksom: meth:get_metadata förutom att den återger ett ProxyMetadata-objekt som bara läser värden från databasen på förfrågan. Det är mycket snabbare än get_metadata när endast ett mindre antal fält behöver nås från återgett metadataobjekt.

get_usage_count_by_id(field)[source]

Återge en översikt av id till räkningsanvändning för alla värden på det angivna fältet, som måste vara en många-en eller många-många fält.

has_book(mi)[source]

Återge True om och endast om databasen innehåller en post med samma titel som den angivna i Metadataobjektet. Jämförelsen är skiftlägeskänslig. Se även :meth:’data_for_has_book`.

has_format(book_id, fmt)[source]

Återge True om (och endast om) formatet existerar på disk

has_id(book_id)[source]

Återge True om (och endast om) specificerat bok_id existerar i db

init()[source]

Initialisera denna buffring med data från fjärrsidan.

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

Återge en lista med sorterade bokidentifierare. Om ids_to_sort är None, kommer alla bokidentifierare att återges.

fälten måste vara en lista med 2-tupler av formatet (field_name, ascending=True eller False). Det mest signifikata fältet är den första 2-tupeln.

pref(name, default=None)[source]

Återge värdet för det specifika förvalet eller värdet angivet som standard om ingen inställning är angivet.

read_backup(book_id)[source]

Återge OPF-metadata-säkerhetskopian för boken som en bytestring eller None om ingen sådan säkerhetskopia finns.

remove_books(book_ids, permanent=False)[source]

Ta bort böckerna angivna av book_ids från databasen och tar bort deras formatfiler. Om permanent är False, så kommer formatfiler placeras i papperskorgen.

remove_formats(formats_map, db_only=False)[source]

Ta bort angivna format från angivna böcker.

Parametrar:
  • formats_map – En översikt av book_id till en lista med format som ska tas bort från boken.
  • db_only – Om True, tas bara handlingen av format från databasen, tar inte bort de aktuella filformaten från filsystemet.
remove_items(field, item_ids, restrict_to_book_ids=None)[source]

Radera alla post i det angivna fältet med de angivna id. Återger uppsättningen påverkade bok-id. restrict_to_book_ids är en valfri uppsättning bok-id. Om specificerat kommer endast posterna att tas bort från dessa böcker.

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

Byt namn på post från många-en eller många-många fält som taggar eller serier.

Parametrar:
  • change_index – Vid namnändring i en serielikt fält förändras även series_index-värden.
  • restrict_to_book_ids – En valfri uppsättning bok-id där namnbyte ska utföras, standard för alla böcker.
restore_book(book_id, mi, last_modified, path, formats)[source]

Återställ bokposten i databasen för en bok som redan finns i filsystemet

restore_original_format(book_id, original_fmt)[source]

Återställer det angivna formatet från tidigare sparat ORIGINAL_FORMAT, om något. Återger True vid framgång. The ORIGINAL_FORMAT tas bort efter en lyckad återställning.

safe_read_lock

Ett säker läsningslås är ett lås som gör ingenting om tråden redan har en skrivlås, annars begärs ett läslås. Detta är nödvändigt för att förhindra DowngradeLockErrors, vilket kan ske vid uppdatering av sökningen bufferten i närvaro av kompositkolumner. Uppdatering av sökningen bufferten har ett exklusivt lås, men söker en sammansatt kolumn vilket innebär läsning av fältvärden via ProxyMetadata som försöker att få ett delat lås. Det kan finnas andra scenarier som utlöser detta.

Den här egenskapen återger ett nytt låsobjekt på varje åtkomst. Detta låsobjekt är inte rekursivt (för prestanda) och får endast användas i ett med uttalande som with cache.safe_read_lock: annars kommer dåliga saker att hända.

save_original_format(book_id, fmt)[source]

Spara en kopia i angivet format som ORIGINAL_FORMAT, skriver över alla befintliga ORIGINAL_FORMAT.

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

Söker i databasen med angiven sökning, återger en uppsättning av matchade bok id:ar.

Parametrar:
  • restriction – En begränsning som är ANDad med angiven förfrågan. Observera att restriktioner lagras i cache, alltså sökandet efter a AND b kommer att vara långsammare än a med restriktion b.
  • virtual_fields – Använt internt (virtuella fält som on_device för söka efter)
  • book_ids – Om inte None, en uppsättning bok id:ar där böckerna kommer att sökas istället för att söka alla böcker.
set_conversion_options(options, fmt=u'PIPE')[source]

alternativ måste vara en översikt på formen {book_id:conversion_options}

set_cover(book_id_data_map)[source]

Ange omslag för denna bok. data kan antingen vara en QImage, QPixmap, filobjekt eller oktettsträng. Det kan också vara None, i fallet omslag är borttaget.

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

Ange värden av fält angivna av name. Återger uppsättningen av bok id:ar som påverkades av förändringen.

Parametrar:
  • book_id_to_val_map – Översikt av book_ids till värden som bör tillämpas.
  • allow_case_change – Om True, i fall det rör sig om många-en eller många-många fälten förändras. Till exempel, om en bok har taggen tag1 och du anger taggen för en annan bok till Tag1 då kommer båda böckerna att ha taggen Tag1 om allow_case_change är True, annars kommer de båda ha taggen tag1.
  • do_path_update – Används internt, du bör aldrig ändra den.
set_metadata(book_id, mi, ignore_errors=False, force_changes=False, set_title=True, set_authors=True, allow_case_change=False)[source]

Ställ in metadata för bokens id från Metadata-objektet mi

När man sätter force_changes=True tvingas set_metadata att uppdatera fält, även om mi innehåller tomma värden. I det här fallet är ”None” skiljt från ”empty”. Om mi.XXX är None ersätts XXX inte, annars görs det. Taggar, identifierare, och omslagsattribut är specialfall. Taggar och identifierare kan inte ställas in på None för då kommer de alltid ersättas om force_changes är True. Du måste se till att mi innehåller de värden som du vill att boken ska ha. Omlslag förändras alltid om ett nytt omslag finns, men de raderas aldrig . Observera också att force_changes har ingen effekt på inställningen titel eller författare.

set_pref(name, val)[source]

Ställ in den angivna inställningen till det angivna värdet. Se också pref().

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

Återge id av alla böcker som har taggen tagg som är äldre än den angivna tiden. taggjämförelse är skiftlägesoberoende.

Parametrar:
  • delta – En timedelta-objekt eller None. Om None kommer alla id:ar med taggen återges.
  • must_have_tag – Om inte None listan av träffar kommer begränsas till böcker som har denna tagg
  • must_have_authors – En lista med författare. Om inte None listan av träffar kommer begränsas till böcker som har dessa författare (skiftlägesokänslig).
user_categories_for_books(book_ids, proxy_metadata_map=None)[source]

Återge användarkategorier för de angivna böckerna. proxy_metadata_map är valfritt och är användbar för en prestandaökning, i sammanhang där ett ProxyMetadata objekt för böckerna redan finns. Det bör vara en korsreferens av book_ids till deras motsvarande ProxyMetadata objekt.