API documentatie voor e-book bewerking functies

De hulpmiddelen voor het bewerken van e-boeken bestaan uit een: class: Calibre.ebooks.oeb.polish.container.Container-object dat een boek vertegenwoordigt als een verzameling HTML + bronbestanden en verschillende hulpmiddelen die kunnen worden gebruikt om bewerkingen uit te voeren op de houder. Alle tools zijn in de vorm van moduleniveaufuncties in de verschillende `` Calibre.ebooks.oeb.polish. * `` Modules.

U verkrijgt een containerobject voor een boek op een pad als dit:

from calibre.ebooks.oeb.polish.container import get_container
container = get_container('Path to book file', tweak_mode=True)

Als u een plug-in schrijft voor de E-book-editor, krijgt u de huidige container voor het bewerken van het boek zoals dit:

from calibre.gui2.tweak_book import current_container
container = current_container()
if container is None:
    report_error # No book has been opened yet

Het container object

class calibre.ebooks.oeb.polish.container.Container(rootpath, opfpath, log, clone_data=None)

Een container stelt een open e-boek voor als een map vol bestanden en een OPF-bestand. Er zijn twee belangrijke concepten:

• De hoofdmap. Dit is de basis van het e-boek. Alle e-boek bestanden bevinden zich in deze map of in zijn submappen.

• Namen: Dit zijn paden naar boekbestanden relatief aan de hoofdmap. Ze bevatten altijd POSIX separatoren en hebben geen aanhalingstekens. Zie ze als canonieke identificatoren voor bestanden in het boek. Meeste methodes op het containerobject werken met namen. Namen zijn altijd in de NFC Unicode normale vorm.

• Klonen: Het containerobject ondersteunt efficiënt op-schijf klonen, gebruikt om controlepunten toe te passen in de e-boek editor. Om dit te laten werken, mag u nooit bestanden direct in het bestandssysteem benaderen. In plaats daarvan, gebruik raw_data() of open() om te lezen/schrijven naar onderdelen in het boek.

Bij converteren tussen hrefs en namen, gebruik de methodes voorzien in deze class, ze gaan ervan uit dat alle hrefs tussen aanhalingstekens staan.

abspath_to_name(fullpath, root=None)

Converteer een absoluut pad naar een canonieke naam relatief ten opzichte van root

Parameters:

root – De hoofdmap, Standaard wordt de root voor dit containerobject gebruikt.

add_file(name, data, media_type=None, spine_index=None, modify_name_if_needed=False, process_manifest_item=None)

Bestand aan deze container toevoegen. Vermeldingen worden automatisch aangemaakt in het OPF manifest en de spine (als het bestand een tekstdocument is)

add_name_to_manifest(name, process_manifest_item=None)

Vermelding toevoegen aan het manifest voor een bestand met de gespecificeerde naam, Geeft het manifest ID terug.

add_properties(name, *properties)

De gespecificeerde eigenschappen toevoegen aan het manifest item geïdentificeerd bij naam.

apply_unique_properties(name, *properties)

Zorg ervoor dat de gespecificeerde eigenschappen enkel geplaatst zijn op het manifest item geïdentificeerd bij naam. U kan Geen doorgeven als naam om de eigenschap van alle items te verwijderen.

book_type = 'oeb'

Het type boek (epub voor EPUB bestanden en azw3 voor AZW3 bestanden)

commit(outpath=None, keep_parsed=False)

Commit all dirtied parsed objects to the filesystem and write out the e-book file at outpath.

Parameters:

• output – Het pad om het opgeslagen e-boekbestand naar toe te schrijven. Indien Geen, wordt het pad van het originele boekbestand gebruikt.

• keep_parsed – If True the parsed representations of committed items are kept in the cache.

commit_item(name, keep_parsed=False)

Commit a parsed object to disk (it is serialized and written to the underlying file). If keep_parsed is True the parsed representation is retained in the cache. See also: parsed()

dirty(name)

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

exists(name)

True iff a file/folder corresponding to the canonical name exists. Note that this function suffers from the limitations of the underlying OS filesystem, in particular case (in)sensitivity. So on a case insensitive filesystem this will return True even if the case of name is different from the case of the underlying filesystem file. See also has_name()

filesize(name)

Return the size in bytes of the file represented by the specified canonical name. Automatically handles dirtied parsed objects. See also: parsed()

