Documentación de la API para complementos

Define varias clases abstractas de base que pueden usarse para crear potentes complementos como subclase. Las clases útiles son:

Complemento

class calibre.customize.Plugin(plugin_path)[fuente]

Un complemento de calibre. Los miembros útiles incluyen:

  • self.plugin_path: Almacena la ubicación del archivo ZIP que contiene
    este complemento o None si es un complemento predefinido
  • self.site_customization: Guarda un texto de personalización introducido
    por el usuario.

Métodos que deben reemplazarse en subclases:

Métodos útiles:

supported_platforms = []

Lista de plataformas con las que este complemento es compatible. Por ejemplo: ['windows', 'osx', 'linux']

name = u'Trivial Plugin'

El nombre de este complemento. Debe establecer algo distinto de «Trivial Plugin» para que funcione.

version = (1, 0, 0)

La versión de este complemento como una 3-tupla (mayor, menor, revisión)

description = u'No hace absolutamente nada'

Una breve descripción de lo que hace este complemento

author = u'Desconocido'

El autor de este complemento

priority = 1

Cuando existe más de un complemento para un tipo de archivo, los complementos se ejecutarán en orden de prioridad decreciente. Los complementos de mayor prioridad se ejecutarán primero. La prioridad más alta posible es sys.maxsize. La prioridad predeterminada es 1.

minimum_calibre_version = (0, 4, 118)

La versión más antigua requerida por este complemento

can_be_disabled = True

Si es False, el usuario no podrá deshabilitar este complemento. Usar con precaución.

type = u'Base'

El tipo de este complemento. Utilizado para clasificar los complementos en la interfaz gráfica.

initialize()[fuente]

Se ejecuta una vez cuando se inicializan los complementos de calibre. Los complementos se vuelven a inicializar cada vez que se añade uno nuevo. Tenga en cuenta que si el complemento se ejecuta como un proceso de trabajo, por ejemplo para añadir libros, el complemento debe inicializarse por cada nuevo proceso.

Realice cualquier inicialización específica del complemento aquí, tal como extraer recursos del archivo ZIP del complemento. La ruta al archivo ZIP está disponible como self.plugin_path.

Tenga en cuenta que self.site_customization no está disponible en este punto.

config_widget()[fuente]

Implemente este método y save_settings() en el complemento para usar un cuadro de diálogo de configuración personalizado, en lugar de emplear la configuración predeterminada basada en textos.

Este método, si se implementa, debe devolver un QWidget. El widget puede tener un mótodo opcional validate() que no toma ningún argumento y se ejecuta en cuanto el usuario pulsa el botón «Aceptar». Los cambios se aplican si y sólo si el método devuelve True.

Si por alguna razón no se puede realizar la configuración en este momento, deberá devolver una tupla de dos textos (mensaje, detalles), que se mostrarán como un cuadro de diálogo de advertencia al usuario y el proceso se cancelará.

save_settings(config_widget)[fuente]

Guardar las configuraciones especificadas por el usuario con config_widget.

Parámetros:config_widget – El widget devuelto por config_widget().
do_user_config(parent=None)[fuente]

Este método muestra un diálogo de configuración para este complemento. Devuelve True si el usuario pulsa en «Aceptar» o False en caso contrario. Los cambios se aplican automáticamente.

load_resources(names)[fuente]

Si este complemento viene en un archivo en formato ZIP (complemento añadido por el usuario), este método le permitirá cargar recursos desde el archivo ZIP.

Por ejemplo, para cargar una imagen:

pixmap = QPixmap()
pixmap.loadFromData(self.load_resources(['images/icon.png'])['images/icon.png'])
icon = QIcon(pixmap)
Parámetros:names – Lista de rutas a los recursos en el archivo ZIP utilizando / como separador
Devuelve:Un diccionario de la forma {nombre: contenido_del_archivo}. Cualquier nombre que no se encuentre en el archivo ZIP, no estará en el diccionario.
customization_help(gui=False)[fuente]

Devuelve un texto que ofrece ayuda sobre cómo personalizar este complemento. De manera predeterminada, genera el error NotImplementedError, que indica que el complemento no necesita personalización.

Si reimplementa este método en la subclase, se le pedirá al usuario que introduzca un texto como personalización para este complemento. El texto de personalización estará disponible como self.site_customization.

site_customization puede ser cualquier cosa, por ejemplo, la ruta de acceso a un archivo binario necesario en el equipo del usuario.

Parámetros:gui – Si es True devuelve la ayuda HTML, de lo contrario devuelve ayuda de texto sin formato.
temporary_file(suffix)[fuente]

Devuelve un objeto de tipo archivo que es un archivo temporal en el sistema de archivos. Este archivo permanecerá disponible incluso después de cerrarse y sólo se eliminará al terminar el intérprete. Utilice el miembro name del objeto devuelto para acceder a la ruta completa del archivo temporal creado.

Parámetros:suffix – El sufijo del archivo temporal.
cli_main(args)[fuente]

Este método es el principal punto de acceso para la interfaz de línea de órdenes de los complementos. Se ejecuta cuando el usuario teclea: calibre-debug -r «Nombre del complemento». Todos los argumentos que se pasen están presentes en la variable args.

FileTypePlugin

class calibre.customize.FileTypePlugin(plugin_path)[fuente]

Bases: calibre.customize.Plugin

Un complemento asociado con un determinado conjunto de tipos de archivo.

file_types = set([])

Conjunto de tipos de archivo para que este complemento debe ejecutarse. Use '*' para todos los tipos de archivo. Por ejemplo: {'lit', 'mobi', 'prc'}

on_import = False

Si es True, este complemento se ejecuta cuando se añaden libros a la base de datos

on_postimport = False

Si es True, este complemento se ejecuta después de añadir libros a la base de datos. En tal caso, se ejecutarán los métodos de postimport() y postadd() del complemento.

on_preprocess = False

Si es True, este complemento se ejecuta justo antes de una conversión

on_postprocess = False

Si es True, este complemento se ejecuta después de la conversión sobre el archivo final producido por el complemento de salida de conversión.

run(path_to_ebook)[fuente]

Ejecutar el complemento. Debe implementarse en subclases. Debe realizar cualquier modificación necesaria sobre el libro y devolver la ruta absoluta al libro modificado. Si no se necesita ninguna modificación, debe devolver la ruta de acceso al libro original. Si ocurre un error, debe generar una excepción. La implementación predeterminada simplemente devuelve la ruta de acceso al libro original. Tenga en cuenta que la ruta al archivo original (antes de que se ejecute ningún complemento de tipo de archivo) está disponible como self.original_path_to_file.

El archivo de libro electrónico modificado debe crearse con el método temporary_file().

Parámetros:path_to_ebook – Ruta absoluta al libro electrónico.
Devuelve:Ruta absoluta al libro electrónico modificado.
postimport(book_id, book_format, db)[fuente]

Se ejecuta después de la importación, es decir, después de añadir el archivo del libro a la base de datos. Tenga en cuenta que se trata de un método diferente de postadd(), que se ejecuta cuando se crea el registro del libro por primera vez. Este método se ejecuta siempre que se añade un archivo nuevo al registro del libro. Resulta útil para modificar el registro del libro según el contenido del archivo recién añadido.

Parámetros:
  • book_id – Identificador de la base de datos del libro añadido.
  • book_format – El tipo de archivo del libro que se ha añadido.
  • db – Base de datos de biblioteca.
postadd(book_id, fmt_map, db)[fuente]

Se ejecuta después la creación, es decir, después de añadir un nuevo libro a la base de datos. Tenga en cuenta que se trata de un método diferente de postimport(), que se ejecuta cuando se añade un archivo de libro a un registro. Este método se ejecuta sólo cuando se crea un nuevo registro de libro, que puede contener más de un archivo de libro. Resulta útil si desea modificar el registro del libro en la base de datos cuando se añade el libro por primera vez en calibre.

Parámetros:
  • book_id – Identificador de la base de datos del libro añadido.
  • fmt_map – Correspondencia de formato de archivo con ruta desde la que se añadió el archivo. Tenga cuenta que esto puede apuntar a un archivo existente en realidad o no, pues a veces se añaden archivos como flujos, en cuyo caso puede ser un valor inútil o una ruta no existente.
  • db – Base de datos de biblioteca

Complementos de metadatos

class calibre.customize.MetadataReaderPlugin(*args, **kwargs)[fuente]

Bases: calibre.customize.Plugin

Un complemento que implementa la lectura de metadatos de un conjunto de tipos de archivo.

file_types = set([])

Conjunto de tipos de archivo para los que este complemento debe ejecutarse. Por ejemplo: set(['lit', 'mobi', 'prc'])

