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) – renvoie x + y. Renvoie une exception si x ou y ne sont pas des nombres.

divide(x, y)

class calibre.utils.formatter_functions.BuiltinDivide[source]

divide(x, y) – renvoie x / y. Renvoie une exception si x ou y ne sont pas des nombres.

multiply(x, y)

class calibre.utils.formatter_functions.BuiltinMultiply[source]

multiply(x, y) – renvoie x * y. Renvoie une exception si x ou y ne sont pas des nombres.

subtract(x, y)

class calibre.utils.formatter_functions.BuiltinSubtract[source]

subtract(x, y) – renvoie x - y. Renvoie une exception si x ou y ne sont pas des nombres.

Boolean

and(value, value, …)

class calibre.utils.formatter_functions.BuiltinAnd[source]

and(value, value, …) – renvoie la chaîne « 1 » si toutes les valeurs ne sont pas vides, sinon renvoie la chaîne vide. Cette fonction fonctionne très bien avec test ou first_non_empty. Vous pouvez avoir autant de valeurs que vous voulez.

not(value)

class calibre.utils.formatter_functions.BuiltinNot[source]

not(value) – renvoie la chaîne « 1 » si la valeur est vide, sinon renvoie la chaîne vide. Cette fonction fonctionne très bien avec test ou first_non_empty.

or(value, value, …)

class calibre.utils.formatter_functions.BuiltinOr[source]

or(value, value, …) – renvoie la chaîne « 1 » si n’importe quelle valeur n’est pas vide, sinon renvoie la chaîne vide. Cette fonction fonctionne très bien avec test ou first_non_empty. Vous pouvez avoir autant de valeurs que vous voulez.

Date functions

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, format_string)

class calibre.utils.formatter_functions.BuiltinFormatDate[source]

format_date(val, format_string) – formate la valeur, qui doit être une date, en utilisant format_string, 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 » à « Dim »). dddd : le nom du jour localisé en entier (p. ex. « Lundi » à « 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 » à « 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

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.

Get values from metadata

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_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.

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()”} ».

field(nom)

class calibre.utils.formatter_functions.BuiltinField[source]

field(nom) – renvoie le champ de métadonnée nommé par nom

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

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(name, separator)

class calibre.utils.formatter_functions.BuiltinRawList[source]

raw_field(name, separator) – renvoie la liste de métadonnées nommée par name sans appliquer aucun formatage ou triage et avec les éléments séparés par separator.

raw_field(nom)

class calibre.utils.formatter_functions.BuiltinRawField[source]

raw_field(nom) – renvoie le champ de métadonnées nommé par nom sans appliquer aucune mise en forme.

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

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, la valeur vide est retournée. Vous pouvez avoir autant de valeurs que vous voulez.

lookup((val, pattern, field, pattern, field, …, else_field)

class calibre.utils.formatter_functions.BuiltinLookup[source]

lookup((val, pattern, field, pattern, field, …, else_field) – comme switch, sauf que les arguments sont des noms de champs (métadonnées), et pas du texte. La valeur du champ approprié sera récupéré et utilisé. Notez que vu que les colonnes composées sont des champs, vous pouvez utiliser cette fonction dans un champ composé pour utiliser la valeur d’autres champs composés. C’est extrêmement utile dans la construction des chemins d’enregistrement variables.

switch(val, pattern, value, pattern, value, …, else_valeur)

class calibre.utils.formatter_functions.BuiltinSwitch[source]

switch(val, pattern, value, pattern, value, …, else_valeur) – pour chaque paire pattern, value, vérifie si val à des correspondances pour l’expression régulière pattern et si oui renvoie cette value. S’il n’y a pas de correspondance alors else_value est renvoyé. Vous pouvez avoir autant de paires pattern, value que vous voulez

List lookup

identifier_in_list(val, id, found_val, not_found_val)

class calibre.utils.formatter_functions.BuiltinIdentifierInList[source]

identifier_in_list(val, id, found_val, not_found_val) – traite val comme une liste d’identifiants séparés par des virgules, en comparant la chaîne de caractères avec chaque valeur de la liste. Un identifiant a la forme « identifier:value ». Le paramètre id doit être soit « id », soit « id:regexp ». Le premier cas est validé s’il y a un identifiant avec cet id. Le second cas est validé si l’expression régulière regexp correspond à la valeur de l’identifiant. S’il y a correspondance, la valeur de retour est found_val, sinon, c’est not_found_val.

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 separator, comparant la pattern avec chaque valeur de la liste. Si la pattern correspond à une valeur, retourne found_val, sinon, retourne not_found_val. pattern et found_value peuvent être répétés autant de fois que désiré, permettant de renvoyer différentes valeurs dépendantes de la recherche. Les modèles sont traitées dans l’ordre. La première correspondance est renvoyée.

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 séparée par des virgules d’items, ceux-ci étant de la forme « id:value ». Trouve la paire avec l’id égale à la clé, et retourne la valeur correspondante.

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 separator, comparant la chaîne de caractères avec chaque valeur de la liste. Si la chaîne correspond à une valeur (ignorant la casse) cela retourne found_val, sinon, cela retourne not_found_val. Si la chaîne contient des séparateurs, alors c’est également traité comme une liste et chaque valeur est vérifiée. String et found_value peuvent être répétés autant de fois que désiré, permettant de renvoyer différentes valeurs dépendantes de la recherche. Les chaînes sont traitées dans l’ordre. La première correspondance est renvoyée.

List manipulation

count(val, separator)

class calibre.utils.formatter_functions.BuiltinCount[source]

count(val, separator) – interprète la valeur comme une liste d’articles séparée 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(&)}

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_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_1_template, …)

class calibre.utils.formatter_functions.BuiltinListReGroup[source]

list_re_group(src_list, separator, include_re, search_re, group_1_template, …) – Comme list_re excepté que les remplacements ne sont pas optionnels. Il utilise re_group(list_item, search_re, group_1_template, …) quand il effectue les remplacements sur la liste résultante.

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_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.

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

assign(id, val)

class calibre.utils.formatter_functions.BuiltinAssign[source]

assign(id, val) – assigne val à id, puis renvoie val. id doit être un identifiant, pas une expression

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) – comparer x et y après les avoir converti tous les deux en nombres. Renvoie lt si x < y. Renvoie eq si x == y. Sinon renvoie gt.

first_matching_cmp(val, cmp1, result1, cmp2, r2, …, else_result)

class calibre.utils.formatter_functions.BuiltinFirstMatchingCmp[source]

first_matching_cmp(val, cmp1, result1, cmp2, r2, …, 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) – effectuer une comparaison insensible à la casse des chaines x et y. Renvoie lt si x < y. Renvoie eq si x == y. Sinon renvoie gt.

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

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_1, for_group_2, …)

class calibre.utils.formatter_functions.BuiltinReGroup[source]

re_group(val, pattern, template_for_group_1, for_group_2, …) – 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-nhoe. 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 une chaine constitué par la concaténation de tous les arguments

strcat_max(max, string1, prefix1, string2, …)

class calibre.utils.formatter_functions.BuiltinStrcatMax[source]

strcat_max(max, string1, prefix1, 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_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

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 ».

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=(u'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 <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

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.

__docformat__ = 'restructuredtext en'

'''
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, for 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 author to an associated hyperlink
    'author_link_map',
))

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