Configurar un entorno de desarrollo de calibre

calibre es código completamente abierto, licenciado bajo la GNU GPL v3. Esto significa que cualquiera es libre de descargar y modificar el programa a su gusto. En esta sección, se mostrará cómo configurar un entorno de desarrollo de calibre en el sistema operativo de su elección. calibre está escrito principalmente en Python, con algo de código C/C++ para mejorar la velocidad y la interfaz con el sistema. Tenga en cuenta que calibre requiere al menos Python 3.8.

Filosofía del diseño

calibre tiene sus raíces en el mundo Unix, lo que significa que su diseño es altamente modular. Los módulos interactúan entre sí a través de interfaces bien definidas. Esto hace que la añadir nuevas característicasy corregir errores en calibre sea muy fácil, lo que resulta en un ritmo frenético de desarrollo. Debido a sus raíces, calibre tiene una interfaz completa de línea de órdenes para todas sus funciones, documentadas en Interfaz de línea de órdenes.

El diseño modular de calibre se manifiesta en los «complementos». Hay un cursillo sobre cómo escribir complementos para calibre. Por ejemplo, agregar soporte para un nuevo dispositivo en calibre implica escribir menos de 100 líneas de código en la forma de un complemento de controlador de dispositivo. Puede examinar los controladores predefinidos. Del mismo modo, agregar soporte para nuevos conversores de formato implica escribir complementos de formato de entrada o salida. Otro ejemplo de la construcción modular es el sistema de fórmulas para la obtención de noticias. Para más ejemplos de complementos diseñados para agregar funciones a calibre, consulte el índice de complementos (en inglés).

Estructura del código

