Документация API инструмента редактирования электронных книг

Инструменты редактирования электронных книг состоят из объекта calibre.ebooks.oeb.polish.container.Container, который представляет книгу как набор файлов ресурсов HTML +, и различных инструментов, которые можно использовать для выполнения операций с контейнером. Все инструменты представлены в виде функций уровня модуля в различных модулях calibre.ebooks.oeb.polish.*.

Вы получаете объект-контейнер для книги по следующему пути:

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

If you are writing a plugin for the E-book editor, you get the current container for the book being edited like this:

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

Объект контейнера

class calibre.ebooks.oeb.polish.container.Container(rootpath=None, opfpath=None, log=<calibre.utils.logging.Log object>, clone_data=None)

Контейнер представляет собой открытую электронную книгу в виде папки, полной файлов и файла OPF. Есть два важных понятия:

• Корневая папка. Это основа электронной книги. Все файлы электронных книг находятся внутри этой папки или в ее подпапках.

• Имена: это пути к файлам книг относительно корневой папки. Они всегда содержат разделители POSIX и не заключаются в кавычки. Их можно рассматривать как канонические идентификаторы файлов в книге. Большинство методов объекта-контейнера работают с именами. Имена всегда в нормальной форме NFC Unicode.

• Клоны: объект-контейнер поддерживает эффективное клонирование на диске, которое используется для реализации контрольных точек в редакторе электронных книг. Чтобы это работало, вы никогда не должны обращаться к файлам в файловой системе напрямую. Вместо этого используйте raw_data() или open() для чтения/записи файлов компонентов в книге.

При преобразовании между hrefs и именами используйте методы, предоставляемые этим классом, они предполагают, что все hrefs заключены в кавычки.

abspath_to_name(fullpath, root=None)

Преобразование абсолютного пути в каноническое имя относительно root

Параметры:

root – Базовая папка. По умолчанию используется корень для этого объекта-контейнера.

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

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, suggested_id='')

Добавить в манифест запись для файла с указанным именем. Возвращает идентификатор манифеста.

add_properties(name, *properties)

Добавить указанные свойства в элемент манифеста, идентифицированный по имени.

apply_unique_properties(name, *properties)

Убедитесь, что указанные свойства установлены только для элемента манифеста, указанного по имени. Вы можете передать None в качестве имени, чтобы удалить свойство из всех элементов.

book_type = 'oeb'

Тип книги epub для файлов EPUB и azw3 для файлов AZW3

commit(outpath=None, keep_parsed=False)

Зафиксировать все загрязненные проанализированные объекты в файловой системе и записать файл электронной книги по пути outpath.

Параметры:

• output – Путь для записи сохраненного файла электронной книги. Если None, используется путь к исходному файлу книги.

• keep_parsed – Если True, проанализированные представления зафиксированных элементов хранятся в кеше.

commit_item(name, keep_parsed=False)

Зафиксировать проанализированный объект на диске (он сериализуется и записывается в базовый файл). Если keep_parsed - True, проанализированное представление сохраняется в кеше. См. также :parsed()

dirty(name)

Отметить проанализированный объект, соответствующий имени, как грязный. См. Также :parsed().

exists(name)

Истинно, только если существует файл/папка, соответствующие каноническому имени. Обратите внимание, что эта функция страдает от ограничений базовой файловой системы ОС, в частности из-за (не) чувствительности. Таким образом, в файловой системе, нечувствительной к регистру, это вернет True, даже если регистр имени отличается от регистра файла базовой файловой системы. См. Также has_name()

filesize(name)

Вернуть размер в байтах файла, представленного указанным каноническим именем. Автоматически обрабатывает загрязненные проанализированные объекты. См. также :parsed()

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

Добавить в манифест элемент с href, производным от заданного имени. Автоматически обеспечивает уникальность href и id. Возвращает сгенерированный элемент.

get_file_path_for_processing(name, allow_modification=True)

Подобно open(), за исключением того, что он возвращает путь к файлу вместо объекта открытого файла.

property guide_type_map

Сопоставление guide типа с каноническим именем

has_name(name)

Вернуть True, если существует файл с тем же каноническим именем, что и указанное. В отличие от exists() этот метод всегда чувствителен к регистру.

href_to_name(href, base=None)

Преобразование href (относительно base) в имя. base должно быть именем или None, в этом случае используется self.root.

