Reference for all built-in template language functions¶

Here, we document all the built-in functions available in the calibre template language. Every function is implemented as a class in python and you can click the source links to see the source code, in case the documentation is insufficient. The functions are arranged in logical groups by type.

Arithmetic ¶

add(x [, y]*)¶

class calibre.utils.formatter_functions.BuiltinAdd[source]¶: add(x [, y]*) – retourne la somme de ses arguments. Déclenche une exception si un argument n’est pas un nombre. Cette fonction peut souvent être remplacée par l’opérateur +.

ceiling(x)¶

class calibre.utils.formatter_functions.BuiltinCeiling[source]¶: ceiling(x) – renvoie le plus petit entier supérieur ou égal à x. Envoie une exception si x n’est pas un nombre.

divide(x, y)¶

class calibre.utils.formatter_functions.BuiltinDivide[source]¶: divide(x, y) – renvoie x / y. Déclenche une exception si x ou y ne sont pas des nombres. Cette fonction peut souvent être remplacée par l’opérateur /.

floor(x)¶

class calibre.utils.formatter_functions.BuiltinFloor[source]¶: floor(x) – renvoie le plus grand entier inférieur ou égal à x. Envoie une exception si x n’est pas un nombre.

fractional_part(x)¶

class calibre.utils.formatter_functions.BuiltinFractionalPart[source]¶: fractional_part(x) – renvoie la valeur après la virgule. Par exemple, fractional_part(3.14) renvoie 0.14. Envoie une exception si x n’est pas un nombre.

mod(x)¶

class calibre.utils.formatter_functions.BuiltinMod[source]¶: mod(x) – renvoie le solde (reste de x / y). Déclenche une exception si x ou y n’est pas un nombre.

multiply(x [, y]*)¶

class calibre.utils.formatter_functions.BuiltinMultiply[source]¶: multiply(x [, y]*) – renvoie le produit de ses arguments. Déclenche une exception si l’un des arguments n’est pas un nombre. Cette fonction peut souvent être remplacée par l’opérateur *.

round(x)¶

class calibre.utils.formatter_functions.BuiltinRound[source]¶: round(x) – renvoie l’entier le plus proche de x. Envoie une exception si x n’est pas un nombre.

subtract(x, y)¶

class calibre.utils.formatter_functions.BuiltinSubtract[source]¶: subtract(x, y) – renvoie x - y. Déclenche une exception si x ou y ne sont pas des nombres. Cette fonction peut souvent être remplacée par l’opérateur -.

Boolean ¶

and(valeur [, valeur]*)¶

class calibre.utils.formatter_functions.BuiltinAnd[source]¶: and(valeur [, valeur]*) – renvoie la chaîne « 1 » si toutes les valeurs ne sont pas vides, sinon renvoie la chaîne vide. Cette fonction fonctionne bien avec test ou first_non_empty. Vous pouvez avoir autant de valeurs que vous le souhaitez. Dans de nombreux cas, l’opérateur && peut remplacer cette fonction.

not(value)¶

class calibre.utils.formatter_functions.BuiltinNot[source]¶: not(value) – retourne la chaîne « 1 » si la valeur est vide, sinon retourne la chaîne vide. Cette fonction fonctionne bien avec test ou first_non_empty. Dans de nombreux cas, l’opérateur ! peut remplacer cette fonction.

or(valeur [, valeur]*)¶

class calibre.utils.formatter_functions.BuiltinOr[source]¶: or(valeur [, valeur]*) – retourne la chaîne « 1 » si une valeur n’est pas vide, sinon retourne la chaîne vide. Cette fonction fonctionne bien avec test ou first_non_empty. Vous pouvez avoir autant de valeurs que vous le souhaitez. Dans de nombreux cas, l’opérateur || peut remplacer cette fonction.

Date functions ¶

date_arithmetic(date, calc_spec, fmt)¶

class calibre.utils.formatter_functions.BuiltinDateArithmetic[source]¶: date_arithmetic(date, calc_spec, fmt) – Calcule une nouvelle date à partir de “date” en utilisant “calc_spec”. Retourne la nouvelle date formatée selon l’option “fmt” : si elle n’est pas fournie, le résultat sera au format iso. calc_spec est une chaîne de caractères formée par la concaténation de paires de “vW” (valueWhat) où “v” est un nombre éventuellement négatif et W est l’une des lettres suivantes : s : ajoute “v” secondes à “date” m : ajoute “v” minutes à “date” h : ajoute “v” heures à “date” d : ajoute “v” jours à “date” w : ajoute “v” semaines à “date” y : ajoute “v” années à “date”, où une année est de 365 jours. Exemple : “1s3d-1m” ajoutera 1 seconde, ajoutera 3 jours et soustraira 1 minute à la “date”.

days_between(date1, date2)¶

class calibre.utils.formatter_functions.BuiltinDaysBetween[source]¶: days_between(date1, date2) – renvoie le nombre de jours entre date1 et date2. Le nombre est positif si date1 est plus grand que date2, sinon négatif. Si date1 ou date2 ne sont pas des dates, la fonction renvoie une chaîne vide.

today()¶

class calibre.utils.formatter_functions.BuiltinToday[source]¶: today() – renvoie une chaîne date pour aujourd’hui. Cette valeur est conçue pour être utilisée avec format_date ou days_between, mais peut être manipulée comme toute autre chaîne. La date est au format ISO.

Formatting values ¶

finish_formatting(val, fmt, prefix, suffix)¶

class calibre.utils.formatter_functions.BuiltinFinishFormatting[source]¶: finish_formatting(val, fmt, prefix, suffix) – applique le format, le préfixe et le suffixe à une valeur de la même manière que cela est effectué dans un modèle comme {series_index:05.2f| - |- }. Par exemple, le programme suivant produit le même résultat que le modèle ci-dessus : programme : finish_formatting(field(« series_index »), « 05.2f », « - « , « - « )

format_date(val, chaine_format)¶

class calibre.utils.formatter_functions.BuiltinFormatDate[source]¶: format_date(val, chaine_format) – formate la valeur, qui doit être une date, en utilisant la chaine_format, retournant une chaine. Les codes de formatage sont : d : le jour comme nombre sans zéro (1 à 31) dd :le jour comme nombre avec zéro (01 à 31) ddd : le nom du jour localisé et abrégé (p. ex. « Lun » to « Dim »). dddd : le nom du jour localisé en entier (p. ex. « Lundi » to « Dimanche »). M : le mois comme nombre sans zéro (1 à 12). MM : le mois comme nombre avec zéro (01 à 12) MMM : le nom du mois localisé et abrégé (p. ex. « Jan » to « Dec »). MMMM : le nom du mois localisé en entier (p. ex. « Janvier » to « Décembre »). yy : l’année comme nombre à 2 chiffres (00 à 99). yyyy : l’année comme nombre à 4 chiffres. h : les heures sans zéro (0 à 11 où 0 à 23, en fonction de am/pm) hh : les heures avec zéro (00 à 11 où 00 à 23, en fonction de am/pm) m : les minutes sans zéro (0 à 59) mm : les minutes avec zéro(00 à 59) s : les secondes sans zéro (0 à 59) ss : les secondes avec zéro (00 à 59) ap : utiliser une horloge à 12-heures au lieu de 24-heures, avec « ap » remplacé par la chaine localisé pour am ou pm AP : utiliser une horloge à 12-heures au lieu de 24-heures, avec « AP » remplacé par la chaine localisé pour AM ou PM iso : la date avec le temps et le fuseau horaire. Doit être le seul format présent to_number : la date sous forme de nombre à virgule flottante from_number[:fmt] : formate l’horodatage en utilisant fmt si présent sinon iso

format_date_field(field_name, format_string)¶

