Documentación de la API para la interfaz de la base de datos

Esta API es segura para subprocesos (utiliza un esquema de bloqueo de un escritor, varios lectores). Puede acceder a esta API así:

from calibre.library import db
db = db('Path to calibre library folder').new_api

Si se trata de un complemento de calibre que es parte de la interfaz gráfica principal, se accede a ella de la siguiente forma:

db = self.gui.current_db.new_api
class calibre.db.cache.Cache(backend)[fuente]

Una copia en memoria caché del archivo metadata.db de la biblioteca de calibre. Esta clase también sirve como un API multihilo para acceder a la base de datos. La copia en memoria se mantiene en forma normal para maximizar el rendimiento.

SQLite se usa simplemente como una manera de leer y escribir eficientemente metadata.db. Toda la lógica de lectura, clasificación, búsqueda y almacenamiento en la memoria caché de las tablas está desarrallada de nuevo. Esto fue necesario para obtener el máximo rendimiento y flexibilidad.

add_books(books, add_duplicates=True, apply_import_tags=True, preserve_uuid=False, run_hooks=True, dbapi=None)[fuente]

Añadir los libros especificados a la biblioteca. Los libros deben ser iterables de 2-tuplas, cada 2-tuplas de la forma (mi, format_map) donde mi es un objeto de metadatos y format_map es un diccionario en la forma {fmt: path_or_stream}, por ejemplo: {'EPUB':'/path/to/file.epub'}.

Devuelve un par de listas: ids, duplicados. ids contiene los identificadores de libros para todos los libros de reciente creación en la base de datos. duplicados contiene el :code: (mi, format_map) para todos los libros que ya existen en la base de datos según la sencilla detección heurística de duplicados utilizada por has_book().

add_custom_book_data(name, val_map, delete_first=False)[fuente]

Añadir datos para name donde val_map es un mapa de book_ids a valores. Si delete_first es True, se eliminarán todos los datos almacenados previamente.

add_format(book_id, fmt, stream_or_path, replace=True, run_hooks=True, dbapi=None)[fuente]

Añadir un formato al libro especificado. Devuelve True si el formato se añadió con éxito.

Parámetros:
  • replace – Si es True, sustituye el formato existente; en caso contrario, si el formato ya existe, devuelve False.
  • run_hooks – Si es True, los complementos de tipo de archivo se ejecutarán sobre el formato antes y después de ser añadido.
  • dbapi – Solo para uso interno.
all_book_ids(type=<type 'frozenset'>)[fuente]

Conjunto fijo de todos los identificadores de libros conocidos.

all_field_for(field, book_ids, default_value=None)[fuente]

Lo mismo que field_for, excepto que opera sobre múltiples libros a la vez.

all_field_ids(name)[fuente]

Conjunto fijo de identificadores para todos los valores del campo name.

all_field_names(field)[fuente]

Conjunto fijo de todos los nombres de campos (sólo se debe utilizar para los campos de tipo varios-uno y varios-varios)

author_data(author_ids=None)[fuente]

Devuelve los datos del autor como un diccionario con claves: name, sort, link

Si no se encuentran autores con los identificadores especificados, se devuelve un diccionario vacío. Si author_ids es None, se devuelven datos para todos los autores.

author_sort_from_authors(authors, key_func=<function lower>)[fuente]

Dada una lista de autores, devolverá el texto author_sort para los autores, prefiriendo el orden de autor asociado con el autor sobre el texto calculado automáticamente.

books_for_field(name, item_id)[fuente]

Devuelve todos los libros relacionados con el elemento identificado por item_id, donde el elemento pertenece al campo name.

El valor devuelto es un conjunto de identificadores de libros, o el conjunto vacío si el elemento o el campo no existen.

books_in_virtual_library(vl, search_restriction=None)[fuente]

Devuelve el conjunto de libros en la biblioteca virtual especificada

copy_cover_to(book_id, dest, use_hardlink=False, report_file_size=None)[fuente]

Copia la portada al objeto de tipo archivo dest. Devuelve False si no existe portada o dest es el mismo archivo que la portada actual. dest también puede ser una ruta de acceso, en cuyo caso la portada se copia en la ruta si y sólo si la ruta es diferente de la actual ruta de acceso (considerando la posible distinción entre mayúsculas y minúsculas).