insert_into_xml(parent, item, index=None)

Вставить элемент в родительский (или добавить, если индекс равен None), исправив отступ. Работает только с самозакрывающимися элементами.

is_dir = False

Если этот контейнер представляет собой распакованную книгу (каталог)

iterlinks(name, get_line_numbers=True)

Перебрать все ссылки по имени. Если get_line_numbers имеет значение True, выдает результаты формы (ссылка, номер_строки, смещение). Где line_number - это номер line_number, в котором находится ссылка, а смещение - это количество символов от начала строки. Обратите внимание, что смещение может охватывать несколько строк, если не ноль.

make_name_unique(name)

Убедится, что name уже не существует в этой книге. Если это так, вернуть измененную версию, которая не существует.

manifest_has_name(name)

Вернуть True, если в манифесте есть запись, соответствующая имени

property manifest_id_map

Сопоставление идентификатора манифеста с каноническими именами

manifest_items_of_type(predicate)

Имена всех элементов манифеста, тип носителя которых соответствует предикату. predicate может быть набором, списком, строкой или функцией, принимающей один аргумент, которая будет вызываться с медиа-типом.

manifest_items_with_property(property_name)

Все элементы манифеста, имеющие указанное свойство

property manifest_type_map

Сопоставление манифестного медиа-типа со списком канонических имен этого медиа-типа

property mi

Метаданные этой книги как объект метаданных. Обратите внимание, что этот объект создается «на лету» каждый раз, когда это свойство запрашивается, поэтому используйте его с осторожностью.

name_to_abspath(name)

Преобразование канонического имени в путь, полностью зависящий от ОС

name_to_href(name, base=None)

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

Набор имен, которые нельзя переименовывать. Зависит от формата файла электронной книги.

property names_that_must_not_be_removed

Набор имен, которые нельзя удалять из контейнера. Зависит от формата файла электронной книги.

property names_that_need_not_be_manifested

Набор имен, которые могут отсутствовать в манифесте. Зависит от формата файла электронной книги.

open(name, mode='rb')

Открыть файл, указанный по имени, для прямого чтения/записи. Обратите внимание, что это зафиксирует файл, если он загрязнен, и удалит его из кеша синтаксического анализа. Вы должны закончить работу с этим файлом, прежде чем снова обращаться к его проанализированной версии, иначе произойдут неприятности.

property opf

Разобранный файл OPF

opf_get_or_create(name)

Удобный метод, позволяющий либо вернуть первый элемент XML с указанным именем, либо создать его в элементе opf:package, а затем вернуть его, если он ещё не существует.

property opf_version

Версия, установленная на <package> элементе OPF

property opf_version_parsed

Версия, заданная в <package> элементе OPF как кортеж целых чисел

opf_xpath(expr)

Удобный метод для оценки выражения XPath в файле OPF имеет предопределенные префиксы пространства имен opf: и dc:.

parsed(name)

Вернуть проанализированное представление файла, указанного по имени. Для файлов HTML и XML возвращается дерево lxml. Для файлов CSS возвращается таблица стилей css_parser. Обратите внимание, что проанализированные объекты кэшируются для повышения производительности. Если вы вносите какие-либо изменения в анализируемый объект, вы должны вызвать dirty(), чтобы контейнер знал, что нужно обновить кеш. См. Также replace().

raw_data(name, decode=True, normalize_to_nfc=True)

Вернуть необработанные данные, соответствующие файлу, указанному по имени

Параметры:

• decode – Если True и файл имеет текстовый MIME-тип, декодировать его и вернуть объект Unicode вместо необработанных байтов.

• normalize_to_nfc – Если True, возвращаемый объект unicode нормализуется до нормальной формы NFC, как это требуется для форматов файлов EPUB и AZW3.

relpath(path, base=None)

Преобразование абсолютного пути (с разделителями os) в путь относительно базы (по умолчанию self.root). Относительный путь - не имя. Для этого используйте abspath_to_name().

remove_from_spine(spine_items, remove_if_no_longer_in_spine=True)

Удалить указанные пункты (по каноническому имени) из корешка. Если remove_if_no_longer_in_spine имеет значение True, элементы также удаляются из книги, а не только из корешка.

remove_from_xml(item)

Удалить элемент из родительского, исправляя отступ (работает только с самозакрывающимися элементами)

