Documentation API pour les extensions

Définit différentes classes abstraites de base qui peuvent être sous-classées pour créer de puissantes extensions. Les classes utiles sont :

Extension

class calibre.customize.Plugin(plugin_path)

Une extension calibre. Les membres utiles incluent:

• self.installation_type : Enregistre la façon dont le plugin a été installé.

• self.plugin_path : Enregistre le chemin vers le fichier ZIP le contenant

  cette extension ou None si c’est une extension intégrée

• self.site_customization: Enregistre une chaîne de personnalisation introduite

  par l’utilisateur.

Les méthodes qui devraient être annulées dans les sous-classes :

• initialize()

• customization_help()

Méthodes utiles :

• temporary_file()

• __enter__()

• load_resources()

supported_platforms = []

Liste des plateformes où fonctionne cette extension. Par exemple ['windows', 'osx', 'linux']

name = 'Trivial Plugin'

Le nom de cette extension. Vous devez le fixer à autre chose que Trivial Plugin pour que cela fonctionne.

version = (1, 0, 0)

La version de cette extension en tant que 3-tuple (majeure, mineure, révision)

description = 'Ne fait absolument rien'

Une courte chaine décrivant ce que fait l’extension

author = 'Inconnu(e)'

L’auteur de cette extension

priority = 1

Quand plus d’une extension existe pour un type de fichier, les extensions sont exécutées dans l’ordre de priorité décroissant. Les extensions avec la priorité la plus haute seront exécutées en premier. La priorité la plus haute possible est sys.maxsize. La priorité par défaut est de 1.

minimum_calibre_version = (0, 4, 118)

La version la plus récente de calibre que nécessite cette extension

installation_type = None

La façon dont ce plugin est installé

can_be_disabled = True

Si False, l’utilisateur ne pourra pas désactiver cette extension. À utiliser avec soin.

type = 'Base'

Le type de cette extension. Utilisé pour catégorisé les extensions dans le GUI

initialize()

Appelé une fois lorsque les extensions calibre sont initialisées. Les extensions sont ré-initialisées à chaque fois qu’une nouvelle extension est ajoutée. Notez également que si l’extension est en exécution dans un processus de travail, tel que pour ajouter des livres, alors l’extension sera initialisée pour tout nouveau processus de travail.

Effectuer n’importe quel initialisation spécifique d’extension ici, comme l’extraction de ressource à partir du fichier ZIP de l’extension. Le chemin vers le ZIP est disponible comme self.plugin_path.

Notez que self.site_customization n’est pas disponible à ce point-ci.

config_widget()

Implémenter cette méthode et save_settings() dans votre extension pour utiliser une boîte de dialogue de configuration personnalisée, plutôt que d’utiliser la simple personnalisation par ligne par défaut.

Cette méthode, si implémentée, doit retourner un QWidget. Le widget peut avoir une méthode optionnelle validate() qui ne prend pas d’argument et qui est appelée dès que l’utilisateur clique sur OK. Les changements sont appliqués si et seulement si la méthode retourne True.

Si pour une raison quelconque, vous ne pouvez pas réaliser la configuration à ce moment, renvoie un tuple de deux chaines (message, détails), qui seront affichés comme un dialogue d’alerte à l’utilisateur et le processus sera interrompu.

save_settings(config_widget)

Sauve les paramètres spécifiés par l’utilisateur avec config_widget

Paramètres:

config_widget – Le widget renvoyé par config_widget().

do_user_config(parent=None)

Cette méthode montre une boîte de dialogue de configuration pour cette extension. Elle renvoie True si l’utilisateur clique OK, sinon False. Les changements sont appliqués automatiquement.

load_resources(names)

Si cette extension est donnée dans un fichier ZIP (extension ajoutée par l’utilisateur), cette méthode vous permettra de charger des ressources du fichier ZIP.

Par exemple pour charger une image

pixmap = QPixmap()
pixmap.loadFromData(self.load_resources(['images/icon.png'])['images/icon.png'])
icon = QIcon(pixmap)

Paramètres:

names – Liste de chemins vers les ressources dans le ZIP utilisant / comme séparateur

Renvoie:

Un dictionnaire sous la forme {name : file_contents}. Tout nom qui n’est pas trouvé dans le fichier ZIP ne sera pas présent dans le dictionnaire.

customization_help(gui=False)

Retourne une chaîne offrant de l’aide sur comment personnalisé cette extension. Par défaut avance un NotImplementedError, qui indique que l’extension ne nécessite pas de personnalisation.

Si vous ré-implémentez cette méthode dans votre sous-classe, il sera demandé à l’utilisateur d’entrer une chaîne pour personnalisé cette extension. La chaîne de personnalisation sera disponible comme self.site_customization.

La personnalisation de site peut-être n’importe quoi, par exemple, le chemin vers un binaire nécessaire sur l’ordinateur de l’utilisateur.

Paramètres:

gui – Si True renvoie l’aide HTML, sinon renvoie l’aide en texte simple.

temporary_file(suffix)

Renvoie un objet ressemblant à un fichier qui est un fichier temporaire dans les fichiers systèmes. Ce fichier reste disponible après avoir été fermé et sera supprimé uniquement après l’extinction de l’interpréteur. Utilisé le membre name de l’objet renvoyé pour accéder au chemin complet vers le fichier temporaire créé.

Paramètres:

suffix – Le suffixe qu’aura le fichier temporaire.

cli_main(args)

Cette méthode est le point d’entrée principal pour les interfaces d’extensions en ligne de commande. Elle est appelée lorsque l’utilisateur fait: calibre-debug -r « Nom de l’Extension ». Tous les arguments sont présents dans les variables args.

FileTypePlugin

class calibre.customize.FileTypePlugin(plugin_path)

Bases : Plugin

Une extension qui est associée à un ensemble particulier de types de fichiers.

file_types = {}

Ensemble de types de fichiers pour lesquels cette extension devrait fonctionner. Utilisez “*” pour tous les types de fichiers. Par exemple : {'lit', 'mobi', 'prc'}

on_import = False

Si True, cette extension est exécutée lorsque des livres sont ajoutés à la base de donnée

on_postimport = False

Si réglé sur True, cette extension est exécutée après que des livres aient été ajoutés à la base de donnée. Dans ce cas, les méthodes postimport et postadd de l’extension sont appelées.

on_postconvert = False

Si True, ce plugin est exécuté après la conversion d’un livre. Dans ce cas, la méthode postconvert du plugin est appelée.

on_postdelete = False

Si True, ce plugin est exécuté après qu’un fichier de livre a été supprimé de la base de données. Dans ce cas, la méthode postdelete du plugin est appelée.

on_preprocess = False

Si True, cette extension est exécutée juste avant une conversion

on_postprocess = False

Si True, cette extension est exécutée après conversion sur le fichier final produit par l’extension de conversion de sortie.

type = 'Type de fichier'

Le type de cette extension. Utilisé pour catégorisé les extensions dans le GUI

run(path_to_ebook)

Exécute l’extension. Doit être implémenté dans les sous-classes. Cela devrait effectuer n’importe quelles modifications requises sur le livre numérique et renvoyer le chemin absolu vers le livre numérique modifié. Si aucune modifications ne sont nécessaire, cela devrait renvoyer le chemin vers le livre numérique original. Si une erreur est rencontrée, cela devrait amener une Exception. L’implémentation par défaut retourne simplement le chemin vers le livre numérique original. Notez que le chemin vers le fichier original (avant que n’importe quelle extension type de fichier ne soit exécutée, est disponible comme ceci self.original_path_to_file).

Le livre numérique modifié devrait être créer avec la méthode temporary_file().

Paramètres:

path_to_ebook – Chemin absolu vers le livre numérique.

Renvoie:

Chemin absolu vers le livre numérique modifié.

postimport(book_id, book_format, db)

post import est appelée, c-à-d après que le fichier de livre ait été ajouté à la base de donnée. Notez que ceci est différent de postadd() qui est appelée lorsque les données du livre sont créées pour la première fois. Cette méthode est appelée à chaque fois qu’un nouveau fichier est ajouté à un livre enregistré. Elle est utile pour modifier les données du livre se basant sur le contenu du fichier nouvellement ajouté.

Paramètres:

• book_id – L’id du livre ajouté dans la base de donnée.

• book_format – Le type de fichier du livre qui a été ajouté.

• db – Base de donnée de la bibliothèque.

postconvert(book_id, book_format, db)

Appelé après la conversion, c’est-à-dire après que le fichier de sortie de la conversion a été ajouté à la base de données. Notez qu’elle n’est exécutée qu’après une conversion, et non après l’ajout d’un livre. Elle est utile pour modifier l’enregistrement du livre en fonction du contenu du fichier nouvellement ajouté.

Paramètres:

• book_id – L’id du livre ajouté dans la base de donnée.

• book_format – Le type de fichier du livre qui a été ajouté.

• db – Base de donnée de la bibliothèque.

postdelete(book_id, book_format, db)

Appelé après la suppression, c’est-à-dire après que le fichier du livre a été supprimé de la base de données. Notez qu’il n’est pas exécuté lorsqu’un enregistrement de livre est supprimé, mais seulement lorsqu’un ou plusieurs formats du livre sont supprimés. Elle est utile pour modifier l’enregistrement du livre en fonction du format du fichier supprimé.

Paramètres:

• book_id – L’id du livre ajouté dans la base de donnée.

• book_format – Le type de fichier du livre qui a été ajouté.

• db – Base de donnée de la bibliothèque.

postadd(book_id, fmt_map, db)

post add est appelée, c-à-d après qu’un livre ait été ajouté à la base de donnée. Notez que ceci est différent de postimport(), qui est appelée lorsque un fichier de livre est ajouté à un livre existant. postadd() est appelée uniquement lorsqu’un dossier entier de livre avec éventuellement plus d’un fichier de livre a été créé pour la première fois. Ceci est utile si vous souhaitez modifier les données d’un livre dans la base de donnée lorsque le livre est initialement ajouté à calibre.

Paramètres:

• book_id – L’id du livre ajouté dans la base de donnée.

• fmt_map – Le chemin de l’emplacement du format du fichier à partir duquel le format a été ajouté. Notez que ceci pourrait ne pas indiquer un fichier existant, vu que parfois certains fichier sont ajoutés en tant que flux. Dans ce cas on pourrait avoir une valeur fausse ou un chemin inexistant.

• db – Base de donnée de la bibliothèque

Les extensions métadonnées

