Mise en place d’un environnement de développement calibre

calibre est complètement open source, sous licence GNU GPL v3. Cela signifie que vous êtes libre de télécharger et de modifier le programme à votre convenance. Dans cette section, vous apprendrez comment obtenir la mise en place d’un environnement de développement calibre sur le système d’exploitation de votre choix. calibre est principalement écrit en Python avec un peu de code C/C++ pour la vitesse et l’interfaçage système. Notez que calibre requiert au moins Python 3.8.

Philosophie de conception

calibre a ses racines dans le monde UNIX, ce qui signifie que sa conception est très modulaire. Les modules interagissent les uns avec les autres par l’intermédiaire d’interfaces bien définies. C’est ce qui rend l’ajout de nouvelles fonctionnalités et la réparation des dysfonctionnements très faciles dans calibre, ayant pour résultat un rythme de développement frénétique. En raison de ses racines,calibre a une interface en ligne de commande complète pour toutes ses fonctions, documentée dans doc:generated/fr/cli-index.

La conception modulaire de calibre est exprimée par l’intermédiaire des Extensions. Il y a un tutoriel sur l’écriture d’extensions calibre. Par exemple, ajouter le support d’un nouveau périphérique à calibre implique typiquement d’écrire moins de 100 lignes de code sous forme d’une extension pilote de périphérique. Vous pouvez parcourir les pilotes intégrés. Similairement, ajouter le support pour de nouveaux formats de conversion implique l’écriture de nouvelles extensions de format entrée/sortie. Un autre exemple de la conception modulaire est le système de recette pour récupérer des actualités. Pour plus d’exemples d’extensions conçues pour ajouter des fonctionnalités à calibre, voir l”Index des extensions.

Disposition du code