get_metadata(stream, type)[fuente]

Devuelve metadatos del archivo representado por stream (un objeto de tipo archivo que admite lectura). Genera una excepción si hay un error con los datos de entrada.

Parámetros:type – El tipo del archivo. Es con seguridad una de las entradas en file_types.
Devuelve:Un objeto calibre.ebooks.metadata.book.Metadata.
class calibre.customize.MetadataWriterPlugin(*args, **kwargs)[fuente]

Bases: calibre.customize.Plugin

Un complemento que implementa la lectura de metadatos de un conjunto de tipos de archivo.

file_types = set([])

Conjunto de tipos de archivo para los que este complemento debe ejecutarse. Por ejemplo: set(['lit', 'mobi', 'prc'])

set_metadata(stream, mi, type)[fuente]

Establece los metadatos del archivo representado por stream (un objeto de tipo archivo que admite lectura). Genera una excepción si hay un error con los datos de entrada.

Parámetros:
  • type – El tipo del archivo. Es con seguridad una de las entradas en file_types.
  • mi – Un objeto calibre.ebooks.metadata.book.Metadata.

Complementos de catálogo

class calibre.customize.CatalogPlugin(plugin_path)[fuente]

Bases: calibre.customize.Plugin

Un complemento que implementa un generador de catálogos.

file_types = set([])

Tipo de archivo de salida para el que debe ejecutarse este complemento. Por ejemplo: «epub» o «xml»

cli_options = []

Opciones del intérprete de línea de órdenes específicas de este complemento, declaradas como un «namedtuple» «Option»:

from collections import namedtuple Option = namedtuple(“Option”, “option, default, dest, help”) cli_options = [Option(“–catalog-title”, default = “My Catalog”, dest = “catalog_title”, help = (_(“Title of generated catalog. nDefault:”) + » “» + “%default” + «”»))] cli_options parsed in calibre.db.cli.cmd_catalog:option_parser()

initialize()[fuente]

Si el complemento no es uno de los incorporados, copiar los archivos .ui y .py del archivo ZIP a $TMPDIR. Se generará dinámicamente una pestaña que se añadirá a las opciones de catálogo en calibre.gui2.dialogs.catalog.py:Catalog

run(path_to_output, opts, db, ids, notification=None)[fuente]

Ejecutar el complemento. Debe implementarse en subclases. Debe generar el catálogo en el formato especificado en file_types y devolver la ruta de acceso absoluta al archivo de catálogo generado. Si ocurre un error, debe generar una excepción.

El archivo del catálogo generado debe crearse con el método temporary_file().

Parámetros:
  • path_to_output – Ruta absoluta al archivo de catálogo generado.
  • opts – Un diccionario de argumentos de palabras claves
  • db – Un objeto LibraryDatabase2

Complementos de descarga de metadatos

class calibre.ebooks.metadata.sources.base.Source(*args, **kwargs)[fuente]

Bases: calibre.customize.Plugin

capabilities = frozenset([])

Conjunto de capacidades ofrecidas por este complemento. Algunas capacidades útiles son: “identify”, “cover”

touched_fields = frozenset([])

Lista de campos de metadatos que este complemento puede descargarse durante la fase de identificación.

has_html_comments = False

Establézcala a True si el complemento devuelve comentarios en formato HTML

supports_gzip_transfer_encoding = False

Si se establece en True el objeto de navegador indicará que admite transferencias codificadas con gzip. Esto puede acelerar las descargas, pero asegúrese primero de que el origen admite transferencias codificadas con gzip correctamente

ignore_ssl_errors = False

Si se establece en true se ignoran los errores de certificado HTTPS al conectar con este origen.

cached_cover_url_is_reliable = True

Los URL de portadas en caché no siempre son fiables (la descarga puede fallar o la imagen puede ser incorrecta). Si esto ocurre a menudo con este origen, establézcalo en False

options = ()

Una lista de objetos Option. Se usarán para construir automáticamente el widget de configuración para este complemento

config_help_message = None

Un texto que se muestra en la parte superior del widget de configuración de este complemento.

can_get_multiple_covers = False

Si es True este recurso puede devolver múltiples portadas para una consulta dada

auto_trim_covers = False

Si se establece en True, las portadas descargadas por este complemento se recortan automáticamente.

prefer_results_with_isbn = True

Si se establece en True, y esta fuente devuelve múltiples resultados para una consulta, algunos de los cuales tienen ISBN y otros no, los resultados sin ISBN se ignorarán

is_configured()[fuente]

Devuelve False si el complemento necesita configurarse antes de usarlo. Por ejemplo, puede requerir un nombre de usuario, contraseña o clave API.

get_author_tokens(authors, only_first_author=True)[fuente]

Toma una lista de autores y devuelve una lista de elementos útiles para una consulta de búsqueda AND. Esta función intenta devolver elementos con el orden «nombres apellidos», suponiendo que si hay una coma en nombre de autor, el nombre está en la forma «apellidos, nombre».

get_title_tokens(title, strip_joiners=True, strip_subtitle=False)[fuente]

Toma un título y devuelve una lista de elementos útiles para una consulta de búsqueda AND. Excluye conectores (opcionalmente) y puntuación.

split_jobs(jobs, num)[fuente]

Divide una lista de tareas en num grupos como máximo, tan igualados como sea posible

test_fields(mi)[fuente]

Devuelve el primer campo de self.touched_fields que es nulo en el objeto mi

clean_downloaded_metadata(mi)[fuente]

Ejecutar este métedo en el método de identificación del complemento para normalizar los metadatos antes de poner el objeto mi en result_queue. Lógicamente puede usar un algoritmo personalizado adecuado a la fuente de metadatos.

get_book_url(identifiers)[fuente]

Devuelve una 3-tupla o None. La 3-tupla es de la forma: (tipo_identificador, valor_identificador, URL). URL es el URL del libro identificado por los identificadores en este origen. tipo_identificador y valor_identificador especifican el identificador correspondiente al URL. Este URL debe ser accesible a un humano por medio de un navegador. El propósito es proporcionar un enlace que el usuario pueda pulsar para visitar la página del libro en este origen. Si no se encuentra ningún URL, devuelve None. Este método debe ser rápido y coherente, por lo que sólo debe implementarlo si es posible construir el URL mediante un esquema conocido dado identifiers.

get_book_url_name(idtype, idval, url)[fuente]

Devuelve un nombre legible por humanos a partir valor devuelto por get_book_url().

get_book_urls(identifiers)[fuente]

Reemplace este método si desea devolver varios URL para este libro. Devuelve una lista de 3-tuplas. De manera predeterminada este método simplemente ejecuta get_book_url().

get_cached_cover_url(identifiers)[fuente]

Devuelve el URL de portada en caché para el libro identificado por el diccionario identifiers o None si no existe el URL.

Tenga en cuenta que este método sólo debe devolver URL validados, es decir no URL que puedan resultar en una imagen de portada genérica o un error.

id_from_url(url)[fuente]

Analiza un URL y devuelve una tupla de la forma: (tipo_de_identificador, valor_de_identificador). Si el URL no coincide con el patrón del origen de metadatos, devuelve None.

identify_results_keygen(title=None, authors=None, identifiers={})[fuente]

Devuelve una función empleada para generar una clave que pueda ordenar objetos de tipo Metadata por su relevancia dada una consulta de búsqueda (title, authors, identifiers).

Estas claves se usan para ordenar los resultados de identify().

Para detalles sobre el algoritmo predeterminado ver InternalMetadataCompareKeyGen. Implemente de nuevo esta función en el complemento si el algoritmo predeterminado no es el adecuado.

identify(log, result_queue, abort, title=None, authors=None, identifiers={}, timeout=30)[fuente]

Identificar un libro por su título, autor, ISBN, etc.

Si se especifica identifiers y no se encuentran coincidencias y este origen de metadatos no almacena todos los identificadores relacionados (por ejemplo, todos los ISBN de un libro), este método debe volver a intentarlo con sólo el título y el autor (si se especificaron).

Si este origen de metadatos también proporciona portadas, el URL de la portada debe almacenarse en caché para que ejecuciones posteriores a la API para obtener portadas con el mismo ISBN o identificador especial no tenga que volver a obtener el URL de portada. Usar la API de caché para esto.

Cada objeto Metadata puesto en result_queue por este método debe tener un atributo attr:source_relevance que es un entero que indica el orden en que el origen de metadatos devuelve los resultados para esta búsqueda. Este entero se usará por compare_identify_results(). Si el orden no es importante, póngalo a cero para todos los resultados.

Asegúrese de que cualquier información de correspondencia de portada o ISBN está en caché antes de que el objeto Metadata sea puesto en result_queue.