class calibre.customize.MetadataReaderPlugin(*args, **kwargs)

Bases : Plugin

Une extension qui implémente les métadonnées de lecture à partir d’un ensemble de types de fichier.

file_types = {}

Ensemble de types de fichier pour lesquels l’extension devrait être exécutée. Par exemple : set(['lit', 'mobi', 'prc'])

supported_platforms = ['windows', 'osx', 'linux']

Liste des plateformes où fonctionne cette extension. Par exemple ['windows', 'osx', 'linux']

version = (7, 22, 0)

La version de cette extension en tant que 3-tuple (majeure, mineure, révision)

author = 'Kovid Goyal'

L’auteur de cette extension

type = 'Lecteur de métadonnées'

Le type de cette extension. Utilisé pour catégorisé les extensions dans le GUI

get_metadata(stream, type)

Renvoie les métadonnées pour le fichier représenté par le flux (un objet-fichier qui supporte la lecture). Renvoie une exception lorsqu’il y a une erreur avec les données d’entrée.

Paramètres:

type – Le type de fichier. Garanti d’être l’une des entrées dans file_types.

Renvoie:

Un objet calibre.ebooks.metadata.book.Metadata

class calibre.customize.MetadataWriterPlugin(*args, **kwargs)

Bases : Plugin

Une extension qui implémente les métadonnées de lecture à partir d’un ensemble de types de fichier.

file_types = {}

Ensemble de types de fichier pour lesquels l’extension devrait être exécutée. Par exemple : set(['lit', 'mobi', 'prc'])

supported_platforms = ['windows', 'osx', 'linux']

Liste des plateformes où fonctionne cette extension. Par exemple ['windows', 'osx', 'linux']

version = (7, 22, 0)

La version de cette extension en tant que 3-tuple (majeure, mineure, révision)

author = 'Kovid Goyal'

L’auteur de cette extension

type = 'Créateur de métadonnées'

Le type de cette extension. Utilisé pour catégorisé les extensions dans le GUI

set_metadata(stream, mi, type)

Règle les métadonnées pour le fichier représenté par le flux (un objet-fichier qui supporte la lecture). Renvoie une exception lorsqu’il y a une erreur avec les données d’entrée.

Paramètres:

• type – Le type de fichier. Garanti d’être l’une des entrées dans file_types.

• mi – Un objet calibre.ebooks.metadata.book.Metadata

Extension de catalogue

class calibre.customize.CatalogPlugin(plugin_path)

Bases : Plugin

Une extension qui implémente un générateur de catalogue.

file_types = {}

Le type de fichier de sortie pour lesquels l’extension devrait être exécutée. Par exemple : “epub” ou “xml”

type = 'Générateur de catalogue'

Le type de cette extension. Utilisé pour catégorisé les extensions dans le GUI

cli_options = []

Les options d’analyseur de CLI spécifiques pour cette extension, déclarée en tant qu”Option namedtuple:

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()

Si l’extension n’est pas native, copier les fichiers .ui et .py de l’extension à partir du fichier ZIP vers $TMPDIR. Un entrée sera dynamiquement générée et ajotée à la boîte de dialogue du Catalogue d’Options dans calibre.gui2.dialogs.catalog.py:Catalog

run(path_to_output, opts, db, ids, notification=None)

Exécute l’extension. Doit être implémenté dans les sous-classes. Cela devrait généré le catalogue dans le format spécifié dans file_types, renvoyant le chemin absolu vers le fichier catalogue généré. SI un erreur est rencontrée, cela devrait faire apparaître une Exception.

Le fichier catalogue généré devrait être créer avec la méthode temporary_file().

Paramètres:

• path_to_output – Chemin absolu vers le fichier catalogue généré.

• opts – Un dictionnaire d’arguments mot-clef

• db – Un objet BaseDeDonnéeLibrairie2

Extension de téléchargement de métadonnées

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

Bases : Plugin

type = 'Source de métadonnées'

Le type de cette extension. Utilisé pour catégorisé les extensions dans le GUI

author = 'Kovid Goyal'

L’auteur de cette extension

supported_platforms = ['windows', 'osx', 'linux']

Liste des plateformes où fonctionne cette extension. Par exemple ['windows', 'osx', 'linux']

capabilities = frozenset({})

Ensemble de capacités supportées par cet extension. Les capacités utiles sont: “identify”, “cover”

touched_fields = frozenset({})

Liste de champ de métadonnée qui peuvent potentiellement être téléchargée par cette extension pendant la phase d’identification

has_html_comments = False

Fixer ceci à True si votre extension renvoie des commentaires formatés en HTML

supports_gzip_transfer_encoding = False

Paramétrer ceci à True veut dire que l’objet navigateur indiquera qu’il prend en charge l’encodage de transfert gzip. Ceci peu accélérer les téléchargements, soyez sûr que la source supporte effectivement les encodages de transfert gzip correctement.

ignore_ssl_errors = False

Paramétrer à TRUE pour ignorer les erreurs de certificat HTTPS lors de la connexion à cette source.

cached_cover_url_is_reliable = True

Des URLs de couverture dans le cache peuvent parfois être peu sûr (càd. que le téléchargement pourrait échouer ou que l’image pourrait ne pas fonctionner). Si c’est souvent le cas avec cette source, fixer à False

options = ()

Un liste d’objet Option. Ils seront utilisés pour construire automatiquement le widget de configuration pour cette extension

config_help_message = None

Une chaîne qui sera affichée au sommet du widget de configuration pour cette extension

can_get_multiple_covers = False

Si True cette source peut renvoyer de multiples couvertures pour une demande donnée

auto_trim_covers = False

Si fixer à True les couvertures téléchargées par cette extension seront automatiquement rognées.

prefer_results_with_isbn = True

Si réglé à True, et cette source retourne de multiples résultats pour une requête, certains de ceux-ci ont des ISBN et certains de ceux-ci n’en ont pas, le résultat sans ISBN sera ignoré.

is_configured()

Renvoie False si votre extension nécessite d’être configurée avant de pouvoir être utilisé. Par exemple, cela pourrait nécessiter un utilisateur/mot de passe/clef de greffon.

customization_help()

Retourne une chaîne offrant de l’aide sur comment personnalisé cette extension. Par défaut avance un NotImplementedError, qui indique que l’extension ne nécessite pas de personnalisation.

Si vous ré-implémentez cette méthode dans votre sous-classe, il sera demandé à l’utilisateur d’entrer une chaîne pour personnalisé cette extension. La chaîne de personnalisation sera disponible comme self.site_customization.

La personnalisation de site peut-être n’importe quoi, par exemple, le chemin vers un binaire nécessaire sur l’ordinateur de l’utilisateur.

Paramètres:

gui – Si True renvoie l’aide HTML, sinon renvoie l’aide en texte simple.

config_widget()

Implémenter cette méthode et save_settings() dans votre extension pour utiliser une boîte de dialogue de configuration personnalisée, plutôt que d’utiliser la simple personnalisation par ligne par défaut.

Cette méthode, si implémentée, doit retourner un QWidget. Le widget peut avoir une méthode optionnelle validate() qui ne prend pas d’argument et qui est appelée dès que l’utilisateur clique sur OK. Les changements sont appliqués si et seulement si la méthode retourne True.

Si pour une raison quelconque, vous ne pouvez pas réaliser la configuration à ce moment, renvoie un tuple de deux chaines (message, détails), qui seront affichés comme un dialogue d’alerte à l’utilisateur et le processus sera interrompu.

save_settings(config_widget)

Sauve les paramètres spécifiés par l’utilisateur avec config_widget

Paramètres:

config_widget – Le widget renvoyé par config_widget().

get_author_tokens(authors, only_first_author=True)

Prend une liste d’auteurs et retourne une liste de jetons utiles pour une demande de recherche AND. Cette fonction tente de renvoyer des jetons dans l’ordre prénom, second nom, nom de famille, en escomptant que si une virgule est dans le nom d’auteur, le nom est dans le nom de famille, sous forme des autres noms.

get_title_tokens(title, strip_joiners=True, strip_subtitle=False)

Prend un titre et retourne une liste de jetons utiles pour une requête de recherche AND. Exclus les conjonctions(optionnel) et la ponctuation.

split_jobs(jobs, num)

Divise une liste de travaux en sous groupe, aussi uniformément que possible

test_fields(mi)

Retourne le premier champs de self.touched_fields qui est nul sur le demi objet

clean_downloaded_metadata(mi)

Appelez cette méthode dans votre méthode d’identification de votre extension pour normaliser les métadonnées avant de rentrer l’objet Métadonnées dans le result_queue. Vous pouvez, bien sûr, utiliser un algorithme personnalisé adapté pour la source de métadonnée.

get_book_url(identifiers)

Renvoie un 3-tuple ou None. Le 3-tuple est sous la forme: (identifier_type, identifier_value, URL). L’URL est celle du livre identifié par les identifiants à la source. identifier_type, identifier_value, spécifiant l’identifiant correspondant à l’URL. Cet URL doit être consultable pour un être humain utilisant un navigateur. Elle est censée offrir un lien cliquable pour l’utilisateur pour visiter facilement les pages du livre à la source. Si aucun URL n’est trouvé, renvoie None. Cette méthode doit être rapide, et cohérente, à implémenter uniquement s’il est possible de construire l’URL à partir d’un schéma connu d’identifiants.

get_book_url_name(idtype, idval, url)

Renvoie un nom lisible par un humain pour la valeur de retour de get_book_url()

get_book_urls(identifiers)

Outrepassez cette méthode si vous souhaiteriez retourner de multiples URLs pour ce livre. Renvoie une liste de 3-tuples. Par défaut cette méthode appelle simplement get_book_url().

get_cached_cover_url(identifiers)

Renvoie l’URL de la couverture mise en cache pour le livre identifié par le dictionnaire d’identifiants ou None si cette URL n’existe pas.

Noter que cette méthode doit uniquement renvoyer des URLs validées, càd. pas des URLs qui pourrait finir en une image de couverture générique ou une erreur « not found »

id_from_url(url)

Analyser une URL et retourner un tuple du formulaire : (identifier_type, identifier_value). Si l’URL ne correspond pas au modèle de la source de métadonnées, renvoyer None.

identify_results_keygen(title=None, authors=None, identifiers={})

Renvoie une fonction qui est utilisée pour générer une clef qui peut trier les objets Métadonnées par leur pertinence en fonction d’une recherche donnée (titre, auteurs, identifiants).