remove_item(name, remove_from_guide=True)

Удалить из этого контейнера элемент, указанный по имени. Это удалит все ссылки на элемент в манифесте, руководстве и корешке OPF, а также из любых внутренних кешей.

rename(current_name, new_name)

Переименовывает файл с current_name в new_name. Он автоматически переустанавливает все ссылки внутри файла, если папка, в которой находится файл, изменяется. Однако обратите внимание, что ссылки не обновляются в других файлах, которые могут ссылаться на этот файл. Это для производительности, такие обновления нужно делать один раз, массово.

replace(name, obj)

Заменить проанализированный объект, соответствующий имени, на obj, который должен быть аналогичным объектом, то есть деревом lxml для HTML/XML или таблицей стилей css_parser для файла CSS.

replace_links(name, replace_func)

Заменить все ссылки в имени с помощью replace_func, которая должна быть вызываемой, которая принимает URL-адрес и возвращает замененный URL-адрес. Он также должен иметь атрибут replace, который имеет значение True, если выполняется какая-либо фактическая замена. Удобные способы создания таких вызываемых объектов - это использование классов LinkReplacer и LinkRebaser.

serialize_item(name)

Преобразовать проанализированный объект (идентифицируемый каноническим именем) в байтовую строку. Смотрите parsed().

set_spine(spine_items)

Задать для spine значение spine_items, где spine_items - это итерабельность формы (имя, линейная). Вызовет ошибку, если одно из имен отсутствует в манифесте.

property spine_items

Итератор, определяющий путь для каждого элемента корешка книги. См. также :spine_iter и spine_items.

property spine_iter

Итератор, который выдает элемент с именем is_linear для каждого элемента в корешке книги. item - это элемент lxml, name - каноническое имя файла, а is_linear - True, если элемент является линейным. См. также :spine_names и spine_items.

property spine_names

Итератор, дающий имя и is_linear для каждого элемента в корешке книги. См. также :spine_iter и spine_items.

Управление файлами компонентов в контейнере

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

Заменить ссылки на файлы в контейнере. Будет перебирать все файлы в контейнере и изменять в них указанные ссылки.

Параметры:

• link_map – Сопоставление старого канонического имени с новым каноническим именем. Например: {'images/old.png': 'images/new.png'}

• frag_map – Вызываемый объект, который принимает два аргумента (имя, привязка) и возвращает новую привязку. Это полезно, если вам нужно изменить привязки в файлах HTML. По умолчанию ничего не делает.

• replace_in_opf – Если false, ссылки не заменяются в файле OPF.

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

Переименовывать файлы в контейнере, автоматически обновляя все ссылки на них.

Параметры:

file_map – Сопоставление старого канонического имени с новым каноническим именем, например: {'text/chapter1.html': 'chapter1.html'}.

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

Вернуть папки, рекомендованные для данных имен файлов. Рекомендация основана на том, где в контейнере находится большинство файлов одного типа. Если файлы определенного типа отсутствуют, рекомендуемая папка считается папкой, содержащей файл OPF.

Хорошая печать и автоматическое исправление ошибок синтаксического анализа

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

Исправить любые ошибки синтаксического анализа в HTML, представленном в виде строки в необработанном виде. Исправление производится с помощью алгоритма парсинга HTML5.

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

Исправить все ошибки синтаксического анализа во всех файлах HTML в контейнере. Исправление производится с помощью алгоритма парсинга HTML5.

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

Хорошая печать HTML в представленного виде строки в необработанном виде

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

Хорошая печать CSS, представленной в виде строки в необработанном виде

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

Хорошая печать XML, представленного в виде строки в необработанном виде. Если name - это имя OPF, выполняется дополнительная обработка, специфичная для OPF.

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

Хорошая печать всех файлов HTML/CSS/XML в контейнере

Управление обложками книг

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

Удалить существующую обложку, если таковая имеется. Возвращает False, если существующая обложка не найдена.

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

Либо создать новую обложку из метаданных книги, либо заменить существующую обложку. Возвращает True, если существующая обложка была заменена.

Разделение и слияние файлов

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

Разделить файл, указанный по имени, в позиции, указанной параметром loc_or_xpath. При разделении автоматически переносятся все ссылки и ссылки на затронутые файлы.

Параметры:

