Documentação da API para as ferramentas de edição de ebooks

As ferramentas de edição de ebooks consistem num objecto contentor calibre.ebooks.oeb.polish.container.Container que representa um livro como uma coleção de ficheiros HTML e de recursos, e diversas ferramentas que podem ser usadas para levar a cabo operações sobre o contentor. Todas as ferramentas estão na forma de funções ao nível de módulo nos vários calibre.ebooks.oeb.polish.* módulos.

Obtém um objecto contentor para um livro num caminho como este:

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

Se estiver a escrever um plugin para o editor de ebooks, pode obter o contentor atual para o livro em edição, do seguinte modo:

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

O objecto contentor

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 folder full of files and an OPF file. There are two important concepts:

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

  • Names: These are paths to the books” files relative to the root folder. 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: o objecto contentor suporta eficientemente a clonagem para disco, o que é usado para implementar pontos de controlo no editor de ebooks. Para que isto funcione, nunca deve aceder directamente aos ficheiros no sistema de ficheiros. Em vez disso, use raw_data() ou open() para leitura/escrita nos ficheiros componentes do livro.

Aquando da conversão entre hrefs e nomes use os métodos fornecidos por esta classe, que assumem que todos os hrefs estão entre aspas.

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

Converte um caminho absoluto para um nome canónico relativo ao root

Parâmetros

root – A pasta base. Por predefinição, é usada a raiz deste objeto contentor.

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

Adiciona um ficheiro a este contentor. Entradas para o ficheiro são criadas automaticamente no manifesto OPF e na lombada (se o ficheiro for um documento de texto)

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

Adiciona uma entrada ao manifesto para um ficheiro com o nome especificado. Devolve o ID do manifesto.

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

Adiciona as propriedades especificadas ao item do manifesto identificado por nome.

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

Assegura que as propriedades especificadas são definidas apenas ao item de manifesto identificado por nome. Pode passar None como valor do parâmetro Nome para remover a propriedade de todos os itens.

book_type = 'oeb'

O tipo de livro (epub para ficheiros EPUB e azw3 para ficheiros AZW3)

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

Submeter ao sistema de ficheiros todos os objetos analisados que tenham sido identificados com problemas e escrever o ficheiro de ebook no caminho de saída.

Parâmetros
  • output – O caminho onde será escrito o ficheiro do ebook guardado. Se for None, é usado o caminho do ficheiro do livro original

  • keep_parsed – Se Verdadeiro, as representações analisadas dos itens confirmados são mantidas em cache.

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