copy_format_to(book_id, fmt, dest, use_hardlink=False, report_file_size=None)[fuente]

Copiar el formato fmt al objeto de tipo archivo dest. Si el formato especificado no existe, se presenta un error NoSuchFormat. dest también puede ser una ruta de acceso (a un archivo), en cuyo caso el formato se copia en la ruta si y sólo si la ruta es diferente de la ruta de acceso actual (considerando la posible distinción entre mayúsculas y minúsculas).

cover(book_id, as_file=False, as_image=False, as_path=False)[fuente]

Devuelve la imagen de portada o None. De manera predeterminada, devuelve la portada como una serie de bytes.

ADVERTENCIA: Si se usa as_path, se copia la portada a un archivo temporal y se devuelve la ruta de acceso al archivo temporal. Deberá eliminar el archivo temporal cuando haya terminado con él.

Parámetros:
  • as_file – Si es True devuelve la imagen como un objeto de archivo abierto (un SpooledTemporaryFile)
  • as_image – Si es True devuelve la imagen como un objeto QImage
  • as_path – Si es True devuelve la imagen como una ruta de acceso a un archivo temporal
data_for_find_identical_books()[fuente]

Devuelve datos que pueden usarse para implementar find_identical_books() en un proceso de trabajo sin acceso a la base de datos. Véase db.utils para una implementación.

data_for_has_book()[fuente]

Devuelve datos adecuados para has_book(). Puede usarse para implementar has_book() en un proceso de trabajo sin acceso a la base de datos.

delete_custom_book_data(name, book_ids=())[fuente]

Borra los datos para name. De manera predeterminada se borran todos los datos, si sólo desea borrar datos de ciertos identificadores de libros, señálelos como una lista de identificadores de libros.

embed_metadata(book_ids, only_fmts=None, report_error=None, report_progress=None)[fuente]

Actualizar metadatos en todos los formatos de los book_ids especificados a los metadatos actuales de la base de datos.

fast_field_for(field_obj, book_id, default_value=None)[fuente]

Igual que field_for, salvo que se evita la búsqueda adicional para obtener el objeto de campo

field_for(name, book_id, default_value=None)[fuente]

Devuelve el valor del campo name para el libro identificado por book_id. Si no existe tal libro o no tiene un valor definido para el campo name o no existe dicho campo, entonces devuelve default_value.

default_value no se utiliza para title, title_sort, authors, author_sort y series_index. Esto se debe a que éstos siempre tienen valores en la base de datos. default_value se utiliza para todas las columnas personalizadas.

El valor devuelto para los campos is_multiple es siempre una tupla, incluso cuando no se encuentran valores (en otras palabras, default_value no tiene efecto). La excepción son los identificadores para los que el valor devuelto es siempre un diccionario. Las tuplas devueltas son siempre en orden de enlace, es decir, el orden en el que fueron creadas.

field_ids_for(name, book_id)[fuente]

Devuelve los identificadores (como una tupla) de los valores que el campo name tiene en el libro identificado por book_id. Si no hay valores, o tal libro o tal campo, se devuelve una tupla vacía.

find_identical_books(mi, search_restriction=u'', book_ids=None)[fuente]

Encuentra libros que contienen los autores en «mi» y tienen el mismo título (la búsqueda de título es difusa). Véase también

format(book_id, fmt, as_file=False, as_path=False, preserve_filename=False)[fuente]

Devuelve el formato de libro electrónico como una serie de bytes o None si el formato no existe, o no hay permiso para escribir en el archivo de libro electrónico.

Parámetros:
  • as_file – Si es True el formato de libro electrónico se devuelve como un objeto de archivo. Tenga en cuenta que el objeto es un archivo SpooledTemporaryFile, por lo que si lo que quiere hacer es copiar el formato a otro archivo, utilice copy_format_to() en su lugar para mejorar el rendimiento.
  • as_path – Copia el archivo de formato a un archivo temporal y devuelve la ruta de acceso al archivo temporal.
  • preserve_filename – Si es True y devuelve una ruta de acceso, el nombre de archivo es el mismo que el utilizado en la biblioteca. Tenga en cuenta que, al utilizar este método, llamadas repetidas producen el mismo archivo temporal (que se vuelve a crear cada vez)
