Documentação da API para ferramentas de edição de e-book

As ferramentas de edição de e-book consistem em um objeto calibre.ebooks.oeb.polish.container.Container que representa um livro como uma coleção de arquivos HTML + de recursos e várias ferramentas que podem ser usadas para executar operações no contêiner. Todas as ferramentas estão na forma de funções de nível de módulo nos vários módulos calibre.ebooks.oeb.polish.*.

Você obtém um conteiner object para um livro com um caminho desta forma:

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

Se você estiver escrevendo um plugin para o editor de E-book, você obterá o contêiner atual para o livro que está sendo editado assim:

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

O objeto Container

class calibre.ebooks.oeb.polish.container.Container(rootpath, opfpath, log, clone_data=None)[código fonte]

A container represents an Open E-Book as a directory full of files and an opf file. There are two important concepts:

  • The root directory. This is the base of the e-book. All the e-books files are inside this directory or in its sub-directories.

  • Names: These are paths to the books’ files relative to the root directory. They always contain POSIX separators and are unquoted. They can be thought of as canonical identifiers for files in the book. Most methods on the container object work with names. Names are always in the NFC unicode normal form.

  • Clones: the container object supports efficient on-disk cloning, which is used to implement checkpoints in the e-book editor. In order to make this work, you should never access files on the filesystem directly. Instead, use raw_data() or open() to read/write to component files in the book.

When converting between hrefs and names use the methods provided by this class, they assume all hrefs are quoted.

abspath_to_name(fullpath, root=None)[código fonte]

Convert an absolute path to a canonical name relative to root


root – The base directory. By default the root for this container object is used.

add_file(name, data, media_type=None, spine_index=None, modify_name_if_needed=False, process_manifest_item=None)[código fonte]

Add a file to this container. Entries for the file are automatically created in the OPF manifest and spine (if the file is a text document)

add_name_to_manifest(name, process_manifest_item=None)[código fonte]

Add an entry to the manifest for a file with the specified name. Returns the manifest id.

add_properties(name, *properties)[código fonte]

Add the specified properties to the manifest item identified by name.

apply_unique_properties(name, *properties)[código fonte]

Ensure that the specified properties are set on only the manifest item identified by name. You can pass None as the name to remove the property from all items.

book_type = 'oeb'

The type of book (epub for EPUB files and azw3 for AZW3 files)

commit(outpath=None, keep_parsed=False)[código fonte]

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

  • output – The path to write the saved e-book file to. If None, the path of the original book file is used.

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

commit_item(name, keep_parsed=False)[código fonte]

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)[código fonte]

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

exists(name)[código fonte]

True iff a file/directory 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)[código fonte]

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)[código fonte]

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)[código fonte]

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)[código fonte]

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)[código fonte]

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)[código fonte]

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)

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)[código fonte]

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)[código fonte]

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)[código fonte]

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)[código fonte]

All manifest items that have the specified property

property manifest_type_map

Mapping of manifest media-type to list of canonical names of that media-type

property mi

The metadata of this book as a Metadata object. Note that this object is constructed on the fly every time this property is requested, so use it sparingly.

name_to_abspath(name)[código fonte]

Convert a canonical name to an absolute OS dependant path

name_to_href(name, base=None)[código fonte]

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

property names_that_must_not_be_changed

Set of names that must never be renamed. Depends on the e-book file format.

property names_that_must_not_be_removed

Set of names that must never be deleted from the container. Depends on the e-book file format.

property names_that_need_not_be_manifested

Set of names that are allowed to be missing from the manifest. Depends on the e-book file format.

open(name, mode='rb')[código fonte]

Open the file pointed to by name for direct read/write. Note that this will commit the file if it is dirtied and remove it from the parse cache. You must finish with this file before accessing the parsed version of it again, or bad things will happen.

property opf

The parsed OPF file

opf_get_or_create(name)[código fonte]

Convenience method to either return the first XML element with the specified name or create it under the opf:package element and then return it, if it does not already exist.

property opf_version

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

property opf_version_parsed

The version set on the OPF’s <package> element as a tuple of integers

opf_xpath(expr)[código fonte]

Convenience method to evaluate an XPath expression on the OPF file, has the opf: and dc: namespace prefixes pre-defined.

parsed(name)[código fonte]

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)[código fonte]

Return the raw data corresponding to the file specified by name

  • decode – If True and the file has a text based MIME type, decode it and return a unicode object instead of raw bytes.

  • normalize_to_nfc – If True the returned unicode object is normalized to the NFC normal form as is required for the EPUB and AZW3 file formats.

relpath(path, base=None)[código fonte]

Convert an absolute path (with os separators) to a path relative to base (defaults to self.root). The relative path is not a name. Use abspath_to_name() for that.

remove_from_spine(spine_items, remove_if_no_longer_in_spine=True)[código fonte]

Remove the specified items (by canonical name) from the spine. If remove_if_no_longer_in_spine is True, the items are also deleted from the book, not just from the spine.

remove_from_xml(item)[código fonte]

Removes item from parent, fixing indentation (works only with self closing items)

remove_item(name, remove_from_guide=True)[código fonte]

Remove the item identified by name from this container. This removes all references to the item in the OPF manifest, guide and spine as well as from any internal caches.