class calibre.utils.formatter_functions.BuiltinFormatDateField[source]¶: format_date_field(field_name, format_string) – formate la valeur du champ “field_name”, qui doit être le nom d’un champ date, standard ou personnalisé. Voir “format_date()” pour les codes de formatage. Cette fonction est beaucoup plus rapide que format_date et doit être utilisée lorsque vous formatez la valeur d’un champ (colonne). Elle ne peut pas être utilisée pour des dates calculées ou des dates dans des variables de type chaîne. Exemples : format_date_field(“pubdate”, “yyyy.MM.dd”)

format_number(v, template)¶

class calibre.utils.formatter_functions.BuiltinFormatNumber[source]¶: format_number(v, template) – formate le nombre v en utilisant un modèle (template) de formatage Python comme « {0:5.2f} » ou « {0:,d} » ou « ${0:5,.2f} ». Le nom du champs (field_name) dans le modèle doit être un 0 (zéro) (le « {0: » dans les exemples ci-dessus). Regardez le langage des modèles et la documentation Python pour plus d’exemples.Vous pouvez omettre le « {0: » au début et le « } » à la fin si le modèle contient uniquement un format. Retourne une chaîne vide si le formatage échoue.

human_readable(v)¶

class calibre.utils.formatter_functions.BuiltinHumanReadable[source]¶: human_readable(v) – renvoie une chaine représentant le nombre v en Ko, Mo, Go, etc.

rating_to_stars(value, use_half_stars)¶

class calibre.utils.formatter_functions.BuiltinRatingToStars[source]¶: rating_to_stars(value, use_half_stars) – Retourne la note sous forme de chaîne de caractères étoilés. La valeur est un nombre entre 0 et 5. Mettre use_half_stars à 1 si vous voulez des caractères demi-étoiles pour les colonnes de classement personnalisées qui ne sont pas des entiers, par exemple 2.5.

urls_from_identifiers(identifiers, sort_results)¶

class calibre.utils.formatter_functions.BuiltinUrlsFromIdentifiers[source]¶: urls_from_identifiers(identifiers, sort_results) – donne une liste d’identifiants séparée par des virgules, où un identifiant est une paire de valeurs séparées par des deux points (name:id_value), renvoie une liste d’URL HTML séparées par des virgules, générées à partir des identifiants. La liste n’est pas triée si sort_results vaut 0 (caractère ou nombre), sinon elle est triée par ordre alphabétique du nom de l’identifiant. Les URL sont générées de la même manière que la colonne d’identifiants intégrée lorsqu’elle est affichée dans Détails du livre.

Get values from metadata ¶

annotation_count()¶

class calibre.utils.formatter_functions.BuiltinAnnotationCount[source]¶: annotation_count() – renvoie le nombre total d’annotations de tous types attachées au livre en cours. Cette fonction ne fonctionne que dans l’interface graphique.

approximate_formats()¶

class calibre.utils.formatter_functions.BuiltinApproximateFormats[source]¶: approximate_formats() – retourne une liste de formats, séparées par des virgules, qui, à un certain moment, on été associés avec le livre. Il n’y a aucune garantie que cette liste est correcte, bien qu’elle le soit probablement. Cette fonction peut-être appelée sous forme de modèle de programme en utilisant le modèle « {:”approximate_formats()”} ». Notez que ces noms de formats sont toujours en majuscule, comme dans EPUB. Cette fonction n’est utilisable que dans l’interface utilisateur. Si vous désirez utiliser cette valeur dans « Enregistrer sous… » ou « Envoyer vers le périphérique connecté », vous devez créer une colonne personnalisée de type « Colonne construite à partir d’autres colonnes » et utiliser cette fonction dans le modèle de la colonne. Vous pourrez ensuite utiliser la valeur de la colonne dans vos modèles d’enregistrement / d’envoi.

author_links(val_separator, pair_separator)¶

class calibre.utils.formatter_functions.BuiltinAuthorLinks[source]¶: author_links(val_separator, pair_separator) – retourne une chaîne contenant une liste d’auteurs et les valeurs de ce lien d’auteur dans la forme auteur1 val_separator author1link pair_separator auteur2 val_separator author2link etc. Un auteur est séparé de la valeur de son lien par la chaîne val_separator sans espaces ajoutés. Les paires author:linkvalue sont séparées par la chaîne d’argument pair_separator sans espaces ajoutés. C’est à vous de choisir des chaines de Il vous incombe de choisir des chaines de séparateur qui n’apparaissent pas dans des noms ou des liens d’auteur. Un auteur est inclus même si le lien d’auteur est vide.

author_sorts(val_separator)¶

class calibre.utils.formatter_functions.BuiltinAuthorSorts[source]¶: author_sorts(val_separator) – renvoie une chaîne contenant une liste des valeurs de tri de l’auteur pour les auteurs du livre. Le tri est celui des métadonnées auteur (différente de l’author_sort dans les livres). La liste renvoyée a la forme tri auteur 1 val_separator tri auteur 2 etc. Les valeurs de tri auteur dans cette liste sont dans le même ordre que les auteurs du livre. Si vous voulez les espaces autour du val_separator incluez les alors dans la chaîne separator

booksize()¶

class calibre.utils.formatter_functions.BuiltinBooksize[source]¶: booksize() – retourne la valeur de la taille du champ. Cette fonction n’est utilisable que dans l’interface utilisateur. Si vous désirez utiliser cette valeur dans « Enregistrer sous… » ou « Envoyer vers le périphérique connecté », vous devez créer une colonne personnalisée de type « Colonne construite à partir d’autres colonnes » et utiliser cette fonction dans le modèle de la colonne. Vous pourrez ensuite utiliser la valeur de la colonne dans vos modèles d’enregistrement / d’envoi.

connected_device_name(storage_location)¶

class calibre.utils.formatter_functions.BuiltinConnectedDeviceName[source]¶: connected_device_name(storage_location) – si un périphérique est connecté alors retournez le nom du périphérique, sinon retournez la chaîne vide. Chaque emplacement de stockage sur un périphérique peut avoir un nom différent. Les noms des emplacements sont « main », « carda » et « cardb ». Cette fonction ne fonctionne que dans l’interface graphique.

connected_device_uuid(storage_location)¶

class calibre.utils.formatter_functions.BuiltinConnectedDeviceUUID[source]¶: connected_device_uuid(storage_location) – si un périphérique est connecté alors retournez l’uuid du périphérique (id unique), sinon retournez la chaîne vide. Chaque emplacement de stockage sur un périphérique a un uuid différent. Les noms des emplacements sont “main”, “carda” et “cardb”. Cette fonction ne fonctionne que dans l’interface graphique.

current_library_name()¶

class calibre.utils.formatter_functions.BuiltinCurrentLibraryName[source]¶: current_library_name() – retourne le dernier nom du chemin de la bibliothèque calibre actuelle. Cette fonction peut-être appelée en mode de modèle de programme en utilisant le modèle « {:”current_library_name()”} ».

current_library_path()¶

class calibre.utils.formatter_functions.BuiltinCurrentLibraryPath[source]¶: current_library_path() – retourne le chemin de la bibliothèque calibre actuelle. Cette fonction peut-être appelée en mode de modèle de programme en utilisant le modèle « {:”current_library_path()”} ».

current_virtual_library_name()¶

class calibre.utils.formatter_functions.BuiltinCurrentVirtualLibraryName[source]¶: current_virtual_library_name() – retourne le nom de la bibliothèque virtuelle actuelle s’il y en a une, sinon la chaîne vide. La casse du nom de la bibliothèque est préservée. Exemple : « program:current_virtual_library_name() ».

field(lookup_name)¶

class calibre.utils.formatter_functions.BuiltinField[source]¶: field(lookup_name) – retourne le champ de métadonnées nommé par lookup_name

formats_modtimes(date_format)¶

class calibre.utils.formatter_functions.BuiltinFormatsModtimes[source]¶: formats_modtimes(date_format) – retourne une liste séparée par des virgules d’éléments séparés par deux-points représentant les dates de modification pour les formats d’un livre. Le paramètre date_format indique comment la date doit être formatée. Regardez la fonction date_format pour des détails. Vous pouvez utiliser la fonction select pour obtenir le mod time pour un format spécifique.Veuillez noter que les noms de format sont toujours en majuscules, comme dans EPUB.

formats_paths()¶

class calibre.utils.formatter_functions.BuiltinFormatsPaths[source]¶: formats_paths() – retourne une liste séparées par des virgules d’éléments séparés par deux points représentant le chemin absolu vers les formats d’un livre. Vous pouvez utiliser cette fonction pour obtenir le chemin d’un format spécifique. Notez que ces noms de formats sont toujours en majuscule, comme dans EPUB.

formats_sizes()¶

class calibre.utils.formatter_functions.BuiltinFormatsSizes[source]¶: formats_sizes() – renvoie une liste séparée par des virgules correspondant à des articles représentant les tailles en octets des formats d’un livre. Vous pouvez utiliser la fonction select pour obtenir la taille d’un format spécifique. Notez que ces noms de formats sont toujours en majuscule, comme dans EPUB.

has_cover()¶

class calibre.utils.formatter_functions.BuiltinHasCover[source]¶: has_cover() – renvoie Yes si le livre a une couverture, sinon renvoie une chaine vide

is_marked()¶

class calibre.utils.formatter_functions.BuiltinIsMarked[source]¶: is_marked() – vérifie si le livre est “marqué” dans calibre. S’il l’est, il renvoie alors la valeur de la marque, soit « true », soit la liste des marques nommées séparées par des virgules. Retourne “” si le livre n’est pas marqué.

language_codes(lang_strings)¶

class calibre.utils.formatter_functions.BuiltinLanguageCodes[source]¶: language_codes(lang_strings) – retourne les codes de langue pour les chaines passées dans lang_strings. Les chaines doivent être dans la langue actuelle de localisation. Lang_strings est une liste séparée par des virgules.

language_strings(lang_codes, localize)¶

class calibre.utils.formatter_functions.BuiltinLanguageStrings[source]¶: language_strings(lang_codes, localize) – retourne les chaines des codes de langue passés dans lang_codes. Si localisation est égale à zéro, retourne les chaines en anglais. Si localisation est différente de zéro, retourne les chaines dans la langue utilisée actuellement. Lang_codes est une liste séparée par des virgules.

ondevice()¶

class calibre.utils.formatter_functions.BuiltinOndevice[source]¶: ondevice() – renvoie Yes si « Sur le périphérique » est activé, sinon renvoie une chaîne vide. Cette fonction n’est utilisable que dans l’interface utilisateur. Si vous désirez utiliser cette valeur dans « Enregistrer sous… » ou « Envoyer vers le périphérique connecté », vous devez créer une colonne personnalisée de type « Colonne construite à partir d’autres colonnes » et utiliser cette fonction dans le modèle de la colonne. Vous pourrez ensuite utiliser la valeur de la colonne dans vos modèles d’enregistrement / d’envoi.

raw_field(lookup_name [, optional_default]))¶

