Nastavení vývojového prostředí Calibre

Calibre je celé open source pod licencí GNU GPL v3. To znamená, že můžete volně stáhnout a upravit program podle své libosti. V této části se naučíte, jak nastavit vývojové prostředí Calibre na vámi zvoleném operačním systému. Calibre je napsáno převážně v Pythonu s nějakým kódem C/C++ kvůli rychlosti a systémovému rozhraní. Pamatujte, že Calibre vyžaduje alespoň Python 3.8.

Filozofie návrhu

Calibre má své kořeny ve světě Unixu, což znamená, že jeho design je vysoce modulární. Moduly se navzájem ovlivňují prostřednictvím dobře definovaných rozhraní. To umožňuje velice snadné přidávání nových funkcí a opravování chyb v Calibre, což má za následek zběsilé tempo vývoje. Vzhledem ke svým kořenům má Calibre komplexní rozhraní příkazového řádku pro všechny své funkce, zdokumentované v Rozhraní příkazového řádku.

Modulární návrh Calibre je vyjádřen prostřednictvím Modulů. K dispozici je kurz psaní modulů Calibre . Například přidání podpory pro nové zařízení do Calibre typicky zahrnuje napsání méně než 100 řádků kódu v podobě modulu ovladače zařízení. Vestavěné ovladače můžete procházet. Podobně přidání podpory pro nové formáty převodu zahrnuje napsání modulu vstupně-výstupního formátu. Dalším příkladem modulárního návrhu je systém předpisů pro načítání zpráv. Pro více příkladů modulů navržených pro přidání funkcí do Calibre se podívejte na Rejstřík modulů..

Rozložení kódu

Všechen kód Pythonu Calibre je v balíčku calibre. Tento balíček obsahuje následující hlavní podbalíčky

  • zařízení – Všechny ovladače zařízení. Prohlédněte si některé z vestavěných ovladačů pro získání představy o tom, jak fungují.

    • Pro podrobnosti se podívejte na devices.interface, které definuje rozhraní podporované ovladači zařízení, a devices.usbms, které definuje obecný ovladač, který se připojuje k zařízení USBMS. Všechny ovladače v Calibre založené na USBMS se z něj dědí.

  • e-knihy – Všechen kód převodu a metadat e-knih. Vhodným výchozím bodem je balíček calibre.ebooks.conversion.cli, což je modul poháněný příkazem ebook-convert. Zpracování převodu je řízeno prostřednictvím conversion.plumber. Kód nezávislý na formátu je všechen ebooks.oeb a kód závislý na formátu je v ebooks.format_name.

    • Čtení, zápis a stahování jsou v ebooks.metadata

    • Převod probíhá v řetězci, pro strukturu řetězce se podívejte na Úvod. Řetězec se skládá ze vstupního modulu, různých transformací a výstupního modulu. Kód, který vytvoří a řídí řetězec se nachází v plumber.py. Řetězec funguje na základě zobrazení e-knihy, které je jako rozbalené EPUB, s manifestem, páteří, obsahem, průvodcem, obsahem html atd. Třída, která spravuje toto zobrazení je OEBBook v ``ebooks.oeb.base`. Různé transformace, které jsou použity na knihu během převodu jsou v oeb/transforms/*.py. A vstupní a výstupní moduly jsou v conversion/plugins/*.py.

    • Úprava e-knihy se odehrává pomocí různých objektů kontejneru. To je zdokumentováno v Dokumentace API pro nástroje pro úpravu e-knih.

  • db – Serverová část databáze. Pro rozhraní do knihovny Calibre se podívejte na Dokumentace API pro rozhraní databáze.

  • Server s obsahem: srv je Server s obsahem Calibre.

  • gui2 – Grafické uživatelské rozhraní. Inicializace grafického rozhraní se odehrává v gui2.main a gui2.ui. Prohlížeč e-knih je v gui2.viewer. Editor e-knih je v ``gui2.tweak_book`.

Pokud chcete najít vstupní body pro všechny jednotlivé spustitelné soubory Calibre, podívejte se na strukturu entry_points v linux.py.

Pokud potřebujete pomoct pochopit kód, odešlete příspěvek do vývojářského fóra a s největší pravděpodobností získáte pomoc od jednoho z mnoha vývojářů Calibre.

Získání kódu

Zdrojový kód Calibre můžete získat dvěma způsoby, pomocí systému řízení verzí nebo přímo stažením tarball.

Calibre používá Git, distribuovaný systém řízení verzí. Git je dostupný na všech platformách, které Calibre podporuje. Po nainstalování Gitu, můžete získat zdrojový kód Calibre pomocí příkazu:

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