rename(current_name, new_name)[código fonte]

Renames a file from current_name to new_name. It automatically rebases all links inside the file if the directory 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)[código fonte]

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.

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)[código fonte]

Convert a parsed object (identified by canonical name) into a bytestring. See parsed().

set_spine(spine_items)[código fonte]

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.

Gerenciando arquivos de componentes em um contêiner

Replace links to files in the container. Will iterate over all files in the container and change the specified links in them.

  • 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 – If False, links are not replaced in the OPF file.

calibre.ebooks.oeb.polish.replace.rename_files(container, file_map)[código fonte]

Rename files in the container, automatically updating all links to them.


file_map – A mapping of old canonical name to new canonical name, for example: {'text/chapter1.html': 'chapter1.html'}.

Return the folders that are recommended for the given filenames. The recommendation is based on where the majority of files of the same type are located in the container. If no files of a particular type are present, the recommended folder is assumed to be the folder containing the OPF file.

Impressão bonita e correção automática de erros de análise

calibre.ebooks.oeb.polish.pretty.fix_html(container, raw)[código fonte]

Fix any parsing errors in the HTML represented as a string in raw. Fixing is done using the HTML5 parsing algorithm.

calibre.ebooks.oeb.polish.pretty.fix_all_html(container)[código fonte]

Fix any parsing errors in all HTML files in the container. Fixing is done using the HTML5 parsing algorithm.

calibre.ebooks.oeb.polish.pretty.pretty_html(container, name, raw)[código fonte]

Pretty print the HTML represented as a string in raw

calibre.ebooks.oeb.polish.pretty.pretty_css(container, name, raw)[código fonte]

Pretty print the CSS represented as a string in raw

calibre.ebooks.oeb.polish.pretty.pretty_xml(container, name, raw)[código fonte]

Pretty print the XML represented as a string in raw. If name is the name of the OPF, extra OPF-specific prettying is performed.

calibre.ebooks.oeb.polish.pretty.pretty_all(container)[código fonte]

Pretty print all HTML/CSS/XML files in the container

Gerenciando capas de livros

calibre.ebooks.oeb.polish.jacket.remove_jacket(container)[código fonte]

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

calibre.ebooks.oeb.polish.jacket.add_or_replace_jacket(container)[código fonte]

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

Dividindo e mesclando arquivos

calibre.ebooks.oeb.polish.split.split(container, name, loc_or_xpath, before=True, totals=None)[código fonte]

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.

  • 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 – Used internally

calibre.ebooks.oeb.polish.split.multisplit(container, name, xpath, before=True)[código fonte]

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.


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

calibre.ebooks.oeb.polish.split.merge(container, category, names, master)[código fonte]

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.

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

  • names – The list of files to be merged

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

Gerenciando capas

calibre.ebooks.oeb.polish.cover.set_cover(container, cover_path, report=None, options=None)[código fonte]

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

  • 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)[código fonte]

Mark the specified image as the cover image.

calibre.ebooks.oeb.polish.cover.mark_as_titlepage(container, name, move_to_start=True)[código fonte]

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


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

Trabalhando com CSS

calibre.ebooks.oeb.polish.fonts.change_font(container, old_name, new_name=None)[código fonte]

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)[código fonte]

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

  • 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.

calibre.ebooks.oeb.polish.css.filter_css(container, properties, names=())[código fonte]

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

  • 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.

Trabalhando com o Índice

calibre.ebooks.oeb.polish.toc.from_xpaths(container, xpaths)[código fonte]

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.

Generate a Table of Contents from links in the book.

calibre.ebooks.oeb.polish.toc.from_files(container)[código fonte]

Generate a Table of Contents from files in the book.

calibre.ebooks.oeb.polish.toc.create_inline_toc(container, title=None)[código fonte]

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


title – The title for this table of contents.

Editar ferramenta de livro

class calibre.gui2.tweak_book.plugin.Tool[código fonte]

Base: object

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

Methods that must be overridden in sub classes:

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)[código fonte]

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

  • 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)[código fonte]

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()
        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

Ver também

Method register_shortcut().

Controlando a interface do usuário do editor

A interface do usuário do editor de e-book é controlada por um único objeto Boss global. Isso tem muitos métodos úteis que podem ser usados no código do plugin para realizar tarefas comuns.

class calibre.gui2.tweak_book.boss.Boss(parent, notify=None)[código fonte]
add_savepoint(msg)[código fonte]

Create a restore checkpoint with the name specified as msg

apply_container_update_to_gui(mark_as_modified=True)[código fonte]

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


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)[código fonte]

Close the editor that is editing the file specified by name

commit_all_editors_to_container()[código fonte]

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)[código fonte]

Open the file specified by name in an editor

  • 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)[código fonte]

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.


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

rewind_savepoint()[código fonte]

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

save_book()[código fonte]

Save the book. Saving is performed in the background

set_modified()[código fonte]

Mark the book as having been modified

show_current_diff(allow_revert=True, to_container=None)[código fonte]

Show the changes to the book from its last checkpointed state

  • 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)[código fonte]

Show the editor that is editing the file specified by name

sync_preview_to_editor()[código fonte]

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