Parámetros:
  • log – Un objeto de registro, úselo para obtener errores e información de depuración
  • result_queue – Un objeto Queue resultante, los resultados deben ser puestos en él. Cada resultado es un objeto Metadata.
  • abort – Si abort.is_set() devuelve True, interrumpir el proceso y volver tan pronto como sea posible
  • title – El título del libro, puede ser None
  • authors – Una lista de autores del libro, puede ser None
  • identifiers – Un diccionario de otros identificadores, principalmente {“isbn”:“1234…”}
  • timeout – Tiempo de espera en segundos, ninguna petición de red debería esperar más de este tiempo.
Devuelve:

None si no hubo ningún error, en caso contrario una representación unicode del error que pueda mostrarse al usuario

download_cover(log, result_queue, abort, title=None, authors=None, identifiers={}, timeout=30, get_best_cover=False)[fuente]

Descargar una portada y poner el resultado en result_queue. Todos los parámetros tienen el mismo significado que para identify(). Poner (self, cover_data) en result_queue.

Este metodo de usar los URL de portada en caché siempre que sea posible. Cuando no se encuentran los datos en caché, la mayoría de los complementos ejecutan identify() y usan sus resultados.

Si el parámetro get_best_cover es True y este complemento puede obtener múltiples portadas, esto debería obtener sólo la «mejor».

class calibre.ebooks.metadata.sources.base.InternalMetadataCompareKeyGen(mi, source_plugin, title, authors, identifiers)[fuente]

Generar una clave de orden para comparar la relevancia de los objetos Metadata, dada una consulta de búsqueda. Esto se usa sólo para comparar resultados del mismo origen de metadatos, no entre distintos orígenes.

La clave de orden garantiza que el orden ascendente corresponde a un orden descendiente de relevancia.

El algoritmo es:

  • Dar prioridad a los resultados que tienen al menos un identificador igual al de la consulta
  • Preferir resultados con un URL de portada en caché
  • Preferir resultados con todos los campos disponibles rellenos
  • Dar prioridad a los resultados en el mismo idioma que la interfaz de usuario actual
  • Preferir resultados con una coincidencia de título perfecto con la consulta
  • Preferir resultados con comentarios más largos (diferencia mayor del 10%)
  • Usar la relevancia del resultado según la indice la búsqueda del origen de metadatos
    motor

Complementos de conversión

class calibre.customize.conversion.InputFormatPlugin(*args)[fuente]

Bases: calibre.customize.Plugin

Los complementos InputFormatPlugin son los responsables de convertir un documento a HTML+OPF+CSS+etc. Los resultados de la conversión deben estar codificados en UTF-8. La acción principal ocurre en convert().

file_types = set([])

Conjunto de tipos de archivo para los que este complemento debe ejecutarse. Por ejemplo: set(['asw', 'mobi', 'prc'])

is_image_collection = False

Si es True, este complemento de entrada genera una colección de imágenes, una por archivo HTML. Esto puede ser establecido dinámicamente en el método convert() si los archivos de entrada pueden ser o no colecciones de imágenes. Si lo establece en True, debe implementar el método get_images() que devuelve una lista de imágenes.

core_usage = 1

Número de núcleos de CPU utilizados por este complemento. Un valor de -1 significa que utiliza todos los núcleos disponibles

for_viewer = False

Si es True, el complemento de entrada realizará un procesado especial para que la salida sea adecuada para visualización

output_encoding = u'utf-8'

La codificación de los archivos que crea el complemento de entrada. Un valor de None significa que la codificación no está definida y debe detectarse individualmente

common_options = set([<calibre.customize.conversion.OptionRecommendation object>])

Opciones compartidas por todos los complementos de formato de entrada. No reemplazar en subclases. Usar options en su lugar. Toda opción debe ser un ejemplar de OptionRecommendation.

options = set([])

Opciones para personalizar el comportamiento de este complemento. Toda opción debe ser un ejemplar de OptionRecommendation.

recommendations = set([])

Un conjunto de 3-tuplas del tipo (nombre_opción, valor_recomendado, nivel_de_recomendación)

get_images()[fuente]

Devuelve una lista de rutas absolutas a las imágenes, si este complemento representa una colección de imágenes. La lista de imágenes está en el mismo orden que el lomo y el índice.

convert(stream, options, file_ext, log, accelerators)[fuente]

Este método debe ser implementado en subclases. Debe volver la ruta al archivo OPF creado o un ejemplar OEBBook. Toda la salida debe estar contenida en el directorio actual. Si este complemento crea archivos fuera del directorio actual, deben ser eliminados o marcados para su eliminación antes de que termine este método.

Parámetros:
  • stream – Un objeto de tipo archivo que contiene el archivo de entrada.
  • options – Opciones para personalizar el proceso de conversión. Debe tener atributos correspondientes a todas las opciones declaradas por este complemento. Además, debe haber un atributo verbose que toma valores enteros a partir de cero. Valores mayores significan más detalles. Otro atributo útil es input_profile, que es un ejemplar de calibre.customize.profiles.InputProfile.
  • file_ext – La extensión (sin el «.») del archivo de entrada. Debe ser uno de los file_types admitidos por este complemento.
  • log – Un objeto calibre.utils.logging.Log. Toda salida debería usar este objeto.
  • accelarators – Un diccionario con diversa información que el complemento de entrada puede obtener fácilmente y que acelerará las etapas posteriores de la conversión.
postprocess_book(oeb, opts, log)[fuente]

Se ejecuta para permitir que el complemento de entrada lleve a cabo el posprocesado del libro después del procesado principal.

specialize(oeb, opts, log, output_fmt)[fuente]

Se ejecuta para permitir que el complemento de entrada especialice el libro analizado para un formato de salida particular. Se ejecuta después de postprocess_book() y antes de que se realice cualquier transformación sobre el libro analizado.

gui_configuration_widget(parent, get_option_by_name, get_option_help, db, book_id=None)[fuente]

Ejecutado para crear el widget que se usa para configurar este complemento en la interfaz de calibre. El widget debe ser un objeto de la clase PluginWidget. Puede ver ejemplos en los complementos de entrada incorporados.

class calibre.customize.conversion.OutputFormatPlugin(*args)[fuente]

Bases: calibre.customize.Plugin

Los complementos OutputFormatPlugin son los responsables de convertir un documento OEB (OPF+HTML) en un libro de salida.

El documento OEB puede suponerse codificado en UTF-8. La acción principal ocurre en convert().

file_type = None

El tipo de archivo (extensión sin punto inicial) que produce este complemento

common_options = set([<calibre.customize.conversion.OptionRecommendation object>])

Opciones compartidas por todos los complementos de formato de entrada. No reemplazar en subclases. Usar options en su lugar. Toda opción debe ser un ejemplar de OptionRecommendation.

options = set([])

Opciones para personalizar el comportamiento de este complemento. Toda opción debe ser un ejemplar de OptionRecommendation.

recommendations = set([])

Un conjunto de 3-tuplas del tipo (nombre_opción, valor_recomendado, nivel_de_recomendación)

convert(oeb_book, output, input_plugin, opts, log)[fuente]

Mostrar el contenido de oeb_book (que es un espécimen de calibre.ebooks.oeb.OEBBook) en el archivo especificado por salida.

Parámetros:
  • output – Un objeto de tipo archivo o un texto. Si es un texto es la ruta a un directorio que puede existir o no. El complemento de salida debe escribir su resultado en este directorio. Si es un objeto de tipo archivo, el complemento de salida debe escribir su resultado en el archivo.
  • input_plugin – El archivo de entrada que se usó al inicio del proceso de conversión.
  • opts – Opciones de conversión. Es seguro que tiene atributos correspondientes a los valores de OptionRecommendations de este complemento.
  • log – El registrador. Escribir mensajes de depuración, información, etc. usando este objeto.
specialize_options(log, opts, input_fmt)[fuente]

Puede usarse para modificar los valores de las opciones de conversión, como en el proceso de conversión.

specialize_css_for_output(log, opts, item, stylizer)[fuente]

Puede usarse para hacer cambios al css durante el proceso de aplanamiento del CSS.