• loc_or_xpath – Должно быть выражением XPath, например //h:div[@id=“split_here“]. Также может быть loc, который используется внутри для реализации разделения на панели предварительного просмотра.

• before – Если True, разделение происходит до идентифицированного элемента, иначе после него.

• totals – Используется внутри

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

Разделить указанный файл в нескольких местах (все теги, соответствующие указанному выражению XPath). См. также: split(). При разделении автоматически переносятся все ссылки и ссылки на затронутые файлы.

Параметры:

before – Если True, разбиение происходит до идентифицированного элемента, иначе после него.

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

Объединить указанные файлы в один файл, автоматически перенеся все ссылки и ссылки на затронутые файлы. Все файлы должны быть либо HTML, либо CSS.

Параметры:

• category – Должен быть либо text для файлов HTML, либо styles для файлов CSS.

• names – Список файлов для слияния

• master – Какой из объединенных файлов является главным файлом, то есть файлом, который останется после объединения.

Управление обложками

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

Установить обложку книги на изображение, на которое указывает cover_path

Параметры:

• cover_path – Либо абсолютный путь к файлу изображения, либо каноническое имя изображения в книге. При использовании изображения в книге вы также должны установить параметры, см. ниже.

• report – Необязательный вызываемый объект, который принимает единственный аргумент. Он будет вызываться с информацией об обрабатываемых задачах

• options – None или словарь, который контролирует установку обложки. В словаре могут быть записи: keep_aspect: True или False (сохранить соотношение сторон обложек в EPUB) no_svg: True или False (использовать обертку обложки SVG на титульной странице EPUB) existing: True или False (cover_path относится к существующему изображению в книге)

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

Отметить указанное изображение как изображение обложки.

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

Отметить указанный HTML-файл как титульную страницу EPUB.

Параметры:

move_to_start – Если True, HTML-файл перемещается в начало корешка.

Работа с CSS

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

Изменить семейство шрифтов с old_name на new_name. Изменяет все вхождения семейства шрифтов в таблицах стилей, тегах стилей и атрибутах стиля. Если old_name относится к встроенному шрифту, он удаляется. Вы можете установить для new_name значение None, чтобы удалить семейство шрифтов вместо его изменения.

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)

Удалить из книги все неиспользуемые правила CSS. Неиспользуемое правило CSS - это правило, не соответствующее фактическому содержанию.

Параметры:

• report – Необязательный вызываемый объект, который принимает единственный аргумент. Вызывается с информацией о выполняемых операциях.

• remove_unused_classes – Если True, атрибуты класса в HTML, которые не соответствуют никаким правилам CSS, также удаляются.

• merge_rules – Если True, правила с идентичными селекторами объединяются.

• merge_rules_with_identical_properties – Если True, правила с одинаковыми свойствами объединяются.

• remove_unreferenced_sheets – Если True, таблицы стилей, на которые не ссылается какой-либо контент, удаляются.

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

Удалить указанные свойства CSS из всех правил CSS в книге.

Параметры:

• properties – Набор свойств для удаления. Например: {'font-family', 'color'}.

• names – Файлы, из которых нужно удалить свойства. По умолчанию используются все файлы HTML и CSS в книге.

Работа с оглавлением

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

Создать оглавление из списка выражений XPath. Каждое выражение в списке соответствует уровню создания ToC. Например: ['//h:h1','//h:h2','//h:h3'] сгенерирует трехуровневую таблицу содержания из <h1>, <h2> и <h3> тегов.

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

Создать оглавление из ссылок в книге.

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

Создать оглавление из файлов в книге.

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

Создать встроенное (HTML) оглавление из существующего оглавления NCX.

Параметры:

title – Заголовок этого оглавления.

Средство редактирования книги

class calibre.gui2.tweak_book.plugin.Tool

Базовые классы: object

Базовый класс для отдельных инструментов в плагине Edit Book. Среди полезных членов:

• self.plugin: ссылка на объект calibre.customize.Plugin, которому принадлежит этот инструмент.

• self. boss

• self. gui

Методы, которые необходимо переопределить в подклассах:

• create_action()

• register_shortcut()

name = None

Установить уникальное имя, которое будет использоваться как ключ

allowed_in_toolbar = True

Если True, пользователь может разместить этот инструмент на панели инструментов плагинов.

allowed_in_menu = True

Если True, пользователь может выбрать размещение этого инструмента в меню плагинов.

