Documentación Técnica: Plugin Metadata RanobeDB para Calibre

Este documento detalla la arquitectura, el funcionamiento interno y la guía de instalación del plugin RanobeDB Light Novels para Calibre, diseñado para obtener metadatos y portadas de Novelas Ligeras desde RanobeDB.

---

1. Descripción General del Plugin

El plugin implementa la interfaz Source de Calibre para interactuar con la API REST v0 de RanobeDB. Su objetivo principal es automatizar el etiquetado, la organización de series y la descarga de portadas en alta resolución de Novelas Ligeras.

Capacidades (capabilities)

• identify: Búsqueda e identificación de libros mediante título, autor, ISBN o identificador de RanobeDB.
• cover: Descarga de portadas asociadas a los volúmenes.

Campos de Metadatos Administrados (touched_fields)

• Título (title)
• Autores (authors)
• Etiquetas / Géneros (tags)
• Fecha de publicación (pubdate)
• Comentarios / Descripción (comments)
• Editorial (publisher)
• Identificadores (identifier:ranobedb, identifier:isbn)
• Serie e Índice de Serie (series, series_index)
• Idioma (languages)

---

2. Arquitectura y Funcionamiento Interno del Código

El código está estructurado en módulos funcionales que manejan desde la interacción HTTP con rate-limiting hasta la extracción y normalización de datos.

A. Control de Rate Limiting (_rate_limit)

Para cumplir con los límites de la API de RanobeDB (máximo 60 peticiones por minuto), el plugin utiliza un bloqueo de hilos (threading.Lock) y una demora mínima obligatoria de 1 segundo entre solicitudes:

RATE_LIMIT_DELAY = 1.0
_last_request_time = 0
_rate_lock = Lock()

Esto garantiza que las búsquedas masivas no provoquen bloqueos de dirección IP.

B. Sistema de Precedencia de Idiomas (_select_by_language y _parse_language_order)

Permite configurar el orden de preferencia de idioma (por defecto en,romaji,ja). El plugin parsea este orden y selecciona dinámicamente el título, nombre de autor o serie más relevante según la disponibilidad en la API.

C. Estrategia de Búsqueda Inteligente (Fases 1, 2 y 3)

1. Fase 1 - Opciones de Configuración Avanzadas: Permite definir el nivel de enriquecimiento de series (no, basic, full) y la activación de búsquedas fallback por serie.

2. Fase 2 - Enriquecimiento de Metadatos de Serie (_apply_series_enrichment): Valida el índice del volumen (series_index) contra la API completa de la serie (/series/{id}). En modo full, además fusiona las etiquetas de la serie con las del libro y anexa la descripción general de la serie al comentario del volumen.

3. Fase 3 - Búsqueda Fallback por Serie (_search_books & _search_series): Si la búsqueda exacta por título falla o incluye números de volumen (ej. "Sword Art Online 05"):

   • Extrae el número de volumen objetivo.
   • Busca la serie general.
   • Filtra automáticamente el volumen exacto dentro del listado oficial de la serie sin perder precisión.

---

3. Guía de Instalación en Calibre

Método 1: Archivo .py Directo

1. Abre Calibre.
2. Ve a Preferencias (Ctrl + P) -> Avanzado -> Plugins.
3. Haz clic en Cargar plugin desde un archivo (botón abajo a la derecha).
4. Selecciona el archivo __init__.py o el archivo ejecutable del plugin.
5. Confirma la advertencia de seguridad haciendo clic en Sí.
6. Reinicia Calibre para aplicar los cambios.

Método 2: Empaquetado como .zip (Recomendado)

Para distribuir o instalar el plugin siguiendo el estándar oficial de Calibre:

1. Renombra o guarda el código ejecutable como __init__.py.
2. Compresión en ZIP desde la terminal:

   zip ranobedb_plugin.zip __init__.py

3. En Calibre, navega a Preferencias -> Plugins -> Cargar plugin desde un archivo.
4. Selecciona ranobedb_plugin.zip y reinicia la aplicación.

---

4. Opciones de Configuración en la Interfaz

Una vez instalado, el plugin se puede configurar desde Preferencias -> Plugins -> Fuentes de Metadatos -> RanobeDB Light Novels:

Opción	Valores / Formato	Descripción
Language preference order	Texto (ej. en,romaji,ja)	Orden de prioridad para títulos y nombres.
Description language	en, ja, both	Idioma de las descripciones descargadas.
Maximum results	Número (1-25)	Límite de resultados retornados por búsqueda.
Series Enhancement	no, basic, full	basic: valida índices. full: incluye descripciones y tags de la serie completa.
Fallback Series Search	yes, no	Habilita la búsqueda inteligente por serie si falla el título exacto.