Parámetros:
  • item – El elemento (archivo HTML) que se está procesando.
  • stylizer – Un objeto de tipo Stylizer que contiene los estilos aplanados para item. Puede obtener el estilo para cualquier elemento con ``stylizer.style(elemento)`.
gui_configuration_widget(parent, get_option_by_name, get_option_help, db, book_id=None)[fuente]

Ejecutado para crear el widget que se usa para configurar este complemento en la interfaz de calibre. El widget debe ser un objeto de la clase PluginWidget. Puede ver ejemplos en los complementos de salida incorporados.

Controladores de dispositivo

La clase base para todos los controladores de dispositivo es DevicePlugin. Sin embargo, si el dispositivo se muestra como una unidad USBMS ante el sistema operativo, debe usar la clase USBMS en su lugar, pues implementa toda la lógica necesaria para este tipo de dispositivos.

class calibre.devices.interface.DevicePlugin(plugin_path)[fuente]

Bases: calibre.customize.Plugin

Define la interfaz que deben implementar los motores que comunican con un lector de libros electrónicos.

FORMATS = [u'lrf', u'rtf', u'pdf', u'txt']

Lista ordenada de formatos soportados

VENDOR_ID = 0

VENDOR_ID puede ser un entero, una lista de enteros o un diccionario. Si es un diccionario, debe ser un diccionario de diccionarios de la forma:

{
 integer_vendor_id : { product_id : [list of BCDs], ... },
 ...
}
PRODUCT_ID = 0

Un entero o una lista de enteros

BCD = None

BCD puede ser bien None para no distinguir entre dispositivos según BCD, o bien una lista de los números BCD de todos los dispositivos soportados por este controlador.

THUMBNAIL_HEIGHT = 68

Altura de las miniaturas en el dispositivo

THUMBNAIL_COMPRESSION_QUALITY = 75

Calidad de compresión para las miniaturas. Cuanto más cercano a 100, mejor será la calidad de las miniaturas y menores los defectos de compresión. Por supuesto, también ocuparán más espacio las miniaturas.

WANTS_UPDATED_THUMBNAILS = False

Establézcalo en True si el dispositivo admite actualizar miniaturas de portada durante meth:sync_booklists. Si es True, se pedirá a device.py que vuelva a cargar las miniaturas al comparar libros

CAN_SET_METADATA = [u'title', u'authors', u'collections']

Especifica si los metadatos de los libros pueden establecerse a través de la interfaz gráfica.

CAN_DO_DEVICE_DB_PLUGBOARD = False

Especifica si el dispositivo puede gestionar paneles de conexiones de metadatos device_db

path_sep = '/'

Separador de ruta para rutas de acceso a los libros en el dispositivo

icon = u'/home/kovid/work/calibre/resources/images/reader.png'

Icono para este dispositivo

UserAnnotation

alias de Annotation

OPEN_FEEDBACK_MESSAGE = None

La interfaz gráfica muestra esto como un mensaje si no es None. Útil si la apertura puede llevar mucho tiempo

VIRTUAL_BOOK_EXTENSIONS = frozenset([])

Conjunto de extensiones que son «libros virtuales» en el dispositivo y por lo tanto no pueden visualizarse, guardarse o añadirse a la biblioteca. Por ejemplo: frozenset(['kobo'])

VIRTUAL_BOOK_EXTENSION_MESSAGE = None

Mensaje que se mostrará al usuario para las extensiones de libro virtuales.

NUKE_COMMENTS = None

Indica si se eliminan los comentarios de la copia del libro que se envía al dispositivo. Si no es None, debería ser un texto corto por el que se sustituirán los comentarios.

MANAGES_DEVICE_PRESENCE = False

Si es True, indica que este controlador gestiona completamente la detección de dispositivos, la desconexión, etc. Si la establece a True, debe implementar los métodos detect_managed_devices y debug_managed_device_detection. Un controlador con esta variable como True tiene la responsabilidad de detectar dispositivos, gestionar una lista negra de dispositivos, una lista de dispositivos desconectados, etc. calibre ejecutará periódicamente el método meth:detect_managed_devices() y si devuleve un dispositivo detectado, calibre ejecutará open(). open() se ejecutará cada vez que se devuelva un dispositivo, incluso si previamente open() falló, por lo tanto el controlador debe mantener su propia lista negra de dispositivos fallidos. Análogamente, al desconectar, calibre ejecutará eject() y, suponiendo que que la siguiente ejecución de detect_managed_devices() devuelva None, ejecutará post_yank_cleanup().

SLOW_DRIVEINFO = False

Si se establece en True, calibre ejecutará el método get_driveinfo() una vezs cargadas las listas de libros para obtener la información de la unidad.

ASK_TO_ALLOW_CONNECT = False

Si se establece en True, calibre preguntará al usuario si quiere administrar el dispositivo con calibre la primera vez que se detecta. Si lo establece en True debe implementar get_device_uid(), ignore_connected_device(), get_user_blacklisted_devices() y set_user_blacklisted_devices()

user_feedback_after_callback = None

Establezca esto a un diccionario de la forma {“title”:título, “msg”:mensaje, “det_msg”:mensaje_detallado} para que calibre muestre una ventana con un mensaje para el usuario tras ejecutar varias acciones (actualmente sólo upload_books()). Procure no mostrar demasiados mensajes al usuario. Esta variable se comprueba después de cada acción, así que establézcala sólo cuando sea realmente necesaria.

is_usb_connected(devices_on_system, debug=False, only_presence=False)[fuente]

Devuelve True, device_info si algún dispositivo gestionado por este complemento está actualmente conectado.

Parámetros:devices_on_system – Lista de dispositivos conectados actualmente
detect_managed_devices(devices_on_system, force_refresh=False)[fuente]

Sólo se llama si MANAGES_DEVICE_PRESENCE es True.

Buscar dispositivos que pueda gestionar este controlador. Debe devolver un objeto de dispositivo si se encuentra algún dispositivo. Este objeto se pasará al método open() como connected_device. Si no se encuentra ningún dispositivo, devuelve None. El objeto devuelto puede ser cualquier cosa, calibre no lo usa, sólo lo pasa a open().

Este método se ejecuta periódicamente por la interfaz gráfica, así que asegúrese de que no requiere demasiados recursos. Use un caché para evitar buscar en el sistema una y otra vez.

Parámetros:
  • devices_on_system – Conjunto de dispositivos USB encontrados en el sistema.
  • force_refresh – Si es True y el controlador usa un caché para evitar búsquedas repetitivas, el caché debe vaciarse.
debug_managed_device_detection(devices_on_system, output)[fuente]

Sólo se llama si MANAGES_DEVICE_PRESENCE es True.

Debe escribir en output información sobre los dispositivos detectados en el sistema, que es un objeto de tipo archivo.

Debe devolver True si se detecta un dispositivo y se abre con éxito, en caso contrario debe devolver False.

reset(key=u'-1', log_packets=False, report_progress=None, detected_device=None)[fuente]
Parámetros:
  • key – La clave para desbloquear el dispositivo
  • log_packets – Si es True, el flujo de paquetes de o al dispositivo se registra
  • report_progress – Función que se ejecuta con un argumento de progreso en porcentaje (número entre 0 y 100) para diversas tareas. Si el argumento es -1 significa que la tarea no tiene información de progreso.
  • detected_device – Información de dispositivo desde el examinador de dispositivos
can_handle_windows(usbdevice, debug=False)[fuente]

Método opcional para comprobar si este controlador puede manejar un dispositivo mediante más pruebas. Si no puede, debe devolver False. Este método sólo se ejecuta una vez que los identificadores del fabricante y del producto, así como el BCD se han reconocido, por lo que puede realizar pruebas que requieran un tiempo relativamente prolongado. La implementación predeterminada devuelve True. Este método sólo se ejecuta en Windows. Véase también can_handle().

Tenga en cuenta que para dispositivos basados en USBMS este método de manera predeterminada delega en can_handle(). Así que sólo necesita sustituir can_handle() en la subclase de USBMS.

Parámetros:usbdevice – Un dispositivo usb devuelto por calibre.devices.winusb.scan_usb_devices()
can_handle(device_info, debug=False)[fuente]

Versión unix de can_handle_windows().

Parámetros:device_info – Es una tupla de (id_fab, id_prod, bcd, fabricante, producto, número de serie)
open(connected_device, library_uuid)[fuente]

Realiza cualquier inicio específico del dispositivo. Se ejecuta una vez que se ha detectado el dispositivo, pero antes de cualquier otra función que comunique con él. Por ejemplo, para dispositivos que se muestran como dispositivos de almacenamiento masivo USB, este método será el responsable de montar el dispositivo o, si se ha montado automáticamente, averiguar dónde. El método calibre.devices.usbms.device.Device.open() tiene una implementación de esta función que puede ser un buen ejemplo para dispositivos de almacenamiento masivo USB.

Este método puede generar una excepción de tipo OpenFeedback para mostrar un mensaje al usuario final.

Parámetros:
  • connected_device – El dispositivo que se intenta abrir. Es una tupla de (identificador de fabricante, identificador de producto, bcd, nombre de fabricante, nombre de producto, número de serie del dispositivo). Sin embargo, algunos dispositivos no tienen número de serie y en Windows sólo aparecen los tres primeros campos, el resto son None.
  • library_uuid – El UUID de la biblioteca de calibre actual. Puede ser None si no existe una biblioteca (por ejemplo cuando se usa desde la línea de órdenes).
eject()[fuente]

Desmontar o expulsar el dispositivo del sistema operativo. Esto no comprueba si hay tareas de interfaz gráfica pendientes que tengan que comunicar con el dispositivo.

NOTA: Este método no puede ejecutarse en el mismo subproceso que el resto de los métodos de dispositivo.

post_yank_cleanup()[fuente]

Se ejecuta si el usuario desconecta el dispositivo sin expulsarlo primero.

set_progress_reporter(report_progress)[fuente]

Establece una función para mostrar información de progreso.

Parámetros:report_progress – Función que se ejecuta con un argumento de progreso en porcentaje (número entre 0 y 100) para diversas tareas. Si el argumento es -1 significa que la tarea no tiene información de progreso.
get_device_information(end_session=True)[fuente]

Pregunta al dispositivo por su información interna. Ver L{DeviceInfoQuery}.

Devuelve:(nombre del dispositivo, versión del dispositivo, versión del software en el dispositivo, tipo mime) La tupla puede tener un quinto elemento opcional, que es un diccionario de información de unidad. Puede verse un ejemplo en usbms.driver.
get_driveinfo()[fuente]

Devuelve el diccionario de información de dispositivo. Normalmente se ejecuta desde get_device_information(), pero si la carga de la información del dispositivo es lenta para este controlador, debería establecer SLOW_DRIVEINFO. En este caso, calibre ejecutará este método después de cargar la lista de libros. Tenga en cuenta que no se ejecuta en el hilo del dispositivo, por lo que el controlador debería almacenar en caché la información del dispositivo en el método books() y esta función debería devolver los datos almacenados.

card_prefix(end_session=True)[fuente]

Devuelve una lista de dos elementos con los prefijos para las rutas de acceso en las tarjetas. Si no hay tarjeta, el prefijo correspondiente será None. Por ejemplo: (“/lugar”, “/lugar2”) (None, “lugar2”) (“lugar”, None) (None, None)

total_space(end_session=True)[fuente]
Obtiene el espacio total disponible en los puntos de montaje:
  1. Memoria principal
  2. Tarjeta de almacenamiento A
  3. Tarjeta de almacenamiento B
Devuelve:Una lista de tres elementos con el espacio total en bytes de (1, 2, 3). Si un dispositivo concreto no tiene alguna de estas ubicaciones, debe devolver 0.
free_space(end_session=True)[fuente]
Obtiene el espacio libre disponible en los puntos de montaje:
  1. Memoria principal
  2. Tarjeta A
  3. Tarjeta B
Devuelve:Una lista de tres elementos con el espacio libre en bytes de (1, 2, 3). Si un dispositivo concreto no tiene alguna de estas ubicaciones, debe devolver -1.
books(oncard=None, end_session=True)[fuente]

Devuelve una lista de los libros electrónicos en el dispositivo.

Parámetros:oncard – Si es “carda” o “cardb”, devuelve una lista de los libros en la tarjeta de almacenamiento especificada, en caso contrario devuelve una lista de los libros en la memoria principal del dispositivo. Si se especifica una tarjeta y no hay libros en ella, devuelva una lista vacía.
Devuelve:Un objeto BookList.
upload_books(files, names, on_card=None, end_session=True, metadata=None)[fuente]

Copia una lista de libros al dispositivo. Si un archivo ya existe en el dispositivio, deberá ser sustituido. Este método debería generar un error FreeSpaceError si no hay suficiente espacio libre en el dispositivo. El texto del error FreeSpaceError debe contener la palabra «card» si ``on_card` no es None, si no, debe contener la palabra «memory».

