Налаштовування середовища для розробки calibre

Увесь початковий код calibre відкрито і ліцензовано відповідно до GNU GPL v3. Це означає, що ви можете безкоштовно отримувати код програми і вносити до нього будь-які потрібні вам зміни. За допомогою цього розділу ви зможете ознайомитися із тим, як створити середовище для розробки calibre у вашій операційній системі. calibre, в основному, написано мовою програмування Python із вставками мовою програмування C/C++ для підвищення швидкодії та роботи із системою. Зауважте, що програма calibre є потребує для роботи принаймні Python 3.8.

Засади структури програми

calibre походить зі світу Unix, і це означає, що значна частина можливостей програми винесена у модулі. Ці модулі взаємодіють між собою за допомогою добре визначених інтерфейсів. Це робить додавання нових можливостей та виправлення вад у calibre дуже простим і надає розвитку програми шаленого темпу. Через своє походження calibre має всеосяжний інтерфейс командного рядка для усіх свої функціональних можливостей. Документацію з нього можна знайти у розділі Інтерфейс командного рядка.

Модульність calibre реалізується додатками. У нашому підручнику є розділ щодо написання додатків до calibre. Наприклад, додавання підтримки нового пристрою у calibre типово полягає у написанні менш ніж 100 рядків коду у формі додатка драйвера пристрою. Ви можете ознайомитися зі списком вбудованих драйверів. Так само, додавання підтримки нових форматів перетворення полягає у написанні додатків форматів введення і виведення даних. Іншим прикладом модульної побудови є система рецептів для отримання новин. З іншими прикладами додатків, розроблених для розширення можливостей calibre, можна ознайомитися тут.

Структура коду