toolbar_button_popup_mode = 'delayed'

Всплывающий режим для меню (если есть) кнопки панели инструментов. Возможные значения: „delayed“, „instant“, „button“.

property boss

Объект calibre.gui2.tweak_book.boss.Boss. Используется для управления пользовательским интерфейсом.

property gui

Главное окно пользовательского интерфейса

property current_container

Вернуть текущий объект calibre.ebooks.oeb.polish.container.Container, представляющий редактируемую книгу.

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

Зарегистрируйте сочетание клавиш, которое будет запускать указанное действие qaction. Это сочетание клавиш станет автоматически настраиваемым пользователем в разделе «Сочетания клавиш» настроек редактора.

Параметры:

• qaction – Объект QAction, он будет срабатывать, когда пользователь нажимает настроенную комбинацию клавиш.

• unique_name – Уникальное имя для этого ярлыка/действия. Он будет использоваться для внутренних целей, он не должен использоваться другими действиями в этом плагине.

• default_keys – Список сочетаний клавиш по умолчанию. Если не указано иное, ярлыки по умолчанию не будут установлены. Если указанные здесь ярлыки конфликтуют со встроенными ярлыками или ярлыками из пользовательской конфигурации/других плагинов, они будут проигнорированы. В этом случае пользователям придется настраивать ярлыки вручную в настройках. Например: default_keys=('Ctrl+J', 'F9').

• short_text – Необязательное краткое описание этого действия. Если не указано иное, будет использован текст из QAction.

• description – Необязательное более подробное описание этого действия, оно будет использовано в записи настроек для этого ярлыка.

create_action(for_toolbar=True)

Создать QAction, который будет добавлен либо на панель инструментов плагинов, либо в меню плагинов в зависимости от for_toolbar. Например:

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

См. также

Метод register_shortcut().

Управление пользовательским интерфейсом редактора

Пользовательский интерфейс редактора электронных книг управляется одним глобальным объектом Boss. У этого есть много полезных методов, которые можно использовать в коде плагина для выполнения общих задач.

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

add_savepoint(msg)

Создать контрольную точку восстановления с именем, указываемым как msg

apply_container_update_to_gui(mark_as_modified=True)

Обновить все компоненты пользовательского интерфейса, чтобы отразить последние данные в текущем контейнере книги.

Параметры:

mark_as_modified – Если True, книга будет помечена как изменённая, поэтому пользователю будет предложено сохранить её при выходе.

close_editor(name)

Закрыть редактор, который редактирует файл, указанный в name.

commit_all_editors_to_container()

Зафиксировать любые изменения, внесённые пользователем в файлы, открытые в редакторах, в контейнер. Вы должны вызвать этот метод перед выполнением каких-либо действий с текущим контейнером.

property currently_editing

Вернуть имя редактируемого файла или None, если файл не редактируется.

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

Открыть файл, указанный по имени, в редакторе

Параметры:

• syntax – Медиа-тип файла, например, text/html. Если не указано, это определяется по расширению файла.

• use_template – Шаблон для инициализации открытого редактора с помощью

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

Открыть электронную книгу по пути для редактирования. Будет отображена ошибка, если формат электронной книги не поддерживается или в текущей книге есть несохраненные изменения.

Параметры:

edit_file – Имя файла во вновь открытой книге, чтобы начать редактирование. Также может быть список имен.

rewind_savepoint()

Отменить предыдущее создание контрольной точки восстановления, полезно, если вы создаете контрольную точку, а затем прерываете операцию без изменений

save_book()

Сохранить книгу. Сохранение происходит в фоновом режиме

set_modified()

Отметить книгу как изменённую

show_current_diff(allow_revert=True, to_container=None)

Показать изменения в книге по сравнению с последней контрольной точкой

Параметры:

• allow_revert – Если True, в диалоговом окне сравнения будет кнопка, позволяющая пользователю отменить все изменения.

• to_container – Объект контейнера, с которым сравнивается текущий контейнер. Если None, используется контейнер с ранее установленной контрольной точкой.

show_editor(name)

Показать редактор, редактирующий файл, указанный в name

sync_preview_to_editor()

Синхронизировать положение панели предварительного просмотра с текущей позицией курсора в текущем редакторе

© Копирайт Kovid Goyal. Последнее обновление июл. 18, 2025.