Na Windows budete potřebovat úplný název cesty, který bude něco jako C:\Program Files\Git\git.exe.

Calibre je velice rozsáhlý projekt s velmi dlouhou historií řízení zdroje, takže výše uvedené může nějakou dobu trvat (10 minut až hodinu v závislosti na vaší rychlosti internetu).

Pokud chcete získat kód rychleji, zdrojový kód pro nejnovější vydanou verzi je vždy dostupný jako archive.

Pro aktualizaci větve na nejnovější kód použijte příkaz:

git pull --no-edit

Také můžete procházet kód na GitHub.

Odesílání vašich změn, které mají být zahrnuty

Pokud plánujete pouze provést několik malých změn, můžete provést změny a vytvořit „direktivu sloučení“, kterou pak můžete připojit k oznámení v přehledu chyb Calibre. Abyste to udělali, proveďte změny, pak spusťte:

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

Tím se vytvoří soubor my-changes v aktuální složce, jednoduše ho připojte k oznámení na přehledu chyb Calibre. Pamatujte, že to bude zahrnovat všechna potvrzení změn, které jste provedli. Pokud chcete odeslat pouze některá potvrzení, musíte změnit výše uvedený origin/master. Pro odeslání pouze posledního potvrzení použijte:

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

Pro odeslání posledních n potvrzení nahraďte 1 pomocí n, například pro poslední 3 potvrzení:

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

Buďte opatrní, abyste nezahrnuli sloučení, když použijete HEAD~n.

Pokud máte v plánu udělat hodně vyvíjet Calibre, pak je nejlepší metodou vytvořit si účet na GitHub. Níže je základní průvodce pro nastavení vaší lastní větve Calibre takovým způsobem, který vám umožní předkládat požadavky o zahrnutí do hlavního úložiště Calibre:

  • Nastavte git ve svém počítači, jak je popsáno v tomto článku: Set Up Git

  • Nastavte klíče ssh pro ověřování na GitHub, jak je popsáno zde: Generating an SSH key

  • Přejděte na https://github.com/kovidgoyal/calibre a klikněte na tlačítko Fork.

  • V terminálu zadejte:

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

    Nahraďte výše uvedené <username> svým uživatelským jménem na GitHub. Tím místně odsouhlasíte svůj fork.

  • Můžete provádět změny a potvrzovat je, kdykoliv budete chtít. Až budete připraveni sloučit svou práci, zadejte:

    git push

    a přejděte na https://github.com/<username>/calibre a klikněte na tlačítko Pull Request pro vygenerování požadavku, který může být sloučen.

  • Svou lokální kopii můžete kdykoliv aktualizovat kódem z hlavního úložiště zadáním:

    git pull upstream

Také byste měli dávat pozor na vývojové fórum Calibre. Před provedením zásadních změn byste měli o nich diskutovat na fóru nebo se přímo obrátit na Kovida (jeho e-mailová adresa je v celém zdrojovém kódu).

Vývojové prostředí Windows

Poznámka

Musíte také získat zdrojový kód Calibre samostatně, jak je popsáno výše.

Nainstalujte normálně Calibre pomocí instalátoru Windows. Pak otevřete příkazový řádek a přejděte do dříve odsouhlasené složky s kódem Calibre. Například:

cd C:\Users\kovid\work\calibre

calibre je složka, která obsahuje podsložky src a resources.

Dalším krokem je nastavení proměnné prostředí CALIBRE_DEVELOP_FROM na absolutní cestu složky src. Takže v návaznosti na výše uvedený příklad by to bylo C:\Users\kovid\work\calibre\src. Zde je krátký průvodce k nastavení proměnných prostředí v systému Windows.

Jakmile nastavíte proměnnou prostředí, otevřete nový příkazový řádek a zkontrolujte, že je správně nastavena pomocí příkazu:

echo %CALIBRE_DEVELOP_FROM%

Nastavení této proměnné prostředí znamená, že Calibre bude nyní načítat všechen svůj kód Pythonu ze zadaného umístění.

A je to! Nyní jste připraveni upravovat kód Calibre. Například otevřete soubor src\calibre\__init__.py ve svém oblíbeném editoru a přidejte řádek:

print("Hello, world!")

na začátek souboru. Nyní spusťte příkaz calibredb. Úplně první řádek výstupu by měl být Hello, world!.

Pokud chcete, můžete také nastavit vývojové prostředí Calibre uvnitř bezplatného programu Microsoft Visual Studio podle pokynů zde.

Vývojové prostředí macOS

Poznámka

Musíte také získat zdrojový kód Calibre samostatně, jak je popsáno výše.

