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, opfpath, log, clone_data=None)[source]

En behållare är en Open Ebook som en katalog full av filer och en OPF-fil. Det finns två viktiga begrepp:

  • Rotkatalogen. Detta är basen för e-boken. Alla e-bok filerna är inuti katalogen och i dess underkataloger.
  • Namn: Dessa är sökvägar till böckernas filerna relativt rotkatalogen. De innehåller alltid POSIX separatorer 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ödjer effektiva on-disk kloning, som används för att implementera kontrollpunkter i e-bokredigeraren. För att göra detta arbete, bör du aldrig komma åt filer på filsystemet direkt. Istället används raw_data() eller :meth:` open` att läsa / skriva till 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 en kanoniskt namn i förhållande till root

Parametrar:root – Grundkatalogen. Som standard används roten till detta behållarobjekt.
add_file(name, data, media_type=None, spine_index=None, modify_name_if_needed=False, process_manifest_item=None)[source]

Lägg en fil till denna behållare. Posten för filen skapas automatiskt i OPF manifestet och rygg (om filen är ett textdokument)

add_name_to_manifest(name, process_manifest_item=None)[source]

Lägg till en post i manifestet för en fil med angivna namnet. Återger manifest id:t.

add_properties(name, *properties)[source]

Lägg specificerade egenskaperna till manifest objektet som identifierats med namn.

apply_unique_properties(name, *properties)[source]

Se till att de angivna egenskaperna är inställt på endast manifest objektet som identifierats med ett namn. Du kan använda None som namn för att ta bort egenskapen från alla objekt.

book_type = u'oeb'

Typen av bok (epub för EPUB-filer och azw3 för AZW3-filer)

commit(outpath=None, keep_parsed=False)[source]

Begå alla smutsiga analyserade objekt till filsystemet och skriva ut ebook filen på utsökväg.

Parametrar:
  • output – Sökvägen att skriva den sparade e-bok-filen till. Om 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 tolkat objekt till disken (det är serialiserade och skrivs till den underliggande fil). Om keep_parsed är True behålls den tolkade representationen i bufferten. Se också: parsed()

dirty(name)[source]

Mark the parsed object corresponding to name as dirty. See also: parsed().

exists(name)[source]

True iff en fil/katalog som motsvarar det kanoniska namnet finns. Observera att denna funktion lider av begränsningarna i det underliggande OS filsystemet, i särskilda fall (o)känslighet. Så ifall filsystem är okänsliga kommer det att återge True även om namnet skiljer sig från fallet med den underliggande filsystemsfilen. Se även has_name()

filesize(name)[source]