Увесь код мовою Python calibre є частиною пакунка «calibre». У цьому пакунку містяться вказані нижче підпакунки

  • devices — усі драйвери до пристроїв. Достатньо ознайомитися з кодом вбудованих до програми драйверів, щоб зрозуміти основні принципи роботи драйверів.

    • Докладніший опис можна знайти у devices.interface, визначенні інтерфейсу підтримки драйверів пристроїв, та у devices.usbms, визначенні типового драйвера, який встановлює з’єднання із пристроєм USBMS. Усі драйвери на основі USBMS у calibre успадковуються від цього драйвера.

  • ebooks — увесь код, який пов’язано із перетворенням та метаданими електронних книг. Варто розпочати з calibre.ebooks.conversion.cli, модуля, який забезпечує роботу програми ebook-convert. Процесом перетворення керує conversion.plumber. Незалежний від форматів код зберігається у ebooks.oeb, а залежний від форматів — у ebooks.format_name.

    • Засоби читання, записування та отримання метаданих зосереджено у ebooks.metadata

    • Перетворення виконується у конвеєрі. Зі структурою конвеєра можна ознайомитися у розділі Вступ. Конвеєр складається із додатка вхідних даних, різноманітних перетворено та додатка вихідних даних. Код, який будує конвеєр і керує ним, зберігається у plumber.py. Конвеєр працює над створенням представлення книги у формі розпакованого файла epub, із маніфестом manifest, вмістом, змістом, путівником, даними html тощо. Класом, який керує цим представленням, є клас OEBBook у ebooks.oeb.base. Різноманітні перетворення, які застосовуються до книги під час обробки, зберігаються у oeb/transforms/*.py. Код додатків вхідних і вихідних даних зберігається у conversion/plugins/*.py.

    • Редагування електронних книг відбувається за допомогою іншого об’єкта-контейнера. Його документовано у розділі Документація з програмного інтерфейсу засобів редагування електронних книг.

  • db — модуль бази даних. Див. розділ Документація з програмного інтерфейсу для роботи з базою даних, щоб дізнатися більше про інтерфейс бібліотеки calibre.

  • Сервер даних: «srv» — це сервер даних calibre.

  • gui2 — графічний інтерфейс користувача. Ініціалізація інтерфейсу виконується у gui2.main і gui2.ui. Сам засіб перегляду електронних книг міститься у gui2.viewer. За редагування електронних книг відповідає gui2.tweak_book.

Якщо вам потрібен доступ до усіх виконуваних файлів calibre, ознайомтеся зі структурою entry_points у linux.py.

Якщо хочете краще зрозуміти код, створіть тему із вашим питанням на форумі розробників. Найімовірніше, там ви отримаєте кваліфіковану відповідь від одного з багатьох розробників calibre.

Отримання коду

Отримати початковий код calibre можна у два способи: за допомогою системи керування версіями та безпосереднього отримання архіву з кодом програми.

Для керування версіями у calibre використовують Git, розподілену систему керування версіями. Git можна користуватися на усіх платформах, на яких працює calibre. Після встановлення Git ви зможете отримати початковий код calibre за допомогою такої команди:

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

У Windows вам знадобиться шлях повністю, щось схоже на C:\Program Files\Git\git.exe.

calibre є дуже великим проектом із дуже довгою історією, отже виконання вказаної вище команди може бути доволі тривалим (від 10 хвилин до години, залежно від пропускної здатності вашого каналу з’єднання).

Якщо ви хочете отримати код швидше, початковий код найсвіжішого випуску завжди можна отримати у форматі архіву.

Щоб оновити гілку до актуального стану, скористайтеся такою командою:

git pull --no-edit

Ви також можете переглядати код на GitHub.

Надсилання ваших змін для включення до програми

Якщо ви плануєте внести лише незначні зміни, ви можете створити з них «інструкцію об’єднання», а потім долучити її до квитка у системі стеження за вадами calibre. Процедура така: вносимо зміни, а потім віддаємо такі команди:

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

У результаті у поточній теці буде створено файл my-changes, який слід просто долучити до квитка у системі стеження за вадами 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.

Якщо ви плануєте значний розвиток коду calibre, вам варто створити обліковий запис на GitHub. Нижче наведено базові настанови щодо створення власної копії коду calibre у спосіб, який надасть вам змогу надсилати запити щодо об’єднання (pull requests) для включення вашого коду до основного сховища коду calibre:

  • Налаштуйте git на вашому комп’ютері так, як це описано у цій статті: Setup Git

  • Налаштуйте ключі ssh для розпізнавання на GitHub, як це описано тут: Generating SSH keys

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

  • У терміналі віддайте команди:

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

    Замініть <ім’я_користувача> у наведеній вище команді на ваше ім’я користувача GitHub. Таким чином, ви отримаєте копію клонованого сховища на вашому комп’ютері.

  • Ви можете внести зміни і надіслати їх будь-коли. Коли ви будете готові до внесення вашої роботи, зробіть от що:

    git push

    перейдіть на сторінку https://github.com/<ім’я користувача>/calibre і натисніть кнопку Pull Request, щоб створити запит на об’єднання.

  • Ви будь-коли можете оновити вашу локальну копію кодом із основного сховища такою командою:

    git pull upstream

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

Середовище для розробки у Windows

Примітка

Вам слід також окремо отримати початковий код calibre, як це було описано вище.

Встановіть calibre у звичний спосіб, за допомогою пакунка для встановлення у Windows. Далі, відкрийте вікно командного рядка і перейдіть до отриманої теки з кодом 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. Далі, відкрийте вікно термінала і перейдіть до отриманої теки з кодом 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

Збережіть цей файл як :file`/usr/bin/calibre-develop`. Далі, встановіть права доступу так, щоб його можна було виконувати:

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

Щойно ви це зробите, віддайте команду:

calibre-develop

Ви маєте побачити певну діагностичну інформацію у вікні термінала під час запуску calibre, і ви маєте побачити зірочку після номеру версії у вікні графічного інтерфейсу, що означає, що програму запущено із початкових кодів.

Середовище розробки у Linux

Примітка

Вам слід також окремо отримати початковий код calibre, як це було описано вище.

Основним середовищем розробки calibre є Linux. У вас є два варіанти налаштовування середовища для розробки. Ви можете встановити виконуваний файл calibre у звичний спосіб і скористатися цим інтерактивним середовищем для розробки. Цей підхід подібний до використаного у Windows і macOS. Крім того, ви можете встановити calibre з початкових кодів. Настанови щодо налаштовування середовища для розробки з початкових кодів наведено у файлі INSTALL дерева початкових кодів програми. Тут ми обговоримо використання середовища з бінарними файлами, тобто рекомендованого методу.

Встановіть calibre за допомогою бінарного пакунка для встановлення. Далі, відкрийте вікно термінала і перейдіть до отриманої теки з кодом 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 для вашої справжньої бібліотеки, досягти цього можна за допомогою запуску calibre з файлів .bat або скриптів оболонки. У наведеному нижче прикладі показано, як досягти цього у 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

Цей улюблений спосіб діагностування Ковіда. Просто вставте інструкції print у потрібні вам місця у коді і запустіть програму з термінала. Наприклад, ви можете запустити графічний інтерфейс програми з термінала ось так:

calibre-debug -g

Так само, ви можете запустити засіб для перегляду електронних книг ось так:

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

The e-book editor can be started as:

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

Використання інтерактивного інтерпретатора Python

Ви можете вставити такі два рядки коду, щоб запустити інтерактивний сеанс Python на цьому кроці:

from calibre import ipython
ipython(locals())

Якщо програму запущено з командного рядка, цей код запустити інтерактивний інтерпретатор Python із доступом до усіх локально визначених змінних (змінних у області local). У інтерактивному командному рядку передбачено навіть автоматичне доповнення за натисканням клавіші Tab властивостей об’єктів. Ви також можете скористатися різноманітними можливостями Python для інтроспекції, зокрема dir(), type(), repr() тощо.

Використання засобу діагностики Python як віддалений засіб діагностики

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

from calibre.rpdb import set_trace
set_trace()

Далі, запустіть calibre у звичний спосіб або за допомогою команд calibre-debug, які описано у попередньому розділі. Щойно буде досягнуто визначеної вище точки у коді, роботу calibre буде призупинено, вона очікуватиме на з’єднання із засобом діагностики.

Тепер відкрийте вікно термінала або командний рядок і віддайте таку команду, щоб розпочати сеанс діагностики:

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

Дізнатися більше про те, як користуватися засобом діагностики python, можна за допомогою документації щодо стандартної бібліотеки Python, модуль pdb.

Примітка

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

Примітка

Засіб діагностики Python не може працювати одночасно з декількома потоками виконання, тому вам слід викликати set_trace для кожного потоку, кожного разу на портах із різними номерами.

Використання засобу діагностики у вашому улюбленому комплексному середовищі розробки Python

Можна скористатися вбудованим засобом діагностики у вашому улюбленому комплексному середовищі для розробки, якщо там передбачено віддалену діагностику. Першим кроком є додавання адреси клону src calibre до змінної PYTHONPATH у вашому комплексному середовищі для розробки. Іншими словами, тека, яку ви визначили для змінної CALIBRE_DEVELOP_FROM вище, має також бути серед тек у змінній PYTHONPATH вашого комплексного середовища для розробки.

Далі, розташуйте модуль віддаленого засобу діагностики комплексного середовища розробки у підтеці src клону початкового коду calibre. Додайте код, який потрібен для запуску віддаленого засобу діагностики у код calibre у потрібному вам місці, наприклад у функції main. Далі, запустіть calibre у звичний спосіб. Після цього ваше комплексне середовище розробки має з’єднатися із засобом віддаленої діагностики, запущеним у 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-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.

Документація з програмного інтерфейсу до різноманітних частин calibre