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_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) – for each « test_expression, value_expression » pair, checks if test_expression is True (non-empty) and if so returns the result of value_expression. If no test_expression is True then the result of else_expression is returned. You can have as many « test_expression, value_expression » pairs as you want.

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]) – treat val as a list of identifiers separated by commas. An identifier has the format « id_name:value ». The id_name parameter is the id_name text to search for, either « id_name » or « id_name:regexp ». The first case matches if there is any identifier matching that id_name. The second case matches if id_name matches an identifier and the regexp matches the identifier’s value. If found_val and not_found_val are provided then if there is a match then return found_val, otherwise return not_found_val. If found_val and not_found_val are not provided then if there is a match then return the identifier:value pair, otherwise the empty string.

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]*) – return a list made by joining the items in the source lists (list1, etc) using with_separator between the items in the result list. Items in each source list[123…] are separated by the associated separator[123…]. A list can contain zero values. It can be a field like publisher that is single-valued, effectively a one-item list. Duplicates are removed using a case-insensitive comparison. Items are returned in the order they appear in the source lists. If items on lists differ only in letter case then the last is used. All separators can be more than one character. Example:

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) – returns a list of numbers generated by looping over the range specified by the parameters start, stop, and step, with a maximum length of limit. The first value produced is “start”. Subsequent values next_v are current_v+step. The loop continues while next_v < stop assuming step is positive, otherwise while next_v > stop. An empty list is produced if start fails the test: start>=stop if step is positive. The limit sets the maximum length of the list and has a default of 1000. The parameters start, step, and limit are optional. Calling range() with one argument specifies stop. Two arguments specify start and stop. Three arguments specify start, stop, and step. Four arguments specify start, stop, step and limit. Examples: 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,5) -> “1,3”. range(1,5,2,1) -> error(limit exceeded).

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]]*) – Used in a stored template to retrieve the arguments passed in the call. It both declares and initializes local variables, effectively parameters. The variables are positional; they get the value of the parameter given in the call in the same position. If the corresponding parameter is not provided in the call then arguments assigns that variable the provided default value. If there is no default value then the variable is set to the empty string.

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) – does a case-sensitive comparison of x and y as strings. Returns lt if x < y. Returns eq if x == y. Otherwise returns gt. Note: This is NOT the default behavior used by calibre, for example, in the lexical comparison operators (==, >, <, etc.). This function could cause unexpected results, preferably use strcmp() whenever 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) – returns the string encoded in hex. This is useful when constructing calibre URLs.

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) – returns the count of books found by searching for query. If use_vl is 0 (zero) then virtual libraries are ignored. This function can be used only in the GUI.

book_values(column, query, sep, use_vl)¶

class calibre.utils.formatter_functions.BuiltinBookValues[source]¶: book_values(column, query, sep, use_vl) – returns a list of the values contained in the column « column », separated by « sep », in the books found by searching for « query ». If use_vl is 0 (zero) then virtual libraries are ignored. This function can be used only in the GUI.

extra_file_modtime(file_name, format_string)¶

class calibre.utils.formatter_functions.BuiltinExtraFileModtime[source]¶: extra_file_modtime(file_name, format_string) – returns the modification time of the extra file “file_name” in the book’s “data/” folder if it exists, otherwise -1.0. The modtime is formatted according to “format_string” (see format_date()). If “format_string” is empty, returns the modtime as the floating point number of seconds since the epoch. The epoch is OS dependent. This function can be used only in the GUI.

extra_file_names(sep [, pattern])¶

class calibre.utils.formatter_functions.BuiltinExtraFileNames[source]¶: extra_file_names(sep [, pattern]) – returns a sep-separated list of extra files in the book’s “data/” folder. If the optional parameter “pattern”, a regular expression, is supplied then the list is filtered to files that match pattern. The pattern match is case insensitive. This function can be used only in the GUI.

extra_file_size(file_name)¶

class calibre.utils.formatter_functions.BuiltinExtraFileSize[source]¶: extra_file_size(file_name) – returns the size in bytes of the extra file “file_name” in the book’s “data/” folder if it exists, otherwise -1.This function can be used only in the GUI.

has_extra_files([pattern])¶

class calibre.utils.formatter_functions.BuiltinHasExtraFiles[source]¶: has_extra_files([pattern]) – returns the count of extra files, otherwise “” (the empty string). If the optional parameter “pattern” (a regular expression) is supplied then the list is filtered to files that match pattern before the files are counted. The pattern match is case insensitive. This function can be used only in the GUI.

other ¶

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

class calibre.utils.formatter_functions.BuiltinSetGlobals[source]¶: set_globals(id[=expression] [, id[=expression]]*) – Sets « global variables » that can be passed into the formatter. The globals are given the name of the id passed in. The value of the id is used unless an expression is provided.

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