Ces clefs sont utilisées pour trier les résultats d’un appel de identify().

Pour plus de détails sur l’algorithme par défaut voir InternalMetadataCompareKeyGen. Ré-implémentez cette fonction dans votre extension si l’algorithme par défaut n’est pas adapté.

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

Identifie un livre par son Titre/Auteur/ISBN/etc.

Si des identifiants sont spécifiés et qu’aucune n’est trouvée et que cette source de métadonnée ne contient pas tous les identifiants demandé (par exemple, tous les ISBNs d’un livre), cette méthode devrait réessayer avec juste le titre et l’auteur (s’ils ont été spécifiés).

Si cette source de métadonnées fournit aussi des couvertures, l’URL de la couverture devrait être mis en cache pour qu’une demande suivant dans une API pour chercher les couvertures avec le même ISBN/identifiant spécial ne nécessite pas de rechercher l’URL de la couverture à nouveau. Utiliser le cache API pour ceci.

Chaque métadonnée introduite dans result_queue avec cette méthode doit avoir un attribut source_relevance qui est un entier indiquant l’ordre dans lequel les résultats seront rendus par la source de métadonnée pour cette recherche. Cet entier sera utilisé par compare_identify_results(). Si l’ordre n’a pas d’importance, fixer à zéro pour chaque résultat.

Assurez-vous que toutes les informations de mappage de couverture/ISBN sont mises en cache avant que l’objet Metadata ne soit placé dans result_queue.

Paramètres:

• log – Un fichier log, utiliser le pour produire des informations de débogage/d’erreurs

• result_queue – Une File d’Attente de résultats, les résultats devraient y être mis. Chaque résultat est une métadonnée

• abort – Si abort.is_set() renvoie True, annule les futurs exécutions et retourne le plus vite possible

• title – Le titre du livre, peut être None

• authors – Une liste d’auteur du livre, peut être None

• identifiers – Un ensemble d’autres identifiants, le plus souvent {“isbn”:”1234…”}

• timeout – « Timeout » en seconde, aucune requête réseau ne devrait durer plus longtemps que « timeout ».

Renvoie:

None si aucune erreur n’apparaît, sinon une représentation unicode de l’erreur adaptée pour le visionnage par l’utilisateur

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

Télécharge une couverture et l’insère dans result_queue. Les paramètres auront tous le même sens que pour identify(). Insère (self, cover_data) dans result_queue.

Cette méthode devrait utiliser les URLs de couvertures mise en cache par efficience le plus souvent possible. Quand aucune donnée n’est présente en cache, la plupart des extensions appel simplement identify et utilise ces résultats.

Si le paramètre get_best_cover est True dans cette extension et que cette extension peut récupérer de multiples couvertures, elle ne devrait prendre que la « meilleure ».

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

Génère une sorte de clef pour la comparaison de la pertinence des métadonnée, en fonction d’une recherche. Ceci est utilisé uniquement pour comparer des résultats d’une même source de métadonnées, pas à travers de différentes sources.

La clé de tri garanti que l’ordre croissant de tri soit trié par pertinence décroissante.

L’algorithme est:

• Préfère des résultats qui ont au moins un identificateur égal à celui de la requête

• Préfère des résultats avec une URL de couverture en cache

• Préfère des résultats avec tous les champs disponible remplis

• Préfère les résultats avec la même langue que la langue de l’interface utilisateur actuelle

• Préfère des résultats qui ont exactement le même titre que la recherche

• Préfère des résultats qui ont des plus longs commentaires (plus de 10% plus grand)

• Utilise la pertinence du résultat comme reporté dans la recherche de source de métadonnées

  machine

Extension de conversion

class calibre.customize.conversion.InputFormatPlugin(*args)

Bases : Plugin

Les InputFormatPlugins sont responsable de la conversion d’un document en HTML+OPF+CSS+etc. Le résultat de la conversion doit être encodé en UTF-8. L’action principale se passe dans convert().

type = 'Entrée de conversion'

Le type de cette extension. Utilisé pour catégorisé les extensions dans le GUI

can_be_disabled = False

Si False, l’utilisateur ne pourra pas désactiver cette extension. À utiliser avec soin.

supported_platforms = ['windows', 'osx', 'linux']

Liste des plateformes où fonctionne cette extension. Par exemple ['windows', 'osx', 'linux']

file_types = {}

Ensemble de type de fichier pour lesquels l’extension devrait être exécuté. Par exemple : set(['azw', 'mobi', 'prc'])

is_image_collection = False

Si True, cette extension d’origine génère un ensemble d’image, une par fichier HTML. Ceci peut-être fait dynamiquement, dans la méthode de conversion si les fichiers d’origines peuvent être des ensembles d’images ou pas. Si vous fixer ceci à True, vous devez implémenter la méthode get_images() qui renvoie une liste d’images.

core_usage = 1

Nombre de cœur du CPU utilisés par cette extension. Une valeur de -1 signifie qu’elle utilise tous les cœurs disponibles

for_viewer = False

Si fixer à True, cette extension d’origine effectuera un exécution spéciale pour que son résultat soit approprié au visionnage

output_encoding = 'utf-8'

L’encodage dans lequel cette extension d’origine crée le fichier. Une valeur de None signifie que l’encodage est indéfini et doit être détecter individuellement

common_options = {<calibre.customize.conversion.OptionRecommendation object>}

Les options partagées par toutes les extensions de Format d’Entrée. N’outrepasses pas en sous-classe. Utiliser options à la place. Chaque option doit être un exemple de OptionRecommendation.

options = {}

Des options pour personnaliser le comportement de cette extension. Chaque option doit être un exemple de OptionRecommendation.

recommendations = {}

Un ensemble de 3-tuples sous la forme (option_name, recommended_value, recommendation_level)

get_images()

Renvoie une liste de chemin absolu vers les images, si cette extension d’origine représente une collection d’image. La liste d’images est dans le même ordre que le manifeste et la TdM

convert(stream, options, file_ext, log, accelerators)

Cette méthode doit être implémentée en sous-classe. Elle doit renvoyer le chemin vers le fichier OPF créé ou un cas OEBBook. Tous les fichiers sortant devrait être contenu dans ce dossier. Si cette extension crée des fichiers en dehors du dossier ils doivent être supprimés/marqués pour suppression avant le résultat de cette méthode.

Paramètres:

• stream – Un objet ressemblant à un fichier qui contient le fichier original.

• options – Des options pour personnalisés le processus de conversion. Garanti d’avoir des attributs correspondant à toutes les options déclarée dans cette extension. De plus, il y aura un attribut « verbose »(bavard) qui prend des valeurs entières à partir de zéro. Plus le nombre est haut, plus l’extension est bavarde. Un autre attribut utile est input_profile qui est un exemple de calibre.customize.profiles.InputProfile.

• file_ext – L’extension (sans le .) du fichier original. Garanti d’être un des file_types supporté par cette extension.

• log – Un objet calibre.utils.logging.Log. Tous les fichiers de sorties devraient utiliser cet objet.

• accelerators – Un dictionnaire d’informations variées que l’extension d’origine peut accéder facilement pour accélérer les étapes suivantes de la conversion.

postprocess_book(oeb, opts, log)

Appelé pour permettre l’extension d’origine d’effectuer du post-traitement après que le livre ait été divisé.

specialize(oeb, opts, log, output_fmt)

Appelé pour permettre à l’extension d’origine pour spécialiser le livre divisé pour un format de sortie particulier. Appelé après postprocess_book et avant toutes transformations effectuée sur le livre divisé.

gui_configuration_widget(parent, get_option_by_name, get_option_help, db, book_id=None)

Appelé pour créer un widget utilisé pour configurer cette extension dans le GUI de calibre. Le widget doit être une instance de la classe PluginWidget. Voir les d’extensions implémentées d’origine pour des exemples.

class calibre.customize.conversion.OutputFormatPlugin(*args)

Bases : Plugin

Les OutputFormatPlugins sont responsables de la conversion d’un document OEB (OPF+HTML) vers le livre numérique de sortie.

Le document OEB peut être supposé être encodé en UTF-8. L’action principale se passe dans conversion().

type = 'Sortie de conversion'

Le type de cette extension. Utilisé pour catégorisé les extensions dans le GUI

can_be_disabled = False

Si False, l’utilisateur ne pourra pas désactiver cette extension. À utiliser avec soin.

supported_platforms = ['windows', 'osx', 'linux']

Liste des plateformes où fonctionne cette extension. Par exemple ['windows', 'osx', 'linux']

file_type = None

Le type de fichier (l’extension sans le point) que cette extension produit

common_options = {<calibre.customize.conversion.OptionRecommendation object>}

Les options partagées par toutes les extensions de Format d’Entrée. N’outrepasses pas en sous-classe. Utiliser options à la place. Chaque option doit être un exemple de OptionRecommendation.

options = {}

Des options pour personnaliser le comportement de cette extension. Chaque option doit être un exemple de OptionRecommendation.

recommendations = {}

Un ensemble de 3-tuples sous la forme (option_name, recommended_value, recommendation_level)

property description

str(object=””) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Créez un nouvel objet chaîne à partir de l’objet donné. Si un encodage ou des erreurs sont spécifiés, l’objet doit alors exposer un tampon de données qui sera décodé en utilisant l’encodage et le gestionnaire d’erreurs donnés. Sinon, renvoie le résultat de object.__str__() (si défini) ou repr(object). encoding default to sys.getdefaultencoding(). errors default to “strict”.

convert(oeb_book, output, input_plugin, opts, log)

Fournit le contenu de oeb_book (qui est une instance de calibre.ebooks.oeb.OEBBook) au fichier spécifié par la sortie.

Paramètres:

• output – Soit un fichier soit une chaîne. Si c’est une chaîne, c’est le chemin vers un dossier qui peut exister ou pas. L’extension de sortie devrait écrire ses restitutions dans ce dossier. Si c’est un fichier, l’extension de sortie devrait écrire ces productions dans le fichier.

• input_plugin – L’extension d’origine qui a été utilisé au début de la pipeline de conversion.

• opts – Des options de conversions. Garantie d’avoir des attributs correspondant aux OptionRecommendations de cette extension.

• log – L’enregistreur. Sauver des messages d’info/débogage etc. en utilisant ceci.

specialize_options(log, opts, input_fmt)

Peut être utilisé pour modifier les valeurs des options de conversion, telles qu’elles sont utilisées par le pipeline de conversion.

specialize_css_for_output(log, opts, item, stylizer)

