Escribir sus propios complementos para extender la funcionalidad de calibre¶

calibre tiene un diseño muy modular. Casi todas las funciones de calibre vienen en forma de complementos. Los complementos se utilizan para la conversión, para la descarga de noticias (aunque éstos se llaman fórmulas), para diversos componentes de la interfaz de usuario, para conectarse a diferentes dispositivos, para procesar archivos cuando se añaden a calibre, etcétera. Puede obtener una lista completa de todos los complementos integrados en calibre en Preferencias > Avanzado > Complementos.

Aquí le enseñaremos como crear sus propios complementos para agregar funciones a calibre.

Nota

Esto sólo se aplica a versiones calibre >= 0.8.60

Anatomía de un complemento de calibre ¶

Un complemento de calibre es muy sencillo, no es más que un archivo ZIP que contiene algo de código Python y otros recursos, como archivos de imagen, que necesite el complemento. Sin más preámbulos, vamos a ver un ejemplo básico.

Supongamos que está usando una instalación de calibre publicar sus propios documentos electrónicos en formatos EPUB y MOBI. Le gustaría que todos los archivos generados por calibre establecieran la editorial como «Hello World», he aquí cómo hacerlo. Cree un archivo llamado __init __.py (éste es un nombre especial y siempre debe ser el del archivo principal del complemento) e introduzca el siguiente código Python en él:

from calibre.customize import FileTypePlugin


class HelloWorld(FileTypePlugin):

    name                = 'Hello World Plugin' # Name of the plugin
    description         = 'Set the publisher to Hello World for all new conversions'
    supported_platforms = ['windows', 'osx', 'linux'] # Platforms this plugin will run on
    author              = 'Acme Inc.' # The author of this plugin
    version             = (1, 0, 0)   # The version number of this plugin
    file_types          = {'epub', 'mobi'} # The file types that this plugin will be applied to
    on_postprocess      = True # Run this plugin after conversion is complete
    minimum_calibre_version = (0, 7, 53)

    def run(self, path_to_ebook):
        from calibre.ebooks.metadata.meta import get_metadata, set_metadata
        with open(path_to_ebook, 'r+b') as file:
            ext  = os.path.splitext(path_to_ebook)[-1][1:].lower()
            mi = get_metadata(file, ext)
            mi.publisher = 'Hello World'
            set_metadata(file, mi, ext)
        return path_to_ebook

Eso es todo. Para agregar este código a calibre como un complemento, simplemente ejecute lo siguiente en la carpeta donde reside el archivo __init__.py:

calibre-customize -b .

Nota

