Настройка среды разработки calibre

У calibre полностью открытый исходный код, лицензированный GNU GPL v3. То есть вы можете загружать и изменять программу по собственному желанию. В этом разделе вы узнаете, как настроить среду разработки calibre на выбранной операционной системе. В основном calibre написана на Python со вставками кода на C/C++ для повышения скорости и взаимодействия с системой. Обратите внимание, что calibre требует, как минимум, Python 3.8.

Философия разработки

Истоки calibre лежат в мире Unix, что означает высокую модульность её дизайна. Модули взаимодействуют друг с другом через чётко определённые интерфейсы. Это заметно облегчает добавление новых возможностей и исправление ошибок, вызывая бурный темп развития. Из-за своих корней calibre имеет полноценный интерфейс командной строки для всех функций, задокументированный в разделе «Командная строка».

Модульная конструкция calibre выражается через «Плагины». Существует tutorial по написанию плагинов calibre. Например, добавление поддержки нового устройства в calibre обычно включает в себя написание менее 100 строк кода в виде плагина драйвера устройства. Вы можете просмотреть встроенные драйверы. Точно так же добавление поддержки новых форматов преобразования включает в себя написание плагинов формата ввода/вывода. Другим примером модульного дизайна является recipe system для получения новостей. Дополнительные примеры плагинов, предназначенных для добавления функций в calibre, см. В разделе «Индекс плагинов <https://www.mobileread.com/forums/showthread.php?p=1362767#post1362767>`_.

Макет кода