Peut-être utilisé pour effectuer des changements dans le CSS durant le processus d’aplanissement CSS.

Paramètres:

• item – L’objet (fichier HTML) étant traité

• stylizer – Un objet Styliste contenant les styles aplani pour l’objet. Vous pouvez obtenir les styles pour n’importe quel élément par stylizer.style(élément).

gui_configuration_widget(parent, get_option_by_name, get_option_help, db, book_id=None)

Appelé pour créer un widget utilisé pour configurer cette extension dans le GUI de calibre. Le widget doit être une manipulation de la classe PluginWidget. Voir la création d’extensions d’origines pour des exemples.

Pilotes de périphérique

La classe de base pour tous les pilotes de périphérique est DevicePlugin. Cependant, si votre périphérique expose un port USBMS au système opérateur, vous devriez utiliser la classe USBMS à la place car elle implémente toute la logique nécessaire pour supporter ce genre de périphérique.

class calibre.devices.interface.DevicePlugin(plugin_path)

Bases : Plugin

Définit l’interface qui devrait être implémentée par les derniers processus qui communiquent avec le lecteur de livre numérique.

type = 'Interface du périphérique'

Le type de cette extension. Utilisé pour catégorisé les extensions dans le GUI

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

Liste ordonnée de formats supportés

VENDOR_ID = 0

VENDOR_ID peut être soit un entier, une liste d’entiers ou un dictionnaire. Si c’est un dictionnaire, cela doit être un dictionnaire de dictionnaires sous la forme:

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

PRODUCT_ID = 0

Un entier ou une liste d’entiers

BCD = None

BCD peut être soit None pour ne pas distingué entre les périphériques basé sur BCD, ou il peut être une liste des nombres BCD de tous les périphériques supportés par ce pilote.

THUMBNAIL_HEIGHT = 68

Hauteur de l’aperçu sur le périphérique

THUMBNAIL_COMPRESSION_QUALITY = 75

Qualité de compression pour les vignettes. Paramétrer ceci proche de 100 pour obtenir une meilleure qualité d’étiquette avec moins d’artefacts de compression. Bien sûr, les vignettes grandiront en conséquence.

WANTS_UPDATED_THUMBNAILS = False

Fixer ceci à True si le périphérique supporte les mises à jours d’aperçus de couverture pendant sync_booklists. Le fixer à True demandera à device.py de rafraîchir les aperçus de couverture pendant la correspondance de livre.

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

Soit les métadonnées des livres sont fixées via le GUI.

CAN_DO_DEVICE_DB_PLUGBOARD = False

Soit le périphérique peut gérer tableau de métadonnée device_db

path_sep = '/'

Le séparateur de chemin pour les chemins vers les livres sur le périphérique

icon = 'reader.png'

Icône de ce périphérique

UserAnnotation

alias de Annotation

OPEN_FEEDBACK_MESSAGE = None

Le GUI affiche ceci en tant que message dans la barre d’état si ce n’est pas None. Utile si l’ouverture peut prendre du temps

VIRTUAL_BOOK_EXTENSIONS = frozenset({})

Ensemble d’extensions qui sont des « livres virtuels » sur le périphérique et par conséquent ne peuvent être vus/sauvés/ajoutés à la bibliothèque. Par exemple : frozenset(['kobo'])

VIRTUAL_BOOK_EXTENSION_MESSAGE = None

Message à afficher à l’utilisateur pour les extensions de livre virtuel

NUKE_COMMENTS = None

S’il faut détruire les commentaires dans la copie du livre envoyé au périphérique . Si ce n’est pas None ce devrait être une courte chaîne qui remplacera le commentaire.

MANAGES_DEVICE_PRESENCE = False

Si True, indique que ce pilote gère entièrement la détection de périphérique, l’éjection etc. Si vous réglez à True, vous devez implémenter les méthodes detect_managed_devices et debug_managed_device_detection. Un pilote avec ceci réglé à True est responsable de la détection des périphériques, de la gestion d’une liste d’exclusion des périphérique, une liste de périphérique éjectés, etc. calibre utilisera périodiquement la méthode detect_managed_devices() et si elle retourne un périphérique détecté, calibre appellera open(). open() sera appelé à chaque fois qu’un périphérique est renvoyé même si des appels précédents à open() ont échoués, donc le pilote doit maintenir sa propre liste d’exclusion de périphériques qui ont échoués. Similairement, à l’éjection, calibre utilisera eject() et assume alors que le prochain appel à detect_managed_devices() renvoye None, il appellera post_yank_cleanup().

SLOW_DRIVEINFO = False

Si fixer à True, calibre utilisera la méthode get_driveinfo() après que la liste de livre a été chargée pour obtenire le driveinfo.

ASK_TO_ALLOW_CONNECT = False

Si fixer à True, calibre demandera à l’utilisateur s’il veut gérer le périphérique avec calibre, la première fois qu’il est détecté. Si vous fixez ceci à True, vous devez implémenter get_device_uid() et ignore_connected_device() et get_user_blacklisted_devices() et set_user_blacklisted_devices()

user_feedback_after_callback = None

Fixer ceci à un dictionnaire de la forme {“title”:title, “msg”:msg, “det_msg”:detailed_msg} pour que calibre fasse surgir un message à l’utilisateur après que quelques rappels aient été fait ( actuellement uniquement upload_books). Il faut faire attention à ne pas noyer l’utilisateur par trop de messages. Cette variable est vérifiée après chaque rappel, donc utilisez la uniquement lorsque c’est réellement nécessaire.

classmethod get_open_popup_message()

L’interface graphique affiche ceci comme une popup non modale. Devrait être une instance de OpenPopupMessage

is_usb_connected(devices_on_system, debug=False, only_presence=False)

Renvoye True , device_info si un périphérique géré par cette extension est actuellement connecté.

Paramètres:

devices_on_system – Liste des périphériques actuellement connectés

detect_managed_devices(devices_on_system, force_refresh=False)

Appelé uniquement si MANAGES_DEVICE_PRESENCE est True.

Cherche des périphérique que ce pilote peut gérer. Devrait renvoyer un objet périphérique si un périphérique est trouvé. Cet objet sera passé à la méthode open() en tant que connected_device. Si aucun périphérique n’est trouvé, renvoie None. L’objet renvoyé peut être n’importe quoi, calibre ne l’utilise pas, il est uniquement passé dans open().

Cette méthode est appelée périodiquement par le GUI, donc soyez sûr qu’il n’utilise pas trop de ressource. Utilisez un cache pour pour éviter de scanner répétitivement le système.

Paramètres:

• devices_on_system – Ensemble de périphériques USB trouvés sur le système.

• force_refresh – Si True et que le pilote utilise un cache pour prévenir les scan répétés, le cache doit être flushé.

debug_managed_device_detection(devices_on_system, output)

Appelé uniquement si MANAGES_DEVICE_PRESENCE est True.

Devrait écrire des informations sur les périphériques détectés par le système pour être affiché, qui devrait être un objet ressemblant à un fichier.

Devrait renvoyer True si un périphérique était détecter et effectivement ouvert, sinon False.

reset(key='-1', log_packets=False, report_progress=None, detected_device=None)

Paramètres:

• key – La clef pour débloquer le périphérique

• log_packets – Si True, le paquet envoyé ou reçu au périphérique est mis au registre

• report_progress – Une fonction qui est appelée avec un % de progression (un nombre en 0 et 100) pour différentes tâches. Si on utilise -1 cela veut dire que la tâche n’a aucune information de progression

• detected_device – Les informations de périphérique recueilient par l’analyse de périphérique

can_handle_windows(usbdevice, debug=False)

Une méthode optionnelle pour effectuer de plus amples vérifications sur un périphérique pour savoir si ce pilote est capable de le gérer. Sinon, cela devrait renvoyer False. Cette méthode est appelée uniquement après que le vendeur, l’identifiant du produit et le bcd sont appariés, donc elle peut faire des vérifications nécessitant pas mal de temps. L’implémentation par défaut renvoye True. Cette méthode est appelée uniquement sur Windows. voir aussi can_handle().

Notez que pour les périphériques basés sur USBMS cette méthode par défaut délègue à can_handle(). Donc vous avez seulement besoin d’outrepasser can_handle() dans votre sous-classe de USBMS.

Paramètres:

usbdevice – Un périphérique USB est rapporté par calibre.devices.winusb.scan_usb_devices()

can_handle(device_info, debug=False)

Version Unix de can_handle_windows().

Paramètres:

device_info – Est un tuple de (vid, pid, bcd, manufacturer, product, serial number)

open(connected_device, library_uuid)

Effectue n’importe quel initialisation spécifique de périphérique. Appelé après que le périphérique soit détecté mais avant que n’importe quelle fonction qui communique avec le périphérique. Par exemple: Pour les périphériques qui se présentent comme des périphériques de stockage de masse USB, cette méthode devrait être responsable du montage du périphérique ou si le périphérique a été monté automatiquement, de trouver où il a été monté. La méthode calibre.devices.usbms.device.Device.open() a une implémentation de cette fonction qui devrait servir comme un bon exemple pour les périphériques de stockage de masse USB.

Cette méthode peut créer une exception OpenFeedback pour afficher un message à l’utilisateur.

Paramètres:

• connected_device – Le périphérique que nous essayons actuellement d’ouvrir. C’est un tuple (vendor id, product id, bcd, manufacturer name, product name, device serial number). Toutefois, certains périphériques n’on aucun numéro de séries et sur Windows seul les trois premier champs sont présent, les autres sont None

• library_uuid – L’UUID de la bibliothèque calibre actuelle. Peut être None s’il n’y a pas de bibliohèque (par exemple lorsqu’il est utilisé de l’invité de commande).

eject()

Démonte/éjecte le périphérique de l’OS. Ceci ne vérifie pas s’il y a des travaux GUI en attente qui nécessite communication avec le périphérique.

NOTEZ: Que cette méthode peut ne pas être appelée sur le même fil que le reste des méthodes périphériques.

post_yank_cleanup()

Appelé si l’utilisateur retire le périphériques sans l’avoir éjecter préalablement.

set_progress_reporter(report_progress)

Pose une fonction pour rapporter les information de progression.

Paramètres:

report_progress – Une fonction qui est appelée avec un % de progression (un nombre en 0 et 100) pour différentes tâches. Si on utilise -1 cela veut dire que la tâche n’a aucune information de progression

get_device_information(end_session=True)

Demande ses informations au périphérique. Voir L{DeviceInfoQuery}.

