Documentation API pour l’interface base de données

Cette API est un fil sûr (Elle utilise un lecteur multiple, un schéma rédacteur unique fermé). Vous pouvez accéder à cette API comme ceci :

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

Si vous êtes dans une extension calibre qui est partie prenante du GUI principal de calibre, vous y obtenez l’accès comme ceci à la place :

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

Un cache mémoire du fichier metadata.db depuis une bibliothèque calibre. Cette classe sert également comme une API de sécurité pour accéder à la base de données. Le cache mémoire est maintenu dans une forme normale pour une performance maximale.

SQLITE est simplement utilisée comme une manière robuste de lire et écrire depuis metadata.db. Toute table lecture/tri/recherche/cache est ré-implémentée. Ceci était nécessaire pour un maximum de performance et de flexibilité.

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

Ajouter les livres spécifiés à la bibliothèque. Les livres doivent être un itérable de 2-tuples, chaque 2-tuple sous la forme (mi, format_map) où mi est un objet métadonnée et format_map est un dictionnaire de la forme {fmt: path_or_stream}, par exemple : {'EPUB': '/path/to/file.epub'}.

Renvoie une paire de listes : ids, duplicates. ids contient les ids de livre pour tous les livres nouvellement créés dans la base de données. duplicates contient (mi, format_map) pour tous les livres qui existent déjà dans la base de données selon l’heuristique simple de détection de doublons utilisée par has_book().

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

Ajouter les données pour le nom où val_map est une carte des book_ids vers les valeurs. Si delete_first est Vrai, toutes les données stockées précédemment seront supprimées.

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

Ajouter un format au livre spécifié. Renvoie True si le format a été ajouté avec succès.

Paramètres:
  • replace – Si Vrai, remplace le format existant, autrement si le format existe déjà, renvoie Faux.
  • run_hooks – Si Vrai, les extensions de type de fichier sont exécutées. dans le format avant et après avoir été ajoutées
  • dbapi – Usage interne uniquement.
all_book_ids(type=<type 'frozenset'>)[source]

Ensemble gelé de tous les ids de livre connus.

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

Identique à field_for, excepté qu’il agit sur de multiples livres en une fois

all_field_ids(name)[source]

Ensemble gelé d’ids pour toutes les valeurs dans le champ``name``.

all_field_names(field)[source]

Ensemble gelé de tous les champs de noms (devrait uniquement être utilisé pour les champs many-one et many-many)

author_data(author_ids=None)[source]

Renvoie la donnée auteur comme un dictionnaire avec des clés : nom, genre, lien

Si aucuns auteurs avec les ids spécifiés ne sont trouvés un dictionnaire vide est renvoyé. Si author_ids est None, les données pour tous les auteurs sont renvoyées.

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

En fonction d’une liste d’auteurs, renvoie la chaîne author_sort pour les auteurs, en préférant l’auteur assorti associé à l’auteur plutôt que la chaîne calculée.

books_for_field(name, item_id)[source]

Renvoie tous les livres associés avec l’élément identifié par item_id, où l’élément appartient au champ name.

La valeur retournée est un ensemble d’ids de livre, ou l’ensemble vide si l’élément n’existe pas.

books_in_virtual_library(vl, search_restriction=None)[source]

Affiche l’ensemble des livres dans la bibliothèque virtuelle spécifiée

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

Copier la couverture dans le fichier comme un objet dest. Renvoie False si aucune couverture n’existe ou dest est le même fichier que la couverture actuelle. dest peut aussi être un chemin dans tel cas la couverture y est copiée si le chemin est différent du chemin actuel (prendre en compte la sensibilité à la casse).

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

Copier le format fmt dans le fichier comme un objet dest. Si le format spécifié n’existe pas, indique l’erreur NoSuchFormat. dest peut aussi être un chemin (vers un fichier) dans tel cas la couverture y est copiée si et seulement si le chemin est différent du chemin actuel (prendre en compte la sensibilité à la casse).

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

Renvoie l’image de couverture ou Aucun. Par défaut, renvoie la couverture comme une chaîne de caractères.

ATTENTION : l’utilisation de as_path copiera la couverture vers un fichier temporaire et renverra le chemin vers ce fichier temporaire. Vous devez supprimer le fichier temporaire quand vous en avez terminé avec celui-ci.

Paramètres:
  • as_file – Si Vrai renvoie l’image en tant qu’objet fichier ouvert (une file d’attente de fichiers temporaires)
  • as_image – Si vrai renvoie l’image comme un objet QImage
  • as_path – Si vrai renvoie l’image comme un chemin pointant vers un fichier temporaire
data_for_find_identical_books()[source]

Renvoie les données qui peuvent être utilisées pour implémenter find_identical_books() dans un processus de travail sans accès à la bd. Voir db.utils pour une implémentation.