Tout le code Python de calibre est dans le paquet calibre. Ce paquet contient les principaux sous-paquets suivants :

  • périphériques - Tous les pilotes de périphériques. Regardez juste certains des pilotes intégrés pour avoir une idée de la façon dont ils fonctionnent.

    • Pour plus de détails, voir : devices.interface qui définit l’interface supportée par les pilotes de périphériques et devices.usbms qui définit un pilote générique qui connecte un périphérique USBMS. Tous les pilotes basés USBMS dans calibre héritent de lui.

  • livres numériques - Tout le code conversion/métadonnées de livre numérique. Un bon point de départ est calibre.ebooks.conversion.cli qui est le module alimentant la commande ebook-convert. Le processus de conversion est contrôlé par l’intermédiaire de conversion.plumber. Le code de format indépendant est entièrement dans ebooks.oeb et le code de format dépendant est dans ebooks.format_name.

    • La lecture, l’écriture et le téléchargement des métadonnées est entièrement dans ebooks.metadata

    • La conversion se produit dans un pipeline, pour la structure du pipeline, voir Introduction. Le pipeline consiste en une extension d’entrée, différentes transformations et une extension de sortie. Le code qui construit et pilote le pipeline est dans plumber.py. Le pipeline fonctionne sur une représentation d’un livre numérique qui est comme un epub décompressé, avec le manifeste, la structure organisationnelle, la TdM, le guide, le contenu html, etc. La classe qui gère cette représentation est OEBBook dans ebooks.oeb.base. Les diverses transformations qui sont appliquées au livre durant la conversion se situent dans oeb/transforms/*.py. Et les extensions d’origines et de sortie se situent dans conversion/plugins/*.py.

    • L’édition de livre numérique se produit en utilisant un objet conteneur différent. Il est documenté dans Documentation API pour l’outil d’édition de livre numérique.

  • db - Le back-end de la base de données. Voir Documentation API pour l’interface base de données pour l’interface à la bibliothèque calibre.

  • Serveur de contenu : srv est le Serveur de contenu calibre.

  • gui2 - L’Interface Graphique Utilisateur. L’initialisation du GUI se produit dans gui2.main et gui2.ui. La visionneuse de livre numérique dans gui2.viewer. L’éditeur de livre numérique dans gui2.tweak_book.

Si vous voulez localiser les points d’entrée de tous les différents exécutables de calibre, regardez à la structure entry_points dans linux.py.

Si vous avez besoin d’aide pour comprendre le code, postez sur le forum de développement et vous obtiendrez très probablement de l’aide de l’un des nombreux développeurs de calibre.

Obtenir le code

Vous pouvez obtenir le code source de calibre de deux manières soit en utilisant un système de contrôle de version soit en téléchargeant directement une tarball.

calibre utilise Git, un système de contrôle de version distribuée. Git est disponible sur toutes les plateformes supportées par calibre. Après avoir installé Git, vous pouvez obtenir le code source de calibre avec la commande:

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

Sous Windows, vous aurez besoin du nom de chemin complet, ce sera quelque chose comme C:\Program Files\Git\git.exe.

calibre est un très grand projet, avec une très longue histoire de contrôle de source, aussi ce qui est décrit plus haut peut prendre un moment (10 minutes à une heure dépendant de la vitesse de votre connexion internet).

Si vous voulez obtenir le code source plus rapidement, le code source de la dernière version est toujours disponible comme archive.

Pour mettre à jour une branche du dernier code, utilisez la commande:

git pull --no-edit

Vous pouvez également parcourir le code sur GitHub.

Soumettre vos changements à inclure

Si vous planifiez de faire quelques petits changements, vous pouvez faire vos changements et crée une « directive de fusion » que vous pouvez alors attacher à un ticket dans le bug tracker de calibre. Pour faire cela, faites vos changements, et exécutez:

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

Cela créera un fichier my-changes dans le dossier actuel, attachez le simplement à un ticket sur le bug tracker de calibre. Notez que ceci inclura toutes les validations effectuées. Si vous voulez seulement envoyer une partie des validations, vous devez changer origin/master ci-dessus. Pour envoyer seulement la dernière validation, employez:

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

Pour envoyer les dernières n validations, remplacer 1 avec n, par exemple, pour les 3 derniers validations:

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

Faites attention à ne pas inclure des fusions en employant HEAD~n.

Si vous planifiez de faire beaucoup de développement sur calibre, alors la meilleure méthode est de créer un compte GitHub. Ci-dessous se trouve un guide basique pour mettre en place votre propre embranchement de calibre d’une manière qui vous permet de soumettre des requêtes de déchargement pour l’inclusion dans le dépôt principal calibre :

  • Installer git sur votre machine comme décrit dans cet article : Installer Git

  • Installez les clés SSH pour l’authentification sur GitHub, comme décrit ici : Generating SSH keys

  • Allez sur https://github.com/kovidgoyal/calibre et cliquez sur le bouton Fork.

  • Dans un Terminal faites:

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

    Remplacez <username> ci-dessus par votre nom d’utilisateur Github. Cela obtiendra que votre embranchement sera vérifié localement.

  • Vous pouvez y faire des changements et des validations chaque fois que vous le désirez. Quand vous êtes prêt à fusionner votre travail, faites un:

    git push

    et rendez vous sur https://github.com/<username>/calibre et cliquez le bouton Pull Request pour générer une requête de déchargement qui peut être fusionnée.

  • Vous pouvez mettre à jour votre copie locale du code depuis le dépôt principal à n’importe quel moment en faisant:

    git pull upstream

Vous devriez aussi garder un oeil sur le forum de développement calibre. Avant de faire des changements majeurs, vous devriez en discuter dans le forum ou contacter directement Kovid (son adresse mail est partout dans le code source).

Environnement de développement Windows

Note

Vous devez aussi récupérer le code source calibre séparément comme décrit plus haut.

Installez calibre normalement, en utilisant l’installateur de Windows. Ouvrez alors une Invite de Commande et changez le dossier calibre précédemment vérifié. Par exemple:

cd C:\Users\kovid\work\calibre

calibre est le dossier qui contient les sous-dossiers src et resources.

L’étape suivante est de régler la variable d’environnement CALIBRE_DEVELOP_FROM au chemin absolu du dossier src. Ainsi, en suivant l’exemple ci-dessus, il devrait être C:\Users\kovid\work\calibre\src. Voici un court guide pour paramétrer les variables d’environnement sous Windows.

Une vois que vous avez réglé la variable d’environnement, ouvrez une nouvelle invite de commande et vérifiez qu’elle est correctement paramétrée en utilisant la commande:

echo %CALIBRE_DEVELOP_FROM%

Paramétrer cette variable d’environnement signifie que calibre chargera maintenant tout son code Python à partir de l’emplacement spécifié.

Voilà. vous êtes maintenant prêt à commencer à bidouiller le code calibre. Par exemple, ouvrez le fichier src\calibre\__init__.py dans votre éditeur préféré et ajoutez la ligne:

print("Hello, world!")

près du dessus du ficher. Exécutez maintenant la commande calibredb. La toute première ligne de production devrait être Hello, world!.

Vous pouvez également mettre en place l’environnement de développement dans le Microsoft Visual Studion libre, si vous préférez, suivre les instructions ici.

Environnement de développement macOS

Note

Vous devez aussi récupérer le code source calibre séparément comme décrit plus haut.

Installez calibre normalement en utilisant les .dmg mis à disposition. Ouvrez alors un Terminal et changez pour le dossier de code précédemment vérifié, par exemple:

cd /Users/kovid/work/calibre

calibre est le dossier qui contient les sous-dossiers src et resources. Les outils en ligne de commande calibre se trouvent à l’intérieur du paquet d’applications calibre, dans /Applications/calibre.app/Contents/MacOS vous devez ajouter ce dossier à votre variable d’environnement PATH, si vous voulez exécuter facilement les outils en ligne de commande.

L’étape suivante est de créer un script bash qui paramétrera les variables d’environnement CALIBRE_DEVELOP_FROM` au chemin absolu du dossier src lors de l’exécution de calibre en mode dépannage.

Créez un fichier texte brut:

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

Sauvegardez le fichier comme /usr/bin/calibre-develop, paramétrer alors ses permissions afin qu’il puisse être exécuté

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

Une fois que vous avez fait cela, exécuter :

calibre-develop

Vous devriez voir quelques informations diagnostiques dans la fenêtre Terminal au démarrage de calibre, et vous devriez voir une astérisque après le numéro de version dans la fenêtre GUI, indiquant que vous exécutez depuis la source.

Environnement de développement Linux

Note

Vous devez aussi récupérer le code source calibre séparément comme décrit plus haut.

calibre est principalement développé sous Linux. Vous avez deux choix pour paramétrer l’environnement de développement. Vous pouvez installer le binaire calibre comme à la normale et l’employer comme environnement d’exécution pour faire votre développement. Cette approche est similaire à celle utilisée dans Windows et macOS. Alternativement, vous pouvez installer calibre depuis la source. Les instructions pour installer un environnement de développement depuis la source sont dans le fichier INSTALL dans l’arborescence de source. Ici nous nous adresserons en utilisant le binaire d’exécution, qui est la méthode recommandée.

Installer calibre en utilisant l’installateur binaire. Ouvrez alors un terminal et changez le dossier du code calibre précédemment vérifié, par exemple:

cd /home/kovid/work/calibre

calibre est le dossier qui contient les sous-dossiers src et resources.

L’étape suivante est de créer un script bash qui paramétrera les variables d’environnement CALIBRE_DEVELOP_FROM au chemin absolu du dossier src. Aussi, en suivant l’exemple ci-dessus, il devrait être /home/kovid/work/calibre/src. Comment paramétrer les variables d’environnement dépend de votre distribution Linux et de quel shell vous utilisez.

Note

Il est recommandé d’utiliser l’installeur binaire fourni en amont. Si vous insistez pour utiliser un paquet fourni par votre distribution, utilisez plutôt les variables CALIBRE_PYTHON_PATH et CALIBRE_RESOURCES_PATH.

Une fois que vous avez paramétré la variable d’environnement, ouvrez un nouveau terminal et vérifiez qu’elle a été correctement paramétrée en utilisant la commande:

echo $CALIBRE_DEVELOP_FROM

Paramétrer cette variable d’environnement signifie que calibre chargera maintenant tout son code Python à partir de l’emplacement spécifié.

Voilà ! Vous êtes maintenant prêt à commencer à bidouiller le code calibre. Par exemple, ouvrez le fichier src\calibre\__init__.py dans votre éditeur préféré et ajoutez la ligne:

print("Hello, world!")

près du dessus du ficher. Exécutez maintenant la commande calibredb. La toute première ligne de production devrait être Hello, world!.

Avoir des installations séparées de calibre « normale » et « développement » sur le même ordinateur

L’arborescence de source calibre est très stable et se rompt rarement, mais si vous sentez la nécessité d’exécuter depuis la source sur une bibliothèque distincte d’essai et de d’exécuter une version libre de calibre avec votre bibliothèque quotidienne, vous pouvez réaliser ceci facilement en utilisant des fichiers .bat ou des scripts shell pour lancer calibre. L’exemple ci-dessous expose comment faire ceci sur Windows utilisant des fichiers .bat (les instructions pour d’autres plates-formes sont identiques, employez juste un script shell au lieu d’un fichier .bat)

Pour lancer la nouvelle version de calibre avec votre bibliothèque quotidienne :

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"

Astuces de dépannage

Python est un langage opérant sur des objets de types déterminés dynamiquement avec d’excellents équipements pour l’introspection. Kovid a écrit le noyau du code calibre sans utiliser une fois un débogueur. Il y a beaucoup de stratégies pour corriger le code calibre :

En utilisant les déclarations d’impression

C’est la manière favorite de Kovid pour dépanner. Insérez simplement des déclarations d’impression aux points d’intérêt et exécuter votre programme dans le terminal. Par exemple : vous pouvez démarrer le GUI à partir du terminal comme:

calibre-debug -g

Similairement, vous pouvez démarrer la visionneuse de livre numérique comme

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

Utilisation d’un interpréte Python interactif

Vous pouvez insérer les deux lignes de code suivantes pour démarrer la session interactive Python à cet endroit:

from calibre import ipython
ipython(locals())

Lors de l’exécution à partir de la ligne de commande, cela démarrera l’interpréteur python interactif avec accès à toutes les variables définies localement (variables dans la portée locale). L’invite interactive a même une complétion Tab pour les propriétés d’objet et vous pouvez utiliser les diverses facilités Python pour l’introspection, telles que dir(), type(), repr(), etc.

Utiliser le débogueur de Python comme débogueur à distance

Vous pouvez utiliser le débogueur intégré de Python (pdb) comme débogueur à distance en ligne de commande. D’abord, démarrez le débogueur à distance au point qui vous intéresse dans le code de calibre, comme ceci:

from calibre.rpdb import set_trace
set_trace()

Exécuter alors calibre, soit comme normal, ou en utilisant une des commandes calibre-debug décrite dans la section précédente. Une fois le point ci-dessus atteint dans le code, calibre gèlera, attendant le débogueur pour se connecter.

Ouvrez maintenant un terminal ou une invite de commande et utilisez la commande suivante pour démarrer la session de débogage:

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

Vous pouvez lire à propos de comment utiliser le débogueur Python dans Python stdlib docs for the pdb module.

Note

Par défaut, le débogueur à distance essaiera de se connecter sur le port 4444. Vous pouvez le changer, en modifiant le paramètre de port des fonctions set_trace() et cli() ci-dessus, comme ceci : set_trace(port=1234) et cli(port=1234).

Note

Le débogueur de Python ne peut pas manipuler des fils multiples, aussi vous devez appeler le set_trace une fois par fil, chaque fois avec un numéro de port différent.

Utiliser le débogueur dans votre IDE Python préféré

Il est possible d’utiliser le débogueur intégré dans votre IDE Python préféré, s’il supporte le débogage à distance. La première étape est d’ajouter la src vérifiée calibre au PYTHONPATH dans votre IDE. En d’autres mots, le dossier que vous avec paramétré plus haut comme CALIBRE_DEVELOP_FROM, doit aussi être dans le PYTHONPATH de votre IDE.

Placez alors me module IDE de débogage à distance dans le sous-dossier src du code source vérifié calibre. Ajoutez ni’importe quel nécessaire pour lancer le débogueur à distance sur calibre au point d’intérêt, par exemple dans la fonction principale. Exécutez alors calibre comme normalement. Votre IDE devrait être capable de se connecter au débogueur à distance s’exécutant dans calibre.

Exécuter des scripts quelconques dans l’environnement Python calibre

La commande calibre-debug fournit quelques commutateurs pratiques pour exécuter votre propre code, avec l’accès aux modules calibre:

calibre-debug -c "some Python code"

est bien pour examiner un petit extrait de code sur la ligne de commande. Cela fonctionne de la même manière que le commutateur -c de l’interpréteur Python:

calibre-debug myscript.py

peut être employé pour exécuter votre propre script python. Cela fonctionne de la même manière que de passer le script à l’interpréteur python, sauf que l’environnement de calibre est entièrement initialisé, ainsi vous pouvez employer tout le code de calibre dans votre script. Pour employer les arguments en ligne de commande avec votre script, utilisez la forme:

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

-- entraîne tous les arguments suivants d’être passés à votre script.

Utilisation de calibre dans vos projets

Il est possible d’utiliser d’utiliser les fonctions/code calibre dans votre projet Python. Deux manières existent pour faire cela :

Installation binaire de calibre

Si vous avez une installation binaire de calibre, vous pouvez utiliser l’interpréteur python empaqueté avec calibre, comme ceci:

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

Installez les sources sur Linux

En complément de l’utilisation de la technique ci-dessus, si vos faites une installation des sources sur Linux, vous pouvez aussi importer directement calibre, comme suit:

import init_calibre
import calibre

print(calibre.__version__)

Il est essentiel que vous importiez le module init_calibre avant tout autre modules/package calibre comme il a installé l’interpréteur pour exécuter le code calibre.

Documentation API pour différentes parties de calibre