Renvoie:

(nom du périphérique, version du périphérique, version du programme sur le périphérique, type MIME) Le tuple peut parfois avoir un cinquième élément, qui est dictionnaire d’information sur le lecteur. Voir usbms.driver pour un exemple.

get_driveinfo()

Renvoie le dictionnaire driveinfo. Habituellement appélé de get_device_information(), mais si le chargement du driveinfo est lent pour ce lecteur, alors il devrait fixer SLOW_DRIVEINFO. Dans ce cas, cette méthode sera appelée par calibre après que la liste de livre ait été chargée. Notez que ceci n’est pas appelé sur le fil du périphérique, donc le pilote devrait cacher les informations du pilote dans la méthode books() et cette fonction devrait renvoyer les données cachées.

card_prefix(end_session=True)

Renvoie une liste de 2 éléments des préfixes vers les chemins sur les cartes. Si aucune carte n’est présent, None est fixé comme le préfixe de la carte. e.g. (“/place”, “/place2”) (None, “place2”) (“place”, None) (None, None)

total_space(end_session=True)

Récupère l’espace disponible sur les points de montages:

1. Mémoire principale

2. Carte Mémoire A

3. Carte Mémoire B

Renvoie:

Une liste à 3 éléments avec des espaces entier en bit de (1, 2, 3). Si un périphérique particulier n’a pas l’une de ces locations, il devrait retourner à 0.

free_space(end_session=True)

Récupère l’espace disponible sur les points de montage:

1. Mémoire principale

2. Carte A

3. Carte B

Renvoie:

Une liste à 3 éléments avec des espaces entier en bit de (1, 2, 3). Si un périphérique particulier n’a pas l’une de ces locations, il devrait retourner à -1.

books(oncard=None, end_session=True)

Renvoie une liste des livres numérique sur le périphérique.

Paramètres:

oncard – Si “carda” ou “cardb”, renvoie une liste de livres numériques sur la carte de stockage spécifique, sinon renvoie une liste de livres numériques dans la mémoire principale du périphérique. Si une carte est spécifiée et qu’aucun livre n’est dans la carte, renvoie une liste vide.

Renvoie:

Une BookList

upload_books(files, names, on_card=None, end_session=True, metadata=None)

Envoie une liste de livres au périphérique. Si un fichier existe déjà sur le périphérique, il devrait être remplacé. Cette méthode devrait soulever une FreeSpaceError s’il n’y a pas d’espace sur le périphérique. Le texte dans la FreeSpaceError doit contenir le mot « carte » si « on_card » n’est pas None il doit contenir le mot « mémoire ».

Paramètres:

• files – Une liste de chemins

• names – Une liste de noms que les livres devraient avoir une fois envoyé au périphérique. len(names) == len(files)

• metadata – Si n’est pas None, est une liste d’objets Métadonnées. L’idée est d’utiliser la métadonnée pour déterminer où mettre le livre sur le périphérique. len(metadata) == len(files). En plus de la couverture habituelle(chemin vers la couverture), il peut aussi y avoir un attribut d’aperçu, qui devrait être utilisée préférentiellement. L’attribut d’aperçu est de la form (largeur, hauteur, cover_data en jpeg).

Renvoie:

Une liste d’ensemble de tuples à 3 éléments. La liste est faite pour être passée à add_books_to_metadata().

classmethod add_books_to_metadata(locations, metadata, booklists)

Ajoute des emplacements à la liste de livres. cette fonction ne doit pas communiquer avec le périphérique.

Paramètres:

• locations – Résultat d’un appel à L{upload_books}

• metadata – Liste d’objets Métadonénes, même chose que upload_books().

• booklists – En tuple contenant le résultat d’appels à (books(oncard=None)(), books(oncard='carda')(), :meth`books(oncard=”cardb”)`).

delete_books(paths, end_session=True)

Supprime les livre aux chemins sur le périphérique.

classmethod remove_books_from_metadata(paths, booklists)

Retire les livres de la liste de métadonnées. Cette fonction ne doit pas communiquer avec le périphérique.

Paramètres:

• paths – les chemins vers les livres sur le périphérique.

• booklists – En tuple contenant le résultat d’appels à (books(oncard=None)(), books(oncard='carda')(), :meth`books(oncard=”cardb”)`).

sync_booklists(booklists, end_session=True)

Met à jour les métadonnées sur le périphérique.

Paramètres:

booklists – En tuple contenant le résultat d’appels à (books(oncard=None)(), books(oncard='carda')(), :meth`books(oncard=”cardb”)`).

get_file(path, outfile, end_session=True)

Lit le fichier à path sur le périphérique et l’écrit sur un fichier extérieur.

Paramètres:

outfile – un objet ressemblant à un fichier sys.stdout ou le résultat d’un appel à une open()

classmethod config_widget()

Devrait renvoyer un QWdiget. Le QWidget contient les paramètres pour l’interface du périphérique.

classmethod save_settings(settings_widget)

Devrait sauver les paramètres sur le disque. Prend le widget créer dans config_widget() et sauve tous les paramètres sur le disque.

classmethod settings()

Devrait renvoyer un objet opts. Les objets opts devrait au moins avoir un attribut format_map qui est une liste ordonnée de formats pour le périphérique.

set_plugboards(plugboards, pb_func)

fournit au pilote le l’ensemble actuel de tableaux de connexion et une fonction pour sélectionner un tableau de connexion spécifique. Cette méthode est appelée immédiatement avant add_books et sync_booklists.

pb_func est appelable avec la signature suivante:

def pb_func(device_name, format, tableaux de connexion)

Vous donnez le nom actuel du périphérique(soit le nom de classe du périphérique soit DEVICE_PLUGBOARD_NAME), le format qui vous intéresse (un “real” format ou “device_db”), et les tableaux de connexion (ceux donnés par set_plugboards, au même endroit qu’où vous avez eu cette méthode).

Renvoie:

None ou unique tableau de connexion

set_driveinfo_name(location_code, name)

Fixe le nom du périphérique dans le driveinfo à “name”. Ce Paramètre persistera jusqu’à ce que le fichier soit recréer ou que le nom soit changé à nouveau.

Des périphériques n’étant pas des disques devrait implémenter cette méthode basée sur les codes d’emplacement renvoyé par la méthode get_device_information().

prepare_addable_books(paths)

En fonction d’une liste de chemins, renvoie une autre liste de chemins. Ces chemins pointe vers des versions cumulable des livres.

S’il y a une erreur dans la préparation d’un livre, alors au lieu du chemin, la position dans la liste renvoyée pour ce livre devrait être un 3-tuple (original_path, l’exception, retraçage)

startup()

Appelé lorsque calibre démarre le périphérique. Fait toutes les initialisations requises. Notez que de multiples utilisation de la classe peuvent être instanciée, et donc __init__ peut être appelé de nombreuse fois, mais une seule instance utilisera cette méthode. Cette méthode est appelée sur le fil périphérique, pas celui du GUI.

shutdown()

Appelé lorsque calibre s’éteint, soit réellement, soit pour redémarrer. Fais n’importe quel nettoyage nécessaire. Cette méthode est appelée sur le fil périphérique, pas celui du GUI.

get_device_uid()

Doit rendre un identificateur unique pour le périphérique connecté (ceci est appelé immédiatement après un appel réussi à open()). Vous devez implémenter cette méthode si vous fixez ASK_TO_ALLOW_CONNECT = True

ignore_connected_device(uid)

Devrait ignorer le périphérique identifié par l’uid (le résultat d’un appel à get_device_uid()) dans le futur. Vous devez implémenter cette méthode si vous avez fixez ASK_TO_ALLOW_CONNECT = True.. Notez que cette fonction est appelée immédiatement après open(), donc si open() cache un état, le pilote devrait réinitialiser cet état.

get_user_blacklisted_devices()

Renvoie un carte d’uid de périphérique à des noms lisibles pour tous les périphériques que l’utilisateur a demandé d’ignorer.

set_user_blacklisted_devices(devices)

Fixe la liste d’uids de périphérique qui devraient être ignorés par ce pilote.

specialize_global_preferences(device_prefs)

Implémentez cette méthode si votre périphérique veut surpasser une préférence particulière. Vous devez vous assurer que tous les sites d’appel qui veulent la préférence qui peut être outrepassée utilise device_prefs[“quelque_chose”] au lieu de prefs[“quelque_chose”]. Votre méthode devrait appeler device_prefs.set_overrides(pref=val, pref=val, …). Acutellement utilisé pour: gestion de métadonnée (prefs[“manage_device_metadata”])

set_library_info(library_name, library_uuid, field_metadata)

Implémentez cette méthode si vous voulez des informations sur la bibliothèque calibre actuelle. Cette méthode est appelée au démarrage et lorsque la bibliothèque calibre est changée un fois connecté.

is_dynamically_controllable()

Appelée par le gestionnaire de périphérique au lancement des extensions. Si cette méthode renvoie une chaîne, alors a) il supporte le contrôle dynamique d’interface du gestionnaire de périphérique, et b) ce nom doit être utiliser lorsqu’on communique avec l’extension.

Cette méthode peut être appelée dans le fil GUI. Un pilote qui implémente cette méthode doit être sûr du fil.

start_plugin()

Cette méthode est appelée au lancement de l’extension. Cette extension devrait commencer à accepter des connexions de périphériques qu’importe la manière dont ils le font. Si l’extension accepte déjà les connexions, alors ne fait rien.

Cette méthode peut être appelée dans le fil GUI. Un pilote qui implémente cette méthode doit être sûr du fil.

stop_plugin()

Cette méthode est appelée pour arrêter l’extension. Cette extension ne devrait plus accepter de connections et devrait nettoyer derrière lui. Il est probable que cette méthode appel une éteinte. Si cette extension n’accepte déjà plus de connections, alors ne fait rien.

Cette méthode peut être appelée dans le fil GUI. Un pilote qui implémente cette méthode doit être sûr du fil.

get_option(opt_string, default=None)

Renvoie la valeur de l’option indiquée par opt_string. Cette méthode peut être appelée lorsque l’extension n’est pas lancée. Renvoie None si cette option n’existe pas.

Cette méthode peut être appelée dans le fil GUI. Un pilote qui implémente cette méthode doit être sûr du fil.

set_option(opt_string, opt_value)

Fixe la valeur de l’option indiquée par opt_string. Cette méthode peut être appelée lorsque l’extension n’est pas lancée.