generate_item(name, id_prefix=None, media_type=None, unique_href=True)

Add an item to the manifest with href derived from the given name. Ensures uniqueness of href and id automatically. Returns generated item.

get_file_path_for_processing(name, allow_modification=True)

Similar to open() except that it returns a file path, instead of an open file object.

property guide_type_map

Mapping of guide type to canonical name

has_name(name)

Return True iff a file with the same canonical name as that specified exists. Unlike exists() this method is always case-sensitive.

href_to_name(href, base=None)

Convert an href (relative to base) to a name. base must be a name or None, in which case self.root is used.

insert_into_xml(parent, item, index=None)

Insert item into parent (or append if index is None), fixing indentation. Only works with self closing items.

is_dir = False

If this container represents an unzipped book (a directory)

iterlinks(name, get_line_numbers=True)

Iterate over all links in name. If get_line_numbers is True the yields results of the form (link, line_number, offset). Where line_number is the line_number at which the link occurs and offset is the number of characters from the start of the line. Note that offset could actually encompass several lines if not zero.

make_name_unique(name)

Ensure that name does not already exist in this book. If it does, return a modified version that does not exist.

manifest_has_name(name)

Return True if the manifest has an entry corresponding to name

property manifest_id_map

Mapping of manifest id to canonical names

manifest_items_of_type(predicate)

The names of all manifest items whose media-type matches predicate. predicate can be a set, a list, a string or a function taking a single argument, which will be called with the media-type.

manifest_items_with_property(property_name)

Alle manifest items die de gespecificeerde eigenschap hebben

property manifest_type_map

Mapping van manifest mediatype naar lijst van canonieke namen van dat mediatype

property mi

De metadata van dit boek als een Metadata object. Merk op dat dit object on the fly wordt samengesteld elke keer om deze eigenschap wordt gevraagd, zuinig gebruiken dus.

name_to_abspath(name)

Converteer een canonieke naam naar een absoluut OS afhankelijk pad

name_to_href(name, base=None)

Converteer een naam naar een href relatief aan de basis, wat een naam moet zijn of Geen in welk geval self.root wordt gebruikt als basis.

property names_that_must_not_be_changed

Set namen die nooit hernoemd mag worden. Afhankelijk van het e-boekbestandsformaat.

property names_that_must_not_be_removed

Set namen die nooit uit de container verwijderd mag worden. Afhankelijk van het e-boekbestandsformaat.

property names_that_need_not_be_manifested

Set namen die mag ontbreken in het manifest. Afhankelijk van het e-boekbestandsformaat.

open(name, mode='rb')

Open het bij naam aangewezen bestand voor direct lezen/schrijven. Merk op dat dit het bestand commit als het vuil is en het uit de verwerkingscache verwijderd. U moet dit bestand afwerken vooraleer de verwerkte versie weer te betreden of er dreigt onheil.

property opf

Het verwerkte OPF bestand

opf_get_or_create(name)

Gemakzuchtige manier om ofwel terug te keren naar het eerste XML element met de gespecificeerde naam of het te creëren onder het opf:package element en het dan terug te geven, als het al niet bestaat.

property opf_version

De versie ingesteld op de OPF’s <package> element

property opf_version_parsed

De versie ingesteld op de OPF’s <package> element als een tupel van gehele getallen

opf_xpath(expr)

Gemakzuchtige manier om een XPath expressie te evalueren in het OPF bestand, heeft de opf: en dc: naamruimte voorvoegsels voor-gedefinieerd.

parsed(name)

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)

Geef de rauwe data terug overeenkomstig met het bestand gespecificeerd bij naam

Parameters:

• decode – Als Waar en het bestand heeft een tekst gebaseerd MIME type, decodeer het en geef een Unicode object terug i.p.v. rauwe bytes.

• normalize_to_nfc – Als Waar is het teruggegeven Unicode object genormaliseerd volgens de NFC vorm zoals vereist voor de EPUB en AZW3 bestandsformaten.

relpath(path, base=None)

Converteer een absoluut pad (met OS separators) naar een pad relatief naar basis (standaard naar self.root). Het relatieve pad is geen naam. Gebruik daarvoor abspath_to_name().

remove_from_spine(spine_items, remove_if_no_longer_in_spine=True)