Parámetros:
  • files – Una lista de rutas
  • names – Una lista de nombres de archivo que los libros deberán tener una vez copiados al dispositivo. len(names) == len(files)
  • metadata – Si no es None, es una lista de objetos Metadata. La idea es utilizar los metadatos para determinar dónde poner el libro en el dispositivo. len(metadata) == len(files). Aparte de la portada normal (ruta a la portada), también puede haber un atributo de miniatura (thumbnail), que debería tener prioridad. El atributo thumbnail es de la forma (anchura, altura, datos_de_portada como jpeg).
Devuelve:

Una lista de tuplas de 3 elementos. La lista se envía a add_books_to_metadata().

classmethod add_books_to_metadata(locations, metadata, booklists)[fuente]

Añade ubicaciones a las listas de libros. Esta función no debe comunicarse con el dispositivo.

Parámetros:
  • locations – Resultado de una llamada a L{upload_books}
  • metadata – Lista de objetos Metadata, igual que para upload_books().
  • booklists – Una tupla que contiene el resultado de las llamadas a (books(oncard=None)(), books(oncard='carda')(), :meth`books(oncard=”cardb”)`).
delete_books(paths, end_session=True)[fuente]

Borrar libros en ubicaciones del dispositivo.

classmethod remove_books_from_metadata(paths, booklists)[fuente]

Elimina libros de la lista de metadatos. Esta función no debe comunicarse con el dispositivo.

Parámetros:
  • paths – rutas a los libros en el dispositivo.
  • booklists – Una tupla que contiene el resultado de las llamadas a (books(oncard=None)(), books(oncard='carda')(), :meth`books(oncard=”cardb”)`).
sync_booklists(booklists, end_session=True)[fuente]

Actualizar metadatos del dispositivo.

Parámetros:booklists – Una tupla que contiene el resultado de las llamadas a (books(oncard=None)(), books(oncard='carda')(), :meth`books(oncard=”cardb”)`).
get_file(path, outfile, end_session=True)[fuente]

Lee el archivo en path en el dispositivo y lo escribe en outfile.

Parámetros:outfile – objeto de archivo como sys.stdout o el resultado de ejecutar open().
classmethod config_widget()[fuente]

Debe devolver un QWidget. El QWidget contiene las configuraciones de la interfaz de dispositivo.

classmethod save_settings(settings_widget)[fuente]

Debe guardar las configuraciones en el disco. Toma el widget creado en config_widget() y guarda todas las configuraciones en el disco.

classmethod settings()[fuente]

Debe devolver un objeto opts. El objeto opts debería tener al menos un atributo format_map que es una lista ordenada de formatos para el dispositivo.

set_plugboards(plugboards, pb_func)[fuente]

Proporciona al controlador el conjunto actual de paneles de conexiones y una función para seleccionar un panel de conexión específico. Este método se ejecuta inmediatamente antes de add_books y sync_booklists.

pb_func es un metodo ejecutable con la siguiente firma:
def pb_func(device_name, format, plugboards)

Le da el nombre del dispositivo actual (ya sea el nombre de la clase o DEVICE_PLUGBOARD_NAME), el formato en que está interesado (un formato «real» o ​​`device_db`), y los paneles de conexiones (suministrados por set_plugboards, en el mismo lugar de donde se obtuvo este método).

Devuelve:None o un único panel de conexiones.
set_driveinfo_name(location_code, name)[fuente]

Establece el nombre de dispositivo en el archivo driveinfo como name. Este ajuste persistirá hasta que el archivo se vuelva a crear o se cambie el nombre de nuevo.

Los dispositivos que no son de disco deberían implementar este método según los códigos de ubicación devueltos por el método get_device_information().

prepare_addable_books(paths)[fuente]

Dada una lista de rutas de acceso, devuelve otra lista de rutas de acceso. Estas rutas apuntan a versiones de los libros que pueden añadirse.

Si ocurre un error al preparar un libro, en lugar de una ruta de acceso, la posición en la lista devuelta para ese libro debería de ser una tupla de tres elementos: (ruta_original, la excepción, rastro)

startup()[fuente]

Se ejecuta cuando calibre inicia el dispositivo. Realiza cualquier inicialización necesaria. Tenga en cuenta que pueden generarse varios especímenes de la clase, y por lo tanto __init__() puede ejecutarse varias veces, pero sólo un espécimen ejecutará este método. Este método se ejecuta en el hilo del dispositivo, no en el de la interfaz gráfica.

shutdown()[fuente]

Se ejecuta cuando calibre se está apagando, ya sea definitivamente o como preparación para reiniciarse. Lleva a cabo cualquier limpieza requerida. Este método se ejecuta en el hilo del dispositivo, no en el de la interfaz gráfica.

get_device_uid()[fuente]