Confirma a escrita de um objeto analisado para o disco (será serializado e escrito no ficheiro subjacente). Se `keep_parsed for Verdadeiro a representação analisada é mantida na Cache. Ver também: parsed()

dirty(name)[código fonte]

Marcar o objecto analisado correspondente ao nome como impuro. Ver também: parsed().

exists(name)[código fonte]

Verdadeiro se e só se existir um ficheiro/pasta correspondente ao nome canónico. Note que esta função sofre as limitações subjacentes ao sistema de ficheiros do sistema operativo, em particular no que respeita à (in)sensibilidade com que são tratadas as maiúsculas e minúsculas. Assim, num sistema de ficheiros que não diferencie entre maiúsculas e minúsculas, será devolvido Verdadeiro mesmo se a maiusculização do nome for diferente da que se encontra no ficheiro do sistema de ficheiros subjacente. Ver também: has_name()

filesize(name)[código fonte]

Devolve o tamanho em bytes do ficheiro representado pelo nome canónico especificado. Manipula automaticamente os objectos analisados como impuros. Ver também: parsed()

generate_item(name, id_prefix=None, media_type=None, unique_href=True)[código fonte]

Adiciona um item ao manifesto com um href derivado do nome fornecido. Assegura automaticamente a unicidade do href e do id. Devolve o item gerado.

get_file_path_for_processing(name, allow_modification=True)[código fonte]

Similar a open() exceto por devolver o caminho de um ficheiro em vez de um objecto de ficheiro aberto.

property guide_type_map

Mapeamento de tipo de guia para o nome canónico

has_name(name)[código fonte]

Devolve Verdadeiro se e só se existe um ficheiro com o mesmo nome canónico que o especificado. Ao contrário de exists() este método é sensível a maiúsculas e minúsculas.

href_to_name(href, base=None)[código fonte]

Converte um href (relativo à base) para um nome. base tem de ser um nome ou None, caso em que self.root será utilizado.

insert_into_xml(parent, item, index=None)[código fonte]

Insere item no ascendente (ou acrescenta se Index for None), ajustando a indentação. Apenas funciona com itens que auto-fecháveis.

is_dir = False

Se este contentor representa um livro não comprimido (uma pasta)

Itera sobre todas as ligações presentes no nome. Se get_line_numbers for Verdadeiro, os resultados devolvidos estarão na forma (ligação, número_de_linha, offset), onde número_de_linha é o número_de_linha na qual a ligação ocorre e offset é o número de caracteres contado desde o início da linha. Note que offset pode englobar diversas linhas se não for zero.

make_name_unique(name)[código fonte]

Assegura que nome não existe previamente neste livro. Se existe, devolve uma versão modificada que não existe.

manifest_has_name(name)[código fonte]

Devolve Verdadeiro se o manifesto tiver uma entrada correspondente ao nome

property manifest_id_map

Mapeamento de ID do manifesto para nomes canónicos

manifest_items_of_type(predicate)[código fonte]

Os nomes de todos os itens de manifesto cujos tipos de media coincidem com o predicado. predicate pode ser um conjunto, uma lista, uma string ou uma função de um único argumento, que será chamada pelo tipo de media.

manifest_items_with_property(property_name)[código fonte]

Todos os itens de manifesto que contêm a propriedade especificada

property manifest_type_map

Mapeamento do tipo de media do manifesto para lista de nomes canónicos desse tipo de media

property mi

Os metadados deste livro sob a forma de um objeto Metadados. Note que este objeto é construído em tempo real de cada vez que esta propriedade é solicitada, pelo que use com moderação.

name_to_abspath(name)[código fonte]

Converte um nome canónico para um caminho absoluto dependente do sistema operativo

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

Converte um nome para um href relativo à base, que tem de ser um nome ou None, caso em que self.root é usado como base

property names_that_must_not_be_changed

Conjunto de nomes que nunca podem ser alterados. Depende do formato do ficheiro do ebook.

property names_that_must_not_be_removed

Conjunto de nomes que nunca podem ser apagados do contentor. Depende do formato de ficheiro do ebook.

property names_that_need_not_be_manifested

Conjunto de nomes que são permitidos estarem em falta no manifesto. Depende do formato do ficheiro do ebook.

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

Abre o ficheiro apontado por nome para leitura/escrita direta. Note que isto efectuará as alterações ao ficheiro se o mesmo se encontrar deteriorado e removê-lo-à da cache do interpretador. É imperativo terminar o trabalho neste ficheiro antes de aceder novamente à sua versão interpretada, ou coisas estranhas certamente acontecerão.

property opf

O ficheiro OPF interpretado

opf_get_or_create(name)[código fonte]

Método de conveniência que devolve o primeiro element XML com o nome especificado ou então cria-o debaixo do elemento opf:package e devolve-o de seguida no caso de ainda não existir.

property opf_version

A versão definida no elemento <package>OPF

property opf_version_parsed

A versão definida no elemento do <package> OPF sob a forma de um énuplo de inteiros

opf_xpath(expr)[código fonte]

Método de conveniência para avaliar uma expressão XPath no ficheiro OPF, que tem os prefixos opf; e dc:namespace predefinidos.

parsed(name)[código fonte]

Devolve uma representação analisada lexicograficamente do ficheiro especificado pelo nome. Para ficheiros HTML e XML é devolvida uma árvore lxml. Para ficheiros CSS é devolvida uma folha de estilo do tipo css_parser. Note que os objectos analisados ficam em cache para melhorar a performance. Se fizer quaisquer alterações ao objecto analisado, tem de invocar dirty() de modo a que o contentor saiba que tem de actualizar a cache. Veja também replace().

raw_data(name, decode=True, normalize_to_nfc=True)[código fonte]

Devolve os dados em bruto correspondentes ao ficheiro especificado por nome

Parâmetros
  • decode – Se Verdadeiro, e se o ficheiro tiver um tipo de MIME baseado em texto, descodificar e devolver um objecto Unicode em vez de bytes em bruto.

  • normalize_to_nfc – Se Verdadeiro o objeto Unicode devolvido é normalizado sob a forma normal NFC tal como requerido pelos formatos de ficheiro EPUB e AZW3.

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

Converte um caminho absoluto (com separadores do SO) para um caminho relativo à base (por omissão, self.root). O caminho relativo não é um nome. Use abspath_to_name() para esse fim.

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

Remove os itens especificados (por nome canónico) da lombada. Se remove_if_no_longer_in_spine for Verdadeiro, os itens também são apagados do livro, e não apenas da lombada.

remove_from_xml(item)[código fonte]

Remove o item do contentor, ajustando a indentação (funciona apenas com itens que se auto-fecham).

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

Remove o item identificado por nome deste contentor. Isto remove todas as referências ao item do manifesto OPF, guia e lombada bem como de todas as caches internas.

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

Substitui os objectos analisados correspondentes ao nome por obj, que tem de ser um objecto similar, isto é, uma árvore lxml no caso de HTML/XML ou uma folha de estilo css_parser no caso de ficheiros CSS.

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.

Gerir ficheiros componentes num contentor

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

Parâmetros
  • 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.

Parâmetros

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.

Pretty printing and auto fixing parse errors

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

Corrija os erros de análise do HTML representados por uma cadeia de caracteres em bruto. A correção é efetuada usando o algoritmo de análise do HTML5.

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

Corrija os erros de análise em todos os ficheiros HTML do contentor. A correção é efetuada usando o algoritmo de análise do HTML5.

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]

Imprime de forma visualmente apelativa todos os ficheiros HTML/CSS/XML existentes no contentor

Gerir sobrecapas de livros

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

Remove uma sobrecapa existente, se existir. Devolve False se não for encontrada uma sobrecapa.

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

Efectua uma de duas operações: ou cria uma nova sobrecapa a partir dos metadados do livro ou substitui a sobrecapa existente. Devolve Verdadeiro se a sobrecapa existente for substituída.

Splitting and merging of files

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.

Parâmetros
  • 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 – Se Verdadeiro a separação ocorre antes do elemento identificado; se não, ocorre depois dele.

  • totals – Usado internamente

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.

Parâmetros

before – Se Verdadeiro as separações ocorrem antes do elemento identificado; se não, ocorrem depois dele.

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

Funde os ficheiros especificados num único ficheiro, com a migração automática de todas as ligações e referências dos ficheiros afetados. Os ficheiros têm todos de ser HTML ou CSS.

Parâmetros
  • category – Tem de ser 'text' para ficheiros HTML ou 'styles' para CSS

  • names – A lista de ficheiros a serem fundidos

  • master – Qual dos ficheiros a fundir será o ficheiro mestre, ou seja, qual é o ficheiro que será mantido depois da fusão.

Gerir capas

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

Torna a capa do livro na imagem apontada por cover_path.

Parâmetros
  • cover_path – O caminho absoluto para um ficheiro de imagem ou o nome canónico de uma imagem no livro. Quando usa uma imagem no livro tem também de definir opções, ver abaixo.

  • report – Um função opcional que pode ser chamada e que tem um único argumento. Será chamada com informação acerca das tarefas em processamento.

  • options – Vazio, ou um dicionário que controla como a capa é criada. O dicionário pode conter as entradas: keep_aspect: Verdadeiro ou Falso (Preservar a proporção das imagens de capa no EPUB) no_svg: Verdadeiro ou Falso (Usar um embrulho SVG para a capa na página de título do EPUB) existing: Verdadeiro ou Falso (cover_path refere-se a uma imagem existente no livro)

calibre.ebooks.oeb.polish.cover.mark_as_cover(container, name)[código fonte]

Marca a imagem especificada como a imagem da capa.

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

Marca o ficheiro HTML especificado como a página de capa do EPUB.

Parâmetros

move_to_start – Se verdadeiro, o ficheiro HTML será movido para o início da lombada

Trabalhar 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, remove_unreferenced_sheets=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.

Parâmetros
  • 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 – Se Verdadeiro, regras com selectores idênticos são fundidas.

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

Remove as propriedades CSS especificadas de todas as regras CSS no livro.

Parâmetros
  • properties – Conjunto de propriedades a remover. Por exemplo: {'font-family', 'color'}.

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

Trabalhar com o Índice

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

Cria um índice a partir de uma lista de expressões XPath. Cada expressão na lista corresponde a um nível do índice gerado. Por exemplo: ['//h:h1', '//h:h2', '//h:h3'] criará um índice de três níveis partindo das etiquetas <h1>, <h2> e <h3>.

Gerar um índice a partir de hiperligações no livro.

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

Gerar um índice a partir de ficheiros no livro.

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.

Parâmetros

title – The title for this table of contents.

Editar ferramenta do livro

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

Bases: 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 shortcuts section of the editor preferences.

Parâmetros
  • 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 – Uma descrição breve opcional desta ação. Se não especificada será usado o texto de QAction.

  • description – Uma descrição mais detalhada desta ação, que será usada na entrada das preferências deste atalho.

create_action(for_toolbar=True)[código fonte]

Cria uma QAction que será adicionada à barra de ferramentas dos plugins ou ao menu de plugins, dependendo valor de for_toolbar. Por exemplo:

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

Veja também

Método 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)[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.

Parâmetros

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

Parâmetros
  • 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)[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.

Parâmetros

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

Parâmetros
  • 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]

Sincronizar posição do painel de pré-visualização com a posição atual do cursor no editor atual