Verwijder de gespecificeerde items (per canonieke naam) uit de opbouw. Als remove_if_no_longer_in_spine Waar is, worden de items ook uit het boek verwijderd, niet enkel uit de opbouw.

remove_from_xml(item)

Verwijdert item van ouder, inspringing herstellend ( werkt enkel met zelksluitende items)

remove_item(name, remove_from_guide=True)

Verwijder het bij naam genoemde item uit deze container. Dit verwijdert alle referenties naar het item in het OPF manifest, gids en opbouw, zowel als elke interne cache.

rename(current_name, new_name)

Renames a file from current_name to new_name. It automatically rebases all links inside the file if the folder the file is in changes. Note however, that links are not updated in the other files that could reference this file. This is for performance, such updates should be done once, in bulk.

replace(name, obj)

Vervang het verwerkte object overeenkomend op naam met obj, wat een gelijkaardig object moet zijn, bv. een lxml boom voor HTML/XML of een css_parser stijlblad voor een CSS bestand.

replace_links(name, replace_func)

Replace all links in name using replace_func, which must be a callable that accepts a URL and returns the replaced URL. It must also have a ‘replaced’ attribute that is set to True if any actual replacement is done. Convenient ways of creating such callables are using the LinkReplacer and LinkRebaser classes.

serialize_item(name)

Converteer een verwerkt object (geïdentificeerd met canonieke naam) in een bytestring. Bekijk parsed().

set_spine(spine_items)

Set the spine to be spine_items where spine_items is an iterable of the form (name, linear). Will raise an error if one of the names is not present in the manifest.

property spine_items

An iterator yielding the path for every item in the books’ spine. See also: spine_iter and spine_items.

property spine_iter

An iterator that yields item, name is_linear for every item in the books’ spine. item is the lxml element, name is the canonical file name and is_linear is True if the item is linear. See also: spine_names and spine_items.

property spine_names

An iterator yielding name and is_linear for every item in the books’ spine. See also: spine_iter and spine_items.

Component bestanden in een container beheren

calibre.ebooks.oeb.polish.replace.replace_links(container, link_map, frag_map=<function <lambda>>, replace_in_opf=False)

Vervang links naar bestanden in de container. Gaat over alle bestanden in de container en verandert de gespecificeerde links erin.

Parameters:

• link_map – A mapping of old canonical name to new canonical name. For example: {'images/old.png': 'images/new.png'}

• frag_map – A callable that takes two arguments (name, anchor) and returns a new anchor. This is useful if you need to change the anchors in HTML files. By default, it does nothing.

• replace_in_opf – Indien Onwaar worden links in het OPF bestand niet vervangen.

calibre.ebooks.oeb.polish.replace.rename_files(container, file_map)

Hernoem bestanden in de container. update links naar hen automatisch.

Parameters:

file_map – Mapping van oude canonieke namen naar nieuwe canonieke namen, bv. {'text/chapter1.html': 'chapter1.html'}.

calibre.ebooks.oeb.polish.replace.get_recommended_folders(container, names)

Geef de mappen terug aanbevolen voor de gegeven bestandsnamen. De aanbeveling is gebaseerd op waar de meerderheid van bestanden van hetzelfde type staan in de container. Als geen bestanden van een bepaald type aanwezig zijn, wordt de aangewezen map veronderstelt de map te zijn met het OPF bestand.

Netjes afdrukken en auto-herstellen verwerkingsfouten

calibre.ebooks.oeb.polish.pretty.fix_html(container, raw)

Herstel alle verwerkingsfouten in de HTML voorgesteld als een rauwe string. Herstellen wordt gedaan met het HTML5 verwerkingsalgoritme.

calibre.ebooks.oeb.polish.pretty.fix_all_html(container)

Herstel alle verwerkingsfouten in alle HTML bestanden in de container. Herstellen wordt gedaan met het HTML5 verwerkingsalgoritme.

calibre.ebooks.oeb.polish.pretty.pretty_html(container, name, raw)

Druk de HTML voorgesteld als een string in rauw netjes af

calibre.ebooks.oeb.polish.pretty.pretty_css(container, name, raw)

Druk de CSS voorgesteld als een string in rauw netjes af

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

Druk de XML voorgesteld als een string in rauw netjes af. Als name de naam is van de OPF, extra OPF specifiek netter maken is gedaan.

calibre.ebooks.oeb.polish.pretty.pretty_all(container)