Cette méthode peut être appelée dans le fil GUI. Un pilote qui implémente cette méthode doit être sûr du fil.

is_running()

Renvoie True si l’extension est lancée, sinon False

Cette méthode peut être appelée dans le fil GUI. Un pilote qui implémente cette méthode doit être sûr du fil.

synchronize_with_db(db, book_id, book_metadata, first_call)

Appelé durant la correspondance de livre lorsqu’un livre sur un périphérique est appareillé avec une livre de la bdd de calibre. La méthode est responsable pour synchroniser les données du périphérique vers la bdd de calibre (si nécessaire).

La méthode doit renvoyer un tuple à deux valeurs. La première valeur est un ensemble des identifiants de livre calibre changés si la base de donnée calibre a été changée ou None si la base de donnée n’a pas été changée. Si la première valeur est un ensemble vide alors les métadonnée pour le livre sur le périphérique sont mises à jour avec les métadonnées de calibre et renvoyée au périphérique, mais aucun rafraîchissement GUI de ce livre n’est effectué. Ceci est pratique lorsque les données de calibre sont justes mais qu’elles doivent être envoyées au périphérique.

La seconde valeur est elle-même un tuple de 2 valeurs. La première valeur dans le tuple spécifie si un format du livre devrait être envoyé au périphérique. L’idée est de permettre de vérifier que le livre sur le périphérique est le même que le livre dans calibre. Cette valeur doit être None si aucun livre ne doit être envoyé, sinon renvoie le nom du fichier de base sur le périphérique (une chaîne comme foobar.epub). Soyez sûr d’inclure l’extension dans le nom. Le sous système du périphérique construira une tâche send_books pour tous les livres qui n’ont pas une valeur None . Note: à part pour récupérer l’extension par après, le nom est ignoré dans le cas où le périphérique utilise un schéma pour générer le nom de fichier, ce que la plupart font. La seconde valeur dans le tuple renvoyé indique si le format est prévu. Renvoie True s’il l’est, sinon renvoie False. calibre affichera une boîte de dialogue à l’utilisateur pour afficher tous les livres prévus.

Extrêmement important: cette méthode est appelée sur le fil GUI. Elle doit être en accord avec le fil du gestionnaire de périphérique.

book_id: l’identificateur calibre pour le livre dans la base de données. book_metadata: la métadonnée pour le livre venant du périphérique. first_call: True si c’est le premier appel durant une synchronisation, sinon False.

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

Bases : list

Un liste de livres. Chaque livre doit avoir les champs

1. titre

2. auteurs

3. taille (taille du fichier du livre)

4. date (un tuple temps UTC)

5. chemin (chemin vers le livre sur le périphérique)

6. aperçu (peut être None) l’aperçu est soit un str/bytes avec les données de l’image ou il devrait avoir un attribut image_path qui contient un chemin absolu (dépendant de la plateforme) vers le livre

7. identifiant (une liste de chaîne, peut être vide).

supports_collections()

Renvoie True si le périphérique supporte les collections de livre pour cette liste de livre.

add_book(book, replace_metadata)

Ajoute le livre dans la liste de livre. L’idée est de maintenir les métadonnées interne du périphérique. Renvoie True si la liste de livre doit être synchronisée.

remove_book(book)

Supprime un livre de la liste de livre. Corrige toutes les métadonnées sur le périphérique en même temps

get_collections(collection_attributes)

Renvoie un dictionnaire de collections créée avec collection_attributes. Chaque entrée dans le dictionnaire est sous la forme nom de collection:[liste de livres]

La liste de livre est triée par titre, sauf pour les collections créée à partir de séries, auquel cas series_index est utilisé.

Paramètres:

collection_attributes – Un liste d’attribut du livre

Périphérique basé sur du stockage de masse USB

La classe de base pour ces périphériques est calibre.devices.usbms.driver.USBMS. Cette classe hérite certaines de ces fonctionnalité de ces bases, documentée plus bas. Un pilote basique typique USBMS (USB Mass Storage) ressemble à ceci :

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)

Bases : DeviceConfig, DevicePlugin

Cette classe fournit une logique commune à tous les pilotes pour les périphériques qui s’exportent comme des périphériques de stockage de masse USB. Fournit des implémentation pour monter/éjecter un périphérique USBMS sur toute les plateformes.

VENDOR_ID = 0

VENDOR_ID peut être soit un entier, une liste d’entiers ou un dictionnaire. Si c’est un dictionnaire, cela doit être un dictionnaire de dictionnaires sous la forme:

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

PRODUCT_ID = 0

Un entier ou une liste d’entiers

BCD = None

BCD peut être soit None pour ne pas distingué entre les périphériques basé sur BCD, ou il peut être une liste des nombres BCD de tous les périphériques supportés par ce pilote.

WINDOWS_MAIN_MEM = None

Une chaîne identifiant la mémoire principale du périphérique dans les chaines d’identifications PnP de Windows. Ceci peut être None, une chaîne, une liste de chaîne ou une expression régulière compilée

WINDOWS_CARD_A_MEM = None

Une chaîne identifiant la première carte du périphérique dans les chaines d’identifications PnP de Windows. Ceci peut être None, une chaîne, une liste de chaîne ou une expression régulière compilée

WINDOWS_CARD_B_MEM = None

Une chaîne identifiant la deuxième carte du périphérique dans les chaines d’identifications PnP de Windows. Ceci peut être None, une chaîne, une liste de chaîne ou une expression régulière compilée

OSX_MAIN_MEM_VOL_PAT = None

Utilisé par la détection du nouveau pilote pour dissocier la mémoire principale des cartes mémoires. Devrait-être une expression régulière qui correspond au point de montage de la mémoire principale assignée par macOS

BACKLOADING_ERROR_MESSAGE = None

MAX_PATH_LEN = 250

La longueur maximum des chemins créés sur le périphérique

NEWS_IN_FOLDER = True

Place les nouvelles dans son propre fichier

reset(key='-1', log_packets=False, report_progress=None, detected_device=None)

Paramètres:

• key – La clef pour débloquer le périphérique

• log_packets – Si True, le paquet envoyé ou reçu au périphérique est mis au registre

• report_progress – Une fonction qui est appelée avec un % de progression (un nombre en 0 et 100) pour différentes tâches. Si on utilise -1 cela veut dire que la tâche n’a aucune information de progression

• detected_device – Les informations de périphérique recueilient par l’analyse de périphérique

set_progress_reporter(report_progress)

Pose une fonction pour rapporter les information de progression.

Paramètres:

report_progress – Une fonction qui est appelée avec un % de progression (un nombre en 0 et 100) pour différentes tâches. Si on utilise -1 cela veut dire que la tâche n’a aucune information de progression

card_prefix(end_session=True)

Renvoie une liste de 2 éléments des préfixes vers les chemins sur les cartes. Si aucune carte n’est présent, None est fixé comme le préfixe de la carte. e.g. (“/place”, “/place2”) (None, “place2”) (“place”, None) (None, None)

total_space(end_session=True)

Récupère l’espace disponible sur les points de montages:

1. Mémoire principale

2. Carte Mémoire A

3. Carte Mémoire B

Renvoie:

Une liste à 3 éléments avec des espaces entier en bit de (1, 2, 3). Si un périphérique particulier n’a pas l’une de ces locations, il devrait retourner à 0.

free_space(end_session=True)

Récupère l’espace disponible sur les points de montage:

1. Mémoire principale

2. Carte A

3. Carte B

Renvoie:

Une liste à 3 éléments avec des espaces entier en bit de (1, 2, 3). Si un périphérique particulier n’a pas l’une de ces locations, il devrait retourner à -1.

windows_sort_drives(drives)

Appelée pour différencier la mémoire principale et les cartes mémoires pour les périphériques qui ne peuvent les différencier sur base de WINDOWS_CARD_NAME. par ex. : L’EB600

can_handle_windows(usbdevice, debug=False)

Une méthode optionnelle pour effectuer de plus amples vérifications sur un périphérique pour savoir si ce pilote est capable de le gérer. Sinon, cela devrait renvoyer False. Cette méthode est appelée uniquement après que le vendeur, l’identifiant du produit et le bcd sont appariés, donc elle peut faire des vérifications nécessitant pas mal de temps. L’implémentation par défaut renvoye True. Cette méthode est appelée uniquement sur Windows. voir aussi can_handle().

Notez que pour les périphériques basés sur USBMS cette méthode par défaut délègue à can_handle(). Donc vous avez seulement besoin d’outrepasser can_handle() dans votre sous-classe de USBMS.

Paramètres:

usbdevice – Un périphérique USB est rapporté par calibre.devices.winusb.scan_usb_devices()

open(connected_device, library_uuid)

Effectue n’importe quel initialisation spécifique de périphérique. Appelé après que le périphérique soit détecté mais avant que n’importe quelle fonction qui communique avec le périphérique. Par exemple: Pour les périphériques qui se présentent comme des périphériques de stockage de masse USB, cette méthode devrait être responsable du montage du périphérique ou si le périphérique a été monté automatiquement, de trouver où il a été monté. La méthode calibre.devices.usbms.device.Device.open() a une implémentation de cette fonction qui devrait servir comme un bon exemple pour les périphériques de stockage de masse USB.

Cette méthode peut créer une exception OpenFeedback pour afficher un message à l’utilisateur.

Paramètres:

• connected_device – Le périphérique que nous essayons actuellement d’ouvrir. C’est un tuple (vendor id, product id, bcd, manufacturer name, product name, device serial number). Toutefois, certains périphériques n’on aucun numéro de séries et sur Windows seul les trois premier champs sont présent, les autres sont None

• library_uuid – L’UUID de la bibliothèque calibre actuelle. Peut être None s’il n’y a pas de bibliohèque (par exemple lorsqu’il est utilisé de l’invité de commande).

eject()

Démonte/éjecte le périphérique de l’OS. Ceci ne vérifie pas s’il y a des travaux GUI en attente qui nécessite communication avec le périphérique.

NOTEZ: Que cette méthode peut ne pas être appelée sur le même fil que le reste des méthodes périphériques.

post_yank_cleanup()

Appelé si l’utilisateur retire le périphériques sans l’avoir éjecter préalablement.

sanitize_callback(path)

Rappel pour permettre aux pilotes individuels de périphérique d’outrepasser l’expurgation des chemins utilisé par create_upload_path().

filename_callback(default, mi)

Rappel pour permettre aux pilotes de changer le nom de fichier par défaut fixé par create_upload_path().