Återge storlek i bytes av filen som representeras av det angivna kanoniska namnet. Automatiskt hanterar dirtied tolkade objekt. Se även: :met:’tolkade`

generate_item(name, id_prefix=None, media_type=None, unique_href=True)[source]

Lägg till ett objekt i manifestetet med href som härrör från förnamnet. Säkerställer unika href och id automatiskt. Återger genererade objekt.

get_file_path_for_processing(name, allow_modification=True)[source]

Liknar open() förutom att den återger en sökväg, istället för ett öppet filobjekt.

guide_type_map

Kartläggning av guidetyp till canonical namn

has_name(name)[source]

Return true om en fil med samma kanoniska namn som angetts existerar. Till skillnad exists() denna metod är alltid små och stora bokstäver.

href_to_name(href, base=None)[source]

Konvertera en href (i förhållande 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 objekt i förälder (eller lägga till om index är None), fastställande indrag. Fungerar endast med självstängande objekt.

is_dir = False

Om denna container representerar en uppackad bok (en katalog)

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 så är fallet, returnera en modifierad version som inte existerar.

manifest_has_name(name)[source]

Returnar True om manifestet har en post som motsvarar namnet

manifest_id_map

Översättning av manifest id till kanoniska namn

manifest_items_of_type(predicate)[source]

Namnen på alla uppenbara poster vars medie typ matcher predikat. predicate kan vara en uppsättning, en lista, en sträng eller en funktion med ett enda argument, som kommer att kallas med media-typ.

manifest_items_with_property(property_name)[source]

Alla uppenbara objekt som har den angivna egenskapen

manifest_type_map

Översättnig av manifest mediatyp till lista med canonical namn av den mediatypen

mi

Metadatan från denna bok som ett metadataobjekt. Observera att detta objekt är konstruerad i farten varje gång den här egenskapen begärs, så använd den sparsamt.

name_to_abspath(name)[source]

Konvertera ett kanoniskt namn till en absolut OS-beroende sökväg

name_to_href(name, base=None)[source]

Konvertera ett namn till en href förhållande till basen, som måste vara ett namn eller None i vilket fall self.root används som bas

names_that_must_not_be_changed

Uppsättning med namn som aldrig får byta namn. Beror på e-bokformatet.

names_that_must_not_be_removed

Uppsättning med namn som aldrig får tas bort från behållaren. Beror på e-bokformat.

names_that_need_not_be_manifested

Uppsättning av namn som får saknas i manifestet. Beror på e-bokformat.

open(name, mode=u'rb')[source]

Öppna filen som utpekas av namn för direkt läs / skriv. Observera att detta kommer att förkasta filen om den är dirtied och ta bort den från tolkningsbufferten. Du måste avsluta med den här filen innan du öppnar den tolkas versionen av den igen, eller dåliga saker kommer att hända.

opf

Den analyserad OPF-filen

opf_get_or_create(name)[source]

Bekvämlig metod för att antingen återge första XML-element med det angivna namnet eller skapar den under opf:package element och sedan lämna tillbaka den, om den inte redan finns.

opf_version

The version set on the OPF’s <package> element

opf_version_parsed

Den versionuppsättning som 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]

Return a parsed representation of the file specified by name. For HTML and XML files an lxml tree is returned. For CSS files a css_parser stylesheet is returned. Note that parsed objects are cached for performance. If you make any changes to the parsed object, you must call dirty() so that the container knows to update the cache. See also replace().

raw_data(name, decode=True, normalize_to_nfc=True)[source]

Återge rådata motsvarande filen som anges med namn

Parametrar:
  • decode – Om True och filen har en textbaserad mimetype, avkoda den och återge ett unicode-objekt istället för råa bytes.
  • normalize_to_nfc – Om True det återges unicode objektet som är normaliserad till NFC normalform som krävs för EPUB- och AZW3-filformat.
relpath(path, base=None)[source]

Konvertera en absolut sökväg (med os avskiljare) till en sökväg i förhållande till basen (standard att self.root). Den relativa sökvägen är inte ett namn. Använd abspath_to_name() för detta.

remove_from_spine(spine_items, remove_if_no_longer_in_spine=True)[source]

Ta bort de angivna objekten (av kanoniskt namn) från ryggen. Om remove_if_no_longer_in_spine är True, tas även objekten bort från boken, inte bara från ryggen.

remove_from_xml(item)[source]

Tar bort objektet från förälder, fasta indrag (fungerar bara med självstängande artiklar)

remove_item(name, remove_from_guide=True)[source]

Ta bort objektet identifierat med namn från denna behållare. Detta tar bort alla referenser till objektet i OPF manifestet, guide och rygg samt från eventuella interna buffertar.

rename(current_name, new_name)[source]

Byter namn på en fil från current_name till new_name. Det automatiskt baserar om alla länkar inne i filen om katalogfilen har förändringar. Observera dock att länkar inte uppdateras i de övriga filerna som kan referera den här filen. Detta är för prestanda, sådana uppdateringar ska göras en gång, i grupp.

replace(name, obj)[source]

Replace the parsed object corresponding to name with obj, which must be a similar object, i.e. an lxml tree for HTML/XML or a css_parser stylesheet for a CSS file.

Ersätt alla länkar i namn med replace_func, vilket måste vara en anropsbar som accepterar en URL och återger den ersatta URL:n. Den måste också ha ett ”ersatt” attribut som är satt till True om någon faktisk ersättning görs. Praktiska sätt att skapa sådana anropbara använd LinkReplacer och LinkRebaser klasser.

serialize_item(name)[source]

Konvertera en analyserat objekt (identifieras av kanoniskt namn) i en oktettsträ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.

spine_items

En iterator som ger sökväg för varje del i bokryggar. Se även: attr:spine_iter och spine_items.

spine_iter

En iterator som ger posten, name is_linear för varje post i bokens rygg. Posten är lxml elementet, som har det kanoniska filnamnet och is_linear är True om objektet är linjärt. Se även: spine_names och spine_items.

spine_names

En iterator som ger name och is_linear för varje post i bokens rygg. Se även: spine_iter and spine_items.

Hantera komponentfiler i en behållare

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 översättning av kanoniska namn till nya kanoniska namn. Till exempel: {'images/old.png': 'images/new.png'}
  • frag_map – Ett anropbart som tar två argument (name, anchor) och återger ett nytt ankare. Detta är användbart om du behöver ändra ankare i HTML-filer. Som standard gör det 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 översättning av gamla kanoniska namn till nya kanoniska, till exempel: {'text/chapter1.html': 'chapter1.html'}.

Återge 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

calibre.ebooks.oeb.polish.pretty.pretty_xml(container, name, raw)[source]

Fin utskrift XML representeras som en råsträng. Om name är namnet på OPF, är extra OPF-specifik försköning utförs.

calibre.ebooks.oeb.polish.pretty.pretty_all(container)[source]

Fin utskrift för alla HTML/CSS/XML-filer i behållaren

Hantera bokomslag

calibre.ebooks.oeb.polish.jacket.remove_jacket(container)[source]

Ta bort ett befintligt skal, om något. Återger False om inget befintligt skal hittades.

calibre.ebooks.oeb.polish.jacket.add_or_replace_jacket(container)[source]

Antingen skapa ett nytt skal från bokens metadata eller ersätta en befintligt skal. Återger True om ett befintligt omslag ersattes.

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örhandsvisningspanelen.
  • 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 etiketter 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å ihop de angivna filerna till en enda fil, automatiskt migrera alla länkar och referenser till de berörda filerna. 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-filer
  • names – Listan med filer som ska sammanfogas
  • 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]

Anpassa omslaget till boken till den bild som utpekas 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 anropsbar som tar ett enda argument. Det kommer att kallas med information om de uppgifter som behandlas.
  • options – Ingen eller en ordlista som bestämmer hur omslaget sätts in. Ordlistan kan ha poster: keep_aspect: True eller False (Bevara bildförhållande på omslag i EPUB) no_svg: True eller False (Använd en SVG omslagshölje i EPUB Titeln) befintliga: True eller False (`` cover_path`` refererar till en befintlig bild i boken)
calibre.ebooks.oeb.polish.cover.mark_as_cover(container, name)[source]

Markera den angivna bilden som omslagsbild.

calibre.ebooks.oeb.polish.cover.mark_as_titlepage(container, name, move_to_start=True)[source]

Märk den angivna HTML-filen som titelsidan för EPUB:n.

Parametrar:move_to_start – Om True kommer HTML-filen flyttas till början av ryggen

Att arbeta med CSS

calibre.ebooks.oeb.polish.fonts.change_font(container, old_name, new_name=None)[source]

Ändra en typsnittsfamilj från old_name att NEW_NAME. Ändrar alla förekomster av typsnitt i utformningsmallar, formatetikett och a<tilattribut. Om old_name avser ett inbäddat typsnitt, tas det bort. Du kan ställa NEW_NAME till None för att ta bort typsnittet istället för att ändra det.

calibre.ebooks.oeb.polish.css.remove_unused_css(container, report=None, remove_unused_classes=False, merge_rules=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 anropsbar som tar ett enda argument. Det kallas med information om den verksamhet som utförs.
  • remove_unused_classes – Om True, klassattribut i HTML som inte matchar några CSS-regler tas också bort.
  • merge_rules – Om True, sammanfogas regler med identiska väljare.
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)[source]

Generera en innehållsförteckning från en lista med XPath-uttryck. Varje uttryck i listan motsvarar en nivå av den genererade innehållsförteckningen. Till exempel: ['//h:h1', '//h:h2', '//h:h3'] kommer att generera en trenivåers innehållsförteckning från <h1>, <h2> and <h3> etiketter.

Generera innehållsförteckning från länkar i boken.

calibre.ebooks.oeb.polish.toc.from_files(container)[source]

Generera innehållsförteckning från filer i boken.

calibre.ebooks.oeb.polish.toc.create_inline_toc(container, title=None)[source]

Skapa en infogad (HTML) Innehållsförteckning från en befintlig NCX innehållsförteckning.

Parametrar:title – Titel för denna innehållsförteckning.

Bokredigeringsverktyg

class calibre.gui2.tweak_book.plugin.Tool[source]

Bas: object

Basklass för enskilda verktyg i ett bokredigering insticksmodul. Användbara medlemmar är:

Metoder som måste bli ersatta i underklasser:

name = 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

allowed_in_menu = True

Om True användaren kan välja att placera detta verktyg i insticksmodul menyn

toolbar_button_popup_mode = u'delayed'

Rullgardinsläget för menyn (om någon) på knappen i verktygsfältet. Möjliga värden är ”fördröjt”, ”snabb”, ”knappen”

boss

calibre.gui2.tweak_book.boss.Boss objektet. Används för att anpassa användargränssnittet.

gui

Huvudfönstret i användargränssnittet

current_container

Återge nuvarande calibre.ebooks.oeb.polish.container.Container objekt som 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 den angivna qaction. Detta kortkommandot blir automatiskt anpassningsbart av användaren i avsnittet Tangentbord 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 genvägen/åtgärden. Den kommer att användas internt, får inte delas av några andra åtgärder i detta insticksmodul.
  • default_keys – En lista med standardtangentbordsgenvägarna. Om inget anges kommer inga standardgenvägar att fastställas. Om genväg anges här konflikt med antingen inbyggda genvägar och genvägar från användarkonfigurations/andra insticksmodul, kommer de att ignoreras. I så fall kommer användarna att behöva anpassa snabb manuellt via Inställningar. Till 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 denna åtgärd, det kommer att användas i inställningsposten för den här genvägen.
create_action(for_toolbar=True)[source]

Skapa en QAction som kommer att läggas till antingen till insticksmodul verktygsfältet eller insticksmodul meny 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 bestäms av ett enda global Boss objekt. Detta har många användbara metoder som kan användas i insticksmodul kod för att utföra vanliga uppgifter.

class calibre.gui2.tweak_book.boss.Boss(parent, notify=None)[source]
add_savepoint(msg)[source]

Skapa en återställningskontrollpunkt med det namn som anges som msg

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å att användaren uppmanas att spara den när du avslutar.
close_editor(name)[source]

Stäng redigeraren som redigerar filen som anges av name

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

currently_editing

Returnamnet på filen som redigeras för närvarande 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 angivits 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)[source]

Öppna e-bok på sökväg fö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

save_book()[source]

Spara boken. Sparning utförs i bakgrunden

set_modified()[source]

Markera boken som har modifierats

show_current_diff(allow_revert=True, to_container=None)[source]

Visa ändringarna i boken från sitt senaste kontrollpunktstillstånd

Parametrar:
  • allow_revert – Om True kommer skillnadsdialogrutan att ha en knapp för att göra det möjligt för användaren att återställa alla förändringar
  • to_container – En behållarobjekt för att jämföra den aktuella behållaren till. Om None är det tidigare kontrollspunktsbehållare som används
show_editor(name)[source]

Visa redigeraren som redigerar filen som anges med name

sync_preview_to_editor()[source]

Synkronisera position av förhandsvisningspanelen till den aktuella markörpositionen i den aktuella redigeraren