Druk alle HTML/CSS/XML bestanden in de container netjes af

Boekomslagen beheren

calibre.ebooks.oeb.polish.jacket.remove_jacket(container)

Remove an existing jacket, if any. Returns False if no existing jacket was found.

calibre.ebooks.oeb.polish.jacket.add_or_replace_jacket(container)

Either create a new jacket from the book’s metadata or replace an existing jacket. Returns True if an existing jacket was replaced.

Splitsen en samenvoegen van bestanden

calibre.ebooks.oeb.polish.split.split(container, name, loc_or_xpath, before=True, totals=None)

Split the file specified by name at the position specified by loc_or_xpath. Splitting automatically migrates all links and references to the affected files.

Parameters:

• loc_or_xpath – Should be an XPath expression such as //h:div[@id=”split_here”]. Can also be a loc which is used internally to implement splitting in the preview panel.

• before – If True the split occurs before the identified element otherwise after it.

• totals – Intern gebruikt

calibre.ebooks.oeb.polish.split.multisplit(container, name, xpath, before=True)

Split the specified file at multiple locations (all tags that match the specified XPath expression). See also: split(). Splitting automatically migrates all links and references to the affected files.

Parameters:

before – If True the splits occur before the identified element otherwise after it.

calibre.ebooks.oeb.polish.split.merge(container, category, names, master)

Merge the specified files into a single file, automatically migrating all links and references to the affected files. The file must all either be HTML or CSS files.

Parameters:

• category – Must be either 'text' for HTML files or 'styles' for CSS files

• names – De lijst van bestanden om samen te voegen

• master – Which of the merged files is the master file, that is, the file that will remain after merging.

Omslagen beheren

calibre.ebooks.oeb.polish.cover.set_cover(container, cover_path, report=None, options=None)

Set the cover of the book to the image pointed to by cover_path.

Parameters:

• cover_path – Either the absolute path to an image file or the canonical name of an image in the book. When using an image in the book, you must also set options, see below.

• report – An optional callable that takes a single argument. It will be called with information about the tasks being processed.

• options – None or a dictionary that controls how the cover is set. The dictionary can have entries: keep_aspect: True or False (Preserve aspect ratio of covers in EPUB) no_svg: True or False (Use an SVG cover wrapper in the EPUB titlepage) existing: True or False (cover_path refers to an existing image in the book)

calibre.ebooks.oeb.polish.cover.mark_as_cover(container, name)

Mark the specified image as the cover image.

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

Mark the specified HTML file as the titlepage of the EPUB.

Parameters:

move_to_start – If True the HTML file is moved to the start of the spine

Werken met CSS

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

Change a font family from old_name to new_name. Changes all occurrences of the font family in stylesheets, style tags and style attributes. If the old_name refers to an embedded font, it is removed. You can set new_name to None to remove the font family instead of changing it.

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)

Remove all unused CSS rules from the book. An unused CSS rule is one that does not match any actual content.

Parameters:

• report – An optional callable that takes a single argument. It is called with information about the operations being performed.

• remove_unused_classes – If True, class attributes in the HTML that do not match any CSS rules are also removed.

• merge_rules – If True, rules with identical selectors are merged.

• merge_rules_with_identical_properties – If True, rules with identical properties are merged.

• remove_unreferenced_sheets – If True, stylesheets that are not referenced by any content are removed

calibre.ebooks.oeb.polish.css.filter_css(container, properties, names=())

Remove the specified CSS properties from all CSS rules in the book.

Parameters:

• properties – Set of properties to remove. For example: {'font-family', 'color'}.

• names – The files from which to remove the properties. Defaults to all HTML and CSS files in the book.

Werken met de inhoudsopgave

calibre.ebooks.oeb.polish.toc.from_xpaths(container, xpaths, prefer_title=False)

Generate a Table of Contents from a list of XPath expressions. Each expression in the list corresponds to a level of the generate ToC. For example: ['//h:h1', '//h:h2', '//h:h3'] will generate a three level Table of Contents from the <h1>, <h2> and <h3> tags.

calibre.ebooks.oeb.polish.toc.from_links(container)

Generate a Table of Contents from links in the book.

calibre.ebooks.oeb.polish.toc.from_files(container)

Generate a Table of Contents from files in the book.

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

Create an inline (HTML) Table of Contents from an existing NCX Table of Contents.