Весь Python код calibre находится в пакете calibre. Этот пакет содержит следующие основные подпакеты

  • devices — все драйверы устройств. Просто просмотрите некоторые встроенные драйверы, чтобы понять, как они работают.

    • Подробнее см.: devices.interface, определяющий интерфейс, поддерживаемый драйверами устройств, и devices.usbms, определяющий универсальный драйвер, который подключается к устройству USBMS. Все драйверы calibre на базе USBMS наследуются от него.

  • e-books — весь код преобразования электронных книг/метаданных. Хорошая отправная точка — calibre.ebooks.conversion.cli, который является модулем, включающим команду ebook-convert. Процесс преобразования контролируется через translation.plumber. Код, не зависящий от формата, находится в ebooks.oeb, а код, зависящий от формата, — в ebooks.format_name.

    • Чтение, запись и загрузка метаданных — всё это в ebooks.metadata

    • Преобразование происходит в конвейере (о структуре конвейера см. Предисловие). Конвейер состоит из входного плагина, различных трансформаций и выходного плагина. Код, который создаёт и управляет конвейером, находится в plumber.py. Конвейер работает над представлением электронной книги, похожей на разархивированный epub, с манифестом, spine, toc, guide, html-содержимым и т. д. Класс, который управляет этим представлением, — OEBBook в ebooks.oeb.base, различные трансформации, применяемые к книге во время конвертации, находятся в oeb/transforms/*.py. А входные и выходные плагины — в translation/plugins/*.py.

    • Редактирование электронной книги происходит с использованием другого объекта контейнера. Это задокументировано в Документация API инструмента редактирования электронных книг.

  • db — серверная часть базы данных. См.: Документация API интерфейса базы данных об интерфейсе библиотеки calibre.

  • Контент-сервер: srv — это контент-сервер calibre.

  • gui2 — графический интерфейс пользователя. Инициализация GUI происходит в gui2.main и gui2.ui. Программа просмотра электронных книг находится в gui2.viewer. Редактор электронных книг находится в gui2.tweak_book.

Если вы хотите найти точки входа для всех исполняемых файлов calibre различного уровня, посмотрите на структуру entry_points в linux.py.

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

Получение кода

Получить исходный код calibre можно двумя способами: при помощи системы управления версиями или прямой загрузкой архива tarball.

calibre использует Git, распределенную систему контроля версий. Git доступен на всех платформах, поддерживаемых calibre. После установки Git вы можете получить исходный код calibre с помощью команды:

git clone https://github.com/kovidgoyal/calibre.git

В Windows вам потребуется полный путь, который будет выглядеть примерно так C:\Program Files\Git\git.exe.

calibre — это очень большой проект с очень длинной историей управления исходным кодом, поэтому описанное выше может занять некоторое время (от 10 минут до часа в зависимости от скорости вашего интернета).

Хотите получить код быстрее - исходный код последней версии всегда доступен в виде archive.

Чтобы обновить ветку до последнего кода, используйте команду:

git pull --no-edit

Вы также можете просмотреть код на GitHub

Отправка ваших изменений для включения

Если вы планируете внести только несколько небольших изменений, вы можете внести свои изменения и создать «merge directive», которую затем можете прикрепить к заявке в calibre bug tracker. Для этого внесите свои изменения, затем запустите:

git commit -am "Comment describing your changes"
git format-patch origin/master --stdout > my-changes

Это создаст файл my-changes в текущей папке, просто прикрепите его к тикету на трекере ошибок calibre <https://bugs.launchpad.net/calibre>`_. Обратите внимание, что сюда будут включены все сделанные вами коммиты. Если вы хотите отправить только несколько коммитов, вам нужно изменить origin/master выше. Чтобы отправить только последний коммит, используйте:

git format-patch HEAD~1 --stdout > my-changes

Чтобы отправить последние n коммитов, замените 1 на n, например, для последних 3 коммитов:

git format-patch HEAD~3 --stdout > my-changes

Будьте осторожны, чтобы не включать слияния при использовании HEAD~n.

Если вы планируете много заниматься разработкой, то лучше всего создать учетную запись GitHub. Ниже приведено основное руководство по настройке собственного форка calibre таким образом, чтобы вы могли отправлять пулл-реквесты для включения в основной репозиторий calibre:

  • Настройте git на своём компьютере, как описано в статье: Setup Git

  • Настройте ssh-ключи для аутентификации на GitHub, как описано здесь: Генерация SSH-ключей

  • Перейдите на https://github.com/kovidgoyal/calibre и нажмите кнопку Fork.

  • В Терминале делай:

    git clone git@github.com:<username>/calibre.git
git remote add upstream https://github.com/kovidgoyal/calibre.git

    Замените <username> выше своим именем пользователя GitHub. Это позволит проверить ваш форк локально.

  • Вы можете вносить изменения и коммитить их в любое время. Когда вы будете готовы объединить свою работу, сделайте:

    git push

    и перейдите к https://github.com/<username>/calibre и нажмите кнопку Pull Request, чтобы сгенерировать пул-реквест, который можно объединить.

  • Вы можете в любое время обновить свою локальную копию кодом из основного репозитория, выполнив:

    git pull upstream

Вам также следует следить за форумом по разработке calibre. Прежде чем вносить серьезные изменения, вы должны обсудить их на форуме или напрямую связаться с Ковидом (его адрес электронной почты указан по всему исходному коду).

Среда разработки под Windows

Примечание

Вы также должны получить исходный код calibre отдельно, как описано выше.

Установите calibre обычным образом, используя Windows installer. Затем откройте командную строку и перейдите в ранее проверенную папку кода calibre. Например:

cd C:\Users\kovid\work\calibre

calibre - это папка, содержащая подпапки src и resources.

Следующий шаг - установка переменной среды CALIBRE_DEVELOP_FROM = абсолютный путь к папке src. Итак, следуя приведенному выше примеру, это будет C:\Users\kovid\work\calibre\src. Вот краткое руководство по настройке переменных среды в Windows.

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

echo %CALIBRE_DEVELOP_FROM%

Установка этой переменной окружения означает, что calibre теперь будет загружать весь свой код Python из указанного места.

Это всё! Теперь вы готовы взломать код calibre. Например, откройте файл src\calibre\__init__.py в вашем любимом редакторе и добавьте строку:

print("Hello, world!")

в верхней части файла. Теперь запустите команду calibredb. Самая первая строка вывода должна быть Hello, world!.

Вы также можете настроить окужение разработки calibre в бесплатной Microsoft Visual Studio, если хотите, следуя инструкциям здесь.

Среда разработки под macOS

Примечание

Вы также должны получить исходный код calibre отдельно, как описано выше.

Установите calibre обычным образом, используя предоставленный .dmg. Затем откройте Terminal и перейдите в ранее проверенную папку кода calibre. Например:

cd /Users/kovid/work/calibre

calibre - это папка, содержащая подпапки src и resources. Инструменты командной строки calibre находятся внутри пакета приложений calibre, в /Applications/calibre.app/Contents/MacOS, вы должны добавить эту папку в переменную среды PATH, если вы хотите легко запускать инструменты командной строки.

Следующий шаг - создание сценария bash, который установит для переменной среды CALIBRE_DEVELOP_FROM абсолютный путь к папке src при запуске calibre в режиме отладки.

Создайте простой текстовый файл:

#!/bin/sh
export CALIBRE_DEVELOP_FROM="/Users/kovid/work/calibre/src"
calibre-debug -g

Сохраните этот файл как /usr/local/bin/calibre-develop, затем установите ему права доступа так, чтобы он мог выполняться:

chmod +x /usr/local/bin/calibre-develop

Как только вы это сделали, запустите:

calibre-develop

При запуске calibre вы должны увидеть диагностическую информацию в окне терминала, а в окне графического интерфейса вы увидите звездочку после номера версии, указывающую, что вы запустились из исходников.

Среда разработки под Linux

Примечание

Вы также должны получить исходный код calibre отдельно, как описано выше.

calibre в основном разработан на Linux. У вас есть два варианта настройки среды разработки. Вы можете установить бинарный файл calibre как обычно и использовать его в качестве среды выполнения для разработки. Этот подход аналогичен тому, который используется в Windows и macOS. Кроме того, вы можете установить calibre из исходных кодов. Инструкции по настройке среды разработки из исходного кода находятся в файле INSTALL в дереве исходного кода. Здесь мы рассмотрим использование двоичного файла в качестве среды выполнения, что является рекомендуемым методом.

Установите calibre обычным образом, используя binary installer. Затем откройте терминал и перейдите в ранее проверенную папку кода calibre. Например:

cd /home/kovid/work/calibre

calibre - это папка, содержащая подпапки src и resources.

Следующий шаг - установка переменной среды CALIBRE_DEVELOP_FROM = абсолютный путь к папке src. Итак, следуя приведенному выше примеру, это будет /home/kovid/work/calibre/src. Как установить переменные среды, зависит от вашего дистрибутива Linux и используемой оболочки.

Примечание

Рекомендуется использовать бинарный установщик, предоставленный из апстрима. Если вы настаиваете на использовании пакета, предоставленного вашим дистрибутивом, используйте вместо этого переменные CALIBRE_PYTHON_PATH и CALIBRE_RESOURCES_PATH

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

echo $CALIBRE_DEVELOP_FROM

Установка этой переменной окружения означает, что calibre теперь будет загружать весь свой код Python из указанного места.

Это всё! Теперь вы готовы взломать код calibre. Например, откройте файл src\calibre\__init__.py в вашем любимом редакторе и добавьте строку:

print("Hello, world!")

в верхней части файла. Теперь запустите команду calibredb. Самая первая строка вывода должна быть Hello, world!.

Раздельная установка «обычной» и «разрабатываемой» версий calibre на одном компьютере

Исходное дерево кодов calibre очень стабильно и редко ломается, но если вы чувствуете необходимость запуска из источника в отдельной тестовой библиотеке и запускаете выпущенную версию calibre с вашей повседневной библиотекой, вы можете легко добиться этого, используя файлы .bat или сценарии оболочки для запуска calibre. В приведенном ниже примере показано, как сделать это в Windows с использованием файлов .bat (инструкции для других платформ такие же, просто используйте сценарий оболочки вместо файла .bat)

Чтобы запустить релизную версию calibre с вашей повседневной библиотекой:

calibre-normal.bat:

calibre.exe "--with-library=C:\path\to\everyday\library folder"

calibre-dev.bat:

set CALIBRE_DEVELOP_FROM=C:\path\to\calibre\checkout\src
calibre.exe "--with-library=C:\path\to\test\library folder"

Советы по отладке

Python — это динамически типизированный язык с отличными возможностями для самоанализа. Ковид написал код ядра calibre без единого использования отладчика. Существует много стратегий для отладки кода calibre:

Использование print statements

Это любимый способ отладки Ковида. Просто вставьте операторы печати в интересующие места и запустите вашу программу в терминале. Например, вы можете запустить графический интерфейс из терминала как:

calibre-debug -g

Точно так же вы можете запустить просмотрщик электронных книг как:

calibre-debug -w /path/to/file/to/be/viewed

Редактор электронных книг может быть запущен так:

calibre-debug --edit-book /path/to/be/edited

Использование интерактивного интерпретатора Python

Вы можете вставить следующие две строки кода, чтобы начать интерактивный сеанс Python в этой точке:

from calibre import ipython
ipython(locals())

При запуске из командной строки запускается интерактивный интерпретатор Python с доступом ко всем локально определенным переменным (переменным в локальной области). Интерактивная подсказка даже имеет завершение по Tab для свойств объекта, и вы можете использовать различные возможности Python для интроспекции, такие как dir(), type(), repr() и т. д.

Использовать отладчик Python как удаленный отладчик

Вы можете использовать встроенный отладчик Python (pdb) в качестве удаленного отладчика из командной строки. Сначала запустите удаленный отладчик в интересующем вас месте кода calibre, например:

from calibre.rpdb import set_trace
set_trace()

Затем запустите calibre, как обычно, или с помощью одной из команд отладки calibre, описанных в предыдущем разделе. Как только вышеуказанная точка в коде будет достигнута, calibre остановится, ожидая подключения отладчика.

Теперь откройте терминал или командную строку и используйте следующую команду для запуска сеанса отладки:

calibre-debug -c "from calibre.rpdb import cli; cli()"

Прочитать о том, как использовать отладчик Python, можно в Документации Python stdlib для модуля pdb (англ.).

Примечание

По умолчанию удаленный отладчик будет пытаться подключиться к порту 4444. Вы можете изменить его, передав параметр порта обеим функциям set_trace() и cli(), описанным выше, например: set_trace(port=1234) и cli(port=1234).

Примечание

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

Использование отладчика в вашей любимой Python IDE

Можно использовать встроенный отладчик в вашей любимой среде разработки Python, если он поддерживает удаленную отладку. Первый шаг - добавить проверку calibre src в PYTHONPATH в вашей среде IDE. Другими словами, папка, которую вы установили как CALIBRE_DEVELOP_FROM выше, также должна находиться в PYTHONPATH вашей IDE.

Затем поместите модуль удаленного отладчика IDE в подпапку src проверки исходного кода calibre. Добавьте любой код, необходимый для запуска удаленного отладчика до нужного уровня, например, в основной функции. Затем запустите calibre как обычно. Теперь ваша IDE должна иметь возможность подключаться к удаленному отладчику, работающему внутри calibre.

Выполнение произвольных скриптов в окружении Python calibre

Команда calibre-debug предоставляет несколько удобных ключей для выполнения собственного кода с доступом к модулям calibre:

calibre-debug -c "some Python code"

отлично подходит для тестирования небольшого фрагмента кода в командной строке. Он работает так же, как ключ -c для интерпретатора Python:

calibre-debug myscript.py

может быть использован для выполнения вашего собственного скрипта Python. Он работает так же, как и передача скрипта интерпретатору Python, за исключением того, что окружение calibre полностью инициализировано, поэтому вы можете использовать весь код calibre в своем скрипте. Чтобы использовать аргументы командной строки с вашим скриптом, используйте форму:

calibre-debug myscript.py -- --option1 arg1

-- заставляет все последующие аргументы быть переданными в ваш скрипт.

Использование calibre в собственных проектах

Можно напрямую использовать функции/код calibre в вашем проекте Python. Существует два способа сделать это:

Установка исполняемого файла calibre

Если у вас есть бинарная установка calibre, вы можете использовать интерпретатор Python в комплекте с calibre, например:

calibre-debug /path/to/your/python/script.py -- arguments to your script

Установка из исходного кода в Linux

Помимо использования описанной выше техники, если вы выполняете установку из исходного кода в Linux, вы также можете напрямую импортировать calibre, как показано ниже:

import init_calibre
import calibre

print(calibre.__version__)

Важно, чтобы вы импортировали модуль init_calibre перед любыми другими модулями/пакетами calibre, поскольку он настраивает интерпретатор для запуска кода calibre.

Документация API различных частей calibre