Nainstalujte normálně Calibre pomocí poskytnutého .dmg. Pak otevřete terminál a přejděte do dříve odsouhlasené složky s kódem Calibre, například:

cd /Users/kovid/work/calibre

calibre je složka, která obsahuje podsložky src a resources. Nástroje příkazového řádku Calibre se nacházejí uvnitř balíčku aplikací Calibre, v /Applications/calibre.app/Contents/MacOS byste měli tuto složku přidat do proměnné prostředí PATH, pokud chcete snadno spouštět nástroje příkazového řádku.

Dalším krokem je vytvoření bashový skript, který nastaví proměnnou prostředí CALIBRE_DEVELOP_FROM na absolutní cestu složky src při spuštění Calibre v režimu ladění.

Vytvořte textový soubor:

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

Uložte tento soubor jako /usr/bin/calibre-develop, pak nastavte jeho oprávnění tak, aby mohl být spuštěn:

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

Jakmile toto uděláte, spusťte:

calibre-develop

Měli byste vidět nějaké diagnostické informace v okně terminálu při spuštění Calibre a měli byste vidět hvězdičku za číslem verze v okně grafického rozhraní, která znamená, že spouštíte ze zdrojového kódu.

Vývojové prostředí Linux

Poznámka

Musíte také získat zdrojový kód Calibre samostatně, jak je popsáno výše.

Calibre je vyvíjeno především na Linuxu. Při nastavování vývojového prostředí máte dvě možnosti. Můžete nainstalovat binární kód Calibre jako normálně a použít ho jako běhové prostředí pro váš vývoj. Tento přístup je podobný tomu použitému ve Windows a macOS. Případně můžete nainstalovat Calibre ze zdrojového kódu. Pokyny pro nastavení vývojového prostředí ze zdrojového kódu jsou v souboru INSTALL ve stromu zdrojového kódu. Zde budeme adresovat pomocí binárního kódu jako běhového prostředí, což je doporučená metoda.

Nainstalujte Calibre pomocí instalátoru binárního kódu. Pak otevřete terminál a přejděte do dříve odsouhlasené složky s kódem Calibre, například:

cd /home/kovid/work/calibre

calibre je složka, která obsahuje podsložky src a resources.

Dalším krokem je nastavení proměnné prostředí CALIBRE_DEVELOP_FROM na absolutní cestu složky src. Takže v návaznosti na výše uvedený příklad by to bylo /home/kovid/work/calibre/src. Jak nastavit proměnné prostředí závisí na vaší distribuci Linuxu a jaké prostředí používáte.

Poznámka

Je doporučeno použít binární instalační program poskytovaný z upstreamu. Pokud trváte na použití balíčku poskytovaného vaší distribucí, použijte místo toho proměnné CALIBRE_PYTHON_PATH a CALIBRE_RESOURCES_PATH.

Jakmile nastavíte proměnnou prostředí, otevřete nový terminál a zkontrolujte, že je správně nastavena pomocí příkazu:

echo $CALIBRE_DEVELOP_FROM

Nastavení této proměnné prostředí znamená, že Calibre bude nyní načítat všechen svůj kód Pythonu ze zadaného umístění.

A je to! Nyní jste připraveni upravovat kód Calibre. Například otevřete soubor src/calibre/__init__.py ve svém oblíbeném editoru a přidejte řádek:

print("Hello, world!")

na začátek souboru. Nyní spusťte příkaz calibredb. Úplně první řádek výstupu by měl být Hello, world!.

Mít samostatnou „normální“ a „vývojovou“ instalaci Calibre na stejném počítači

Zdrojový strom Calibre je velice stabilní a zřídka kdy spadne, ale pokud cítíte potřebu spouštět ze zdroje na samostatné zkušební knihovně a spouštět vydanou verzi Calibre se svou každodenní knihovnou, můžete toho snadno dosáhnout pomocí souborů .bat nebo skriptů prostředí pro spuštění Calibre. Níže uvedený příklad ukazuje, jak to provést v systému Windows pomocí souborů .bat (pokyny pro ostatní platformy jsou stejné, stačí použít skript prostředí namísto souboru .bat)

Pro spuštění vydané verze Calibre s vaší každodenní knihovnou:

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"

Tipy k ladění

Python je dynamicky napsaný jazyk s vynikajícím vybavením pro introspekci. Kovid napsal kód jádra Calibre, aniž by jedinkrát použil ladicí program. Existuje mnoho strategií ladění kódu Calibre:

Používání příkazů tisku

Toto je Kovidův oblíbený způsob ladění. Jednoduše vložte příkazy tisku do nejdůležitějších bodů a spusťte program v terminálu. Grafické rozhraní můžete spustit z terminálu například takto:

calibre-debug -g

Podobně můžete spustit Prohlížeč e-knih takto:

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

Editor e-knih může být spuštěn takto:

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

Používání interaktivního překladače Pythonu

Můžete vložit následující dva řádky kódu pro spuštění interaktivní relace Pythonu v tomto bodě:

from calibre import ipython
ipython(locals())

Při spuštění z příkazového řádku toto spustí interaktivní překladač Pythonu s přístupem ke všem místně definovaným proměnným (proměnné v místním rozsahu). Interaktivní výzva má dokonce dokončení Tab pro vlastnosti objektů a můžete použít různé vybavení Pythonu pro introspekci, například dir(), type(), repr(), atd.

Používání ladicího programu Pythonu jako vzdáleného ladicího programu

Můžete použít vestavěný ladicí program Pythonu (pdb) jako vzdálený ladicí program z příkazového řádku. Nejdříve takto spusťte vzdálený ladicí program v místě v kódu Calibre, které vás zajímá:

from calibre.rpdb import set_trace
set_trace()

Pak spusťte Calibre, a to buď jako normálně, nebo pomocí jednoho z ladicích příkazů Calibre popsaných v předchozím oddílu. Jakmile je dosažen výše uvedený bod v kódu, Calibre se zablokuje a počká na připojení ladicího programu.

Nyní otevřete terminálu nebo příkazový řádek a použijte následující příkaz pro spuštění relace ladění:

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

Jak používat ladicí program Pythonu, si můžete přečíst v dokumentaci stdlib Pythonu pro modul pdb.

Poznámka

Ve výchozím nastavení se vzdálený ladicí program pokusí připojit na portu 4444. Můžete jej změnit předáním parametru portu výše uvedeným funkcím set_trace() a cli() takto : set_trace(port=1234) a cli(port=1234).

Poznámka

Ladicí program Pythonu nemůže zpracovat více vláken, takže musíte volat set_trace pro každé vlákno, pokaždé s jiným číslem portu.

Používání ladicího programu ve vašem oblíbeném IDE Pythonu

Je možné použít vestavěný ladicí program ve vašem oblíbeném IDE Pythonu, pokud podporuje vzdálené ladění. Prvním krokem je přidání rezervační složky src Calibre do PYTHONPATH ve vašem IDE. Jinými slovy, složka nastavená výše jako CALIBRE_DEVELOP_FROM, musí být také v PYTHONPATH vašeho IDE.

Pak umístěte modul vzdáleného ladicího programu IDE do podsložky src rezervační složky zdrojového kódu Calibre. Přidejte jakýkoliv potřebný kód pro spuštění vzdáleného ladicího programu do Calibre v důležitém místě, například do hlavní funkce. Pak spusťte Calibre jako normálně. Váš IDE by nyní měl být schopný se připojit ke vzdálenému ladicímu programu běžícímu uvnitř Calibre.

Provádění libovolných skriptů uvnitř prostření Pythonu Calibre

Příkaz calibre-debug poskytuje několik šikovných přepínačů pro provádění vašeho kódu s přístupem k modulům Calibre:

calibre-debug -c "some Python code"

je skvělý pro testování malého fragmentu kódu na příkazovém řádku. Funguje to stejným způsobem jako přepínač -c pro překladač Pythonu:

calibre-debug myscript.py

může být použit ke spuštění vašeho skriptu Python. Funguje to stejným způsobem jako předání skriptu překladači Pythonu, kromě toho, že prostředí Calibre je plně inicializované, takže můžete ve svém skriptu použít celý kód Calibre. Pro použití parametrů příkazového řádku s vaším skriptem použijte formulář:

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

-- způsobí, že všechny následující parametry budou předány do vašeho skriptu.

Používání Calibre ve vašich projektech

Je možné přímo použít funkce nebo kód Calibre ve vašem projektu v Pythonu. Existují dva způsoby, jak to udělat:

Binární instalace Calibre

Pokud máte binární instalaci Calibre, můžete použít překladač Pythonu nainstalovaný s Calibre takto:

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

Zdrojová instalace na Linuxu

Kromě použití výše uvedené techniky, pokud provedete zdrojovou instalaci na Linuxu, můžete také přímo importovat Calibre následujícím způsobem:

import init_calibre
import calibre

print(calibre.__version__)

Je nezbytné, abyste importovali modul init_calibre před jakýmikoliv jinými moduly nebo balíčky Calibre, protože nastavuje překladač ke spuštění kódu Calibre.

Dokumentace API pro různé části Calibre