En macOS, las herramientas de línea de órdenes están dentro del paquete calibre, por ejemplo, si ha instalado calibre en /Aplicaciones las herramientas de línea de órdenes están en :file:/Aplicaciones/calibre.app/Contents/MacOS/`.

Puede descargar el complemento Hello World de helloworld_plugin.zip.

Cada vez que utilice calibre para convertir un libro, el método run() del complemento se ejecutará y el libro convertido tendrá como editorial predeterminada «Hello World». Éste es un complemento intranscendente, veamos un ejemplo más complejo que agrega un componente a la interfaz de usuario.

Un complemento de interfaz de usuario ¶

Este complemento ocupará unos pocos archivos (para mantener el código más limpio). Le mostrará cómo obtener recursos (imágenes o archivos de datos) desde el archivo ZIP del complemento, cómo permitir a los usuarios configurar el complemento, cómo crear elementos en la interfaz de usuario de calibre y cómo acceder y consultar la base de datos de libros de calibre.

Puede descargar este complemento de interface_demo_plugin.zip

Lo primero que hay que tener en cuenta es que este archivo ZIP tiene muchos más archivos en su interior, explicados a continuación, preste especial atención a plugin-import-name-interface_demo.txt.

plugin-import-name-interface_demo.txt
Un archivo de texto vacío utilizado para activar la gestión de múltiples archivos en el complemento. Este archivo debe estar presente en todos los complementos que utilicen más de un archivo .py. Debe quedar vacío y su nombre debe ser de la forma: plugin-import-name-**some_name**.txt. La presencia de este archivo le permite importar código de los archivos .py presentes dentro del archivo ZIP, usando una sentencia como ésta:
from calibre_plugins.some_name.some_module import some_object
El prefijo calibre_plugins siempre debe estar presente. some_name proviene del nombre del archivo de texto vacío. some_module se refiere al archivo some_module.py dentro del archivo ZIP. Tenga en cuenta que esta importación es tan potente como las importaciones normales en Python. Puede crear paquetes y subpaquetes de módulos .py dentro del archivo ZIP, igual que lo haría normalmente (definiendo __init__.py en cada subcarpeta), y todo «debería funcionar».

El nombre que utilice para some_name entra en un espacio global de nombres compartido por todos los complementos, así que hágalo tan único como sea posible. Pero recuerde que debe ser un identificador Python válido (sólo letras, números y guión bajo).
__init__.py
Como antes, el archivo que define la clase del complemento

main.py
Este archivo contiene el código real que realiza alguna operación útil

ui.py
Este archivo define la interfaz del complemento

images/icon.png
El icono para este complemento

about.txt
Un archivo de texto con información acerca de este complemento

translations
Una carpeta que contiene archivos .mo con las traducciones de la interfaz de usuario del complemento a diferentes idiomas. Ver más adelante para más detalles.

Ahora veamos el código.

init.py ¶

Primero, el __init__.py obligatorio para definir los metadatos del complemento:

from calibre.customize import InterfaceActionBase


class InterfacePluginDemo(InterfaceActionBase):
    '''
    This class is a simple wrapper that provides information about the actual
    plugin class. The actual interface plugin class is called InterfacePlugin
    and is defined in the ui.py file, as specified in the actual_plugin field
    below.

    The reason for having two classes is that it allows the command line
    calibre utilities to run without needing to load the GUI libraries.
    '''
    name                = 'Interface Plugin Demo'
    description         = 'An advanced plugin demo'
    supported_platforms = ['windows', 'osx', 'linux']
    author              = 'Kovid Goyal'
    version             = (1, 0, 0)
    minimum_calibre_version = (0, 7, 53)

    #: This field defines the GUI plugin class that contains all the code
    #: that actually does something. Its format is module_path:class_name
    #: The specified class must be defined in the specified module.
    actual_plugin       = 'calibre_plugins.interface_demo.ui:InterfacePlugin'

    def is_customizable(self):
        '''
        This method must return True to enable customization via
        Preferences->Plugins
        '''
        return True

    def config_widget(self):
        '''
        Implement this method and :meth:`save_settings` in your plugin to
        use a custom configuration dialog.

        This method, if implemented, must return a QWidget. The widget can have
        an optional method validate() that takes no arguments and is called
        immediately after the user clicks OK. Changes are applied if and only
        if the method returns True.

        If for some reason you cannot perform the configuration at this time,
        return a tuple of two strings (message, details), these will be
        displayed as a warning dialog to the user and the process will be
        aborted.

        The base class implementation of this method raises NotImplementedError
        so by default no user configuration is possible.
        '''
        # It is important to put this import statement here rather than at the
        # top of the module as importing the config class will also cause the
        # GUI libraries to be loaded, which we do not want when using calibre
        # from the command line
        from calibre_plugins.interface_demo.config import ConfigWidget
        return ConfigWidget()

    def save_settings(self, config_widget):
        '''
        Save the settings specified by the user with config_widget.

        :param config_widget: The widget returned by :meth:`config_widget`.
        '''
        config_widget.save_settings()

        # Apply the changes
        ac = self.actual_plugin_
        if ac is not None:
            ac.apply_settings()

La única característica notable es el campo actual_plugin. Puesto que calibre posee tanto una interfaz gráfica como de línea de órdenes, los complementos con interfaz gráfica como éste no cargan ninguna biblioteca gráfica en __init__.py. El campo actual_plugin se encargad de esto, informando a calibre de que el complemento real se encuentra en otro archivo dentro del archivo ZIP, que sólo se cargará en un contexto de interfaz gráfica.

Recuerde que para que esto funcione, debe tener un archivo plugin-import-name-some_name.txt en el archivo ZIP del complemento, como se discutió anteriormente.

También hay un par de métodos para permitir la configuración por parte del usuario del complemento. Éstos se discuten más adelante.

ui.py ¶

Veamos ahora ui.py, que define la interfaz gráfica del complemento. El código fuente está explícitamente comentado y se explica por sí mismo:

from calibre.gui2.actions import InterfaceAction
from calibre_plugins.interface_demo.main import DemoDialog


class InterfacePlugin(InterfaceAction):

    name = 'Interface Plugin Demo'

    # Declare the main action associated with this plugin
    # The keyboard shortcut can be None if you dont want to use a keyboard
    # shortcut. Remember that currently calibre has no central management for
    # keyboard shortcuts, so try to use an unusual/unused shortcut.
    action_spec = ('Interface Plugin Demo', None,
            'Run the Interface Plugin Demo', 'Ctrl+Shift+F1')

    def genesis(self):
        # This method is called once per plugin, do initial setup here

        # Set the icon for this interface action
        # The get_icons function is a builtin function defined for all your
        # plugin code. It loads icons from the plugin zip file. It returns
        # QIcon objects, if you want the actual data, use the analogous
        # get_resources builtin function.
        #
        # Note that if you are loading more than one icon, for performance, you
        # should pass a list of names to get_icons. In this case, get_icons
        # will return a dictionary mapping names to QIcons. Names that
        # are not found in the zip file will result in null QIcons.
        icon = get_icons('images/icon.png', 'Interface Demo Plugin')

        # The qaction is automatically created from the action_spec defined
        # above
        self.qaction.setIcon(icon)
        self.qaction.triggered.connect(self.show_dialog)

    def show_dialog(self):
        # The base plugin object defined in __init__.py
        base_plugin_object = self.interface_action_base_plugin
        # Show the config dialog
        # The config dialog can also be shown from within
        # Preferences->Plugins, which is why the do_user_config
        # method is defined on the base plugin class
        do_user_config = base_plugin_object.do_user_config

        # self.gui is the main calibre GUI. It acts as the gateway to access
        # all the elements of the calibre user interface, it should also be the
        # parent of the dialog
        d = DemoDialog(self.gui, self.qaction.icon(), do_user_config)
        d.show()

    def apply_settings(self):
        from calibre_plugins.interface_demo.config import prefs
        # In an actual non trivial plugin, you would probably need to
        # do something based on the settings in prefs
        prefs

main.py ¶

El código que implementa el cuadro de diálogo «Interface Plugin Demo».

from qt.core import QDialog, QLabel, QMessageBox, QPushButton, QVBoxLayout


class DemoDialog(QDialog):

    def __init__(self, gui, icon, do_user_config):
        QDialog.__init__(self, gui)
        self.gui = gui
        self.do_user_config = do_user_config

        # The current database shown in the GUI
        # db is an instance of the class LibraryDatabase from db/legacy.py
        # This class has many, many methods that allow you to do a lot of
        # things. For most purposes you should use db.new_api, which has
        # a much nicer interface from db/cache.py
        self.db = gui.current_db

        self.l = QVBoxLayout()
        self.setLayout(self.l)

        self.label = QLabel(prefs['hello_world_msg'])
        self.l.addWidget(self.label)

        self.setWindowTitle('Interface Plugin Demo')
        self.setWindowIcon(icon)

        self.about_button = QPushButton('About', self)
        self.about_button.clicked.connect(self.about)
        self.l.addWidget(self.about_button)

        self.marked_button = QPushButton(
            'Show books with only one format in the calibre GUI', self)
        self.marked_button.clicked.connect(self.marked)
        self.l.addWidget(self.marked_button)

        self.view_button = QPushButton(
            'View the most recently added book', self)
        self.view_button.clicked.connect(self.view)
        self.l.addWidget(self.view_button)

        self.update_metadata_button = QPushButton(
            'Update metadata in a book\'s files', self)
        self.update_metadata_button.clicked.connect(self.update_metadata)
        self.l.addWidget(self.update_metadata_button)

        self.conf_button = QPushButton(
                'Configure this plugin', self)
        self.conf_button.clicked.connect(self.config)
        self.l.addWidget(self.conf_button)

        self.resize(self.sizeHint())

    def about(self):
        # Get the about text from a file inside the plugin zip file
        # The get_resources function is a builtin function defined for all your
        # plugin code. It loads files from the plugin zip file. It returns
        # the bytes from the specified file.
        #
        # Note that if you are loading more than one file, for performance, you
        # should pass a list of names to get_resources. In this case,
        # get_resources will return a dictionary mapping names to bytes. Names that
        # are not found in the zip file will not be in the returned dictionary.
        text = get_resources('about.txt')
        QMessageBox.about(self, 'About the Interface Plugin Demo',
                text.decode('utf-8'))

    def marked(self):
        ''' Show books with only one format '''
        db = self.db.new_api
        matched_ids = {book_id for book_id in db.all_book_ids() if len(db.formats(book_id)) == 1}
        # Mark the records with the matching ids
        # new_api does not know anything about marked books, so we use the full
        # db object
        self.db.set_marked_ids(matched_ids)

        # Tell the GUI to search for all marked records
        self.gui.search.setEditText('marked:true')
        self.gui.search.do_search()

    def view(self):
        ''' View the most recently added book '''
        most_recent = most_recent_id = None
        db = self.db.new_api
        for book_id, timestamp in db.all_field_for('timestamp', db.all_book_ids()).items():
            if most_recent is None or timestamp > most_recent:
                most_recent = timestamp
                most_recent_id = book_id

        if most_recent_id is not None:
            # Get a reference to the View plugin
            view_plugin = self.gui.iactions['View']
            # Ask the view plugin to launch the viewer for row_number
            view_plugin._view_calibre_books([most_recent_id])

    def update_metadata(self):
        '''
        Set the metadata in the files in the selected book's record to
        match the current metadata in the database.
        '''
        from calibre.ebooks.metadata.meta import set_metadata
        from calibre.gui2 import error_dialog, info_dialog

        # Get currently selected books
        rows = self.gui.library_view.selectionModel().selectedRows()
        if not rows or len(rows) == 0:
            return error_dialog(self.gui, 'Cannot update metadata',
                             'No books selected', show=True)
        # Map the rows to book ids
        ids = list(map(self.gui.library_view.model().id, rows))
        db = self.db.new_api
        for book_id in ids:
            # Get the current metadata for this book from the db
            mi = db.get_metadata(book_id, get_cover=True, cover_as_data=True)
            fmts = db.formats(book_id)
            if not fmts:
                continue
            for fmt in fmts:
                fmt = fmt.lower()
                # Get a python file object for the format. This will be either
                # an in memory file or a temporary on disk file
                ffile = db.format(book_id, fmt, as_file=True)
                ffile.seek(0)
                # Set metadata in the format
                set_metadata(ffile, mi, fmt)
                ffile.seek(0)
                # Now replace the file in the calibre library with the updated
                # file. We dont use add_format_with_hooks as the hooks were
                # already run when the file was first added to calibre.
                db.add_format(book_id, fmt, ffile, run_hooks=False)

        info_dialog(self, 'Updated files',
                'Updated the metadata in the files of %d book(s)'%len(ids),
                show=True)

    def config(self):
        self.do_user_config(parent=self)
        # Apply the changes
        self.label.setText(prefs['hello_world_msg'])

Obtener recursos del archivo ZIP del complemento ¶

El sistema de carga de complementos de calibre tiene predefinidas un par de funciones que permiten obtener archivos desde el archivo ZIP del complemento de manera práctica.

get_resources(nombre_o_lista_de_nombres)
Esta función debe ejecutarse con una lista de rutas de acceso a archivos dentro del archivo ZIP. Por ejemplo, para acceder al archivo icon.png en la carpeta images del archivo ZIP, utilizaría: images/icon.png. Use siempre una barra inclinada a la derecha como separador de ruta, incluso en windows. Cuando se pasa un solo nombre, la función devolverá los bytes en bruto de ese archivo o None si el nombre no se encuentra en el archivo ZIP. Si se pasa más de un nombre, entonces devuelve un diccionario de mapeo de nombres a bytes. Si no se encuentra un nombre, no estará presente en el diccionario devuelto.

get_icons(nombre_o_lista_de_nombres, nombre_de_complemento)
Una extensión de get_resources() que crea objetos QIcon a partir de los bytes en bruto devueltos por get_resources. Si un nombre no se encuentra en el archivo ZIP, el correspondiente QIcon será nulo. Para permitir el uso de temas de iconos, pase el nombre «para humanos» del complemento como nombre de complemento. Si el usuario está usando un tema de iconos con iconos para el complemento, se usarán éstos de manera preferente.

Habilitar la configuración de usuario para el complemento ¶

Para permitir a los usuarios configurar el complemento, debe definir tres métodos en la clase base del complemento, is_customizable, config_widget y save_settings como se muestra a continuación:

    def is_customizable(self):
        '''
        This method must return True to enable customization via
        Preferences->Plugins
        '''
        return True

    def config_widget(self):
        '''
        Implement this method and :meth:`save_settings` in your plugin to
        use a custom configuration dialog.

        This method, if implemented, must return a QWidget. The widget can have
        an optional method validate() that takes no arguments and is called
        immediately after the user clicks OK. Changes are applied if and only
        if the method returns True.

        If for some reason you cannot perform the configuration at this time,
        return a tuple of two strings (message, details), these will be
        displayed as a warning dialog to the user and the process will be
        aborted.

        The base class implementation of this method raises NotImplementedError
        so by default no user configuration is possible.
        '''
        # It is important to put this import statement here rather than at the
        # top of the module as importing the config class will also cause the
        # GUI libraries to be loaded, which we do not want when using calibre
        # from the command line
        from calibre_plugins.interface_demo.config import ConfigWidget
        return ConfigWidget()

    def save_settings(self, config_widget):
        '''
        Save the settings specified by the user with config_widget.

        :param config_widget: The widget returned by :meth:`config_widget`.
        '''
        config_widget.save_settings()

        # Apply the changes
        ac = self.actual_plugin_
        if ac is not None:
            ac.apply_settings()

calibre tiene muchas maneras diferentes de almacenar los datos de configuración (un legado de su larga historia). El método recomendado es usar la clase JSONConfig, que almacena la información de configuración en un archivo .json.

El código para gestionar los datos de configuración en el complemento de demostración está en config.py:

from qt.core import QHBoxLayout, QLabel, QLineEdit, QWidget

# This is where all preferences for this plugin will be stored
# Remember that this name (i.e. plugins/interface_demo) is also
# in a global namespace, so make it as unique as possible.
# You should always prefix your config file name with plugins/,
# so as to ensure you dont accidentally clobber a calibre config file
prefs = JSONConfig('plugins/interface_demo')

# Set defaults
prefs.defaults['hello_world_msg'] = 'Hello, World!'


class ConfigWidget(QWidget):

    def __init__(self):
        QWidget.__init__(self)
        self.l = QHBoxLayout()
        self.setLayout(self.l)

        self.label = QLabel('Hello world &message:')
        self.l.addWidget(self.label)

        self.msg = QLineEdit(self)
        self.msg.setText(prefs['hello_world_msg'])
        self.l.addWidget(self.msg)
        self.label.setBuddy(self.msg)

    def save_settings(self):
        prefs['hello_world_msg'] = self.msg.text()

El objeto prefs está ahora disponible en todo el código del complemento simplemente con:

from calibre_plugins.interface_demo.config import prefs

Puede observar que el objeto prefs se usa en main.py:

        self.do_user_config(parent=self)
        # Apply the changes
        self.label.setText(prefs['hello_world_msg'])

Complementos para modificar libros ¶

Vamos a cambiar de tercio y enfocarnos en la creación de un complemento para añadir herramientas al editor de libros de calibre. El complemento está disponible aquí: editor_demo_plugin.zip.

El primer paso, como para todos los complementos es crear el archivo vacío con el nombre de importación descrito anteriormente. Vamos a nombrar el archivo plugin-import-name-editor_plugin_demo.txt.

Ahora creamos el archivo obligatorio __init__.py que contiene los metadatos del complemento: nombre, autor, versión, etc.

from calibre.customize import EditBookToolPlugin


class DemoPlugin(EditBookToolPlugin):

    name = 'Edit Book plugin demo'
    version = (1, 0, 0)
    author = 'Kovid Goyal'
    supported_platforms = ['windows', 'osx', 'linux']
    description = 'A demonstration of the plugin interface for the ebook editor'
    minimum_calibre_version = (1, 46, 0)

Un solo complemento del editor puede proporcionar múltiples herramientas; cada herramienta corresponde a un único botón en la barra de herramientas y entrada en el menú Complementos del editor. Éstos pueden tener submenús en el caso de que la herramienta posea múltiples acciones relacionadas.

Todas las herramientas deben estar definidas en el archivo main.py del complemento. Cada herramienta es una clase que hereda de la clase calibre.gui2.tweak_book.plugin.Tool. Echemos un vistazo al main.py del complemento de demostración; el código fuente está profusamente comentado y se explica por sí mismo. Lea la documentación de la API de la clase :clase:`calibre.gui2.tweak_book.plugin.Tool` para más detalles.

main.py ¶

Aquí veremos la definición de una herramienta que multiplicará todos los tamaños de letra en el libro por un número proporcionado por el usuario. Esta herramienta demuestra varios conceptos importantes que se necesitarán para desarrollar otros complementos, por lo que debe leer el código fuente (muy comentado) cuidadosamente.

import re

from calibre import force_unicode
from calibre.ebooks.oeb.polish.container import OEB_DOCS, OEB_STYLES, serialize
from calibre.gui2 import error_dialog

# The base class that all tools must inherit from
from calibre.gui2.tweak_book.plugin import Tool
from css_parser.css import CSSRule
from qt.core import QAction, QInputDialog


class DemoTool(Tool):

    #: Set this to a unique name it will be used as a key
    name = 'demo-tool'

    #: If True the user can choose to place this tool in the plugins toolbar
    allowed_in_toolbar = True

    #: If True the user can choose to place this tool in the plugins menu
    allowed_in_menu = True

    def create_action(self, for_toolbar=True):
        # Create an action, this will be added to the plugins toolbar and
        # the plugins menu
        ac = QAction(get_icons('images/icon.png'), 'Magnify fonts', self.gui)  # noqa
        if not for_toolbar:
            # Register a keyboard shortcut for this toolbar action. We only
            # register it for the action created for the menu, not the toolbar,
            # to avoid a double trigger
            self.register_shortcut(ac, 'magnify-fonts-tool', default_keys=('Ctrl+Shift+Alt+D',))
        ac.triggered.connect(self.ask_user)
        return ac

    def ask_user(self):
        # Ask the user for a factor by which to multiply all font sizes
        factor, ok = QInputDialog.getDouble(
            self.gui, 'Enter a magnification factor', 'Allow font sizes in the book will be multiplied by the specified factor',
            value=2, min=0.1, max=4
        )
        if ok:
            # Ensure any in progress editing the user is doing is present in the container
            self.boss.commit_all_editors_to_container()
            try:
                self.magnify_fonts(factor)
            except Exception:
                # Something bad happened report the error to the user
                import traceback
                error_dialog(self.gui, _('Failed to magnify fonts'), _(
                    'Failed to magnify fonts, click "Show details" for more info'),
                    det_msg=traceback.format_exc(), show=True)
                # Revert to the saved restore point
                self.boss.revert_requested(self.boss.global_undo.previous_container)
            else:
                # Show the user what changes we have made, allowing her to
                # revert them if necessary
                self.boss.show_current_diff()
                # Update the editor UI to take into account all the changes we
                # have made
                self.boss.apply_container_update_to_gui()

    def magnify_fonts(self, factor):
        # Magnify all font sizes defined in the book by the specified factor
        # First we create a restore point so that the user can undo all changes
        # we make.
        self.boss.add_savepoint('Before: Magnify fonts')

        container = self.current_container  # The book being edited as a container object

        # Iterate over all style declarations in the book, this means css
        # stylesheets, <style> tags and style="" attributes
        for name, media_type in container.mime_map.items():
            if media_type in OEB_STYLES:
                # A stylesheet. Parsed stylesheets are css_parser CSSStylesheet
                # objects.
                self.magnify_stylesheet(container.parsed(name), factor)
                container.dirty(name)  # Tell the container that we have changed the stylesheet
            elif media_type in OEB_DOCS:
                # A HTML file. Parsed HTML files are lxml elements

                for style_tag in container.parsed(name).xpath('//*[local-name="style"]'):
                    if style_tag.text and style_tag.get('type', None) in {None, 'text/css'}:
                        # We have an inline CSS <style> tag, parse it into a
                        # stylesheet object
                        sheet = container.parse_css(style_tag.text)
                        self.magnify_stylesheet(sheet, factor)
                        style_tag.text = serialize(sheet, 'text/css', pretty_print=True)
                        container.dirty(name)  # Tell the container that we have changed the stylesheet
                for elem in container.parsed(name).xpath('//*[@style]'):
                    # Process inline style attributes
                    block = container.parse_css(elem.get('style'), is_declaration=True)
                    self.magnify_declaration(block, factor)
                    elem.set('style', force_unicode(block.getCssText(separator=' '), 'utf-8'))

    def magnify_stylesheet(self, sheet, factor):
        # Magnify all fonts in the specified stylesheet by the specified
        # factor.
        for rule in sheet.cssRules.rulesOfType(CSSRule.STYLE_RULE):
            self.magnify_declaration(rule.style, factor)

    def magnify_declaration(self, style, factor):
        # Magnify all fonts in the specified style declaration by the specified
        # factor
        val = style.getPropertyValue('font-size')
        if not val:
            return
        # see if the font-size contains a number
        num = re.search(r'[0-9.]+', val)
        if num is not None:
            num = num.group()
            val = val.replace(num, '%f' % (float(num) * factor))
            style.setProperty('font-size', val)
        # We should also be dealing with the font shorthand property and
        # font sizes specified as non numbers, but those are left as exercises
        # for the reader

Vamos a analizar main.py. Vemos que define una única herramienta, llamada Magnify fonts. Esta herramienta le pediráá al usuario un número y multiplicará todos los tamaños de letra en el libro por dicho número.

La primera cosa importante es el nombre de la herramienta que debe establecer a algún texto relativamente único, ya que se utilizará como clave para esta herramienta.

El siguiente punto de entrada importante es calibre.gui2.tweak_book.plugin.Tool.create_action(). Este método crea los objetos QAction que aparecen en la barra de herramientas y en el menú de complementos. También, opcionalmente, asigna un atajo de teclado que el usuario puede personalizar. La señal que se genera en el objeto QAction está conectada con el método ask_user() que pide al usuario el multiplicador del tamaño de letra, y luego ejecuta el código de ampliación.

El código de aumento está bien comentado y es bastante simple. Lo principal que hay que destacar es que se obtiene una referencia a la ventana del editor como self.gui y al Boss del editor como self.boss. El Boss es el objeto que controla la interfaz de usuario del editor. Tiene muchos métodos útiles, que se documentan en la clase calibre.gui2.tweak_book.boss.Boss.

Finalmente está self.current_container, que es una referencia al libro que se está editando como un objeto calibre.ebooks.oeb.polish.container.Container. Éste representa el libro como una colección de archivos HTML, CSS e imágenes y posee diversos métodos prácticos para hacer varias cosas útiles. El objeto contenedor y varias funciones utilitarias que se pueden reutilizar en el código de los complementos están documentados en Documentación de la API para las herramientas de modificación de libros electrónicos.

Añadir traducciones al complemento ¶

Puede traducir todos los textos de la interfaz de usuario del complemento y mostrarlos en el idioma en que está configurada la interfaz principal de calibre.

El primer paso es ir al código fuente del complemento y marcar todos los textos visibles por el usuario como traducibles, encerrándolos con _(). Por ejemplo:

action_spec = (_('My plugin'), None, _('My plugin is cool'), None)

Después utilice algún programa para generar archivos .po para el código fuente del complemento. Debe haber un archivo .po para cada idioma al que lo quiera traducir. Por ejemplo: de.po para el alemán, fr.po para el francés, etc. Puede utilizar el programa Poedit para esto.

Envíe estos archivos .po a los traductores. Cuando reciba los archivos traducidos, compílelos en archivos .mo. Puede utilizar nuevamente Poedit para ello, o simplemente ejecutar:

calibre-debug -c "from calibre.translations.msgfmt import main; main()" filename.po

Ponga los archivos .mo en la carpeta translations del complemento.

El último paso es simplemente ejecutar la función load_translations() al principio de los archivos .py del complemento. Por motivos de rendimiento, sólo debe llamar a esta función en aquellos archivos .py que realmente poseen textos traducibles. Así que en un complemento de interfaz de usuario típico, la ejecutaría en ui.py pero no en __init__.py.

Puede probar las traducciones del complemento cambiando el idioma de la interfaz de usuario en calibre bajo Preferencias > Interfaz > Apariencia o ejecutando calibre con la variable de entorno CALIBRE_OVERRIDE_LANG establecida. Por ejemplo:

CALIBRE_OVERRIDE_LANG=de

Sustituya de por el código del idioma que desea probar.

Para traducciones con plurales, use la función ngettext() en lugar de _(). Por ejemplo:

ngettext('Delete a book', 'Delete {} books', num_books).format(num_books)

La API del complemento ¶

Como ya se habrá dado cuenta, un complemento en calibre es una clase. Hay diferentes clases para los diferentes tipos de complementos en calibre. Los detalles de cada clase, incluyendo la clase base de todos los complementos, se pueden encontrar en Documentación de la API para complementos.

Es casi seguro que el complemento va a usar el código de calibre. Para saber cómo encontrar los distintos elementos de funcionalidad en el código base de calibre, lea la sección Estructura del código.

Depurar complementos ¶

El primer paso, el más importante, es ejecutar calibre en modo de depuración. Puede hacer esto desde la línea de órdenes con:

calibre-debug -g

O desde el mismo calibre, pulsando con el botón derecho en Preferencias o usando el atajo de teclado Ctrl+Mayús+R.

Cuando se ejecuta desde la línea de órdenes, la salida de depuración se enviará a la consola, si se ejecuta dentro de calibre, la salida irá a un archivo txt.

Puede insertar sentencias de impresión en cualquier lugar en el código fuente del complemento, tendrán efecto en el modo de depuración. Recuerde, esto es Python, no debe necesitar más que sentencias de impresión para depurar ;) He desarrollado todo calibre usando sólo esta técnica de depuración.

Puede probar rápidamente los cambios en el complemento con la siguiente orden:

calibre-debug -s; calibre-customize -b /path/to/your/plugin/folder; calibre

Esto cerrará calibre, esperará hasta que se cierre completamente, después actualiza el complemento en calibre y vuelve a iniciar calibre.

Más ejemplos de complementos ¶

Puede encontrar una lista de muchos complementos de calibre más complejos aqui.