API-dokumentation för e-bokredigeringsverktygen¶
E-bokredigeringsverktygen består av calibre.ebooks.oeb.polish.container.Container poster som representerar en bok som en samling av HTML + resursfiler, samt olika verktyg som kan användas för att utföra operationer på behållaren. Alla verktyg är i form av modulnivåsfunktioner i de olika calibre.ebooks.oeb.polish.* modulerna.
Du erhåller ett behållarobjekt för en bok på en sökväg så här:
from calibre.ebooks.oeb.polish.container import get_container
container = get_container('Path to book file', tweak_mode=True)
Om du skriver en insticksmodul för E-bokredigeraren, får du den aktuella behållaren för boken som redigeras så här:
from calibre.gui2.tweak_book import current_container
container = current_container()
if container is None:
report_error # No book has been opened yet
Behållarobjektet¶
- class calibre.ebooks.oeb.polish.container.Container(rootpath=None, opfpath=None, log=<calibre.utils.logging.Log object>, clone_data=None)[source]¶
En behållare representerar en öppen e-bok som en mapp full av filer och en OPF-fil. Det finns två viktiga begrepp:
Rotmappen. Detta är basen för e-boken. Alla e-böcker finns i denna mapp eller i dess undermappar.
Namn: Dessa är sökvägar till böckernas filer relativt rotmappen. De innehåller alltid POSIX-avskiljare och är utan citattecken. De kan ses som kanoniska identifierare för filer i boken. De flesta metoder på behållarobjektet arbetar med namn. Namn är alltid i NFC Unicode-normalformen.
Kloner: Behållarobjektet stöder effektiv kloning på disk, vilket används för att implementera kontrollpunkter i e-bokredigeraren. För att detta ska fungera får du aldrig komma åt filerna i filsystemet direkt. Använd i stället
raw_data()elleropen()för att läsa och skriva komponentfiler i boken.
När du konverterar mellan hrefs och namn använd de metoder som denna klass tillhandahåller, de antar att alla hrefs är i citattecken.
- abspath_to_name(fullpath, root=None)[source]¶
Konvertera en absolut sökväg till ett kanoniskt namn i förhållande till
root- Parametrar:
root – Grundmappen. Som standard används roten till detta behållarobjekt.
- add_file(name, data=b'', media_type=None, spine_index=None, modify_name_if_needed=False, process_manifest_item=None, suggested_id='')[source]¶
Lägg till en fil i denna behållare. Poster för filen skapas automatiskt i OPF-manifestet och bokryggen (om filen är ett textdokument)
- add_name_to_manifest(name, process_manifest_item=None, suggested_id='')[source]¶
Lägg till en post i manifestet för en fil med angivna namnet. Returnerar manifest-id.
- add_properties(name, *properties)[source]¶
Lägg specificerade egenskaperna i manifestposten som identifierats med namn.
- apply_unique_properties(name, *properties)[source]¶
Se till att de angivna egenskaperna är inställt på endast manifestposten som identifierats med ett namn. Du kan använda None som namn för att ta bort egenskapen från alla post.
- book_type = 'oeb'¶
Typen av bok (epub för EPUB-filer och azw3 för AZW3-filer)
- commit(outpath=None, keep_parsed=False)[source]¶
Skriv alla ändrade analyserade objekt till filsystemet och skriv e-boksfilen till utsökvägen.
- Parametrar:
output – Sökvägen som den sparade e-boksfilen ska skrivas till. Om värdet är None används sökvägen till den ursprungliga bokfilen.
keep_parsed – Om True kommer analyserade representationer av engagerade poster hållas i cache.
- commit_item(name, keep_parsed=False)[source]¶
Överlämnar ett analyserat objekt till disken (det serialiseras och skrivs till den underliggande filen). Om
keep_parsedär True behålls den analyserade representationen i cachen. Se även:parsed()
- dirty(name)[source]¶
Markera det analyserade objektet som motsvarar namnet som smutsigt. Se även:
parsed().
- exists(name)[source]¶
Returnerar True om och endast om en fil eller mapp med det kanoniska namnet finns. Observera att funktionen begränsas av det underliggande filsystemet, särskilt dess skiftlägeskänslighet. På ett skiftlägesokänsligt filsystem returneras därför True även om skiftläget i name skiljer sig från filens eller mappens faktiska namn. Se även
has_name().
- filesize(name)[source]¶
Returnera filstorleken i byte för filen med det angivna kanoniska namnet. Ändrade analyserade objekt hanteras automatiskt. Se även
parsed().
- generate_item(name, id_prefix=None, media_type=None, unique_href=True)[source]¶
Lägg till en post i manifestet med href härledd från det angivna namnet. Säkerställer unika href och id automatiskt. Returnerar genererad post.
- get_file_path_for_processing(name, allow_modification=True)[source]¶
Liknar open() förutom att den returnerar en sökväg, i stället för ett öppet filobjekt.
- property guide_type_map¶
Kartläggning av guidetyp till kanoniskt namn
- has_name(name)[source]¶
Returnera True om och endast om en fil med samma kanoniska namn som angetts finns. Till skillnad från
exists()är denna metod alltid skiftlägeskänslig.
- href_to_name(href, base=None)[source]¶
Konvertera en href (relativ till bas) till ett namn. basen måste vara ett namn eller None, i vilket fall self.root används.
- insert_into_xml(parent, item, index=None)[source]¶
Infoga post i förälder (eller lägga till om index är None), fastställande indrag. Fungerar endast med självstängande post.
- is_dir = False¶
Om denna container representerar en uppackad bok (en katalog)
- iterlinks(name, get_line_numbers=True)[source]¶
Iterera över alla länkar i namnet. Om get_line_numbers är True ger det resultat i form (länk, line_number, offset). Där line_number är line_number där länken förekommer och offset är antalet tecken från början av raden. Observera att offset kan faktiskt omfatta flera rader om inte noll.
- make_name_unique(name)[source]¶
Se till att name inte redan finns i denna bok. Om den gör det, returnera en ändrad version som inte finns.
- property manifest_id_map¶
Kartläggning av manifest-id till kanoniska namn
- manifest_items_of_type(predicate)[source]¶
Namnen på alla manifestposter vars medietyp matcher predikat. predicate kan vara en uppsättning, en lista, en sträng eller en funktion som tar ett enda argument, som kommer att anropas med medietypen.
- manifest_items_with_property(property_name)[source]¶
Alla uppenbara post som har den angivna egenskapen
- property manifest_type_map¶
Kartläggning av manifest mediatyp till lista med canonical namn av den mediatypen Kartläggning av manifest mediatyp till lista med kanoniska namn på den medietypen
- property mi¶
Metadata från den här boken som ett metadataobjekt. Observera att det här objektet är konstruerad i farten varje gång den här egenskapen begärs, så använd den sparsamt.
- name_to_href(name, base=None)[source]¶
Konvertera ett namn till en href relativt base, som måste vara ett namn eller None. Om värdet är None används self.root som bas
- property names_that_must_not_be_changed¶
Uppsättning med namn som aldrig får byta namn. Beror på e-bokformatet.
- property names_that_must_not_be_removed¶
Uppsättning med namn som aldrig får tas bort från behållaren. Beror på e-bokformat.
- property names_that_need_not_be_manifested¶
Uppsättning av namn som får saknas i manifestet. Beror på e-bokformat.
- open(name, mode='rb')[source]¶
Öppna filen som name pekar på för direkt läsning och skrivning. Observera att ändringarna sparas om filen modifieras och att filen tas bort från tolkningscachen. Du måste vara klar med filen innan du åter öppnar den tolkade versionen, annars kan fel uppstå.
- property opf¶
Den analyserad OPF-filen
- opf_get_or_create(name)[source]¶
Hjälpmetod som returnerar det första XML-elementet med det angivna namnet. Om elementet inte finns skapas det under
opf:packageoch returneras sedan.
- property opf_version¶
Den version som ställts in på OPF:s <package> elementet
- property opf_version_parsed¶
Den version som ställts in på OPF:s <package> element som en tupel av heltal
- opf_xpath(expr)[source]¶
Bekväm metod för att beräkna ett XPath-uttryck på OPF-filen har fördefinierade opf: och dc:namespace prefix.
- parsed(name)[source]¶
Returnera en analyserad representation av filen med det angivna namnet. För HTML- och XML-filer returneras ett lxml-träd, och för CSS-filer en formatmall från css_parser. Analyserade objekt cachelagras av prestandaskäl. Om du ändrar ett analyserat objekt måste du anropa
dirty()så att behållaren vet att cachen ska uppdateras. Se ävenreplace().
- raw_data(name, decode=True, normalize_to_nfc=True)[source]¶
Returnera rådata motsvarande filen som anges med namn
- Parametrar:
decode – Om True och filen har en textbaserad MIME-typ, avkoda den och returnera ett unicode-objekt i stället för råa byte.
normalize_to_nfc – Om True är det återgivna unicode-objektet normaliserat till NFC-normalformen som krävs för filformaten EPUB och AZW3.
- relpath(path, base=None)[source]¶
Konvertera en absolut sökväg, med operativsystemets sökvägsavgränsare, till en sökväg relativ till base. Standardvärdet för base är self.root. Den relativa sökvägen är inte ett namn. Använd
abspath_to_name()för det.
- remove_from_spine(spine_items, remove_if_no_longer_in_spine=True)[source]¶
Ta bort de angivna posterna (av kanoniskt namn) från bokryggen. Om
remove_if_no_longer_in_spineär True tas även posten bort från boken, inte bara från bokryggen.
- remove_from_xml(item)[source]¶
Tar bort posten från förälder, rättar till indrag (fungerar bara med självstängande poster)
- remove_item(name, remove_from_guide=True)[source]¶
Ta bort posten som identifieras med namn från den här behållaren. Detta tar bort alla referenser till posten i OPF-manifestet, guiden och ryggrraden samt från eventuella interna cacher.
- rename(current_name, new_name)[source]¶
Byter namn på en fil från current_name till new_name. Den omställer automatiskt alla länkar inuti filen om den mapp filen är i ändras. Observera dock att länkar inte uppdateras i andra filer som kan referera till den här filen. Detta är för prestanda, sådana uppdateringar bör göras en gång, i grupp.
- replace(name, obj)[source]¶
Ersätt det analyserade objektet som motsvarar namnet med obj, som måste vara ett liknande objekt, dvs. ett lxml-träd för HTML/XML eller en css_parser-formatmall för en CSS-fil.
- replace_links(name, replace_func)[source]¶
Ersätt alla länkar i
namemedreplace_func. Funktionen måste vara ett anropbart objekt som tar emot en URL och returnerar den nya URL:en. Den måste även ha attributetreplaced, som sätts till True när en faktisk ersättning görs. Sådana objekt kan enkelt skapas medLinkReplacerochLinkRebaser.
- serialize_item(name)[source]¶
Konvertera ett analyserat objekt, identifierat med sitt kanoniska namn, till en bytesträng. Se
parsed().
- set_spine(spine_items)[source]¶
Anpassa bokryggen att vara spine_items där spine_items visas som en iterabel av formen (name, linear). Kommer ge ett felmeddelande om ett av namnen finns inte i manifestet.
- property spine_items¶
En iterator som ger sökväg för varje del i bokryggar. Se även:
spine_iterochspine_items.
- property spine_iter¶
En iterator som för varje post i bokens rygg returnerar
item, name, is_linear.itemär lxml-elementet,namedet kanoniska filnamnet ochis_linearär True om posten är linjär. Se ävenspine_namesochspine_items.
- property spine_names¶
En iterator som ger name och is_linear för varje post i bokens rygg. Se även:
spine_iterochspine_items.
Hantera komponentfiler i en behållare¶
- calibre.ebooks.oeb.polish.replace.replace_links(container, link_map, frag_map=<function <lambda>>, replace_in_opf=False)[source]¶
Ersätt länkar till filer i behållaren. Kommer iterera över alla filer i behållaren och ändra de angivna länkar i dem.
- Parametrar:
link_map – En kartläggning av kanoniska namn till nya kanoniska namn. Till exempel:
{'images/old.png': 'images/new.png'}frag_map – Ett anropbart objekt som tar argumenten
(name, anchor)och returnerar ett nytt ankare. Det är användbart när ankare i HTML-filer behöver ändras. Som standard gör objektet ingenting.replace_in_opf – Om False, ersätts inte länkar i OPF-filen.
- calibre.ebooks.oeb.polish.replace.rename_files(container, file_map)[source]¶
Byt namn på filer i behållaren, uppdaterar automatiskt alla länkar till dem.
- Parametrar:
file_map – En kartläggning av gammalt kanoniskt namn till nytt kanoniskt namn, till exempel:
{'text/chapter1.html': 'chapter1.html'}.
- calibre.ebooks.oeb.polish.replace.get_recommended_folders(container, names)[source]¶
Returnera mapparna som rekommenderas för de givna filnamnen. Rekommendationen är baserad på var majoriteten av filer av samma typ finns i behållaren. Om inga filer av en viss typ är närvarande, antas den rekommenderade mappen vara den mapp som innehåller OPF-filen.
Fin utskrift och automatisk reparation av tolkningsfel¶
- calibre.ebooks.oeb.polish.pretty.fix_html(container, raw)[source]¶
Åtgärda eventuella tolkningsfel i HTML representeras som en råsträng. Åtgärd görs med HTML5 tolkningsalgoritmen.
- calibre.ebooks.oeb.polish.pretty.fix_all_html(container)[source]¶
Åtgärda eventuella tolkningsfel i alla HTML-filer i containern. Åtgärd görs med HTML5 tolkningsalgoritmen.
- calibre.ebooks.oeb.polish.pretty.pretty_html(container, name, raw)[source]¶
Fin utskrift HTML representeras som en råsträng
- calibre.ebooks.oeb.polish.pretty.pretty_css(container, name, raw)[source]¶
Fin utskrift CSS representerad som en råsträng
Hantera bokomslag¶
Delning och sammanslagning av filer¶
- calibre.ebooks.oeb.polish.split.split(container, name, loc_or_xpath, before=True, totals=None)[source]¶
Dela upp filen som anges med namn vid den position som anges av loc_or_xpath. Uppdelning migrerar automatiskt alla länkar och referenser till de berörda filerna.
- Parametrar:
loc_or_xpath – Bör vara ett XPath-uttryck som //h:div[@id=”split_here”]. Kan också vara en loc som används internt för att genomföra uppdelningen i förhandsgranskningspanelen.
before – Om True sker uppdelningen innan det identifierade elementet annars efter det.
totals – Används internt
- calibre.ebooks.oeb.polish.split.multisplit(container, name, xpath, before=True)[source]¶
Dela den angivna filen på flera platser (alla taggar som matchar det angivna XPath-uttrycket). Se också:
split(). Delning migrerar automatiskt alla länkar och referenser till de berörda filerna.- Parametrar:
before – Om True sker uppdelningar innan det identifierade elementet annars efter det.
- calibre.ebooks.oeb.polish.split.merge(container, category, names, master)[source]¶
Slå samman de angivna filerna till en enda fil, migrera alla länkar och referenser till de berörda filerna automatiskt. Alla filer måste vara antingen HTML- eller CSS-filer.
- Parametrar:
category – Måste vara antingen
'text'för HTML-filer eller'styles'för CSS-filernames – Listan med filer som ska slås samman
master – Vilken av de sammanslagna filer är huvud-fil, som är den fil som kommer att finnas kvar efter sammanslagning.
Hanterar omslag¶
- calibre.ebooks.oeb.polish.cover.set_cover(container, cover_path, report=None, options=None)[source]¶
Ställ in omslaget på boken till den bild som hänvisas till av cover_path.
- Parametrar:
cover_path – Antingen den absoluta sökvägen till en bildfil eller kanoniska namn på en bild i boken. När du använder en bild i boken måste du också ställa in alternativ, se nedan.
report – En valfri anropningsbar som tar ett enda argument. Den kommer att anropas med information om de uppgifter som behandlas.
options – None eller en ordbok som styr hur omslaget anges. Ordboken kan innehålla följande poster: keep_aspect: True eller False (bevara omslagets proportioner i EPUB), no_svg: True eller False (använd en SVG-omslutning för omslaget på EPUB-titelsidan), existing: True eller False (
cover_pathhänvisar till en befintlig bild i boken).
Att arbeta med CSS¶
- calibre.ebooks.oeb.polish.fonts.change_font(container, old_name, new_name=None)[source]¶
Ändra en teckensnittsfamilj från old_name till new_name. Alla förekomster av teckensnittsfamiljen ändras i formatmallar, style-taggar och style-attribut. Om old_name hänvisar till ett inbäddat teckensnitt tas det bort. Du kan ange None för new_name om du vill ta bort teckensnittsfamiljen i stället för att ändra den.
- calibre.ebooks.oeb.polish.css.remove_unused_css(container, report=None, remove_unused_classes=False, merge_rules=False, merge_rules_with_identical_properties=False, remove_unreferenced_sheets=False)[source]¶
Ta bort alla oanvända CSS-regler från boken. En oanvänd CSS-regel är en som inte matchar något faktiskt innehåll.
- Parametrar:
report – En valfri anropningsbar som tar ett enda argument. Den anropas med information om de operationer som utförs.
remove_unused_classes – Om True tas klassattribut i HTML som inte matchar några CSS-regler också bort.
merge_rules – Om True, slå samman regler med identiska väljare.
merge_rules_with_identical_properties – Om True, slå samman regler med identiska egenskaper.
remove_unreferenced_sheets – Om True, tas formatmallar som inte refereras av något innehåll bort
- calibre.ebooks.oeb.polish.css.filter_css(container, properties, names=())[source]¶
Ta bort de angivna CSS-egenskaperna från alla CSS-regler i boken.
- Parametrar:
properties – Uppsättning av egenskaper för att ta bort. Till exempel:
{'font-family', 'color'}.names – Filerna från vilka egenskaper ska tas bort. Standardvärden för alla HTML- och CSS-filer i boken.
Arbeta med innehållsförteckning¶
- calibre.ebooks.oeb.polish.toc.from_xpaths(container, xpaths, prefer_title=False)[source]¶
Skapa en innehållsförteckning från en lista med XPath-uttryck. Varje uttryck i listan motsvarar en nivå av den skapade innehållsförteckningen. Till exempel:
['//h:h1', '//h:h2', '//h:h3']kommer att skapa en trenivåers innehållsförteckning från<h1>,<h2>och<h3>taggar.
- calibre.ebooks.oeb.polish.toc.from_links(container)[source]¶
Skapa innehållsförteckning från länkar i boken.
Bokredigeringsverktyg¶
- class calibre.gui2.tweak_book.plugin.Tool[source]¶
Baser:
objectBasklass för enskilda verktyg i ett bokredigering insticksmodul. Användbara medlemmar är:
self.plugin: En referens till detcalibre.customize.Plugin-objekt som verktyget tillhör.self.
bossself.
gui
Metoder som måste åsidosättas i underklasser:
- name: str | None = None¶
Ändra detta till ett unikt namn det kommer att användas som en nyckel
- allowed_in_toolbar = True¶
Om True användaren kan välja att placera detta verktyg i insticksmodul verktygsfältet
Om True användaren kan välja att placera detta verktyg i insticksmodul menyn
- toolbar_button_popup_mode = 'delayed'¶
Rullgardinsläget för menyn (om någon) på knappen i verktygsfältet. Möjliga värden är ”fördröjt”, ”snabb”, ”knappen”
- property boss¶
calibre.gui2.tweak_book.boss.Bossobjektet. Används för att anpassa användargränssnittet.
- property gui¶
Huvudfönstret i användargränssnittet
- property current_container¶
Returnera det aktuella objektet
calibre.ebooks.oeb.polish.container.Containersom representerar boken som redigeras.
- register_shortcut(qaction, unique_name, default_keys=(), short_text=None, description=None, **extra_data)[source]¶
Registrera ett kortkommando som utlöser angiven
qaction. Användaren kan automatiskt anpassa kortkommandot under Kortkommandon i redigerarens inställningar.- Parametrar:
qaction – Ett QAction-objekt kommer att utlösas när den anpassade tangentkombinationen trycks av användaren.
unique_name – Ett unikt namn för kortkommandot eller åtgärden. Namnet används internt och får inte delas med någon annan åtgärd i insticksmodulen.
default_keys – En lista över standardkortkommandon. Om listan utelämnas anges inga standardkommandon. Kortkommandon som krockar med inbyggda kommandon eller kommandon från användarinställningar eller andra insticksmoduler ignoreras. Användaren måste då konfigurera dem manuellt i Inställningar. Exempel:
default_keys=('Ctrl+J', 'F9').short_text – En valfri kort beskrivning av denna åtgärd. Om inte angivet kommer texten från QAction att användas.
description – En valfri längre beskrivning av åtgärden. Den används i inställningsposten för kortkommandot.
- create_action(for_toolbar=True)[source]¶
Skapa en QAction som kommer att läggas till antingen i insticksmodulsverktygsfältet eller insticksmodulsmenyn beroende på
for_toolbar. Till exempel:def create_action(self, for_toolbar=True): ac = QAction(get_icons('myicon.png'), 'Do something') if for_toolbar: # We want the toolbar button to have a popup menu menu = QMenu() ac.setMenu(menu) menu.addAction('Do something else') subaction = menu.addAction('And another') # Register a keyboard shortcut for this toolbar action be # careful to do this for only one of the toolbar action or # the menu action, not both. self.register_shortcut(ac, 'some-unique-name', default_keys=('Ctrl+K',)) return ac
Se även
Metod
register_shortcut().
Anpassa redigerarens användargränssnitt¶
E-bokredigerarens användargränssnitt styrs av ett enda globalt Boss-objekt. Objektet har många användbara metoder som kan användas i insticksmodulskod för att utföra vanliga uppgifter.
- class calibre.gui2.tweak_book.boss.Boss(parent, notify=None)[source]¶
-
- apply_container_update_to_gui(mark_as_modified=True)[source]¶
Uppdatera alla komponenter i användargränssnittet för att återspegla de senaste data i den aktuella bokbehållaren.
- Parametrar:
mark_as_modified – Om True kommer boken att markeras som ändrad, så användaren kommer att uppmanas att spara den vid avslutning.
- commit_all_editors_to_container()[source]¶
Utför eventuella ändringar som användaren har gjort i filer öppnas i redigeraren till behållaren. Du bör anropa den här metoden innan du utför några åtgärder på den aktuella behållaren
- property currently_editing¶
Returnera namnet på filen som för närvarande redigeras eller None om ingen fil redigeras
- edit_file(name, syntax=None, use_template=None)[source]¶
Öppna filen som namnges i en redigerare
- Parametrar:
syntax – Mediatypen för filen, till exempel,
'text/html'. Om inget angetts uppskattas den från filändelsen.use_template – En mall för att initiera den öppnade redigeraren med
- open_book(path=None, edit_file=None, clear_notify_data=True, open_folder=False, search_text=None)[source]¶
Öppna e-bok på
pathför redigering. Kommer att visa ett fel om e-boken inte är i ett format som stöds eller den aktuella boken har osparade ändringar.- Parametrar:
edit_file – Namnet på en fil inne i den nyöppnade boken för att börja redigera. Kan också vara en lista med namn.
- rewind_savepoint()[source]¶
Ångra föregående skapande en återställningskontrollpunkt, användbart om du skapar en kontrollpunkt, sedan avbryta med inga ändringar
- show_current_diff(allow_revert=True, to_container=None)[source]¶
Visa ändringarna i boken från dess senaste kontrollpunktstillstånd
- Parametrar:
allow_revert – Om True kommer skillnadsdialogrutan att ha en knapp som låter användaren återställa alla ändringar
to_container – Ett behållarobjekt som den aktuella behållaren ska jämföras med. Om värdet är None används behållaren från den senaste kontrollpunkten.