class calibre.utils.formatter_functions.BuiltinRawField[source]¶: raw_field(lookup_name [, optional_default])) – renvoie le champ de métadonnées nommé par lookup_name sans appliquer de formatage. Il évalue et renvoie le second argument optionnel “default” si le champ est indéfini (“None”).

raw_field(lookup_name, separator)¶

class calibre.utils.formatter_functions.BuiltinRawList[source]¶: raw_field(lookup_name, separator) – renvoie la liste de métadonnées nommée par lookup_name sans appliquer aucun formatage ou triage et avec les éléments séparés par separator.

series_sort()¶

class calibre.utils.formatter_functions.BuiltinSeriesSort[source]¶: series_sort() – renvoie la valeur de tri des séries

user_categories()¶

class calibre.utils.formatter_functions.BuiltinUserCategories[source]¶: user_categories() – retourne une liste séparée par des virgules des catégories utilisateur contenant ce livre, séparées par des virgules . Cette fonction n’est utilisable que dans l’interface utilisateur. Si vous désirez utiliser cette valeur dans « Enregistrer sous… » ou « Envoyer vers le périphérique connecté », vous devez créer une colonne personnalisée de type « Colonne construite à partir d’autres colonnes », utiliser cette fonction dans ce modèle de colonne, et utiliser la valeur de la colonne dans vos modèles d’enregistrement / d’envoi.

virtual_libraries()¶

class calibre.utils.formatter_functions.BuiltinVirtualLibraries[source]¶: virtual_libraries() – retourne une liste de bibliothèques virtuelles contenant ce livre, séparées par des virgules. Cette fonction n’est utilisable que dans l’interface utilisateur. Si vous désirez utiliser ces valeurs dans les modèles enregistrement-sur-disque ou envoi-vers-appareil, vous devez créer une colonne personnalisée de type « Colonne construite à partir d’autres colonnes », utiliser cette fonction dans le modèle de la colonne, et utiliser la valeur de la colonne dans vos modèles d’enregistrement/envoi.

If-then-else ¶

check_yes_no(field_name, is_undefined, is_false, is_true)¶

