Tecnología · GUÍA PRÁCTICA
¿EPUB muestra «no item named»? Rastree el miembro ZIP ausente antes de cambiar el libro
Un script ausente, un capítulo perdido y una diferencia de mayúsculas pueden causar el mismo KeyError. Cuatro paquetes muestran por qué una comprobación ZIP limpia no acredita un EPUB completo.
Un error de EPUB que indica que no existe un elemento en cierta ruta significa que falló una búsqueda dentro del archivo. No indica si falta un capítulo o un script, o si la referencia está mal escrita. Preserve el archivo exacto y la ruta completa del error antes de cambiar nada.
Probamos cuatro paquetes EPUB 3 locales originales con Python 3.12.14, EbookLib 0.20.0 y lxml 6.1.3. El control cargó. Eliminar un script declarado, eliminar el segundo capítulo del spine o cambiar una letra a mayúscula en la referencia de un capítulo produjo KeyError en cada caso. Los cuatro pasaron ZipFile.testzip() y sus hashes de entrada no cambiaron durante la auditoría.
Es una prueba de búsqueda dentro del paquete, no una demostración de conformidad EPUB completa del control ni de visualización correcta en un dispositivo. No ejecutamos EPUBCheck, Calibre, EpubSplit ni un lector gráfico. La aportación práctica es una comparación que dirige la misma excepción hacia investigaciones diferentes.
Siga la referencia desde el paquete hasta el archivo
Enumere los miembros sin extraerlos ni sobrescribirlos; la opción de Python es python -m zipfile -l book.epub. Lea META-INF/container.xml para identificar el documento de paquete. En nuestros casos era OEBPS/package.opf: el href Text/chapter2.xhtml del manifest apuntaba a OEBPS/Text/chapter2.xhtml.
Registre ID del manifest, href original, tipo de medio, nombre resuelto, existencia exacta y posición en el spine, si la tiene. W3C define el documento de paquete como base de sus URL y los nombres del contenedor distinguen mayúsculas. Probamos rutas locales simples; recursos remotos, nombres codificados, fragmentos, múltiples representaciones o XML incorrecto requieren sus reglas de URL y paquete, no una unión de rutas improvisada.
Distinga contenido ausente de una referencia incorrecta
En el caso del capítulo ausente, c2 apuntaba al inexistente OEBPS/Text/chapter2.xhtml en la posición 2 del spine. No lo sustituya por un capítulo vacío ni omita la excepción para declarar completo el resultado. Obtenga un archivo fuente corregido o pida al productor autorizado que restaure el contenido real y sus enlaces.
En el caso de mayúsculas, el manifest solicitaba Text/Chapter1.xhtml y el archivo contenía Text/chapter1.xhtml. La auditoría informó del candidato con distinta capitalización sin seleccionarlo ni renombrarlo automáticamente. Compruebe todas las referencias y la intención del productor antes de corregir: una coincidencia aproximada es una pista, no una prueba de equivalencia.
Un script fuera del spine no es automáticamente prescindible
Eliminar OEBPS/js/unused.js también detuvo EbookLib, aunque ambos capítulos del spine seguían presentes. En este caso sintético sabíamos que no se utilizaba porque creamos todos los archivos. En un libro ajeno, un script fuera del spine puede estar referenciado por el contenido o sostener una función.
Rastree dependencias y pida al productor restaurar el recurso o retirar deliberadamente la declaración obsoleta y sus referencias. No reclasifique un archivo local ausente como recurso remoto permitido, descargue un script con nombre parecido ni capture todos los KeyError para continuar. La incidencia 281 ya describe este fallo de carga del manifest; el mecanismo no es un descubrimiento nuevo.
Separe las comprobaciones de ZIP, publicación y entrega
testzip() comprueba CRC y cabeceras de los miembros guardados; no sabe cuáles debía contener la publicación. Devolvió None en los cuatro casos, incluido el capítulo ausente. Que EbookLib cargara el control solo acredita que ese analizador lo aceptó con las opciones probadas, no conformidad EPUB completa.
La función documentada Tools → Check book de Calibre ya informa de enlaces rotos y problemas OPF, y W3C recomienda un comprobador de conformidad como EPUBCheck. Use esas vías existentes en una copia de trabajo y conserve sus informes. Tras una reparación autorizada, repita la operación fallida, verifique orden y texto de los capítulos y pruebe la lectura requerida. Preserve el original y registre recursos pendientes: un reintento exitoso no demuestra por sí solo que no se perdiera texto o funcionalidad.