sanitize_path_components(components)

Effectue n’importe quel expurgation de chemins spécifique au périphérique pour les fichiers devant être envoyés au périphérique

get_annotations(path_map)

Résous path_map pour annotation_map pour les fichier trouvés sur le périphérique

add_annotation_to_library(db, db_id, annotation)

Ajoute une annotation dans la bibliothèque calibre

class calibre.devices.usbms.cli.CLI

class calibre.devices.usbms.driver.USBMS(plugin_path)

Bases : CLI, Device

Les classes de base pour tous les périphériques USBMS. Implémente la logique d’envoi/réception/màj/métadonnée/encachement de métadonnée/etc.

description = 'Communiquer avec une liseuse de livre numérique.'

Une courte chaine décrivant ce que fait l’extension

author = 'John Schember'

L’auteur de cette extension

supported_platforms = ['windows', 'osx', 'linux']

Liste des plateformes où fonctionne cette extension. Par exemple ['windows', 'osx', 'linux']

booklist_class

alias de BookList

book_class

alias de Book

FORMATS = []

Liste ordonnée de formats supportés

CAN_SET_METADATA = []

Soit les métadonnées des livres sont fixées via le GUI.

get_device_information(end_session=True)

Demande ses informations au périphérique. Voir L{DeviceInfoQuery}.

Renvoie:

(nom du périphérique, version du périphérique, version du programme sur le périphérique, type MIME) Le tuple peut parfois avoir un cinquième élément, qui est dictionnaire d’information sur le lecteur. Voir usbms.driver pour un exemple.

set_driveinfo_name(location_code, name)

Fixe le nom du périphérique dans le driveinfo à “name”. Ce Paramètre persistera jusqu’à ce que le fichier soit recréer ou que le nom soit changé à nouveau.

Des périphériques n’étant pas des disques devrait implémenter cette méthode basée sur les codes d’emplacement renvoyé par la méthode get_device_information().

books(oncard=None, end_session=True)

Renvoie une liste des livres numérique sur le périphérique.

Paramètres:

oncard – Si “carda” ou “cardb”, renvoie une liste de livres numériques sur la carte de stockage spécifique, sinon renvoie une liste de livres numériques dans la mémoire principale du périphérique. Si une carte est spécifiée et qu’aucun livre n’est dans la carte, renvoie une liste vide.

Renvoie:

Une BookList

upload_books(files, names, on_card=None, end_session=True, metadata=None)

Envoie une liste de livres au périphérique. Si un fichier existe déjà sur le périphérique, il devrait être remplacé. Cette méthode devrait soulever une FreeSpaceError s’il n’y a pas d’espace sur le périphérique. Le texte dans la FreeSpaceError doit contenir le mot « carte » si « on_card » n’est pas None il doit contenir le mot « mémoire ».

Paramètres:

• files – Une liste de chemins

• names – Une liste de noms que les livres devraient avoir une fois envoyé au périphérique. len(names) == len(files)

• metadata – Si n’est pas None, est une liste d’objets Métadonnées. L’idée est d’utiliser la métadonnée pour déterminer où mettre le livre sur le périphérique. len(metadata) == len(files). En plus de la couverture habituelle(chemin vers la couverture), il peut aussi y avoir un attribut d’aperçu, qui devrait être utilisée préférentiellement. L’attribut d’aperçu est de la form (largeur, hauteur, cover_data en jpeg).

Renvoie:

Une liste d’ensemble de tuples à 3 éléments. La liste est faite pour être passée à add_books_to_metadata().

upload_cover(path, filename, metadata, filepath)

Envoie les couvertures de livre au périphérique. L’implémentation par défaut ne fait rien.

Paramètres:

• path – Le chemin complet vers le dossier où se trouve le livre associé.

• filename – Le nom du fichier du livre sans l’extension.

• metadata – métadonnée appartenant au livre. Utilisez metadata.thumbnail pour les couvertures

• filepath – Le chemin absolu vers le livre numérique

add_books_to_metadata(locations, metadata, booklists)

Ajoute des emplacements à la liste de livres. cette fonction ne doit pas communiquer avec le périphérique.

Paramètres:

• locations – Résultat d’un appel à L{upload_books}

• metadata – Liste d’objets Métadonénes, même chose que upload_books().

• booklists – En tuple contenant le résultat d’appels à (books(oncard=None)(), books(oncard='carda')(), :meth`books(oncard=”cardb”)`).

delete_books(paths, end_session=True)

Supprime les livre aux chemins sur le périphérique.

remove_books_from_metadata(paths, booklists)

Retire les livres de la liste de métadonnées. Cette fonction ne doit pas communiquer avec le périphérique.

Paramètres:

• paths – les chemins vers les livres sur le périphérique.

• booklists – En tuple contenant le résultat d’appels à (books(oncard=None)(), books(oncard='carda')(), :meth`books(oncard=”cardb”)`).

sync_booklists(booklists, end_session=True)

Met à jour les métadonnées sur le périphérique.

Paramètres:

booklists – En tuple contenant le résultat d’appels à (books(oncard=None)(), books(oncard='carda')(), :meth`books(oncard=”cardb”)`).

classmethod normalize_path(path)

Renvoie le chemin avec les séparateurs de chemin natif à la platforme

Actions interface utilisateur

Si vous ajoutez votre propre extension dans un fichier ZIP, vous devriez sous-classer InterfaceActionBase et InterfaceAction. La méthode load_actual_plugin() de votre sous-classe InterfaceActionBase doit renvoyer un objet instancié de votre sous-classe InterfaceBase.

class calibre.gui2.actions.InterfaceAction(parent, site_customization)

Bases : QObject

Une extension représentant une « action » qui peut être effectuée dans le GUI. Tous les menus de la barre d’outil et les menus contextuels sont implémentés par ces extensions.

Notez que cette classe est la classe de base pour ces extensions, toutefois, pour intégrer l’extension avec le système d’extension de calibre, vous devez avoir une classe englobante qui référence la vrai extension.Voir le module calibre.customize.builtins pour des exemples.

Si deux objets InterfaceAction ont le même nom, celui avec la priorité la plus haute à préséance.

Les sous-classes devrait implémenter les méthodes library_changed(), location_selected(), shutting_down(), initialization_complete() et tag_browser_context_action().

Une fois initialisé, cette extension à accès au Gui principal de calibre via le membre gui. Vous pouvez accéder d’autres extensions par nom, par exemple:

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

Pour accéder à la réelle extension, utiliser l’attribut interface_action_base_plugin, cet attribut devient disponible uniquement après que l’extension ait été initialisée. Utile si vous souhaitez utiliser des méthodes de la classe extension comme do_user_config().

La QAction spécifiée par action_spec est automatiquement créée et rendue disponible sous self.qaction.

name = 'Implement me'

Le nom de l’extension. Si deux extensions avec le même nom sont présentes, celle avec la plus haute priorité à préséance.

priority = 1

La priorité de l’extension. Si deux extensions avec le même nom sont présentes, celle avec la plus haute priorité a préséance.

popup_type = 1

Le type de menu contextuel pour lorsque cette extension est ajoutée à la barre d’outils

auto_repeat = False

Si cette action devrait être répétée automatiquement lorsque son raccourci est maintenant enfoncé.

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

De la forme : (texte, icon_path, infobulle,raccourcis clavier) icône, infobulle et raccourcis clavier peuvent être None. Le raccourcis doit être une chaîne, None ou un tuple de raccourcis. Si None, aucune touche n’est enregistrée pour correspondre à l’action. Si vous entrez un tuple vide, alors le raccourcis est enregistré sans attache spécifique à une touche.

action_shortcut_name = None

Si ce n’est pas None, utilisé pour le nom affiché de l’utilisateur lors de la personnalisation des raccourcis clavier pour la spécification d’action ci-dessus au lieu de action_spec[0]

action_add_menu = False

Si True, un menu est automatiquement créé et ajouté à self.qaction

action_menu_clone_qaction = False

Si True, un clône de self.qaction est ajouté au menu de self.qaction. Si vous souhaitez que le texte de cette action soit différent de self.qaction, fixer cette variable aux nouveau texte

dont_add_to = frozenset({})

Ensemble d’emplacements vers lesquels cette action ne doit pas être ajoutée. Voir all_locations pour une liste des emplacements possible

dont_remove_from = frozenset({})

Ensemble d’emplacements d’où cette action ne doit pas être supprimé. Voir all_locations pour une liste des emplacements possible

action_type = 'global'

Type d’action. “current” signifie qu’il agit sur la vue courante, “global” représente une action qui ne change pas la vue courante, mais plutôt calibre tout entier

accepts_drops = False

Si True, alors cette InterfaceAction aura l’opportunité d’interagir avec les événements glisser-déposer. Voir les méthodes accept_enter_event(), :meth`:accept_drag_move_event`, drop_event() pour plus de détails.

accept_enter_event(event, mime_data)

Cette méthode devrait renvoyer True ssi cette action d’interface est capable de gérer les événements glisser. Ne pas appeler accepter/ignorer sur l’événement, ceci sera géré par l’UI de calibre.

accept_drag_move_event(event, mime_data)

Cette méthode devrait renvoyer True ssi cette action d’interface est capable de gérer les événements glisser. Ne pas appeler accepter/ignorer sur l’événement, ceci sera géré par l’UI de calibre.

drop_event(event, mime_data)

Cette méthode devrait effectuer des actions utiles et renvoyer True ssi cette action interface est capable de gérer les événement déposer. Ne pas appeler accepter/ignorer sur cet événement, cela sera géré par l’UI de calibre. Vous ne devriez pas effectuer d’opérations longues/bloquantes avec cette fonction. À la place, émettez un signal ou utiliser un QTimer.singleShot et renvoyez rapidement. Voir les actions intégrées pour des exemples.

create_menu_action(menu, unique_name, text, icon=None, shortcut=None, description=None, triggered=None, shortcut_name=None, persist_shortcut=False)

Une méthode commode pour ajouter facilement des actions à un QMenu. Renvoie la QAction créée. Cette action a un attribut de plus, calibre_shortcut_unique_name qui s’il n’est pas None réfère à un nom unique sous lequel cette action est enregistrée dans le gestionnaire du clavier.

Paramètres:

• menu – Le QMenu auquel la nouvelle action créée sera ajouté

• unique_name – Un nom unique pour cette action, ceci doit être globalement unique, donc faites en sorte qu’il soit le plus descriptif possible. Dans le doute, ajoutez-y un UUID