Debe devolver un identificador único para el dispositivo conectado actualmente (se ejecuta inmediatamente después de ejecutarse open() con éxito). Debe implementar este método si establece ASK_TO_ALLOW_CONNECT = True.

ignore_connected_device(uid)[fuente]

El dispositivo identificado por uid (el resultado de ejecutar get_device_uid()) debe ignorarse en el futuro. Debe implementar este método si establece ASK_TO_ALLOW_CONNECT = True. Tenga en cuenta que esta función se ejecuta inmediatamente después de open(), así que si open() almacena algún estado en caché el controlador debería restablecer el estado.

get_user_blacklisted_devices()[fuente]

Devuelve un diccionario de identificadores y nombres de dispositivo para todos los dispositivos que el usuario ha pedido ignorar.

set_user_blacklisted_devices(devices)[fuente]

Establecer la lista de uids de dispositivo que deben ser ignorados por este controlador.

specialize_global_preferences(device_prefs)[fuente]

Implemente este método si el dispositivo quiere sustituir una preferencia particular. Debe asegurarse de que todos los lugares de ejecución que emplean una preferencia que pueda ser sustituida usen device_prefs['algo'] en lugar de prefs['algo']. El metodo debe ejecutar device_prefs.set_overrides(pref=val, pref=val, ...). Actualmente se usa para: gestión de metadatos (prefs['manage_device_metadata']).

set_library_info(library_name, library_uuid, field_metadata)[fuente]

Implemente este método si quiere información sobre la biblioteca de calibre actual. Este método se ejecuta al inicio y cuando la biblioteca de calibre cambia mientras está conectado.

is_dynamically_controllable()[fuente]

Ejecutado por el administrador de dispositivos al iniciar complementos. Si este método devuelve un texto, entonces a) soporta la interfaz de control dinámica del administrador de dispositivos y b) debe usarse ese nombre para comunicarse con el complemento.

Este método puede ejecutarse en el hilo de la interfaz gráfica. Un controlador que implemente este método debe ser seguro para subprocesos.

start_plugin()[fuente]

Este método se ejecuta para iniciar el complemento. El complemento debe empezar a aceptar conexiones de dispositivos de la manera que lo haga. Si el complemento ya acepta conexiones, no debe hacer nada.

Este método puede ejecutarse en el hilo de la interfaz gráfica. Un controlador que implemente este método debe ser seguro para subprocesos.

stop_plugin()[fuente]

Este método se ejecuta para detener el complemento. El complemento debe dejar de aceptar conexiones y debe hacer hacer limpieza tras de sí. Probablemente este método debería ejecutar shutdown(). Si el complemento ya no acepta conexiones, no debe hacer nada.

Este método puede ejecutarse en el hilo de la interfaz gráfica. Un controlador que implemente este método debe ser seguro para subprocesos.

get_option(opt_string, default=None)[fuente]

Devuelve el valor de la opción indicada por opt_string. Este método puede ejecutarse cuando el complemento no se ha iniciado. Devuelve None si la opción no existe.

Este método puede ejecutarse en el hilo de la interfaz gráfica. Un controlador que implemente este método debe ser seguro para subprocesos.

set_option(opt_string, opt_value)[fuente]

Establece el valor de la opción indicada por opt_string. Este método puede ejecutarse cuando el complemento no se ha iniciado.

Este método puede ejecutarse en el hilo de la interfaz gráfica. Un controlador que implemente este método debe ser seguro para subprocesos.

is_running()[fuente]

Devuelve True si el complemento está iniciado, de lo contrario False.

Este método puede ejecutarse en el hilo de la interfaz gráfica. Un controlador que implemente este método debe ser seguro para subprocesos.

synchronize_with_db(db, book_id, book_metadata, first_call)[fuente]

Se ejecuta durante el emparejamiento de libros, cuando cada libro del dispositivo se empareja con un libro en la base de datos de calibre. El método tiene por cometido sincronizar los datos del dispositivo con la base de datos de calibre (si es necesario).

Este método debe devolver una tupla de dos valores. El primer valor es un conjunto de identificadores de libro de calibre modificados si se modificó la base de datos de calibre, o None si la base de datos no se modificó. Si el primer valor es un conjunto vacío, los metadatos del libro en el dispositivo se actualizan con los metadatos de calibre y se vuelven a mandar al dispositivo, pero no se actualiza la interfaz gráfica para ese libro. Esto es útil cuando los metadatos de calibre son correctos, pero deben enviarse al dispositivo.

El segundo valor es una tupla de dos dos valores. El primer valor de la tupla especifica si debe enviarse un formato de libro al dispositivo. El propósito es permitir comprobar que el libro en el dispositivo es el mismo que en calibre. Este valor debe ser None si no debe enviarse ningún libro, en caso contrario debe devolver el nombre de archivo base en el dispositivo (un texto como «foobar.epub»). Asegúrese de incluir la extensión en el nombre. El subsistema del dispositivo generará una tarea send_books para todos los libros cuyo valor devuelto no sea None. Nota: aparte de para extraer la extensión, el nombre de archivo no tiene efecto en los casos en que el dispositivo usa una plantilla para generar el nombre de archivo, lo que ocurre para la mayoría. El segundo valor en la tupla devuelta indica si el formato está fechado en el futuro. Devuelve True si lo está, en caso contrario devuelve False. calibre mostrará un cuadro de diálogo con todos los libros fechados en el futuro.

Extremadamente importante: este método se ejecuta en el subproceso de la interfaz gráfica. Debe ser seguro con respecto al subproceso del administrador de dispositivos.

book_id: el identificador de calibre para el libro en la base de datos. book_metadata: el objeto de tipo Metadata para el libro que viene del dispositivo. first_call: True si ésta es la primera ejecución durante la sincronización, False en caso contrario.

class calibre.devices.interface.BookList(oncard, prefix, settings)[fuente]

Bases: list

Una lista de libros. Cada objeto Book debe tener los campos

  1. title (título)
  2. authors (autores)
  3. size (tamaño del archivo del libro)
  4. datetime (tupla de tiempo UTC)
  5. path (ruta de acceso del libro en el dispositivo)
  6. thumbnail (puede ser None) thumbnail (miniatura) es bien un objeto str o bytes con los datos de la imagen, o debería tener un atributo image_path que almacena una ruta de acceso completa (en el formato de la plataforma) a la imagen
  7. tags (una lista de textos, puede estar vacía).
supports_collections()[fuente]

Devuelve True si el dispositivo es compatible con colecciones para esta lista de libros.

add_book(book, replace_metadata)[fuente]

Añadir el libro a la lista de libros. El propósito es mantener todos los metadatos internos del dispositivo, devuelve True si la las listas de libros deben sincronizarse

remove_book(book)[fuente]

Elimina un libro de una lista de libros. Simultáneamente, corrige cualquier metadato de dispositivo.

get_collections(collection_attributes)[fuente]

Devuelve un diccionario de colecciones creadas a partirde collection_attributes. Cada entrada del diccionario es de la forma nombre de la colección:[lista de libros]

El listado de los libros se ordena por título, excepto en colecciones creadas a partir de series, donde se usa series_index.

Parámetros:collection_attributes – Una lista de atributos del objeto Book.

Dispositivos basados en almacenamiento masivo USB

La clase base para tales dispositivos es calibre.devices.usbms.driver.USBMS. Esta clase hereda algunas de sus funcionalidades de sus bases, documentadas a continuación. Un controlador típico basado en USBMS es así:

from calibre.devices.usbms.driver import USBMS

class PDNOVEL(USBMS):
    name = 'Pandigital Novel device interface'
    gui_name = 'PD Novel'
    description = _('Communicate with the Pandigital Novel')
    author = 'Kovid Goyal'
    supported_platforms = ['windows', 'linux', 'osx']
    FORMATS = ['epub', 'pdf']

    VENDOR_ID   = [0x18d1]
    PRODUCT_ID  = [0xb004]
    BCD         = [0x224]

    THUMBNAIL_HEIGHT = 144

    EBOOK_DIR_MAIN = 'eBooks'
    SUPPORTS_SUB_DIRS = False

    def upload_cover(self, path, filename, metadata):
        coverdata = getattr(metadata, 'thumbnail', None)
        if coverdata and coverdata[2]:
            with open('%s.jpg' % os.path.join(path, filename), 'wb') as coverfile:
                coverfile.write(coverdata[2])
class calibre.devices.usbms.device.Device(plugin_path)[fuente]

Bases: calibre.devices.usbms.deviceconfig.DeviceConfig, calibre.devices.interface.DevicePlugin

Esta clase proporciona una lógina común a todos los controladores para dispositivos que se manifiestan como dispositivos USB de almacenamiento masivo. Proporciona implementaciones para montar o extraer dispositivo USBMS en todas las plataformas.