format_abspath(book_id, fmt)[fuente]

Devuelve la ruta de acceso absoluta al archivo de libro electrónico de formato format. Casi nunca debe usarlo, ya que rompe la filosofía multihilo de esta API. Use copy_format_to().

Actualmente sólo se usa en calibredb list, el visor, modificar libro, compare_format con formato original, abrir con, modificación de metadatos en masa y los catálogos (vía get_data_as_dict()).

Aparte del visor, abrir con y el editor de libros, no creo que ningún otro realice ninguna operación de entrada o salida con el resultado de esta función.

format_hash(book_id, fmt)[fuente]

Devuelve el código de comprobación para el formato y libro especificados. El tipo de código de comprobación es dependiente del motor, pero generalmente es SHA-256.

format_metadata(book_id, fmt, allow_cache=True, update_db=False)[fuente]

Devuelve la ruta, el tamaño y mtime para el formato especificado del libro especificado. No debe utilizar la ruta a menos que sea absolutamente necesario, ya que el acceso directo rompe las garantías multihilo de esta API. Use método copy_format_to() en su lugar.

Parámetros:
  • allow_cache – Si es True se usan los valores almacenados en memoria, en caso contrario se produce un acceso lento al sistema de archivos. Los valores en la memoría podrían estar desfasados si se ha realizado algún acceso al sistema de archivos fuera de esta API.
  • update_db – Si es True el campo max_size de la base de datos se actualiza para este libro.
formats(book_id, verify_formats=True)[fuente]

Devuelve una tupla con todos los formatos del libro especificado. Si verify_formats es True, se verifica que los archivos existen en el disco.

get_categories(sort=u'name', book_ids=None, already_fixed=None, first_letter_sort=False)[fuente]

Usado internamente para implementer el exlorador de etiquetas

get_custom_book_data(name, book_ids=(), default=None)[fuente]

Obtener datos para name. De manera predeterminada devuelve datos para todos los book_ids, pase una lista de identificadores de libros si sólo desea algunos dato. Devuelve un mapa de book_id a valores. Si un valor particular no puede ser descodificado, utiliza el predeterminado.

get_id_map(field)[fuente]

Devuelve un mapa de números de identificación a valores para el campo especificado. El campo debe ser un campo de varios-uno o varios-varios, de lo contrario se presenta un ValueError.

get_ids_for_custom_book_data(name)[fuente]

Devuelve el conjunto de identificadores de libros para los que name tiene datos.

get_item_id(field, item_name)[fuente]

Devuelve el identificador del elemento para item_name (no distingue mayúsculas y minúsculas)

get_item_ids(field, item_names)[fuente]

Devuelve el identificador del elemento para item_name (no distingue mayúsculas y minúsculas)

get_item_name(field, item_id)[fuente]

Devuelve el nombre del elemento para el elemento especificado por item_id en el campo especificado. Ver también get_id_map().

get_metadata(book_id, get_cover=False, get_user_categories=True, cover_as_data=False)[fuente]

Devuelve metadatos para el libro identificado por book_id como un objeto de calibre.ebooks.metadata.book.base.Metadata. Tenga en cuenta que la lista de formatos no se verifica. Si get_cover es True, se devuelve la portada, ya sea como una ruta de acceso a un archivo temporal o como mi.cover, o si cover_as_data es True como mi.cover_data.

get_next_series_num_for(series, field=u'series', current_indices=False)[fuente]

Devuelva el siguiente índice la serie especificada, teniendo en cuenta las distintas preferencias que controlan la generación del siguiente número de serie.

Parámetros:
  • field – El campo de tipo serie (de manera predeterminada la columna predefinida «series»)
  • current_indices – Si es True, devuelve un mapa de book_id al valor actual de series_index.
get_proxy_metadata(book_id)[fuente]