class calibre.utils.formatter_functions.BuiltinCheckYesNo[source]¶: check_yes_no(field_name, is_undefined, is_false, is_true) – vérifie la valeur du champ oui/non nommé par la clé de recherche field_name pour une valeur spécifiée par les paramètres, en retournant « yes » si une correspondance est trouvée, sinon en retournant une chaîne vide. Définissez le paramètre is_undefined, is_false, ou is_true à 1 (le nombre) pour vérifier cette condition, sinon mettez le à 0. Exemple : check_yes_no(« #bool », 1, 0, 1) renvoie « yes » si le champ oui/non « #bool » est soit indéfini (ni True ni False) ou True. Plus d’un des champs is_undefined, is_false ou is_true peut être mis à 1. Cette fonction est généralement utilisée par les fonctions test() ou is_empty().

contains(val, pattern, texte si correspondance, texte si pas de correspondance)¶

class calibre.utils.formatter_functions.BuiltinContains[source]¶: contains(val, pattern, texte si correspondance, texte si pas de correspondance) – vérifie si val contient des correspondances pour l’expression régulière pattern. Renvoie texte si correspondance si des correspondances sont trouvées, sinon il renvoie texte si pas de correspondance

field_exists(field_name)¶

class calibre.utils.formatter_functions.BuiltinFieldExists[source]¶: field_exists(field_name) – vérifie si un champ (colonne) nommé field_name existe, en retournant “1” si oui et “” si non.

ifempty(val, texte si vide)¶

class calibre.utils.formatter_functions.BuiltinIfempty[source]¶: ifempty(val, texte si vide) – renvoie val si val n’est pas vide, sinon renvoie texte si vide

test(val, text if not empty, text if empty)¶

class calibre.utils.formatter_functions.BuiltinTest[source]¶: test(val, text if not empty, text if empty) – renvoie texte si non vide si val n’est pas vide, sinon renvoie texte si vide

Iterating over values ¶

first_non_empty(value [, value]*)¶

class calibre.utils.formatter_functions.BuiltinFirstNonEmpty[source]¶: first_non_empty(value [, value]*) – retourne la première valeur non vide. Si toutes les valeurs sont vides, alors la chaîne vide est retournée. Vous pouvez avoir autant de valeurs que vous voulez.

lookup(val, [pattern, field,]+ else_field)¶

class calibre.utils.formatter_functions.BuiltinLookup[source]¶: lookup(val, [pattern, field,]+ else_field) – comme switch, sauf que les arguments sont des noms de champs (métadonnées) et non du texte. La valeur du champ approprié sera récupérée et utilisée. Notez que les colonnes composites étant des champs, vous pouvez utiliser cette fonction dans un champ composite pour utiliser la valeur d’un autre champ composite. Cette fonction est extrêmement utile pour construire des chemins de sauvegarde variables.

switch(val, [pattern, value,]+ else_value)¶

class calibre.utils.formatter_functions.BuiltinSwitch[source]¶: switch(val, [pattern, value,]+ else_value) – pour chaque paire pattern, value, vérifie si val correspond à l’expression régulière pattern et si oui, retourne cette value. Si aucun motif ne correspond, alors else_value est retourné. Vous pouvez avoir autant de paires pattern, value que vous le souhaitez.

switch_if([test_expression, value_expression,]+ else_expression)¶

class calibre.utils.formatter_functions.BuiltinSwitchIf[source]¶: switch_if([test_expression, value_expression,]+ else_expression) – pour chaque paire « test_expression, value_expression », vérifie si test_expression est vrai (non vide) et si c’est le cas, renvoie le résultat de value_expression. Si aucune test_expression n’est Vraie, le résultat de else_expression est renvoyé. Vous pouvez avoir autant de paires « test_expression, value_expression » que vous le souhaitez.

List lookup ¶

identifier_in_list(val, id_name [, found_val, not_found_val])¶

class calibre.utils.formatter_functions.BuiltinIdentifierInList[source]¶: identifier_in_list(val, id_name [, found_val, not_found_val]) – traite val comme une liste d’identifiants séparés par des virgules. Un identifiant a le format « id_name:value ». Le paramètre « id_name » est le texte de l’identifiant à rechercher, soit « id_name » soit « id_name:regexp ». Dans le premier cas, la recherche s’effectue s’il existe un identifiant correspondant à ce nom d’utilisateur. Dans le second cas, la recherche se fait si le « id_name » correspond à un identifiant et que l’expression rationnelle correspond à la valeur de l’identifiant. Si « found_val » et « not_found_val » sont fournis, alors s’il y a une correspondance, il retourne « found_val », sinon il retourne « not_found_val ». Si « found_val » et « not_found_val » ne sont pas fournis, alors s’il y a une correspondance, alors la paire « identifier:value » est retournée, sinon une chaîne vide.

in_list(val, separator, [ pattern, found_val, ]+ not_found_val)¶

class calibre.utils.formatter_functions.BuiltinInList[source]¶: in_list(val, separator, [ pattern, found_val, ]+ not_found_val) – Traite val comme une liste d’éléments séparés par un séparateur, si le motif correspond à l’une des valeurs de la liste, retourne found_val. Si le motif ne correspond à aucune valeur de la liste, retourne not_found_val. Les paires pattern et found_value peuvent être répétées autant de fois que souhaité. Les patterns sont vérifiés dans l’ordre. La valeur found_val de la première correspondance est retournée. Alias : in_list(), list_contains()

list_item(val, index, separator)¶

class calibre.utils.formatter_functions.BuiltinListitem[source]¶: list_item(val, index, separator) – interprète la valeur comme une liste d’articles séparée par separator, retourne l’article index. Le premier article est le nombre zéro. Le dernier article peut être retourné en utilisant list_item(-1,separator). Si l’article n’est pas dans liste, alors une valeur vide est renvoyée. Le séparateur a la même signafication que dans la fonction count.

select(val, key)¶

class calibre.utils.formatter_functions.BuiltinSelect[source]¶: select(val, key) – interprète la valeur comme une liste d’éléments séparés par des virgules, les éléments étant « id:value ». Trouve la paire dont l’id est égal à key, et retourne la valeur correspondante. Retourne la chaîne vide si aucune correspondance n’est trouvée.

str_in_list(val, separator, [string, found_val, ]+ not_found_val)¶

class calibre.utils.formatter_functions.BuiltinStrInList[source]¶: str_in_list(val, separator, [string, found_val, ]+ not_found_val) – Traite val comme une liste d’éléments séparés par un séparateur, si la chaîne de caractères correspond à l’une des valeurs de la liste, elle renvoie found_val. La comparaison est exacte (pas de contenu) et n’est pas sensible à la casse. Les paires string et found_value peuvent être répétées autant de fois que souhaité. Les patterns sont vérifiés dans l’ordre. La valeur found_val de la première correspondance est renvoyée.

List manipulation ¶

count(separator)¶

class calibre.utils.formatter_functions.BuiltinCount[source]¶: count(separator) – interprète la valeur comme une liste d’articles séparés par separator, retourne le nombre d’articles dans la liste. Beaucoup de listes utilisent une virgule comme séparateur, mais les auteurs utilisent l’esperluette. Exemples: {tags:count(,)}, {authors:count(&)}. Alias : count(), list_count()

list_count_matching(list, pattern, separator)¶

class calibre.utils.formatter_functions.BuiltinListCountMatching[source]¶: list_count_matching(list, pattern, separator) – interprète “list” comme une liste d’éléments séparés par “separator”, en retournant le nombre d’éléments dans la liste qui correspondent à l’expression régulière “pattern”. Alias : list_count_matching(), count_matching()

list_difference(list1, list2, separator)¶

class calibre.utils.formatter_functions.BuiltinListDifference[source]¶: list_difference(list1, list2, separator) – restitue une liste en supprimant de list1 tout élément trouvé dans list2 en utilisant une comparaison insensible à la casse. Les éléments dans list1 et list2 sont séparés par le séparateur, comme le sont les éléments dans la liste restituée.

list_equals(list1, sep1, list2, sep2, yes_val, no_val)¶

class calibre.utils.formatter_functions.BuiltinListEquals[source]¶: list_equals(list1, sep1, list2, sep2, yes_val, no_val) –retourne yes_val si la liste 1 et la liste 2 contiennent les mêmes éléments, sinon renvoie no_val. Les éléments sont déterminés en éclatant chaque liste à l’aide du séparateur approprié (sep1 ou sep2). L’ordre des éléments dans la liste n’est pas pris en compte. La comparaison est insensible à la casse.

list_intersection(list1, list2, separator)¶

class calibre.utils.formatter_functions.BuiltinListIntersection[source]¶: list_intersection(list1, list2, separator) – restitue une liste en supprimant de list1 tout élément non trouvé dans list2 en utilisant une comparaison insensible à la casse. Les éléments dans list1 et list2 sont séparés par le séparateur, comme le sont les éléments dans la liste restituée.

list_join(with_separator, list1, separator1 [, list2, separator2]*)¶

class calibre.utils.formatter_functions.BuiltinListJoin[source]¶

list_join(with_separator, list1, separator1 [, list2, separator2]*) – retourne une liste faite en joignant les éléments des listes sources (list1 etc) en utilisant with_separator entre les éléments de la liste résultante. Les éléments de chaque liste[123…] source sont séparés par le séparateur[123…] associé. Une liste peut contenir zéro valeur. Il peut s’agir d’un champ comme publisher qui n’a qu’une seule valeur, c’est à dire une liste d’un seul élément. Les doublons sont supprimés en utilisant une comparaison insensible à la casse. Les éléments sont retournés dans l’ordre où ils apparaissent dans les listes sources. Si les éléments des listes ne diffèrent que par la casse des lettres, c’est la dernière qui est utilisée. Tous les séparateurs peuvent comporter plus d’un caractère. Exemple :

program:
list_join(“#@#”, $authors, “&”, $tags, “,”)

Vous pouvez utiliser list_join sur les résultats des appels précédents à list_join comme suit :

program:

a = list_join(“#@#”, $authors, “&”, $tags, “,”); b = list_join(“#@#”, a, “#@#”, $#genre, “,”, $#people, “&”)

Vous pouvez utiliser des expressions pour générer une liste. Par exemple, supposons que vous vouliez des éléments pour auteurs et #genre, mais avec le genre changé en mot “Genre“ suivi de la première lettre du genre, c’est-à-dire que le genre “Fiction” devient “GenreF”. Ce qui suit fera l’affaire :

program:: list_join(“#@#”, $authors, “&”, list_re($#genre, “,”, “^(.).*$”, “Genre: 1”), “,”)

list_re(src_list, separator, include_re, opt_replace)¶

class calibre.utils.formatter_functions.BuiltinListRe[source]¶: list_re(src_list, separator, include_re, opt_replace) – Construit une liste en séparant d’abord src_list en éléments utilisant le caractère de séparation. Pour chaque élément dans la liste, vérifie s’il correspond à include_re. Si c’est le cas, alors il l’ajoute à la liste à renvoyer. Si opt_replace n’est pas une chaîne vide, alors effectue le remplacement avant d’ajouter l’élément à la liste renvoyée.

list_re_group(src_list, separator, include_re, search_re [, group_template]+)¶

class calibre.utils.formatter_functions.BuiltinListReGroup[source]¶: list_re_group(src_list, separator, include_re, search_re [, group_template]+) – Comme list_re sauf que les remplacements ne sont pas optionnels. Elle utilise re_group(list_item, search_re, group_template, …) pour effectuer les remplacements sur la liste résultante.

list_remove_duplicates(list, separator)¶

class calibre.utils.formatter_functions.BuiltinListRemoveDuplicates[source]¶: list_remove_duplicates(list, separator) – retourne une liste faite en supprimant les éléments en double dans la liste des sources. Si les éléments ne diffèrent qu’au cas par cas, le dernier d’entre eux est renvoyé. Les éléments de la liste source sont séparés par un séparateur, tout comme les éléments de la liste retournée.

list_sort(liste, direction, separator)¶

class calibre.utils.formatter_functions.BuiltinListSort[source]¶: list_sort(liste, direction, separator) – retourne une liste triée en utilisant un tri insensible à la casse. Si la direction est zéro, la liste est triée de manière ascendante, sinon descendante. Les éléments des listes 1 et 2 sont séparés par le séparateur, comme ceux de la liste retournée.

list_split(list_val, sep, id_prefix)¶

class calibre.utils.formatter_functions.BuiltinListSplit[source]¶: list_split(list_val, sep, id_prefix) – divise la list_val en valeurs séparées en utilisant “sep”, puis affecte les valeurs à des variables nommées “id_prefix_N” où N est la position de la valeur dans la liste. Le premier élément a la position 0 (zéro). La fonction renvoie le dernier élément de la liste. Exemple : split(“one:two:foo”, “:”, “var”) est équivalent à var_0 = “one” ; var_1 = “two” ; var_2 = “foo”.

list_union(list1, list2, separator)¶

class calibre.utils.formatter_functions.BuiltinListUnion[source]¶: list_union(list1, list2, separator) – restitue une liste créée de la fusion des éléments dans list1 et list2, supprimant les doublons en utilisant une comparaison insensible à la casse. Si la casse des éléments diffère, celle de list1 est utilisée. Les éléments dans list1 et list2 sont séparés par le séparateur, comme ceux de la liste restituée. Alias: list_union(), merge_lists()

range(start, stop, step, limit)¶

class calibre.utils.formatter_functions.BuiltinRange[source]¶: range(start, stop, step, limit) – renvoie une liste de nombres générés en bouclant sur la plage spécifiée par les paramètres start, stop, et step, avec une longueur maximale de limit. La première valeur produite est “start”. Les valeurs suivantes next_v sont current_v+step. La boucle continue pendant que next_v < stop en supposant que le pas est positif, sinon pendant que next_v > stop. Une liste vide est produite si start échoue le test : start>=stop si step est positif. La limite définit la longueur maximale de la liste et a une valeur par défaut de 1000. Les paramètres start, step et limit sont facultatifs. L’appel de range() avec un seul argument spécifie stop. Deux arguments spécifient start et stop. Trois arguments spécifient start, stop et step. Quatre arguments spécifient start, stop, le step et limit. Exemples : range(5)->”0,1,2,3,4”. range(0,5)->”0,1,2,3,4”. range(-1,5)->”-1,0,1,2,3,4”. range(1,5)->”1,2,3,4”. range(1,5,2)->”1,3”. range(1,5,2)->”1,3”. range(1,5,2,5)->”1,3”. range(1,5,2,1)->error(limite dépassée).

subitems(val, start_index, end_index)¶

class calibre.utils.formatter_functions.BuiltinSubitems[source]¶: subitems(val, start_index, end_index) – Cette fonction est utilisée pour séparer des listes d’éléments comme les genres. Elle interprète la valeur comme une liste d’éléments séparés par des virgules, où chaque élément est une liste séparée par des points. Retourne une nouvelle liste composée en trouvant d’abord tous les éléments séparés par des points, puis pour chacun de ces éléments en extrayant les composantes entre start_index et end_index avant de les recombiner. Le premier élément dans une liste séparée par des points a un index de 0. Si un index est négatif, alors il part de la fin de la liste. Comme cas spécial, un fin_index de zéro est considéré comme étant la longueur de la liste. Des exemples utilisant le mode de modèle basique et supposant une valeur de #genre de « A.B.C » : {#genre:subitems(0,1)} retourne « A ». {#genre:subitems(0,2)} retourne « A.B ». {#genre:subitems(1,0)} retourne « B.C ». Supposant une valeur de #genre de « A.B.C, D.E.F », {#genre:subitems(0,1)} retourne « A, D ». {#genre:subitems(0,2)} retourne « A.B, D.E »

sublist(val, start_index, end_index, séparator)¶

class calibre.utils.formatter_functions.BuiltinSublist[source]¶: sublist(val, start_index, end_index, séparator) – interprète la valeur comme une liste d’éléments séparés par séparator, retournant une nouvelle liste composée des éléments compris entre start_index et fin_index. Le premier élément est le numéro 0. Si un index est négatif, alors il part de la fin de la liste. Comme cas spécial, un fin_index de zéro est considéré comme étant la longueur de la liste. Des exemples utilisant le mode de modèle basique et supposant que la colonne des étiquettes (qui sont séparées par des virgules) contient « A, B, C » : {tags:sublist(0,1,\,)} retourne « A ». {tags:sublist(-1,0,\,)} retourne « C ». {tags:sublist(0,-1,\,)} retourne « A, B ».

Other ¶

arguments(id[=expression] [, id[=expression]]*)¶

class calibre.utils.formatter_functions.BuiltinArguments[source]¶: arguments(id[=expression] [, id[=expression]]*) – Utilisé dans un modèle stocké pour récupérer les arguments passés dans l’appel. Il déclare et initialise à la fois des variables locales, en fait des paramètres. Les variables sont positionnelles ; elles obtiennent la valeur du paramètre donné dans l’appel dans la même position. Si le paramètre correspondant n’est pas fourni dans l’appel, alors les arguments attribuent à cette variable la valeur par défaut fournie. S’il n’y a pas de valeur par défaut, alors la variable est définie comme une chaîne vide.

assign(id, val)¶

class calibre.utils.formatter_functions.BuiltinAssign[source]¶: assign(id, val) – assigne val à id, puis retourne val. id doit être un identifiant, pas une expression. Cette fonction peut souvent être remplacée par l’opérateur =.

globals(id[=expression] [, id[=expression]]*)¶

class calibre.utils.formatter_functions.BuiltinGlobals[source]¶: globals(id[=expression] [, id[=expression]]*) – Récupère les « variables globales » qui peuvent être passées dans le formateur. Il déclare et initialise les variables locales avec les noms des variables globales passées. Si la variable correspondante n’est pas fournie dans les variables globales transmises, il lui attribue la valeur par défaut fournie. S’il n’y a pas de valeur par défaut, alors la variable est définie comme une chaîne vide.

print(a[, b]*)¶

class calibre.utils.formatter_functions.BuiltinPrint[source]¶: print(a[, b]*) – affiche les arguments sur la sortie standard. À moins que vous ne lanciez calibre depuis la ligne de commande (calibre-debug -g), la sortie ira dans un trou noir.

Recursion ¶

eval(modèle)¶

class calibre.utils.formatter_functions.BuiltinEval[source]¶: eval(modèle) – évalue le modèle, en passant les variables locales (celles assignées) à la place des métadonnées du livre. Cela permet en utilisant le traitement du modèle de construire des résultats complexes à partir de variables locales. Parce que les caractères { et } sont spéciaux, vous devez utiliser [[ pour le caractère { et ]] pour le caractère } ; ils sont convertis automatiquement. Notez également que les préfixes et les suffixes (la syntaxe |prefix|suffix) ne peuvent pas être utilisés dans les arguments de cette fonction lorsque le mode modèle de programme est utilisé.

template(x)¶

class calibre.utils.formatter_functions.BuiltinTemplate[source]¶: template(x) – évalue x comme un modèle. L’évaluation est effectuée dans son propre contexte, cela veut dire que les variables ne sont pas partagées entre l’appelant et l’évaluation du modèle. Comme les caractères { et } sont spéciaux, vous devez utiliser [[ pour le caractère { et ]] pour le caractère }; ils sont convertis automatiquement. Par exemple, template(“[[title_sort]]”) évaluera le modèle {title_sort} et retournera sa valeur. Notez également que les préfixes et les suffixes (la syntaxe |prefix|suffix syntax) ne peuvent pas être utilisés dans les arguments de cette fonction lorsque le mode modèle de programme est utilisé.

Relational ¶

cmp(x, y, lt, eq, gt)¶

class calibre.utils.formatter_functions.BuiltinCmp[source]¶: cmp(x, y, lt, eq, gt) – compare x et y après les avoir convertis en nombres. Retourne lt si x < y. Retourne eq si x == y. Sinon, retourne gt. Dans de nombreux cas, les opérateurs de comparaison numérique (>#, <#, ==# etc) peuvent remplacer cette fonction.

first_matching_cmp(val, cmp1, result1,]+, else_result)¶

class calibre.utils.formatter_functions.BuiltinFirstMatchingCmp[source]¶: first_matching_cmp(val, cmp1, result1,]+, else_result) – compare « val < cmpN » dans la séquence, retourne resultN pour la première comparaison qui réussit. Retourne un autre résultat si aucune comparaison ne réussit. Exemple: first_matching_cmp(10,5, »petit »,10, »moyen »,15, »grand », »géant ») retourne « grand ». Le même exemple avec une première valeur de 16 retourne « géant ».

strcmp(x, y, lt, eq, gt)¶

class calibre.utils.formatter_functions.BuiltinStrcmp[source]¶: strcmp(x, y, lt, eq, gt) – effectue une comparaison insensible à la casse de x et y en tant que chaînes de caractères. Retourne lt si x < y. Retourne eq si x == y. Sinon, retourne gt. Dans de nombreux cas, les opérateurs de comparaison lexicale (>, <, == etc) peuvent remplacer cette fonction.

strcmpcase(x, y, lt, eq, gt)¶

class calibre.utils.formatter_functions.BuiltinStrcmpcase[source]¶: strcmpcase(x, y, lt, eq, gt) – effectue une comparaison sensible à la casse de x et y en tant que chaînes de caractères. Retourne lt si x < y. Retourne eq si x == y. Sinon, retourne gt. Note : Ce n’est PAS le comportement par défaut utilisé par calibre, par exemple, dans les opérateurs de comparaison lexicale (==, >, <, etc.). Cette fonction pourrait provoquer des résultats inattendus, utilisez de préférence strcmp() lorsque cela est possible.

String case changes ¶

capitalize(val)¶

class calibre.utils.formatter_functions.BuiltinCapitalize[source]¶: capitalize(val) – renvoie val en lettres capitales

lowercase(val)¶

class calibre.utils.formatter_functions.BuiltinLowercase[source]¶: lowercase(val) – renvoie val en miniscule

titlecase(val)¶

class calibre.utils.formatter_functions.BuiltinTitlecase[source]¶: titlecase(val) – renvoie val en casse titre

uppercase(val)¶

class calibre.utils.formatter_functions.BuiltinUppercase[source]¶: uppercase(val) – renvoie val en majuscule

String manipulation ¶

character(character_name)¶

class calibre.utils.formatter_functions.BuiltinCharacter[source]¶: character(character_name) – renvoie le caractère nommé par character_name. Par exemple, character(“newline”) renvoie un caractère de nouvelle ligne (”n”). Les noms de caractères pris en charge sont “newline”, “return”, “tab” et “backslash”.

re(val, pattern, replacement)¶

class calibre.utils.formatter_functions.BuiltinRe[source]¶: re(val, pattern, replacement) – renvoie le champ après avoir appliquer l’expression régulière. Toutes les instances de pattern seront remplacées par replacement. Comme tout dans calibre, celles-ci sont des expressions régulières compatibles Python

re_group(val, pattern [, template_for_group]*)¶

class calibre.utils.formatter_functions.BuiltinReGroup[source]¶: re_group(val, pattern [, template_for_group]*) – renvoie une chaîne faite en appliquant le modèle d’expression régulière à la valeur et en remplaçant chaque instance assortie par la chaîne calculée en remplaçant chaque groupe assorti par la valeur retournée par le modèle correspondant. La valeur assortie originale pour le groupe est disponible comme $. En mode programmation de modèle, comme pour le modèle et les fonctions eval, vous utiliserez [[pour { et ]] pour}. L’exemple suivant en mode programmation de modèle recherche des séries avec plus d’un mot et des majuscules dans le premier mot : {series:”re_group($, « (S* )(.*) », « [[$:uppercase()]] », « [[$]] »)”}

shorten(val, left chars, middle text, right chars)¶

class calibre.utils.formatter_functions.BuiltinShorten[source]¶: shorten(val, left chars, middle text, right chars) – Retourne une version raccourcie de val, constituée par les left chars caractères du début de val, suivis par middle text et enfin par right chars de la fin de la chaîne. left chars et right chars doivent être des entiers. Par exemple, supposons que le titre du livre est Anciennes Lois Anglaises aux Temps d’Ivanhoe, et que vous voulez que ce titre rentre dans un espace maximal de 15 caractères. Si vous utilisez {title:shorten(9,-,5)}, le resultat sera Ancienn L-anhoe. Si la longueur du champ est inférieure à caractères à gauche + caractères à droite + la longueur de texte du milieu, alors le champ ne sera pas modifié. Par exemple, le titre Le Dôme ne serait pas modifié.

strcat(a [, b]*)¶

class calibre.utils.formatter_functions.BuiltinStrcat[source]¶: strcat(a [, b]*) – peut avoir tout nombre d’arguments. Renvoie la chaîne constituée par la concaténation de tous les arguments

strcat_max(max, string1 [, prefix2, string2]*)¶

class calibre.utils.formatter_functions.BuiltinStrcatMax[source]¶: strcat_max(max, string1 [, prefix2, string2]*) – Retourne la chaîne de caractères formée de la concaténation des arguments. La valeur retournée est initialisée à string1. Les paires Prefix,string sont ajoutées au bout de la valeur tant que la taille de la chaîne de sortie est plus petite que max. String1 est retournée même si string1 est plus grande que max. Vous pouvez passer autant de paires de prefix,string que vous le souhaitez.

strlen(a)¶

class calibre.utils.formatter_functions.BuiltinStrlen[source]¶: strlen(a) – Retourne la longueur de la chaîne de caractères passée en argument

substr(ch, start, end)¶

class calibre.utils.formatter_functions.BuiltinSubstr[source]¶: substr(ch, start, end) – renvoie les caractères de début jusqu’à fin de la chaîne ch. Le premier caractère dans la chaine ch est le caractère 0. Si fin est négatif, cela indique que le comptage des caractères est effectué à partir de la droite. Si end est à zéro, cela indique le dernier caractère. Par exemple, substr(“12345”, 1, 0) renvoie “2345”, et substr(“12345”, 1, -1) renvoie “234”.

swap_around_articles(separator)¶

class calibre.utils.formatter_functions.BuiltinSwapAroundArticles[source]¶: swap_around_articles(separator) – renvoie la val avec les articles déplacés à la fin. La valeur peut être une liste, auquel cas chaque membre de la liste est traité. Si la valeur est une liste, alors vous devez fournir le séparateur de valeur de liste. Si aucun séparateur n’est fourni, la valeur est traitée comme une valeur unique et non comme une liste.

swap_around_comma(val)¶

class calibre.utils.formatter_functions.BuiltinSwapAroundComma[source]¶: swap_around_comma(val) – pour une valeur au format « B, A », renvoie « A B ». Ceci est très utile pour la conversion des noms du format LN, FN vers FN LN. Si il n’y a pas de virgule, la fonction renvoie val non modifiée

to_hex(val)¶

class calibre.utils.formatter_functions.BuiltinToHex[source]¶: to_hex(val) – renvoie la chaîne encodée en hexadécimal. Ceci est utile lors de la construction d’URLs calibre.

transliterate(a)¶

class calibre.utils.formatter_functions.BuiltinTransliterate[source]¶: transliterate(a) - Restitue une chaîne en alphabet latin représentant approximativement le son des mots de la chaîne source. Par exemple, avec la source « Фёдор Миха́йлович Достоевский » la fonction renverra « Fiodor Mikhailovich Dostoievskii ».

Template database functions ¶

book_count(query, use_vl)¶

class calibre.utils.formatter_functions.BuiltinBookCount[source]¶: book_count(query, use_vl) – retourne le nombre de livres trouvés en cherchant la requête. Si use_vl est 0 (zéro) alors les bibliothèques virtuelles sont ignorées. Cette fonction ne peut être utilisée que dans l’interface graphique.

book_values(column, query, sep, use_vl)¶

class calibre.utils.formatter_functions.BuiltinBookValues[source]¶: book_values(column, query, sep, use_vl) – renvoie une liste des valeurs contenues dans la colonne « column », séparées par « sep », dans les livres trouvés en recherchant « query ». Si use_vl vaut 0 (zéro), les bibliothèques virtuelles sont ignorées. Cette fonction ne peut être utilisée que dans l’interface graphique.

extra_file_modtime(file_name, format_string)¶

class calibre.utils.formatter_functions.BuiltinExtraFileModtime[source]¶: extra_file_modtime(file_name, format_string) – retourne l’heure de modification du fichier supplémentaire « file_name » dans le dossier « data/ » du livre s’il existe, sinon -1. La date de modification est formatée selon « format_spec » (voir format_date() pour plus de détails). Si « format_spec » est une chaîne vide, elle retourne l’heure de modification sous la forme d’un nombre de secondes en virgule flottante depuis Epoch. L’Epoch dépend du système d’exploitation. Cette fonction ne peut être utilisée que dans l’interface graphique.

extra_file_names(sep [, pattern])¶

class calibre.utils.formatter_functions.BuiltinExtraFileNames[source]¶: extra_file_names(sep [, pattern]) – retourne une liste séparée de « sep » de fichiers supplémentaires dans le dossier « data/ » du livre. Si le paramètre optionnel « pattern », une expression régulière, est fourni, alors la liste est filtrée sur les fichiers qui correspondent à « pattern ». La correspondance est insensible à la casse. Cette fonction ne peut être utilisée que dans l’interface graphique.

extra_file_size(file_name)¶

class calibre.utils.formatter_functions.BuiltinExtraFileSize[source]¶: extra_file_size(file_name) – retourne la taille en octets du fichier supplémentaire « file_name » dans le dossier « data/ » du livre s’il existe, sinon -1. Cette fonction ne peut être utilisée que dans l’interface graphique.

get_link(field_name, field_value)¶

class calibre.utils.formatter_functions.BuiltinGetLink[source]¶: get_link(field_name, field_value) – récupère le lien pour le champ « field_name » avec la valeur « field_value ». S’il n’y a pas de lien attaché, il renvoie “”. Exemple : get_link(“tags”, “Fiction”) renvoie le lien attaché a l’étiquette « Fiction ».

get_note(field_name, field_value, plain_text)¶

class calibre.utils.formatter_functions.BuiltinGetNote[source]¶: get_note(field_name, field_value, plain_text) – récupère la note pour le champ « field_name » avec la valeur « field_value ». Si « plain_text » est vide, le HTML de la note est retourné. Si « plain_text » n’est pas vide, la note est retournée en texte brut. Si la note n’existe pas, le système renvoie “” dans les deux cas. Exemple : get_note(“tags”, “Fiction”, “”) renvoie le code HTML de la note attachée a l’étiquette « Fiction ».

has_extra_files([pattern])¶

class calibre.utils.formatter_functions.BuiltinHasExtraFiles[source]¶: has_extra_files([pattern]) – retourne le nombre de fichiers supplémentaires, sinon “” (la chaîne vide). Si le paramètre optionnel « pattern » (une expression régulière) est fourni, alors la liste est filtrée sur les fichiers qui correspondent à « pattern » avant que les fichiers ne soient comptés. La correspondance est insensible à la casse. Cette fonction ne peut être utilisée que dans l’interface graphique.

has_note(field_name, field_value)¶

class calibre.utils.formatter_functions.BuiltinHasNote[source]¶: has_note(field_name, field_value) – renvoie “1” si la valeur « field_value » dans le champ « field_name » a une note attachée, “” sinon. Exemple : has_note(“tags”, “Fiction”) renvoie “1” si le tag « Fiction » a une note attachée, sinon “”.

other ¶

set_globals(id[=expression] [, id[=expression]]*)¶

class calibre.utils.formatter_functions.BuiltinSetGlobals[source]¶: set_globals(id[=expression] [, id[=expression]]*) – Définit les « variables globales » qui peuvent être passées au formateur. Les variables globales reçoivent le nom de l’id passé. La valeur de l’id est utilisée sauf si une expression est fournie.

API of the Metadata objects ¶

The python implementation of the template functions is passed in a Metadata object. Knowing it’s API is useful if you want to define your own template functions.

class calibre.ebooks.metadata.book.base.Metadata(title, authors=('Inconnu(e)',), other=None, template_cache=None, formatter=None)[source]¶

A class representing all the metadata for a book. The various standard metadata fields are available as attributes of this object. You can also stick arbitrary attributes onto this object.

Metadata from custom columns should be accessed via the get() method, passing in the lookup name for the column, for example: « #mytags ».

Use the is_null() method to test if a field is null.

This object also has functions to format fields into strings.

The list of standard metadata fields grows with time is in STANDARD_METADATA_FIELDS.

Please keep the method based API of this class to a minimum. Every method becomes a reserved field name.

is_null(field)[source]¶

Return True if the value of field is null in this object. “null” means it is unknown or evaluates to False. So a title of _(“Unknown”) is null or a language of “und” is null.

Be careful with numeric fields since this will return True for zero as well as None.

Also returns True if the field does not exist.

deepcopy(class_generator=<function Metadata.<lambda>>)[source]¶: Do not use this method unless you know what you are doing, if you want to create a simple clone of this object, use deepcopy_metadata() instead. Class_generator must be a function that returns an instance of Metadata or a subclass of it.

get_identifiers()[source]¶: Return a copy of the identifiers dictionary. The dict is small, and the penalty for using a reference where a copy is needed is large. Also, we don’t want any manipulations of the returned dict to show up in the book.

set_identifiers(identifiers)[source]¶: Set all identifiers. Note that if you previously set ISBN, calling this method will delete it.

set_identifier(typ, val)[source]¶: If val is empty, deletes identifier of type typ

standard_field_keys()[source]¶: return a list of all possible keys, even if this book doesn’t have them

custom_field_keys()[source]¶: return a list of the custom fields in this book

all_field_keys()[source]¶: All field keys known by this instance, even if their value is None

metadata_for_field(key)[source]¶: return metadata describing a standard or custom field.

all_non_none_fields()[source]¶: Return a dictionary containing all non-None metadata fields, including the custom ones.

get_standard_metadata(field, make_copy)[source]¶: return field metadata from the field if it is there. Otherwise return None. field is the key name, not the label. Return a copy if requested, just in case the user wants to change values in the dict.

get_all_standard_metadata(make_copy)[source]¶: return a dict containing all the standard field metadata associated with the book.

get_all_user_metadata(make_copy)[source]¶: return a dict containing all the custom field metadata associated with the book.

get_user_metadata(field, make_copy)[source]¶: return field metadata from the object if it is there. Otherwise return None. field is the key name, not the label. Return a copy if requested, just in case the user wants to change values in the dict.

set_all_user_metadata(metadata)[source]¶: store custom field metadata into the object. Field is the key name not the label

set_user_metadata(field, metadata)[source]¶: store custom field metadata for one column into the object. Field is the key name not the label

remove_stale_user_metadata(other_mi)[source]¶: Remove user metadata keys (custom column keys) if they don’t exist in “other_mi”, which must be a metadata object

template_to_attribute(other, ops)[source]¶: Takes a list [(src,dest), (src,dest)], evaluates the template in the context of other, then copies the result to self[dest]. This is on a best-efforts basis. Some assignments can make no sense.

smart_update(other, replace_metadata=False)[source]¶: Merge the information in other into self. In case of conflicts, the information in other takes precedence, unless the information in other is NULL.

format_field(key, series_with_index=True)[source]¶: Returns the tuple (display_name, formatted_value)

to_html()[source]¶: A HTML representation of this object.

calibre.ebooks.metadata.book.base.STANDARD_METADATA_FIELDS¶: The set of standard metadata fields.

'''
All fields must have a NULL value represented as None for simple types,
an empty list/dictionary for complex types and (None, None) for cover_data
'''

SOCIAL_METADATA_FIELDS = frozenset((
    'tags',             # Ordered list
    'rating',           # A floating point number between 0 and 10
    'comments',         # A simple HTML enabled string
    'series',           # A simple string
    'series_index',     # A floating point number
    # Of the form { scheme1:value1, scheme2:value2}
    # For example: {'isbn':'123456789', 'doi':'xxxx', ... }
    'identifiers',
))

'''
The list of names that convert to identifiers when in get and set.
'''

TOP_LEVEL_IDENTIFIERS = frozenset((
    'isbn',
))

PUBLICATION_METADATA_FIELDS = frozenset((
    'title',            # title must never be None. Should be _('Unknown')
    # Pseudo field that can be set, but if not set is auto generated
    # from title and languages
    'title_sort',
    'authors',          # Ordered list. Must never be None, can be [_('Unknown')]
    'author_sort_map',  # Map of sort strings for each author
    # Pseudo field that can be set, but if not set is auto generated
    # from authors and languages
    'author_sort',
    'book_producer',
    'timestamp',        # Dates and times must be timezone aware
    'pubdate',
    'last_modified',
    'rights',
    # So far only known publication type is periodical:calibre
    # If None, means book
    'publication_type',
    'uuid',             # A UUID usually of type 4
    'languages',        # ordered list of languages in this publication
    'publisher',        # Simple string, no special semantics
    # Absolute path to image file encoded in filesystem_encoding
    'cover',
    # Of the form (format, data) where format is, e.g. 'jpeg', 'png', 'gif'...
    'cover_data',
    # Either thumbnail data, or an object with the attribute
    # image_path which is the path to an image file, encoded
    # in filesystem_encoding
    'thumbnail',
))

BOOK_STRUCTURE_FIELDS = frozenset((
    # These are used by code, Null values are None.
    'toc', 'spine', 'guide', 'manifest',
))

USER_METADATA_FIELDS = frozenset((
    # A dict of dicts similar to field_metadata. Each field description dict
    # also contains a value field with the key #value#.
    'user_metadata',
))

DEVICE_METADATA_FIELDS = frozenset((
    'device_collections',   # Ordered list of strings
    'lpath',                # Unicode, / separated
    'size',                 # In bytes
    'mime',                 # Mimetype of the book file being represented
))

CALIBRE_METADATA_FIELDS = frozenset((
    'application_id',   # An application id, currently set to the db_id.
    'db_id',            # the calibre primary key of the item.
    'formats',          # list of formats (extensions) for this book
    # a dict of user category names, where the value is a list of item names
    # from the book that are in that category
    'user_categories',
    # a dict of items to associated hyperlink
    'link_maps',
))

ALL_METADATA_FIELDS =      SOCIAL_METADATA_FIELDS.union(
                           PUBLICATION_METADATA_FIELDS).union(
                           BOOK_STRUCTURE_FIELDS).union(
                           USER_METADATA_FIELDS).union(
                           DEVICE_METADATA_FIELDS).union(
                           CALIBRE_METADATA_FIELDS)

# All fields except custom fields
STANDARD_METADATA_FIELDS = SOCIAL_METADATA_FIELDS.union(
                           PUBLICATION_METADATA_FIELDS).union(
                           BOOK_STRUCTURE_FIELDS).union(
                           DEVICE_METADATA_FIELDS).union(
                           CALIBRE_METADATA_FIELDS)

# Metadata fields that smart update must do special processing to copy.
SC_FIELDS_NOT_COPIED =     frozenset(('title', 'title_sort', 'authors',
                                      'author_sort', 'author_sort_map',
                                      'cover_data', 'tags', 'languages',
                                      'identifiers'))

# Metadata fields that smart update should copy only if the source is not None
SC_FIELDS_COPY_NOT_NULL =  frozenset(('device_collections', 'lpath', 'size', 'comments', 'thumbnail'))

# Metadata fields that smart update should copy without special handling
SC_COPYABLE_FIELDS =       SOCIAL_METADATA_FIELDS.union(
                           PUBLICATION_METADATA_FIELDS).union(
                           BOOK_STRUCTURE_FIELDS).union(
                           DEVICE_METADATA_FIELDS).union(
                           CALIBRE_METADATA_FIELDS) - \
                           SC_FIELDS_NOT_COPIED.union(
                           SC_FIELDS_COPY_NOT_NULL)

SERIALIZABLE_FIELDS =      SOCIAL_METADATA_FIELDS.union(
                           USER_METADATA_FIELDS).union(
                           PUBLICATION_METADATA_FIELDS).union(
                           CALIBRE_METADATA_FIELDS).union(
                           DEVICE_METADATA_FIELDS) - \
                           frozenset(('device_collections', 'formats',
                               'cover_data'))
# these are rebuilt when needed