WINDOWS_MAIN_MEM = None

Texto que identifica la memoria principal del dispositivo en los textos de identificación PnP de Windows. Puede ser None, un texto, una lista de textos o una expresión regular compilada

WINDOWS_CARD_A_MEM = None

Texto que identifica la primera tarjeta del dispositivo en los textos de identificación PnP de Windows. Puede ser None, un texto, una lista de textos o una expresión regular compilada

WINDOWS_CARD_B_MEM = None

Texto que identifica la segunda tarjeta del dispositivo en los textos de identificación PnP de Windows. Puede ser None, un texto, una lista de textos o una expresión regular compilada

OSX_MAIN_MEM_VOL_PAT = None

Usado por la nueva detección de controladores para distinguir la memoria principal de las tarjetas de almacenamiento. Debería ser una expresión regular que corresponda al punto de montaje de la memoria principal asignado por macOS

MAX_PATH_LEN = 250

La longitud máxima para las rutas de acceso en el dispositivo

NEWS_IN_FOLDER = True

Poner noticias en una carpeta propia

windows_sort_drives(drives)[fuente]

Ejecutado para distinguir la memoria principal y la tarjeta de almacenamiento para dispositivos en los que WINDOWS_CARD_*_NAME no funciona. Por ejemplo, el EB600

sanitize_callback(path)[fuente]

Método para permitir a los controladores de dispositivo individuales reemplazar la limpieza de rutas de acceso empleada por create_upload_path().

filename_callback(default, mi)[fuente]

Devuelve la llamada para permitir a los conductores cambiar el nombre de archivo por defecto introducido por create_upload_path()

sanitize_path_components(components)[fuente]

Realiza cualquier limpieza específica del dispositivo en los componentes de la ruta de acceso para los archivos que se copiarán al dispositivo

get_annotations(path_map)[fuente]

Resuelve path_map a annotation_map para archivos en el dispositivo

add_annotation_to_library(db, db_id, annotation)[fuente]

Añadir una anotación a la biblioteca de calibre

class calibre.devices.usbms.cli.CLI[fuente]
class calibre.devices.usbms.driver.USBMS(plugin_path)[fuente]

Bases: calibre.devices.usbms.cli.CLI, calibre.devices.usbms.device.Device

La clase base para todos los dispositivos USBMS. Implementa la lógica para enviar, recibir, actualizar metadatos, retener metadatos, etc.

upload_cover(path, filename, metadata, filepath)[fuente]

Envía una portada de libro al dispositivo. La implementación predeterminada no hace nada.

Parámetros:
  • path – La ruta completa del directorio donde se encuentra el libro asociado.
  • filename – El nombre del archivo del libro electrónico sin la extensión.
  • metadata – metadatos perteneciente al libro. Use metadata.thumbnail para la portada
  • filepath – La ruta completa al archivo del libro electrónico
classmethod normalize_path(path)[fuente]

Devuelve path con los separadores de ruta propios de la plataforma

Acciones de interfaz de usuario

Si añade un complemento propio en un archivo ZIP, debería crear subclases de InterfaceActionBase e InterfaceAction. El método load_actual_plugin() de la nueva subclase de InterfaceActionBase debe devolver un espécimen de la subclase de InterfaceBase.

class calibre.gui2.actions.InterfaceAction(parent, site_customization)[fuente]

Bases: PyQt5.QtCore.QObject

Un complemento que representa una «acción» que puede ejecutarse en la interfaz gráfica. Todos los elementos de la barra de herramientas y de los menús contextuales están implementados mediante estos complementos.

Tenga en cuenta que esta clase es la clase base para estos complementos, pero para integrar el complemento con el sistema de complementos de calibre debe crear una clase envoltorio que haga referencia al complemento real. Ver ejemplos en el módulo calibre.customize.builtins.

Si dos objetos InterfaceAction tienen el mismo nombre, tiene preferencia el que tenga mayor prioridad.

Las subclases deben implementar los métodos genesis(), library_changed(), location_selected(), shutting_down() y initialization_complete().

Una vez inicializado, este complemento tiene acceso a la interfaz gráfica principal de calibre vía gui. Puede acceder a otros complementos por su nombre, por ejemplo:

self.gui.iactions['Save To Disk']

Para acceder al complemento real, use el atributo interface_action_base_plugin; este atributo sólo está disponible una vez que el complemento se ha iniciado. Es útil si quiere usasr métodos de la clase del complemento como do_user_config().

La QAction especificada por action_spec se crea automáticamente y está disponible como self.qaction.

name = u'Implement me'

El nombre del complemento. Si dos complementos con el mismo nombre están presentes, el que tenga mayor prioridad tiene preferencia.

priority = 1

La prioridad del complemento. Si dos complementos con el mismo nombre están presentes, el que tenga mayor prioridad tiene preferencia.

popup_type = 1

El tipo de menú emergente para cuando se añade este complemento a una barra de herramientas

auto_repeat = False

Especifica si esta acción debe repetirse automáticamente cuando el atajo de teclado se mantiene presionado.

action_spec = (u'text', u'icon', None, None)

De la forma: (texto, ruta_icono, ayuda, atajo_teclado). ruta_icono, ayuda y atajo_teclado pueden ser None. atajo_teclado puede ser un texto, None o una tupla de atajos. Si es None, no se registra ningún atajo de teclado correspondiente a la acción. Si se pasa una tupla vacía, se registra un atajo sin ninguna tecla predefinida.

action_add_menu = False

Si es True, se crea automáticamente un menú y se añade a self.qaction

action_menu_clone_qaction = False

Si es True, se añade un clon de self.qaction al menú de self.qaction. Si quiere que el texto de esta acción sea distinto del de self.qaction, establezca esta variable como el nuevo texto.

dont_add_to = frozenset([])

Conjunto de ubicaciones a las que no debe añadirse esta acción. Ver all_locations para una lista de posibles ubicaciones

dont_remove_from = frozenset([])

Conjunto de ubicaciones de las que no se debe eliminar esta acción. Ver: all_locations para obtener una lista de posibles ubicaciones

action_type = u'global'

Tipo de acción. «current» significa que actúa sobre la vista actual, «global» indica una acción que no actúa sobre la vista actual, sino sobre calibre en general

accepts_drops = False

Si es True, este InterfaceAction tendrá la oportunidad de interactuar con acciones de arrastrar y soltar. Ver los métodos accept_enter_event(), :meth`:accept_drag_move_event`, drop_event() para más detalles.

accept_enter_event(event, mime_data)[fuente]

Este método debe devolver True si y sólo si esta acción de interfaz puede gestionar la acción de arrastrar. No ejecute accept o ignore en la acción, la interfaz de calibre se encargará de ello.

accept_drag_move_event(event, mime_data)[fuente]

Este método debe devolver True si y sólo si esta acción de interfaz puede gestionar la acción de arrastrar. No ejecute accept o ignore en la acción, la interfaz de calibre se encargará de ello.

drop_event(event, mime_data)[fuente]

Este método debe realizar algunas acciones útiles y devolver True si y sólo si esta acción de interfaz puede manejar el suceso drop. No ejecute accept o ignore sobre el suceso, la interfaz de calibre se encargará de eso. No debe realizar operaciones largas o que causen bloqueo en esta función. En su lugar lugar emita una señal o use QTimer.singleShot y finalice rápidamente. Vea las acciones predefinidas como ejemplos.

create_menu_action(menu, unique_name, text, icon=None, shortcut=None, description=None, triggered=None, shortcut_name=None)[fuente]

Método práctico para añadir acciones a un QMenu. Devuelve la QAction creada. Esta acción tiene un atributo adicional calibre_shortcut_unique_name que, si no es None, se refiere al nombre único con el que esta acción se registra en el gestor de teclado.

Parámetros:
  • menu – El QMenu al que se añadirá la nueva acción creada
  • unique_name – Un nombre único para esta acción. Debe ser un nombre globalmente único, así que hágalo tan descriptivo como sea posible. Si duda, añádale un identificador uuid.
  • text – El texto de la acción.
  • icon – Un QIcon o un nombre de archivo. El nombre de archivo se pasa al I() predefinido, así que no necesita pasar la ruta completa al directorio de imágenes.
  • shortcut – Un texto, una lista de textos, None o False. Si es False, no se registra ningún atajo de teclado para esta acción. Si es None, se registra un atajo de teclado sin ninguna tecla predeterminada. Con un texto o lista de textos se registra un atajo con las teclas asociadas predeterminadas que se especifiquen.
  • description – Una descripción para esta acción. Usado para establecer ayudas de herramienta.
  • triggered – Un objeto ejecutable conectado con la señal desencadenada de la acción creada.
  • shortcut_name – El texto que se muestra al usuario al personalizar los atajos de teclado para esta acción. De manera predeterminada toma el valor de text.