data_for_has_book()[source]

Renvoie les données appropriées pour être utilisées dans has_book(). Ceci peut être utilisé pour une implémentation de has_book() dans un processus de travail sans accès à la bd.

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

Effacer les données pour le nom. Par défaut efface toutes les données, si vous voulez seulement effacer les données pour certaines ids de livres, passez dans une liste d’ids de livres.

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

Mettre à jour les métadonnées pour tous les fomats du book_ids sélectionné vers les métadonnées actuelle dans la base de données.

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

Semblable à field_for, sauf qu’il évite la consultation supplémentaire pour obtenir l’objet du champ

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

Renvoie la valeur du champ name pour le livre identifié par book_id. Si un tel livre n’existe pas ou s’il n’y a pas de valeur spécifiée pour le champ name` ou qu'un tel champ n'existe pas, alors ``default_value est renvoyée.

default_value n’est pas utilisée pour title, title_sort, authors, author_sort and series_index. C’est parce que ceux-ci ont toujours des valeurs dans la base de données. default_value est utilisée pour toutes les colonnes personnalisées.

La valeur retournée pour les champs is_multiple sont toujours des tuples, même quand aucunes valeurs ne sont trouvées (en d’autres mots, default_value est ignorée). L’exception est les identifiants pour lesquels la valeur renvoyée est toujours un dict. Les tuples renvoyés sont toujours dans l’ordre du lien, c’est à dire, l’ordre dans lequel ils ont été créé.

field_ids_for(name, book_id)[source]

Renvoie les ids (en tant que tuples) pour les valeurs que le champ name à dans le livre identifié par book_id. S’il n’y a pas de valeurs, ou pas de tel livre, ou pas de tel champ, un tuple vide est renvoyé.

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

Trouve les livres qui ont un sur-ensemble d’auteurs dans mi et ont le même titre (titre est à correspondance floue). Voir aussi data_for_find_identical_books().

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

Renvoie le format de livre numérique comme une chaîne de caractères ou None si le format n’existe pas, ou que nous n’avons pas la permission d’écrire dans le fichier de livre numérique.

Paramètres:
  • as_file – Si True le format de livre numérique est renvoyé comme un objet fichier. Notez que l’objet fichier est un fichier temporaire de file d’attente, aussi si ce que vous voulez faire est de copier le format sur un autre fichier, utilisez copy_format_to() à la place pour la performance.
  • as_path – Copie le format de fichier vers un fichier temporaire et renvoie le chemin vers le fichier temporaire
  • preserve_filename – Si Vrai et renvoie un chemin le nom de fichier est le même que celui utilisé dans la bibliothèque. Notez qu’utiliser ceci signifie donner des appels répétés du même fichier temporaire (qui est recréé chaque fois)
format_abspath(book_id, fmt)[source]

Renvoie le chemin absolu du fichier livre numérique du format format. Vous ne devriez presque jamais utiliser ceci, car compromet la promesse threadsafe de cette API. A la place utilisez, copy_format_to().

Actuellement utilisé uniquement dans la liste calibredb, la visionneuse, éditer le livre, compare_format au format original, Open With et les catalogues (via get_data_as_dict()).

A part depuis la visionneuse, open with et éditer le livre, je ne crois pas qu’aucun des autres ne fassent de fichier écriture I/O avec les résultats de cet appel.

format_hash(book_id, fmt)[source]

Renvoie le hash du format spécifié pour le livre spécifié. Le type de hash est dépendant du système principal, mais il est habituellement SHA-256.

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

Renvoie le chemin, la taille et mtime pour le format spécifié. Vous ne devriez presque jamais utiliser path à moins que vous n’en ayez absolument besoin, dès qu’il est accédé il compromet directement la promesse threadsafe de cette API. A la place utilisez la méthode copy_format_to().

Paramètres:
  • allow_cache – Si Vrai les valeurs en cache sont utilisées, autrement un accès lent au système de fichiers est fait. Le cache des valeurs peut être périmé si l’accès est effectué au système de fichier en dehors de cette API.
  • update_db – Si Vrai Le champ max_size de la base de données est mis à jour pour ce livre.
formats(book_id, verify_formats=True)[source]

Renvoie le tuple pour tous les formats du livre spécifié. Si verify_format est Vrai, vérifie que les fichiers existent sur le disque.

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

Utilisé en interne pour implémenter le Navigateur d’Etiquettes

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

Donne les données pour le nom. Par défaut renvoie les données pour tous les book_ids, passez dans une liste d’ids de livre si vous voulez seulement quelques données. Renvoie un mappage du book_id à la valeur. Si une valeur particulière ne peut être décodée, utilise l’option par défaut pour celle-ci.

get_id_map(field)[source]

Renvoie un mappage des nombres id aux valeurs pour le champ spécifié. Le champ doit être un champ many-one ou many-many, autrement une ValueError est évoquée.

get_ids_for_custom_book_data(name)[source]

Renvoie un ensemble d’ids de livre pour lesquels le nom a des données.

get_item_id(field, item_name)[source]

Renvoie l’id élément pour item_name(sensible à la casse)

get_item_ids(field, item_names)[source]

Renvoie l’id élément pour item_name(sensible à la casse)

get_item_name(field, item_id)[source]

Renvoie le nom d’élément pour l’élément spécifié par item_id dans le champ spécifié. Voir aussi get_id_map().

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

Renvoie les métadonnées pour le livre identifié par book_id comme un un objet calibre.ebooks.metadata.book.base.Metadata . Notez que la liste des formats n’est pas vérifiée. Si get_cover est True, la couverture est retournée, soit un chemin au fichier temporaire comme mi.cover ou si cover_as_date est True comme mi.cover_data.

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

Renvoie les index de séries suivants pour les séries spécifiées, prendre en compte les préférences variées qui contrôlent la génération du numéro suivant de séries.

Paramètres:
  • field – Le champ series-like (par défaut à la colonne séries intégrées)
  • current_indices – Si Vrai, renvoie à la place un mappage de book_id à l’actuelle valeur series_index.
get_proxy_metadata(book_id)[source]

Semblable à get_metadata() excepté qu’il renvoie un objet ProxyMedadata qui lit uniquement les valeurs depuis la base de données à la demande. Ceci est beaucoup plus rapide que get_metadata quand seulement un petit nombre de champs ont besoin d’être accédés depuis l’objet métadonnées renvoyé.

get_usage_count_by_id(field)[source]

Renvoie un mappage de l’id au compte d’utilisation pour toutes les valeurs du champ spécifié, qui doit être un champ many-one ou many-many.

has_book(mi)[source]

Renvoie True si et seulement si la base de donnée contient une entrée avec le même titre que l’objet Metadata transmis. La comparaison est sensible à la casse. Voir aussi data_for_has_book().

has_format(book_id, fmt)[source]

Renvoie Vrai si et seulement si le format existe sur le disque

has_id(book_id)[source]

Renvoie Vrai si et seulement si le book_id spécifié existe dans la base de données.

init()[source]

Initialiser ce cache avec des données depuis le système principal.

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

Renvoie une liste des ids de livre triés. Si ids_to_sort est Aucun, tout les ids de livre sont retournés.

les champs doivent être une liste de 2-tuples de la forme (field_name, ascending = True ou False). Le champ le plus important est le 2-tuple.

pref(name, default=None)[source]

Renvoie la valeur pour la préférence spécifiée ou la valeur spécifiée comme étant par défaut si la préférence n’est pas paramétrée.

read_backup(book_id)[source]

Renvoie la sauvegarde des métadonnées OPF comme une chaîne de caractères ou Aucun si une telle sauvegarde n’existe pas.

remove_books(book_ids, permanent=False)[source]

Supprimer de la base de données les livres spécifiés par les book_ids et effacer leurs formats de fichier . Si permanent est à False, alors les formats de fichiers sont placés dans la corbeille.

remove_formats(formats_map, db_only=False)[source]

Supprimer les formats spécifiés des livres spécifiés.

Paramètres:
  • formats_map – Un mappage de book_id à une liste de formats à supprimer du livre.
  • db_only – Si Vrai, retirer uniquement l’enregistrement pour le format de la base de données, n’efface pas le fichier de format actuel du système de fichiers.
remove_items(field, item_ids, restrict_to_book_ids=None)[source]

Supprimer tous les éléments dans le champ spécifié avec les ids spécifiés. Renvoie l’ensemble des ids de livres affectés. restrict_to_book_ids est un ensemble optionnel d’ids de livres. Si spécifié les éléments seront uniquement supprimés de ces livres.

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

Renommer les éléments d’un champ many-one ou many-many comme étiquettes ou séries.

Paramètres:
  • change_index – Lors du renommage d’un champ series-like change aussi les valeurs series_index.
  • restrict_to_book_ids – Un ensemble optionnel d’ids de livres pour lesquels le renommage est effectué, par défaut à tous les livres.
restore_book(book_id, mi, last_modified, path, formats)[source]

Restaure l’entre du livre dans la base de données pour un livre qui existe déjà dans le système de fichiers.

restore_original_format(book_id, original_fmt)[source]

Restaure le format spécifié à partir du ORIGINAL_FORMAT précédemment sauvé, s’il y en a. Renvoie Vrai en cas de réussite. Le ORIGINAL_FORMAT est supprimé après une restauration réussie.

safe_read_lock

Un verrou en lecture sûr qui ne fait rien si le thread à déjà un verrou en écriture, autrement il acquiert un verrou en lecture.Ceci est nécessaire pour prévenir les DowngradeLockErrors, qui peuvent survenir quand on met à jour le cache de recherche en la présence de colonnes composées. Mettre à jour le cache de recherche préserve un verrou exclusif, mais la recherche d’une colonne composée implique de lire des valeurs de champ par l’intermédiaire de ProxyMetadata qui essaye d’obtenir un verrou partagé. Il peut y avoir d’autres scénarios qui déclenchent ceci également.

Cette propriété renvoie un nouvel objet verrou à chaque accès. Cet objet verrou n’est pas récursif (pour la performance) et doit être uniquement utilisé dans une déclaration with comme with cache.safe_read_lock: autrement de mauvaises choses peuvent survenir.

save_original_format(book_id, fmt)[source]

Sauver une copie du format spécifié comme ORIGINAL_FORMAT, écrase tout ORIGINAL_FORMAT existant.

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

Rechercher dans la base de données pour la requête spécifiée, en renvoyant un ensemble d’ids de livre correspondants.

Paramètres:
  • restriction – Une restriction qui est ANDed à la requête spécifique. Notez que ces restrictions sont en cache, dès lors une recherche pour a AND b plus lente que celle avec une restriction b.
  • virtual_fields – Utilisé en interne (champs virtuels tels que on_device pour y faire une recherche)
  • book_ids – Si n’est pas Aucun, un ensemble d’ids de livre pour les livres sera recherché à la place de rechercher tous les livres.
set_conversion_options(options, fmt=u'PIPE')[source]

les options doivent être une carte de la forme {book_id:conversion_options}

set_cover(book_id_data_map)[source]

Paramétrer la couverture pour ce livre. Les données peuvent être soit une QImage, une QPixmap, un objet fichier ou une chaîne de caractères. Elles peuvent être aussi Aucun, dans quel cas toute couverture existante sera supprimée.

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

Paramétrer les valeurs du champ spécifié par name. Renvoie l’ensemble de tous les ids de livre affectés par le changement.

Paramètres:
  • book_id_to_val_map – Mappage des book_ids aux valeurs qui devraient être appliquées.
  • allow_case_change – Si Vrai, la casse des champs many-one ou many-many sera changée. Par exemple, si un livre à l’étiquette tag1 et que vous paramétrez l’étiquette pour un autre livre à Tag1 alors les deux livres ont l’étiquette Tag1 si allow_case_change est Vrai, autrement ils ont tous les deux l’étiquette tag1.
  • do_path_update – Utilisé en interne, vous ne devriez jamais le changer.
set_metadata(book_id, mi, ignore_errors=False, force_changes=False, set_title=True, set_authors=True, allow_case_change=False)[source]

Paramétrer les métadonnées pour le livre id depuis l’objet Metadata mi.

En réglant force_changes=True forcera set_metadata à mettre à jour les champs même si mi contient des valeurs vides. Dans ce cas, “Aucun” est distingué de “vide”. Si mi.XXX est Aucun, le XXX n’est pas remplacé, autrement il l’est. Les étiquettes, identifiants, et attributs de couverture sont des cas spéciaux. Étiquettes et identifiants ne peuvent être paramétrés à Aucun aussi seront-ils toujours remplacés si force_change est Vrai. Vous devez vous assurer que mi contient les valeurs que vous voulez que le livre ait.. Les couvertures sont toujours changées si une nouvelle couverture est procurée, mais ne sont jamais supprimées. Aussi notez que force_changes n’a pas d’effet sur les réglages titre ou auteurs.

set_pref(name, val)[source]

Paramétrer la préférence spécifiée à la valeur spécifiée. Voir aussi pref().

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

Renvoie les ids de tous les livres ayant l’étiquette tag qui sont plus anciennes que le moment spécifié, la comparaison d’étiquette est insensible à la casse.

Paramètres:
  • delta – Un objet timedelta ou Aucun. Si Aucun, alors tous les ids avec l’étiquette sont retournées.
  • must_have_tag – Si pas Aucun la liste des correspondances sera restreinte aux livres qui ont cette étiquette
  • must_have_authors – Une liste d’auteurs. Si pas Aucun la liste des correspondances sera restreinte aux livres qui ont ces auteurs (insensible à la casse).
user_categories_for_books(book_ids, proxy_metadata_map=None)[source]

Retourne les catégories utilisateur pour les livres spécifiés. proxy_metadata_map est optionnel et est utile pour une amélioration de la performance, dans les contextes où un objet ProxyMetadata pour les livres existe déjà. Il devrait être une cartographie des book_ids à leurs objets correspondants ProxyMetadata.