Como get_metadata() excepto que devuelve un objeto ProxyMetadata que sólo lee valores desde la base de datos bajo demanda. Es mucho más veloz que get_metadata() cuando sólo se quiere acceder a un pequeño número de campos desde el objeto metatados devuelto.

get_usage_count_by_id(field)[fuente]

Devuelve un mapa de identificador a cuenta de uso para todos los valores del campo especificado, que debe ser un campo de tipo varios-uno o varios-varios.

has_book(mi)[fuente]

Devuelve True si y sólo si la base de datos contiene una entrada con el mismo título que el objeto Metadata pasado como argumento. La comparación no distingue mayúsculas y minúsculas. Véase también

has_format(book_id, fmt)[fuente]

Devuelve True si y sólo si el formato existe en el disco.

has_id(book_id)[fuente]

Devuelve True si y sólo si el book_id especificado existe en la base de datos.

init()[fuente]

Inicializar esta copia en caché con datos del motor.

multisort(fields, ids_to_sort=None, virtual_fields=None)[fuente]

Devuelve una lista de identificadores de libros ordenados. Si ids_to_sort es None, devuelve todos los identificadores de libros.

los campos deben ser una lista de 2-tuplas de la forma (field_name, ascending=True|False). El campo más significativo es la primera 2-tupla.

pref(name, default=None)[fuente]

Devuelve el valor de la preferencia especificada o el valor especificado como default si la preferencia no se ha establecido.

read_backup(book_id)[fuente]

Devuelve la copia de seguridad de los metadatos OPF para el libro como una serie de bytes o None si no existe dicha copia de seguridad.

remove_books(book_ids, permanent=False)[fuente]

Eliminar los libros especificados por los book_ids de la base de datos y eliminar sus archivos de formato. Si permanent es False, los archivos de formato se dejan en la papelera.

remove_formats(formats_map, db_only=False)[fuente]

Eliminar los formatos especificados de los libros especificados.

Parámetros:
  • formats_map – Un mapa de book_id a una lista de formatos para eliminar del libro.
  • db_only – Si es True, sólo se elimina el registro del formato de la base de datos, no se borra el archivo de formato del sistema de archivos.
remove_items(field, item_ids, restrict_to_book_ids=None)[fuente]

Elimina todos los elementos del campo especificado con los id especificados. Devuelve el conjunto de id de libro afectados. restrict_to_book_ids es un conjunto de id de libros opcional. Si se especifica, sólo se eliminarán los elementos de estos libros.

rename_items(field, item_id_to_new_name_map, change_index=True, restrict_to_book_ids=None)[fuente]

Cambiar el nombre de elementos de un campo de tipo varios-uno o varios-varios, como etiquetas o series.

Parámetros:
  • change_index – Al cambiarel nombre de un campo del tipo serie cambiar también los valores de «series_index».
  • restrict_to_book_ids – Un conjunto de id de libros opcional sobre los que se realiza el cambio de nombre, de manera predeterminada incluye todos los libros.
restore_book(book_id, mi, last_modified, path, formats)[fuente]

Restaurar la entrada del libro en la base de datos de un libro que ya existe en el sistema de archivos.

restore_original_format(book_id, original_fmt)[fuente]

Restaurar el formato especificado a partir del ORIGINAL_FORMAT previamente guardado, si lo hubiera. Devuelve True en caso de éxito. El ORIGINAL_FORMAT se elimina después de una restauración correcta.

safe_read_lock

Un bloqueo de lectura segura es un bloqueo que no hace nada si el hilo ya tiene un bloqueo de escritura, de lo contrario, agrega un bloqueo de lectura. Esto es necesario para evitar DowngradeLockErrors, lo que puede suceder cuando se actualiza la caché de búsqueda en presencia de columnas compuestas. Al actualizar la caché de búsqueda se crea un bloqueo exclusivo, pero al buscar en una columna compuesta tiene lugar la lectura de valores de campo vía ProxyMetadata, que trata de obtener un bloqueo compartido. Puede haber otras situaciones que desencadenen esto.

Esta propiedad devuelve un nuevo objeto de bloqueo en cada acceso. Este objeto de bloqueo no es recursivo (por rendimiento) y sólo debe ser utilizado en una sentencia with como with cache.safe_read_lock:, de lo contrario habrá problemas.