Parameters:

title – De titel voor deze inhoudsopgave.

Bewerken Boekhulpmiddel

class calibre.gui2.tweak_book.plugin.Tool

Basisklassen: object

The base class for individual tools in an Edit Book plugin. Useful members include:

• self.plugin: A reference to the calibre.customize.Plugin object to which this tool belongs.

• self. boss

• self. gui

Methods that must be overridden in sub classes:

• create_action()

• register_shortcut()

name = None

Set this to a unique name it will be used as a key

allowed_in_toolbar = True

If True the user can choose to place this tool in the plugins toolbar

allowed_in_menu = True

If True the user can choose to place this tool in the plugins menu

toolbar_button_popup_mode = 'delayed'

The popup mode for the menu (if any) of the toolbar button. Possible values are ‘delayed’, ‘instant’, ‘button’

property boss

The calibre.gui2.tweak_book.boss.Boss object. Used to control the user interface.

property gui

The main window of the user interface

property current_container

Return the current calibre.ebooks.oeb.polish.container.Container object that represents the book being edited.

register_shortcut(qaction, unique_name, default_keys=(), short_text=None, description=None, **extra_data)

Register a keyboard shortcut that will trigger the specified qaction. This keyboard shortcut will become automatically customizable by the user in the Keyboard shortcuts section of the editor preferences.

Parameters:

• qaction – A QAction object, it will be triggered when the configured key combination is pressed by the user.

• unique_name – A unique name for this shortcut/action. It will be used internally, it must not be shared by any other actions in this plugin.

• default_keys – A list of the default keyboard shortcuts. If not specified no default shortcuts will be set. If the shortcuts specified here conflict with either builtin shortcuts or shortcuts from user configuration/other plugins, they will be ignored. In that case, users will have to configure the shortcuts manually via Preferences. For example: default_keys=('Ctrl+J', 'F9').

• short_text – An optional short description of this action. If not specified the text from the QAction will be used.

• description – An optional longer description of this action, it will be used in the preferences entry for this shortcut.

create_action(for_toolbar=True)

Create a QAction that will be added to either the plugins toolbar or the plugins menu depending on for_toolbar. For example:

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

Zie ook

Method register_shortcut().

Controlling the editor’s user interface

The e-book editor’s user interface is controlled by a single global Boss object. This has many useful methods that can be used in plugin code to perform common tasks.

class calibre.gui2.tweak_book.boss.Boss(parent, notify=None)

add_savepoint(msg)

Create a restore checkpoint with the name specified as msg

apply_container_update_to_gui(mark_as_modified=True)

Update all the components of the user interface to reflect the latest data in the current book container.

Parameters:

mark_as_modified – If True, the book will be marked as modified, so the user will be prompted to save it when quitting.

close_editor(name)

Close the editor that is editing the file specified by name

commit_all_editors_to_container()

Commit any changes that the user has made to files open in editors to the container. You should call this method before performing any actions on the current container

property currently_editing

Return the name of the file being edited currently or None if no file is being edited

edit_file(name, syntax=None, use_template=None)

Open het bestand op basis van naam in een beweker

Parameters:

• syntax – The media type of the file, for example, 'text/html'. If not specified it is guessed from the file extension.

• use_template – A template to initialize the opened editor with

open_book(path=None, edit_file=None, clear_notify_data=True, open_folder=False, search_text=None)

Open the e-book at path for editing. Will show an error if the e-book is not in a supported format or the current book has unsaved changes.

Parameters:

edit_file – The name of a file inside the newly opened book to start editing. Can also be a list of names.

rewind_savepoint()

Undo the previous creation of a restore checkpoint, useful if you create a checkpoint, then abort the operation with no changes

save_book()

Save the book. Saving is performed in the background

set_modified()

Boek markeren als bewerkt

show_current_diff(allow_revert=True, to_container=None)

Show the changes to the book from its last checkpointed state

Parameters:

• allow_revert – If True the diff dialog will have a button to allow the user to revert all changes

• to_container – A container object to compare the current container to. If None, the previously checkpointed container is used

show_editor(name)

Show the editor that is editing the file specified by name

sync_preview_to_editor()

Sync the position of the preview panel to the current cursor position in the current editor

© Auteursrecht Kovid Goyal. Laatst geüpdated op mei 03, 2024.