• text – Le texte de l’action.

• icon – Soit une QIcon ou un nom de fichier. Le nom de fichier est passé aux QIcon.ic() intégré, donc vous ne devez pas passer le chemin absolu vers le dossier d’images.

• shortcut – Une chaîne, un ensemble de chaînes, None ou False. Si False, aucun raccourci clavier ne sera enregistré pour cette action. Si None, un raccourci clavier sans touche par défaut est enregistré. La chaîne et la liste de chaîne enregistre un raccourci avec une touche par défaut comme spécifié.

• description – Une description pour cette action. Utilisée pour fixer les infobulles.

• triggered – Un appelable qui est connecté au signal déclenché de l’action créée.

• shortcut_name – Le texte affiché à l’utilisateur lors de la personnalisation des raccourcis clavier pour cette action. Par défaut il est fixer à une valeur text.

• persist_shortcut – Les raccourcis pour les actions qui n’apparaissent pas toujours, ou qui dépendent de la bibliothèque, peuvent disparaître lorsque d’autres raccourcis clavier sont édités, sauf si « Persist_shortcut » est réglé sur True.

load_resources(names)

Si cette extension est donnée dans un fichier ZIP (extension ajoutée par l’utilisateur), cette méthode vous permettra de charger des ressources du fichier ZIP.

Par exemple pour charger une image

pixmap = QPixmap()
pixmap.loadFromData(tuple(self.load_resources(['images/icon.png']).values())[0])
icon = QIcon(pixmap)

Paramètres:

names – Liste de chemins vers les ressources dans le ZIP utilisant / comme séparateur

Renvoie:

Un dictionnaire sous la forme {name : file_contents}. Tout nom qui n’est pas trouvé dans le fichier ZIP ne sera pas présent dans le dictionnaire.

genesis()

Paramètre cette extension. Uniquement appelé une fois lors de l’initialisation. self.gui est disponible. L’action spécifiée par action_spec est disponible à self.qaction.

location_selected(loc)

Appelé dès que la liste de livre étant affichée dans calibre change. Actuellement, les valeur pour loc sont: library, main, card and cardb.

Cette méthode devrait activer/désactiver cette action et ces sous-actions en fonction de l’emplacement

library_about_to_change(olddb, db)

Appelé dès que la bibliothèque actuelle est changée.

Paramètres:

• olddb – La LibraryDatabase correspondant à la bibliothèque précédente

• db – La LibraryDatabase correspondant à la nouvelle bibliothèque.

library_changed(db)

Appelé dès que la bibliothèque actuelle est changée.

Paramètres:

db – La LibraryDatabase correspondant à la bibliothèque actuelle

gui_layout_complete()

Appelée une fois par action lorsque l’affichage du Gui principal est complété. Si votre action nécessite de faire des changements dans l’affichage, elles devraient être faite ici, plutôt que dans initialization_complete().

initialization_complete()

Appelée un fois par action lorsque l’initiation du GUI principal est complète.

tag_browser_context_action(index)

Appelé lors de l’affichage du menu contextuel dans le Navigateur d’étiquettes. index est le QModelIndex qui pointe vers l’élément du Navigateur d’étiquettes qui a été cliqué avec le bouton droit. Testez sa validité avec index.valid() et obtenez l’objet TagTreeItem sous-jacent avec index.data(Qt.ItemDataRole.UserRole). Tout objet d’action produit par cette méthode sera ajouté au menu contextuel.

shutting_down()

Appelée une fois par extension lorsque le GUI principal est en train de s’éteindre. Relâche toute les ressources utilisée, mais essaye de ne pas bloquer l’arrêt pour un longue période.

class calibre.customize.InterfaceActionBase(*args, **kwargs)

Bases : Plugin

supported_platforms = ['windows', 'osx', 'linux']

Liste des plateformes où fonctionne cette extension. Par exemple ['windows', 'osx', 'linux']

author = 'Kovid Goyal'

L’auteur de cette extension

type = 'Action interface utilisateur'

Le type de cette extension. Utilisé pour catégorisé les extensions dans le GUI

can_be_disabled = False

Si False, l’utilisateur ne pourra pas désactiver cette extension. À utiliser avec soin.

load_actual_plugin(gui)

Cette méthode doit renvoyer l’extension d’action interface correspondante.

Extensions préférences

class calibre.customize.PreferencesPlugin(plugin_path)

Bases : Plugin

Une extension représentant un widget affiché dans la boîte de dialogue des préférences.

Cette extension n’a qu’un méthode importante create_widget(). Les différents champs de l’extension contrôlent comment c’est catégorisé dans l’UI.

supported_platforms = ['windows', 'osx', 'linux']

Liste des plateformes où fonctionne cette extension. Par exemple ['windows', 'osx', 'linux']

author = 'Kovid Goyal'

L’auteur de cette extension

type = 'Préférences'

Le type de cette extension. Utilisé pour catégorisé les extensions dans le GUI

can_be_disabled = False

Si False, l’utilisateur ne pourra pas désactiver cette extension. À utiliser avec soin.

config_widget = None

Importe le chemin vers le module qui contient une classe nommée ConfigWidget qui implémente ConfigWidgetInterface. Utilisé par create_widget().

category_order = 100

Où dans la liste de catégories la catégorie de cette extension devrait se trouver.

name_order = 100

Où dans la liste de noms d’une catégorie, le gui_name de cette extension devrait se trouver

category = None

La catégorie où devrait se trouver cette extension

gui_category = None

Le nom de catégorie affiché à l’utilisateur pour cette extension

gui_name = None

Le nom affiché à l’utilisateur pour cette extension

icon = None

L’icône pour cette extension, devrait être un chemin absolu

description = None

La description pour les infobulles etc

create_widget(parent=None)

Crée et renvoie le Qt widget effectivement utilisé pour paramétrer ce groupe de préférence. Le widget doit implémenter la calibre.gui2.preferences.ConfigWidgetInterface.

L’implémentation par défaut utilise config_widget pour instancié le widget.

class calibre.gui2.preferences.ConfigWidgetInterface

Cette classe définit l’interface que tous les widgets affichée dans la boîte de dialogues de Préférences doit implémenter. Voir ConfigWidgetBase pour une classe de base qui implémente cette interface et définit aussi des méthodes pratiques.

changed_signal = None

Ce signal doit être émis dès que l’utilisateur change une valeur de ce widget

supports_restoring_to_defaults = True

Fixer à TRue ssi la méthode ConfigWidgetBase est implémentée.

restore_defaults_desc = 'Restaurer les réglages aux valeurs par défaut. Vous devez cliquer sur Appliquer pour enregistrer réellement les réglages par défaut.'

L’infobulle pour le bouton « Restauration des paramètres par défaut »

restart_critical = False

Si True, le la boite de dialogue de Préférence ne permettra pas à l’utilisateur d’ajouter d’autres préférences. A de l’effet uniquement si commit() renvoie True.

genesis(gui)

Appelé une fois avant que le widget ne soit affiché, devrait effectuer les paramétrages nécessaire

Paramètres:

gui – L’interface graphique utilisateur principale de calibre

initialize()

Devrait définir toutes les valeurs de configuration à leurs valeurs initiales (les valeurs stockées dans les fichiers de configuration). L’instruction « return » est facultative. Renvoie False si la boîte de dialogue ne doit pas être affichée.

restore_defaults()

Devrait fixer toutes les valeurs de configuration à leur valeur par défaut.

commit()

Sauve tout changement de paramètre. Renvoie True si les changements requière un redémarrage, sinon False. Crée un exception :class:`AbortCommit pour indiquer qu’une erreur est survenue. Vous êtes responsable de donner des informations à l’utilisateur sur ce qu’est l’erreur et comment la corriger.

refresh_gui(gui)

Appelée une fois que ce widget est engagé. Responsable la relecture par le GUI de tous les paramètres modifiés. Notez que par défaut le GUI réinitialise de toutes façon différents éléments, donc la plupart des widgets ne nécessitent pas cette méhode.

initial_tab_changed()

Appelé si l’onglet initialement affiché est modifié avant l’affichage du widget, mais après son initialisation.

class calibre.gui2.preferences.ConfigWidgetBase(parent=None)

Une classe de base qui contient du code pour ajouter facilement des widgets de configuration standards comme des cases, des listes déroulantes, des zones de textes, etc. Voir la méthode register().

Cette classe gère automatiquement changement de notification, les remises aux paramètres par défaut, la traduction entre les objets GUI et les objets configuration, etc. pour l’enregistrement de paramètres.

Si votre widget de configuration hérite de cette classe mais inclus des paramètres qui ne sont pas enregistrés, vous devriez outrepasser les méthodes ConfigWidgetInterface et appelé les méthodes de base à l’intérieur des dérogations.

changed_signal

Ce signal doit être émis dès que l’utilisateur change une valeur de ce widget

supports_restoring_to_defaults = True

Fixer à TRue ssi la méthode ConfigWidgetBase est implémentée.

restart_critical = False

Si True, le la boite de dialogue de Préférence ne permettra pas à l’utilisateur d’ajouter d’autres préférences. A de l’effet uniquement si commit() renvoie True.

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

Enregistrer un paramètre.

Paramètres:

• name – Le nom du paramètre

• config_obj – Un configuration qui lit/écrit le paramètre

• gui_name – Le nom de l’objet GUI qui présente une interface à changer par le paramètre. Par défaut, il est présumé être 'opt_' + name.

• choices – Si le paramètre est un paramètre de base à plusieurs choix (une liste déroulante), la liste de choix. La liste est une liste de tuples sous la forme [(nom GUI, valeur), ...]

• setting – La classe responsable de la gestion de ce paramètre. La classe par défaut gère presque ous les cas, donc ce paramètre est rarement utilisé.

initialize()

Devrait définir toutes les valeurs de configuration à leurs valeurs initiales (les valeurs stockées dans les fichiers de configuration). L’instruction « return » est facultative. Renvoie False si la boîte de dialogue ne doit pas être affichée.

commit(*args)

Sauve tout changement de paramètre. Renvoie True si les changements requière un redémarrage, sinon False. Crée un exception :class:`AbortCommit pour indiquer qu’une erreur est survenue. Vous êtes responsable de donner des informations à l’utilisateur sur ce qu’est l’erreur et comment la corriger.

restore_defaults(*args)

Devrait fixer toutes les valeurs de configuration à leur valeur par défaut.

© Copyright Kovid Goyal. Dernière mise à jour nov. 29, 2024