Документация 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, opfpath, log, clone_data=None)[исходный код]

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

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

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

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

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

abspath_to_name(fullpath, root=None)[исходный код]

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

Параметры

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

add_file(name, data, media_type=None, spine_index=None, modify_name_if_needed=False, process_manifest_item=None)[исходный код]

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)[исходный код]

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

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

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

Перебрать все ссылки по имени. Если 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_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.

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

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

Параметры
  • 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'}.

Вернуть папки, рекомендованные для данных имен файлов. Рекомендация основана на том, где в контейнере находится большинство файлов одного типа. Если файлы определенного типа отсутствуют, рекомендуемая папка считается папкой, содержащей файл 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)[исходный код]

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

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

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

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

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()[исходный код]

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