save_original_format(book_id, fmt)[fuente]

Guardar una copia del formato especificado como ORIGINAL_FORMAT, sustituyendo cualquier ORIGINAL_FORMAT existente.

search(query, restriction=u'', virtual_fields=None, book_ids=None)[fuente]

Buscar en la base de datos con la consulta especificada, devolviendo un conjunto de identificadores de libros que coincidan.

Parámetros:
  • restriction – Una restricción que se añade como Y a la consulta especificada. Tenga en cuenta que las restricciones se almacenan en caché, por lo tanto, la búsqueda de a Y b será más lenta que a con una restricción b.
  • virtual_fields – Usado internamente (campos virtuales tales como «on_device» para búsquedas).
  • book_ids – Si no es None, un conjunto de identificadores de libros en los que buscar en vez de buscar en todos los libros.
set_conversion_options(options, fmt=u'PIPE')[fuente]

options debe ser un mapa de la forma {book_id:opciones de conversión}

set_cover(book_id_data_map)[fuente]

Establecer la portada de este libro. data puede ser un objeto de tipo QImage, QPixmap, archivo o una serie de bytes. También puede ser None, en cuyo caso se elimina cualquier portada existente.

set_field(name, book_id_to_val_map, allow_case_change=True, do_path_update=True)[fuente]

Establecer los valores del campo especificado por name. Devuelve el conjunto de todos los identificadores de libros afectados por el cambio.

Parámetros:
  • book_id_to_val_map – Mapa de book_ids a los valores que se deben aplicar.
  • allow_case_change – Si es True, se cambiará el uso de mayúsculas y minúsculas de campos de tipo varios-uno o varios-varios. Por ejemplo, si un libro tiene la etiqueta «etiqueta1» y establece la etiqueta de otro libro a «Etiqueta1», entonces los libros de ambos tendrá la etiqueta «Etiqueta1» si allow_case_change es True, de lo contrario ambos tendrán la etiqueta «etiqueta1».
  • do_path_update – Usado internamente, nunca debe cambiarse.
set_metadata(book_id, mi, ignore_errors=False, force_changes=False, set_title=True, set_authors=True, allow_case_change=False)[fuente]

Aplicar metadatos para el libro id a partir del objeto Metadata mi

Si se establece force_changes=True set_metadata actualizará los campos, incluso si mi contiene valores vacíos. En este caso, None se distingue de «vacío». Si mi.XXX es None, el XXX no se sustituye, en caso contrario sí. Las etiquetas, identificadores y los atributos de portadas son casos especiales. Las etiquetas e identificadores no se pueden establecer en None por lo que siempre se sustituirán si force_changes es True. Debe asegurarse de que mi contenga los valores que desea que tenga el libro. Las portadas siempre se cambian si se proporciona una nueva, pero nunca se borran. Tenga también en cuenta que force_changes no tiene ningún efecto en la configuración de título o autores.

set_pref(name, val)[fuente]

Establecer la preferencia especificada al el valor especificado. Ver también pref().

tags_older_than(tag, delta=None, must_have_tag=None, must_have_authors=None)[fuente]

Devuelve los identificadores de todos los libros que tienen la etiqueta tag que son anteriores al momento especificado. La comparación de etiquetas no distingue entre mayúsculas y minúsculas.

Parámetros:
  • delta – Un objeto de tipo timedelta o None. Si es None, se devuelven todos los identificadores con etiqueta.
  • must_have_tag – Si no es None, la lista de coincidencias se limitará a los libros que tengan esta etiqueta
  • must_have_authors – Una lista de autores. Si no es None, la lista de coincidencias se limitará a los libros que tengan estos autores (no distingue mayúsculas y minúsculas).
user_categories_for_books(book_ids, proxy_metadata_map=None)[fuente]

Devuelve las categorías de usuario de los libros especificados. proxy_metadata_map es opcional y es útil para aumentar el rendimiento en contextos donde ya existe un objeto ProxyMetadata de los libros. Debe ser un mapa de book_ids a los objetos ProxyMetadata correspondientes.