Todo el código Python de calibre está en el paquete calibre. Este paquete contiene los siguientes subpaquetes principales

  • devices - Todos los controladores de dispositivos. Examite alguno de los controladores predefinidos para hacerse una idea de cómo funcionan.

    • Para obtener más información, consulte: devices.interface que define la interfaz soportada por los controladores de dispositivos y devices.usbms que define un controlador genérico que se conecta a un dispositivo USBMS. Todos los controladores de dispositivos basados en USBMS ​​en calibre descienden de él.

  • ebooks - Todo el código de conversión y metadatos de libros electrónicos. Un buen punto de partida es calibre.ebooks.conversion.cli que es el módulo que realiza las funciones de la orden ebook-convert. El proceso de conversión se controla mediante conversion.plumber. El código independiente de formato está todo en ebooks.oeb y el código dependiente de formato está ebooks.format_name.

    • La lectura, escritura y descarga de metadatos están en ebooks.metadata

    • La conversión tiene lugar en diferentes etapas, para ver la estructura de estas etapas vea conversión-introduction. Las etapas consisten en un complemento de entrada, diversas transformaciones y un complemento de salida. El código que controla las etapas está en plumber.py. La sucesión de etapas trabaja sobre una representación del libro electrónico que es como un epub descomprimido, con manifiesto, lomo, índice, guía, contenidos html, etc. La clase que maneja esta representación es OEBBook en ebooks.oeb.base. Las diversas transformaciones que se aplican al libro durante las conversiones están en oeb/transforms/*.py. Los complementos de entrada y salida están en conversion/plugins/*.py.

    • La modificación de libros electrónicos se realiza mediante un objeto contenedor diferente. Está documentado en Documentación de la API para las herramientas de modificación de libros electrónicos.

  • db - El motor de base de datos. Vea Documentación de la API para la interfaz de la base de datos para más información sobre la interfaz de la biblioteca de calibre.

  • servidor de contenido: srv es el servidor de contenido de calibre.

  • gui2 - La interfaz gráfica de usuario (GUI). La inicialización de la GUI ocurre en gui2.main y gui2.ui. El visor de libros electrónicos está en gui2.viewer. El editor de libros electrónicos está en gui2.tweak_book.

Si desea localizar los puntos de entrada de todos los ejecutables de calibre, vea la estructura entry_points en linux.py.

Si necesita ayuda para entender el código, escriba en el foro de desarrollo https://www.mobileread.com/forums/forumdisplay.php?f=240 y probablemente obtendrá ayuda de uno de los muchos desarrolladores de calibre.

Obtener el código

Puede obtener el código fuente de calibre de dos maneras, usando un sistema de control de versiones o descargando directamente un :website_base:`tarball <dist/src>`_.

calibre utiliza Git, un sistema de control de versiones distribuido. Git está disponible en todas las plataformas que soporta calibre. Una vez instalado Git, puede obtener el código fuente de calibre con la orden:

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

En Windows necesitará la ruta completa, que será algo así como C:\Archivos de programa\Git\git.exe.

calibre es un gran proyecto con un extenso historial de control de código fuente, asi que esto puede tomar un tiempo (de 10 minutos a una hora, dependiendo de la velocidad de la conexión a Internet).

Si quiere obtener el código más rápidamente, el código fuente de la última versión está siempre disponible como un :website_base:`archivo <dist/src>`_.

Para actualizar el código de una rama a su versión más reciente, use la orden:

git pull --no-edit

También puede explorar el código en GitHub.

Enviar cambios para que se incluyan

Si sólo va a hacer algunos pequeños cambios, puede hacer los cambios y crear una «directiva de fusión» que luego puede adjuntar a un informe en el registro de errores. Para ello, realice los cambios y después ejecute:

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

Esto creará un archivo my-changes en la carpeta actual, simplemente adjúntelo a un informe en el registro de errores. Tenga en cuenta que esto incluirá todos los cambios que haya realizado. Si sólo desea enviar algunos cambios, tendrá que sustituir el origin/master anterior. Para enviar sólo el último cambio, use:

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

Para enviar los últimos n cambios, sustituya 1 por n, por ejemplo, para los últimos 3 cambios:

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

Tenga cuidado de no incluir uniones cuando use HEAD~n.

Si planea realizar mucho desarrollo en calibre, el mejor método es crear una cuenta en GitHub. A continuación se muestra una guía básica para la creación de su propia derivación de calibre, de manera que le permitirá presentar una solicitud de colaboración para que se incluya en el repositorio principal de calibre:

  • Configure git en el equipo como se describe en este artículo: Setup Git (en inglés)

  • Configure las claves SSH para la autenticación con GitHub, como se describe aquí: Generating SSH keys (en inglés)

  • Vaya a https://github.com/kovidgoyal/calibre y pulse en el botón Fork.

  • En una terminal escriba:

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

    Sustituya el <username> de arriba por su nombre de usuario en GitHub. Esto hará que la derivación se actualice localmente.

  • Puede hacer cambios y fijarlos siempre que lo desee. Cuando esté listo para que su trabajo se una con el repositorio principal, escriba:

    git push

    y vaya a https://github.com/<username>/calibre, pulse en el botón Pull Request para generar una solicitud de contribución que pueda ser incluida.

  • Puede actualizar la copia local con código del repositorio principal en cualquier momento haciendo:

    git pull upstream

También debe mantener un ojo en el foro de desarrollo de calibre. Antes de hacer cambios importantes, discútalos en el foro o contacte directamente con Kovid (su dirección de correo electrónico está por todo el código fuente).

Entorno de desarrollo en Windows

Nota

También debe obtener el código fuente de calibre por separado como se describe anteriormente.

Instale calibre normalmente, usando el instalador de Windows. A continuación, abra un símbolo del sistema y vaya a la carpeta del código de calibre previamente descargado. Por ejemplo:

cd C:\Users\kovid\work\calibre

calibre es la carpeta que contiene las subcarpetas src y resources.

El siguiente paso es establecer la variable de entorno CALIBRE_DEVELOP_FROM a la ruta absoluta de la carpeta src. Siguiendo el ejemplo anterior, sería C:\Users\Kovid\work\calibre\src. He aquí una breve guía (en inglés) para establecer variables de entorno en Windows.

Una vez que haya establecido la variable de entorno, abra un nuevo símbolo del sistema y compruebe que se estableció correctamente utilizando la orden:

echo %CALIBRE_DEVELOP_FROM%

Al establecer esta variable de entorno, calibre cargará todo su código Python desde la ubicación especificada.

¡Eso es todo! Ya está listo para comenzar a modificar el código de calibre. Por ejemplo, abra el archivo src\calibre\__init__.py en su editor favorito y añada la línea:

print("Hello, world!")

cerca del inicio del archivo. Ahora ejecute la orden calibredb. La primera línea de salida deberá ser Hello, world!.

También puede configurar un entorno de desarrollo de calibre dentro de Microsoft Visual Studio, si lo desea, siguiendo estas instrucciones (en inglés).

Entorno de desarrollo macOS

Nota

También debe obtener el código fuente de calibre por separado como se describe anteriormente.

Instale calibre normalmente, usando el archivo .dmg suministrado. A continuación, abra una Terminal y vaya a la carpeta del código de calibre previamente descargado, por ejemplo:

cd /Users/kovid/work/calibre

calibre es la carpeta que contiene las subcarpetas src y resources. Las herramientas de líneas de órdenes de calibre se encuentran en el paquete de la aplicación calibre, en /Applications/calibre.app/Contents/MacOS; debe añadir esta carpeta a la variable de entorno PATH si desea ejecutar estas herramientas cómodamente.

El siguiente paso es crear un script bash que establezca la variable de entorno CALIBRE_DEVELOP_FROM a la ruta absoluta de la carpeta src cuando ejecute calibre en modo de depuración.

Cree un archivo de texto sencillo:

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

Guarde este archivo como /usr/local/bin/calibre-develop, después configure los permisos para poder ejecutarlo:

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

Una vez hecho esto, ejecute:

calibre-develop

Debería aparecerer alguna información de diagnóstico en la ventana de la terminal mientras calibre se inicia, y debería ver un asterisco después del número de versión en la ventana de la interfaz gráfica, lo que indica que se está ejecutando desde el código fuente.

Entorno de desarrollo Linux

Nota

También debe obtener el código fuente de calibre por separado como se describe anteriormente.

calibre está desarrollado principalmente en Linux. Tiene dos opciones para configurar el entorno de desarrollo. Puede instalar el binario de calibre de modo normal y usarlo como un entorno de ejecución para realizar su desarrollo. Este enfoque es similar al que se utiliza en Windows y macOS. Como alternativa, puede instalar calibre a partir del código fuente. Las instrucciones para configurar un entorno de desarrollo a partir del código fuente están en el archivo INSTALL en el árbol de origen. Aquí vamos a tratar el archivo binario como un entorno de ejecución, que es el método recomendado.

Instale calibre, usando el instalador binario. A continuación, abra una terminal y vaya a la carpeta del código de calibre previamente descargado, por ejemplo:

cd /home/kovid/work/calibre

calibre es la carpeta que contiene las subcarpetas src y resources.

El siguiente paso es establecer la variable de entorno CALIBRE_DEVELOP_FROM a la ruta absoluta de la carpeta src. Siguiendo el ejemplo anterior, sería /home/kovid/work/calibre/src. La manera de establecer variables de entorno depende de la distribución de Linux y la shell que esté utilizando.

Nota

Se recomienda usar el instalador binario suministrado en el repositorio oficial. Si insiste en usar un paquete provisto por su distribución, use las variables CALIBRE_PYTHON_PATH y CALIBRE_RESOURCES_PATH.

Una vez que haya establecido la variable de entorno, abra una nueva sesión de terminal y compruebe que se ha establecido correctamente usando esta orden:

echo $CALIBRE_DEVELOP_FROM

Al establecer esta variable de entorno, calibre cargará todo su código Python desde la ubicación especificada.

¡Eso es todo! Ya está listo para empezar a modificar el código de calibre. Por ejemplo, abra el archivo src/calibre/__init__.py en su editor favorito y añada la línea:

print("Hello, world!")

cerca del inicio del archivo. Ahora ejecute la orden calibredb. La primera línea de salida deberá ser Hello, world!.

Mantener una instalación «normal» y otra de «desarrollo» de calibre en el mismo equipo

El árbol del código fuente de calibre es muy estable y rara vez se rompe, pero si siente la necesidad de ejecutar a partir del código fuente en una biblioteca de prueba separada y ejecutar la versión oficial de calibre en la biblioteca habitual, puede lograr esto fácilmente usando archivos .bat o scripts de shell para ejectuar calibre. El siguiente ejemplo muestra cómo hacer esto en Windows utilizando archivos .bat (las instrucciones para otras plataformas son las mismas, sólo tiene que utilizar un script de shell en lugar de un archivo .bat)

Para ejecutar la versión oficial de calibre con la biblioteca habitual:

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"

Consejos de depuración

Python es un lenguaje de programación dinámico con excelentes prestaciones para la introspección. Kovid escribió el código central de calibre sin siquiera utilizar un depurador. Hay varias estrategias para depurar el código de calibre:

Usar sentencias de impresión

Ésta es la forma favorita de Kovid para depurar. Basta con insertar sentencias de impresión en los puntos de interés y ejecutar el programa en la terminal. Por ejemplo, puede iniciar la interfaz gráfica desde la terminal como:

calibre-debug -g

Del mismo modo, se puede iniciar el visor de libros electrónicos como:

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

El editor de libros electrónicos puede iniciarse como:

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

Usar un intérprete de Python interactivo

Puede insertar las siguientes dos líneas de código para iniciar una sesión interactiva de Python en ese punto:

from calibre import ipython
ipython(locals())

Cuando se ejecuta desde la línea de órdenes, esto iniciará un intérprete interactivo de Python con acceso a todas las variables definidas localmente (variables en el ámbito local). El modo interactivo puede incluso completar con Tab las propiedades de objetos y puede utilizar las diversas funciones de Python para la introspección, como dir(), type(), repr(), etc.

Usar el depurador de Python como un depurador remoto

Puede utilizar el depurador incorporado de Python (pdb) como un depurador remoto desde la línea de órdenes. En primer lugar, inicie el depurador remoto en el punto del código de calibre en el que esté interesado, de esta forma:

from calibre.rpdb import set_trace
set_trace()

A continuación ejecute calibre, ya sea en modo normal o usando una de las órdenes de depuración de calibre descritas en la sección anterior. Una vez que se alcanza el punto del código anterior, calibre se detendrá, esperando a que se conecte el depurador.

Ahora abra una terminal o un símbolo de sistema y utilice el siguiente comando para iniciar la sesión de depuración:

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

Puede leer acerca de cómo usar el depurador de Python en la documentación de stdlib de Python para el módulo pdb.

Nota

De forma predeterminada, el depurador remoto intentará conectarse con el puerto 4444. Puede cambiarlo, pasando el parámetro de puerto tanto a la función set_trace() como a cli(), de este modo: set_trace(port=1234) y cli(port=1234).

Nota

El depurador de Python no puede manejar múltiples hilos, así que tiene que llamar set_trace una vez por hilo, cada vez con un número de puerto diferente.

Usar el depurador en su IDE de Python favorito

Es posible utilizar el depurador incorporado en su IDE de Python favorito, si éste admite depuración remota. El primer paso es añadir la el src de calibre descargado a PYTHONPATH en el IDE. En otras palabras, la carpeta que habilitó como CALIBRE_DEVELOP_FROM anteriormente también debe estar en el PYTHONPATH del IDE`.

A continuación coloque el módulo depurador remoto del IDE en la subcarpeta src del código fuente de calibre. Añada cualquier código que necesite para iniciar el depurador remoto en calibre en el punto de interés, por ejemplo, en la función main. A continuación, ejecute calibre de modo normal. El IDE ahora debería ser capaz de conectar con el depurador remoto ejecutándose dentro de calibre.

Ejecutar scripts arbitrarios en el entorno Python de calibre

La orden calibre-debug suministra un par de interruptores útiles para ejecutar su propio código, con acceso a los módulos de calibre:

calibre-debug -c "some Python code"

es ideal para probar un pequeño fragmento de código en la línea de órdenes. Funciona de la misma manera que la opción -c del intérprete de Python:

calibre-debug myscript.py

puede utilizarse para ejecutar su propio script de Python. Funciona de la misma manera que pasar el script por el intérprete de Python, excepto que el entorno de calibre está totalmente inicializado, así que puede utilizar todo el código de calibre en el script. Para utilizar argumentos de línea de órdenes con los scripts utilice la forma:

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

El -- hace que todos los argumentos posteriores sean pasados al script.

Usar calibre en sus proyectos

Es posible usar directamente las funciones y código de calibre en un proyecto de Python. Existen dos maneras de hacer esto:

Instalación binaria de calibre

Si posee una instalación binaria de calibre, puede utilizar el intérprete de Python incluido con calibre, de esta forma:

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

Instalación de código fuente sobre Linux

Además de usar la técnica anterior, si realiza una instalación de código fuente en Linux, también puede importar directamente calibre de la siguiente manera:

import init_calibre
import calibre

print(calibre.__version__)

Es esencial que importe el módulo init_calibre antes que cualquier otro módulo o paquete de calibre, pues esto configura el intérprete para ejecutar el código de calibre.

Documentación de la API de varias partes de calibre