load_resources(names)[fuente]

Si este complemento viene en un archivo en formato ZIP (complemento añadido por el usuario), este método le permitirá cargar recursos desde el archivo ZIP.

Por ejemplo, para cargar una imagen:

pixmap = QPixmap()
pixmap.loadFromData(tuple(self.load_resources(['images/icon.png']).values())[0])
icon = QIcon(pixmap)
Parámetros:names – Lista de rutas a los recursos en el archivo ZIP utilizando / como separador
Devuelve:Un diccionario de la forma {nombre: contenido_del_archivo}. Cualquier nombre que no se encuentre en el archivo ZIP, no estará en el diccionario.
genesis()[fuente]

Configurar este complemento. Sólo se ejecuta una vez durante la inicialización. self.gui está disponible. La acción especificada por action_spec está disponible como self.qaction.

location_selected(loc)[fuente]

Ejecutado siempre que cambia la lista que se muestra en calibre. Actualmente los valores para loc son: library, main, card y cardb.

Este método debe habilitar o deshabilitar esta acción y sus subacciones, según sea adecuado para la ubicación.

library_changed(db)[fuente]

Ejecutado cada vez que se cambia la biblioteca actual.

Parámetros:db – La LibraryDatabase correspondiente a la biblioteca actual.
gui_layout_complete()[fuente]

Ejecutado una vez por acción cuando se completa la disposición de la interfaz gráfica principal. Si la acción necesita hacer cambios en la disposición, deben ocurrir aquí y no en initialization_complete().

initialization_complete()[fuente]

Se ejecuta una vez por acción cuando se completa la inicialización de la interfaz gráfica principal.

shutting_down()[fuente]

Ejecutado una vez por complemento cuando la interfaz gráfica se está apagando. Libere los recursos en uso, pero procure no bloquear el apagado durante un tiempo prolongado.

Devuelve:False para detener el apagado. Es su responsabilidad decirle al usuario por qué se detuvo el apagado.
class calibre.customize.InterfaceActionBase(*args, **kwargs)[fuente]

Bases: calibre.customize.Plugin

load_actual_plugin(gui)[fuente]

Este método debe devolver el objeto real de acción de interfaz.

Complementos de preferencias

class calibre.customize.PreferencesPlugin(plugin_path)[fuente]

Bases: calibre.customize.Plugin

Un complemento que representa un widget mostrado en el cuadro de diálogo Preferencias.

Este complemento posee un solo método importante: create_widget(). Los diversos campos de este complemento controlan cómo se categoriza en la interfaz de usuario.

config_widget = None

Ruta de importación al módule que contiene una clase llamada ConfigWidget que implementa ConfigWidgetInterface. Usado por create_widget().

category_order = 100

Donde debe estar la :attr: category de este complemento en la lista de categorías.

name_order = 100

Dónde debe estar el :attr: gui_name de este complemento en la lista de nombres.

category = None

La categoría en la que debe estar este complemento

gui_category = None

El nombre de categoría mostrado al usuario para este complemento

gui_name = None

El nombre que se muestra al usuario para este complemento

icon = None

El icono para este complemento, debe ser una ruta de acceso absoluta

description = None

La descripción usada para ayudas de herramientas y similares

create_widget(parent=None)[fuente]

Crea y devuelve el widget Qt real usado para establecer este grupo de preferencias. El widget debe implementar calibre.gui2.preferences.ConfigWidgetInterface.

La implementación predeterminada usa config_widget para crear el widget.

class calibre.gui2.preferences.ConfigWidgetInterface[fuente]

Esta clase define la interfaz que deben implementar todos los widgets mostrados en el cuadro de diálogo Preferencias. Ver ConfigWidgetBase para una clase base que implementa esta interfaz y también define varios métodos prácticos.

changed_signal = None

Esta señal debe emitirse cuando el usuario cambia un valor en este widget

supports_restoring_to_defaults = True

Es True si y sólo si el método restore_to_defaults() está implementado.

restore_defaults_desc = u'Restablecer las configuraciones a sus valores predeterminados. Debe pulsar \xabAplicar\xbb para guardar las configuraciones.'

La ayuda de herramienta para el botón de restauración de los valores predeterminados

restart_critical = False

Si es True el cuadro de diálogo de preferencias no permitirá al usuario establecer más preferencias. Sólo tiene efecto si commit() devuelve True.

genesis(gui)[fuente]

Se ejecuta una vez antes de mostrar el widget, debe realizar cualquier configuración necesaria.

Parámetros:gui – La interfaz gráfica principal de calibre
initialize()[fuente]

Debe establecer todos los valores de configuración a sus valores iniciales (los valores almacenados en los archivos de configuración).

restore_defaults()[fuente]

Debe establecer todos los valores de configuración a sus valores predeterminados.

commit()[fuente]

Guarda cualquier configuración modificada. Devuelve True si los cambios requieren un reinicio, False si no es así. Genera una excepción AbortCommit para indicar que ocurrió un error. Es su responsabilidad informar al usuario del error y cómo corregirlo.

refresh_gui(gui)[fuente]

Se ejecuta una vez después de crear este widget. Es responsable de hacer que la interfaz gráfica vuelva a leer cualquier configuración modificada. Tenga en cuenta que la interfaz gráfica predeterminada reinicia varios elementos de todas formas, así que la mayoría de los widgets no necesitarán usar este método.

class calibre.gui2.preferences.ConfigWidgetBase(parent=None)[fuente]

Clase base que contiene código para añadir widgets de configuración corrientes, como casillas de verificación, cuadros combinados, campos de texto, etc. Ver el método register().

Esta clase gestiona automáticamente, para las configuraciones registradas, notificaciones de cambio, reinicio a valores predeterminados, correspondencia entre objetos de interfaz gráfica y de configuración, etc.

Si el widget de configuración hereda esta clase pero incluye configuraciones que no están registradas, debe reemplazar los métodos de ConfigWidgetInterface y llamar a los métodos de la clase base en los reemplazos.

register(name, config_obj, gui_name=None, choices=None, restart_required=False, empty_string_is_None=True, setting=<class 'calibre.gui2.preferences.Setting'>)[fuente]

Registrar una configuración.

Parámetros:
  • name – El nombre de la configuración
  • config – El objeto de configuración que lee y escribe la configuración
  • gui_name – El nombre del objeto de interfaz gráfica que ofrece una interfaz para modificar la configuración. De manera predeterminada se supone que es 'opt_' + name.
  • choices – Si esta configuración es de elección múltiple (un cuadro combinado), la lista de posibilidades. La lista es una lista de tuplas de dos elementos de la forma: [(nombre de interfaz, valor), ...].
  • setting – La clase responsable de la gestión de esta configuración. La clase predeterminada contempla casi todos los casos, por lo que este parámetro es raramente usado.

Complementos de visor

class calibre.customize.ViewerPlugin(plugin_path)[fuente]

Bases: calibre.customize.Plugin

type = u'Visor'

Estos complementos se usan para añadir funcionalidad al visor de libros de calibre.

load_fonts()[fuente]

Este método se ejecuta al iniciar el visor. El método debe cargar cualquier tipo de letra que quiera hacer disponible. Por ejemplo:

def load_fonts():
    from PyQt5.Qt import QFontDatabase
    font_data = get_resources(['myfont1.ttf', 'myfont2.ttf'])
    for raw in font_data.values():
        QFontDatabase.addApplicationFontFromData(raw)
load_javascript(evaljs)[fuente]

Este método se ejecuta cada vez que se carga un nuevo documento HTML en el visor. Úselo para cargar bibliotecas de javascript en el visor. Por ejemplo:

def load_javascript(self, evaljs):
    js = get_resources('myjavascript.js')
    evaljs(js)
run_javascript(evaljs)[fuente]

Este método se ejecuta cada vez que termina de cargarse un documento. Úselo de la misma manera que load_javascript().

customize_ui(ui)[fuente]

Este método se ejecuta una vez al crear el visor. Úselo para hacer cualquier personalización que desee en la interfaz de usuario del visor. Por ejemplo, puede modificar las barras de herramientas mediante ui.tool_bar y ui.tool_bar2.

customize_context_menu(menu, event, hit_test_result)[fuente]

Este método se ejecuta cada vez que se muestra el menú de contexto (botón derecho). Puede usarlo para personalizar el menú de contexto. event es la acción del menú de contextoy ``hit_test_result``es el QWebHitTestResult para esta acción en el documento cargado actualmente.