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.

Arithmétique

add

class calibre.utils.formatter_functions.BuiltinAdd[source]

add(x [, y]*) – retourne la somme de ses arguments. Lance une exception si un argument n’est pas un nombre. Dans la plupart des cas, vous pouvez utiliser l’opérateur + à la place de cette fonction.

ceiling

class calibre.utils.formatter_functions.BuiltinCeiling[source]

ceiling(value) – retourne le plus petit entier supérieur ou égal à value. Lance une exception si value n’est pas un nombre.

divide

class calibre.utils.formatter_functions.BuiltinDivide[source]

divide(x, y) – retourne x / y. Lance une exception si x ou y ne sont pas des nombres. Cette fonction peut généralement être remplacée par l’opérateur /.

floor

class calibre.utils.formatter_functions.BuiltinFloor[source]

floor(value) – retourne le plus grand entier inférieur ou égal à value. Lance une exception si value n’est pas un nombre.

fractional_part

class calibre.utils.formatter_functions.BuiltinFractionalPart[source]

fractional_part(value) – retourne la partie décimale de la valeur. Par exemple, fractional_part(3.14) retourne 0.14. Lance une exception si value n’est pas un nombre.

mod

class calibre.utils.formatter_functions.BuiltinMod[source]

mod(value, y) – retourne floor du reste de value / y. Lance une exception si value ou y ne sont pas des nombres.

multiply

class calibre.utils.formatter_functions.BuiltinMultiply[source]

multiply(x [, y]*) – retourne le produit de ses arguments. Lance une exception si un argument n’est pas un nombre. Cette fonction peut généralement être remplacée par l’opérateur *.

round

class calibre.utils.formatter_functions.BuiltinRound[source]

round(value) – retourne l’entier le plus proche de value. Lance une exception si value n’est pas un nombre.

subtract

class calibre.utils.formatter_functions.BuiltinSubtract[source]

subtract(x, y) – retourne x - y. Lance une exception si x ou y ne sont pas des nombres. Cette fonction peut généralement être remplacée par l’opérateur -.

Autre

arguments

class calibre.utils.formatter_functions.BuiltinArguments[source]

arguments(id[=expression] [, id[=expression]]*) – Utilisé dans un modèle stocké pour récupérer les arguments passés dans l’appel. Il déclare et initialise des variables locales avec les noms fournis, les id, ce qui en fait des paramètres. Les variables sont positionnelles ; elles obtiennent la valeur de l’argument donné dans l’appel à la même position. Si l’argument correspondant n’est pas fourni dans l’appel, alors arguments() assigne à cette variable la valeur par défaut fournie. S’il n’y a pas de valeur par défaut, la variable est initialisée avec un chaîne vide.

assign

class calibre.utils.formatter_functions.BuiltinAssign[source]

assign(id, value) – assigne value à id, puis retourne value. id doit être un identifiant, pas une expression. Dans la plupart des cas, vous pouvez utiliser l’opérateur = à la place de cette fonction.

globals

class calibre.utils.formatter_functions.BuiltinGlobals[source]

globals(id[=expression] [, id[=expression]]*) – Récupère les variables globales qui peuvent être passées au formateur. Le nom id est le nom de la variable globale. Il déclare et initialise les variables locales avec les noms des variables globales passées (les paramètres id). Si la variable correspondante n’est pas fournie dans les variables globales, il lui assigne la valeur par défaut fournie. S’il n’y a pas de valeur par défaut, la variable est initialisée avec un chaîne vide).

is_dark_mode

class calibre.utils.formatter_functions.BuiltinIsDarkMode[source]

is_dark_mode() – retourne '1'``si Calibre fonctionne en mode sombre, sinon ``'' (chaîne vide). Cette fonction peut être utilisée dans les règles avancées de couleurs et d’icônes pour choisir des couleurs/icônes différentes selon le mode. Exemple :

if is_dark_mode() then 'dark.png' else 'light.png' fi

print

class calibre.utils.formatter_functions.BuiltinPrint[source]

print(a [, b]*) – imprime les arguments dans la sortie standard. À moins que vous ne lanciez Calibre à partir de la ligne de commande (calibre-debug -g), la sortie ira dans un trou noir. La fonction print retourne toujours son premier argument.

set_globals

class calibre.utils.formatter_functions.BuiltinSetGlobals[source]

set_globals(id[=expression] [, id[=expression]]*) – définit les variables globales qui peuvent être passées au formateur. Les variables globales reçoivent le nom de l”id passé. La valeur de l”id est utilisée sauf si une expression est fournie.

Booléen

and

class calibre.utils.formatter_functions.BuiltinAnd[source]

and(value [, value]*) – retourne la chaîne '1' si toutes les valeurs ne sont pas vides, sinon il retourne une chaîne vide. Vous pouvez avoir autant de valeurs que vous le souhaitez. Dans la plupart des cas, vous pouvez utiliser l’opérateur && à la place de cette fonction. Une raison de ne pas remplacer and() par && est lorsque le court-circuitage peut changer les résultats à cause d’effets de bord. Par exemple, and(a='',b=5) fera toujours les deux affectations, alors que l’opérateur && ne fera pas la seconde.

not

class calibre.utils.formatter_functions.BuiltinNot[source]

not(value) – retourne la chaîne '1' si la valeur est vide, sinon elle retourne une chaîne vide. Cette fonction peut généralement être remplacée par l’opérateur unaire not (!).

or

class calibre.utils.formatter_functions.BuiltinOr[source]

or(value [, value]*) – retourne la chaîne '1'``si une valeur n'est pas vide, sinon retourne une chaîne vide. Vous pouvez avoir autant de valeurs que vous le souhaitez. Cette fonction peut généralement être remplacée par l'opérateur ``||. Elle ne peut pas être remplacée si un court-circuit modifie les résultats en raison d’effets secondaires.

Changements de Case

capitalize

class calibre.utils.formatter_functions.BuiltinCapitalize[source]

capitalize(value) – retourne value avec la première lettre en majuscule et le reste en minuscule.

lowercase

class calibre.utils.formatter_functions.BuiltinLowercase[source]

lowercase(value) – retourne value en minuscules.

titlecase

class calibre.utils.formatter_functions.BuiltinTitlecase[source]

titlecase(value) – retourne value en case de titre (premiére lettre de chaque mot en majuscule).

uppercase

class calibre.utils.formatter_functions.BuiltinUppercase[source]

uppercase(value) – retourne value en majuscules.

Consultation de liste

identifier_in_list

class calibre.utils.formatter_functions.BuiltinIdentifierInList[source]

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

list_contains

class calibre.utils.formatter_functions.BuiltinInList[source]

list_contains(value, separator, [pattern, found_val,]* not_found_val) – interprète value comme une liste d’éléments séparés par un separator, en vérifiant le pattern par rapport à chaque élément de la liste. Si le pattern correspond à un élément, alors il retourne found_val, sinon il retourne not_found_val. La paire pattern et found_val peut être répétée autant de fois que désiré, permettant de retourner des valeurs différentes en fonction de la valeur de l’élément. Les pattern sont vérifiés dans l’ordre, et la première correspondance est retournée.

Alias : in_list(), list_contains()

list_item

class calibre.utils.formatter_functions.BuiltinListitem[source]

list_item(value, index, separator) – interprète value comme une liste d’éléments séparés par un separator, en retournant l’élément a l”index. Le premier élément est le numéro zéro. Le dernier élément a l’index -1 comme dans list_item(value, -1, separator). Si l’élément n’est pas dans la liste, alors une chaîne vide est retournée. Le séparateur a la même signification que dans la fonction list_count(), habituellement une virgule, mais c’est une esperluette pour les listes de type auteur.

select

class calibre.utils.formatter_functions.BuiltinSelect[source]

select(value, key) – interprète value comme une liste d’éléments séparés par des virgules, chaque élément ayant la forme id:id_value (le format identifiant de Calibre). La fonction trouve la première paire dont l’identifiant est égal à key et retourne le id_value correspondante. Si aucun identifiant ne correspond, la fonction retourne une chaîne vide.

str_in_list

class calibre.utils.formatter_functions.BuiltinStrInList[source]

str_in_list(value, separator, [string, found_val,]+ not_found_val) – interprète value comme une liste d’éléments séparés par separator puis compare string à chaque valeur de la liste. La string n’est pas une expression régulière. Si string est égale à n’importe quel élément (en ignorant la casse), alors elle retourne le found_val correspondante. Si string contient des separator alors elle est aussi traitée comme une liste et chaque sous-valeur est vérifiée. Les paires string et found_val peuvent être répétées autant de fois que désiré, permettant de retourner des valeurs différentes en fonction de la valeur de la chaîne. Si aucune des chaînes ne correspond, alors not_found_value est retourné. Les chaînes sont vérifiées dans l’ordre. La première correspondance est retournée.

Finction de date

date_arithmetic

class calibre.utils.formatter_functions.BuiltinDateArithmetic[source]

date_arithmetic(value, calc_spec, fmt) – Calcule une nouvelle date à partir value``date`` en utilisant calc_spec. Retourne la nouvelle date formatée selon le format optionnel fmt : s’il n’est pas fourni, le résultat sera au format ISO. Le calc_spec est une chaîne 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 a date

  • m : ajoute v minutes a date

  • h : ajoute v heures a date

  • d : ajoute v jours a date

  • w : ajoute v semaines a date

  • y : ajoute v années a date, où une année compte 365 jours.

Exemple : '1s3d-1m' ajoutera 1 seconde, ajoutera 3 jours et soustraira 1 minute de date.

days_between

class calibre.utils.formatter_functions.BuiltinDaysBetween[source]

days_between(date1, date2) – retourne le nombre de jours entre date1 et date2. Le nombre est positif si date1 est plus grand que date2, sinon il est négatif. Si date1 ou date2 ne sont pas des dates, la fonction retourne une chaîne vide.

today

class calibre.utils.formatter_functions.BuiltinToday[source]

today() – retourne une chaîne date+heure pour aujourd’hui (maintenant). Cette valeur est conçue pour être utilisée dans format_date ou days_between, mais peut être manipulée comme n’importe quelle autre chaîne. La date est exprimée en date/temp format ISO.

Fonctions de la base de données

book_count

class calibre.utils.formatter_functions.BuiltinBookCount[source]

book_count(query, use_vl) – retourne le nombre de livres trouvés en recherchant query. Si use_vl est 0 (zéro) alors les bibliothèques virtuelles sont ignorées. Cette fonction et sa compagne book_values() sont particulièrement utiles dans les recherches de modèles, supportant les recherches qui combinent des informations provenant de plusieurs livres, comme la recherche de séries avec un seul livre. Elle ne peut pas être utilisée dans les colonnes composites à moins que le paramètre allow_template_database_functions_in_composites ne soit mis à True. Cette fonction ne marche que dans l’interface graphique.

Par exemple, ce modèle de recherche utilise cette fonction et son complément pour trouver toutes les séries ne comportant qu’un seul livre :

  • Définir un modèle stocké (en utilisant Préférences → Avancé → Modèle de fonctions) nommée series_only_one_book (le nom est arbitraire). Le modèle est :

    program:
        vals = globals(vals='');
        if !vals then
            all_series = book_values('series', 'series:true', ',', 0);
            for series in all_series:
                if book_count('series:="' & series & '"', 0) == 1 then
                    vals = list_join(',', vals, ',', series, ',')
                fi
            rof;
        set_globals(vals)
        fi;
        str_in_list(vals, ',', $series, 1, '')
    

    La première fois que le modèle s’exécute (le premier livre vérifié), il stocke les résultats des recherches dans la base de données dans une variable globale du modèle nommée vals. Ces résultats sont utilisés pour vérifier les livres suivants sans avoir à refaire les recherches.

  • Utiliser le modèle enregistré dans une recherche de modèle :

template:"program: series_only_one_book()#@#:n:1"

L’utilisation d’un modèle stocké au lieu d’insérer le modèle dans la recherche élimine les problèmes causés par l’obligation d’échapper les guillemets dans les expressions de recherche.

book_values

class calibre.utils.formatter_functions.BuiltinBookValues[source]

book_values(column, query, sep, use_vl) – retourne une liste des valeurs uniques contenues dans la colonne column (un nom de recherche), séparées par sep, dans les livres trouvés en recherchant query. Si use_vl est 0 (zéro), les bibliothèques virtuelles sont ignorées. Cette fonction et sa compagne book_count() sont particulièrement utiles dans les recherches de modèles, supportant les recherches qui combinent des informations provenant de plusieurs livres, comme la recherche de séries ne comportant qu’un seul livre. Elle ne peut pas être utilisée dans les colonnes composites à moins que le tweak allow_template_database_functions_in_composites ne soit mis à True. Cette fonction ne marche que dans l’interface graphique.

extra_file_modtime

class calibre.utils.formatter_functions.BuiltinExtraFileModtime[source]

extra_file_modtime(file_name, format_string) – retourne l’heure de modification du fichier supplémentaire file_name dans le dossier data/ du livre s’il existe, sinon -1. La date de modification est formatée selon format_string (voir format_date() pour plus de détails). Si format_string est une chaîne vide, elle retourne “heure de modification sous la forme d’un nombre de secondes en virgule flottante depuis la valeur epoch. Voir aussi les fonctions has_extra_files(), extra_file_names() et extra_file_size(). La valeur epoch dépend du système d’exploitation. Cette fonction ne marche que dans l’interface graphique.

extra_file_names

class calibre.utils.formatter_functions.BuiltinExtraFileNames[source]

extra_file_names(sep [, pattern]) – retourne une liste séparée par sep des fichiers supplémentaires dans le dossier data/ du livre. Si le paramètre optionnel pattern, une expression régulière, est fourni, alors la liste est filtrée sur les fichiers qui correspondent à pattern. La correspondance est insensible à la casse. Voir aussi les fonctions has_extra_files(), extra_file_modtime() et extra_file_size(). Cette fonction ne marche que dans l’interface graphique.

extra_file_size

class calibre.utils.formatter_functions.BuiltinExtraFileSize[source]

extra_file_size(file_name) – retourne la taille en octets du fichier supplémentaire file_name dans le dossier data/ du livre s’il existe, sinon -1. Voir aussi les fonctions has_extra_files(), extra_file_names() et extra_file_modtime(). Cette fonction ne marche que dans l’interface graphique.

get_note

class calibre.utils.formatter_functions.BuiltinGetNote[source]

get_note(field_name, field_value, plain_text) – récupère la note pour le champ field_name avec la valeur field_value. Si plain_text est vide, il retourne le code HTML de la note, y compris les images. Si plain_text est 1 (ou '1'), il retourne le texte brut de la note. Si la note n’existe pas, une chaîne vide est retournée dans les deux cas. Exemple :

  • Retourner le code HTML de la note attachée à la balise Fiction :

    program: get_note('tags', 'Fiction', '')
    
  • Retourner le texte brut de la note attachée à l’auteur Isaac Asimov :

    program: get_note('authors', 'Isaac Asimov', 1)
    

has_extra_files

class calibre.utils.formatter_functions.BuiltinHasExtraFiles[source]

has_extra_files([pattern]) – retourne le nombre de fichiers supplémentaires, sinon``””(chaîne vide). Si le paramètre optionnel ``pattern (une expression régulière) est fourni, alors la liste est filtrée sur les fichiers qui correspondent à pattern avant que les fichiers ne soient comptés. La correspondance est insensible à la casse. Voir aussi les fonctions extra_file_names(), extra_file_size() et extra_file_modtime(). Cette fonction ne marche que dans l’interface graphique.

has_note

class calibre.utils.formatter_functions.BuiltinHasNote[source]

has_note(field_name, field_value) – vérifier si un champ a une note. Cette fonction a deux variantes :

  • Si field_value n’est pas '' (chaîne vide) retourne '1' si la valeur field_value dans le champ field_name a une note, sinon ''.

    Exemple : has_note('tags', 'Fiction') retourne '1' si le tag fiction a une note jointe, sinon ''.

  • Si field_value est '' alors retourne une liste de valeurs dans field_name qui ont une note. Si aucun élément du champ n’a de note, retourne ''. Cette variante permet d’afficher des icônes de colonne si une valeur du champ est accompagnée d’une note, plutôt que d’une valeur spécifique.

    Exemple : has_note('authors', '') retourne une liste des auteurs qui ont des notes, ou '' si aucun auteur n’a de note.

Vous pouvez tester si toutes les valeurs de field_name ont une note en comparant la longueur de liste de la valeur retournée de cette fonction à la longueur de liste des valeurs de field_name. Exemple :

list_count(has_note('authors', ''), '&') ==# list_count_field('authors')

Formatage de valeurs

finish_formatting

class calibre.utils.formatter_functions.BuiltinFinishFormatting[source]

finish_formatting(value, format, prefix, suffix) – applique le format, le prefix et le suffixe à value de la même manière que dans un modèle comme {series_index:05.2f| - |- }. Cette fonction est fournie pour faciliter la conversion de modèles complexes à fonction unique ou des modèles Mode Programme de Modèles en modèles GPM. Par exemple, le programme suivant produit la même sortie que le modèle ci-dessus :

program: finish_formatting(field('series_index'), '05.2f', ' - ', ' - ')

Autre exemple : pour le modèle :

{series:re(([^\s])[^\s]+(\s|$),\1)}{series_index:0>2s| - | - }{title}

utilise :

program:
    strcat(
        re(field('series'), '([^\s])[^\s]+(\s|$)', '\1'),
        finish_formatting(field('series_index'), '0>2s', ' - ', ' - '),
        field('title')
    )

format_date

class calibre.utils.formatter_functions.BuiltinFormatDate[source]

format_date(value, format_string) – formater la valeur, qui doit être une chaîne de date, à l’aide de format_string, en retourant une chaîne. Il est préférable que la date soit au format ISO, car l’utilisation d’autres formats de date provoque souvent des erreurs, la valeur réelle de la date ne pouvant être déterminée sans ambiguïté. Notez que la fonction format_date_field() est à la fois plus rapide et plus fiable.

Les codes de formatage sont :

  • d : le jour sous la forme d’un nombre sans 0 initial (1 à 31)

  • dd : le jour sous la forme d’un nombre avec 0 initial (01 à 31)

  • ddd : le nom abrégé du jour localisé (par exemple de « lun. » à « dim. »)

  • dddd : le nom long du jour localisé (par exemple de « lundi » à « dimanche »)

  • M : le mois sous la forme d’un nombre sans 0 initial (1 à 12)

  • MM : le mois sous la forme d’un nombre avec 0 initial (01 à 12)

  • MMM : le nom abrégé du mois localisé (par exemple de « jan. » à « déc. »)

  • MMMM : le nom long du mois localisé (par exemple de « janvier » à « décembre »)

  • yy : l’année sous la forme d’un nombre à deux chiffres (00 à 99)

  • yyyy : l’année sous la forme d’un nombre à quatre chiffres.

  • h : les heures sans 0 initial (0 à 11 ou 0 à 23, selon am/pm)

  • hh : les heures avec 0 initial (00 à 11 ou 00 à 23, selon am/pm)

  • m : les minutes sans 0 initial (0 à 59)

  • mm : les minutes avec 0 initial (00 à 59)

  • s : les secondes sans 0 initial (0 à 59)

  • ss : les secondes avec 0 initial (00 à 59)

  • ap : utilise une horloge de 12 heures au lieu d’une horloge de 24 heures, avec « ap » remplacé par la chaîne localisée pour am ou pm.

  • AP : utilise une horloge de 12 heures au lieu d’une horloge de 24 heures, avec « AP » remplacé par la chaîne localisée pour AM ou PM.

  • iso : la date avec l’heure et le fuseau horaire. Ce doit être le seul format présent.

  • to_number : convertit la date et l’heure en un nombre à virgule flottante (un timestamp)

  • from_number : convertit un nombre à virgule flottante (un timestamp) en une date formatée iso. Si vous souhaitez un format de date différent, ajoutez la chaîne de formatage souhaitée après from_number et un deux-points (:). Exemple :

    format_date(val, 'from_number:MMM dd yyyy')
    

Vous pouvez obtenir des résultats inattendus si la date que vous formatez contient des noms de mois localisés, ce qui peut se produire si vous avez modifié les ajustements de format de date pour qu’ils contiennent MMMM. L’utilisation de format_date_field() évite ce problème.

format_date_field

class calibre.utils.formatter_functions.BuiltinFormatDateField[source]

format_date_field(field_name, format_string) – formate la valeur du champ field_name, qui doit être le nom d’un champ de date, standard ou personnalisé. Voir format_date() pour les codes de formatage. Cette fonction est beaucoup plus rapide que format_date() et devrait être utilisée lorsque vous formatez la valeur d’un champ (colonne). Elle est également plus fiable car elle travaille directement sur la date sous-jacente. Elle ne peut pas être utilisée pour des dates calculées ou des dates dans des variables de type chaîne. Exemples :

format_date_field('pubdate', 'yyyy.MM.dd')
format_date_field('#date_read', 'MMM dd, yyyy')

format_number

class calibre.utils.formatter_functions.BuiltinFormatNumber[source]

format_number(value, template) – interprète value comme un nombre et formate ce nombre en utilisant un modèle de formatage Python comme {0:5.2f} ou {0:,d} ou ${0:5,.2f}. Le modèle de formatage doit commencer par {0: et se terminer par } comme dans les exemples ci-dessus. Exception : vous pouvez omettre le {0: de tête et le } de fin si le modèle de format ne contient qu’un format. Voir le langage des modèles et la documentation Python pour plus d’exemples. Retourne une chaîne vide si le formatage échoue.

human_readable

class calibre.utils.formatter_functions.BuiltinHumanReadable[source]

human_readable(value) – s’attend à ce que valeur soit un nombre et retourne une chaîne représentant ce nombre en Ko, Mo, Go, etc.

rating_to_stars

class calibre.utils.formatter_functions.BuiltinRatingToStars[source]

rating_to_stars(value, use_half_stars) – retourne value sous forme de chaîne de caractères étoilés (). La valeur doit être un nombre entre 0 et 5. Mettez use_half_stars à 1 si vous voulez des demi-étoiles pour les nombres fractionnaires disponibles avec les colonnes d’évaluation personnalisées.

urls_from_identifiers

class calibre.utils.formatter_functions.BuiltinUrlsFromIdentifiers[source]

urls_from_identifiers(identifiers, sort_results) – étant donné une liste d’identifiants séparés par des virgules, où un identifiant est une paire de valeurs séparées par deux points (id_name:id_value), retourne une liste d’URLs HTML générées à partir des identifiants, séparées par des virgules. La liste n’est pas triée si sort_results vaut 0 (caractère ou nombre), sinon elle est triée alphabétiquement par le nom de l’identifiant. Les URL sont générées de la même manière que la colonne des identifiants intégrés lorsqu’ils sont affichés dans les détails du livre.

Itérer sur les valeurs

first_non_empty

class calibre.utils.formatter_functions.BuiltinFirstNonEmpty[source]

first_non_empty(value [, value]*) – retourne la première valeur qui n’est pas vide. Si toutes les valeurs sont vides, alors une chaîne vide est retournée. Vous pouvez avoir autant de valeurs que vous le souhaitez.

lookup

class calibre.utils.formatter_functions.BuiltinLookup[source]

lookup(value, [pattern, key,]* else_key) – les patterns seront comparés à value dans l’ordre. Si un pattern correspond, la valeur du champ nommé par key est retournée. Si aucun motif ne correspond, alors la valeur du champ nommé par else_key est retournée. Voir aussi la fonction switch().

switch

class calibre.utils.formatter_functions.BuiltinSwitch[source]

switch(value, [patternN, valueN,]+ else_value) – pour chaque paire patternN, valueN, vérifie si la valeur correspond à l’expression régulière patternN et si c’est le cas retourne la valueN associée. Si aucun pattern ne correspond, alors else_value est retourné. Vous pouvez avoir autant de paires patternN, valueN que vous le souhaitez. La première correspondance est retournée.

switch_if

class calibre.utils.formatter_functions.BuiltinSwitchIf[source]

switch_if([test_expression, value_expression,]+ else_expression) – pour chaque paire test_expression, value_expression, vérifie si test_expression est Vrai (non vide) et si c’est le cas retourne le résultat de value_expression. Si aucune test_expression n’est Vrai, alors le résultat de else_expression est retourné. Vous pouvez avoir autant de paires test_expression, value_expression que vous le souhaitez.

Manipulation de chaînes

character

class calibre.utils.formatter_functions.BuiltinCharacter[source]

character(character_name) – retourne le caractère nommé par character_name. Par exemple, character('newline') retourne une nouvelle ligne ('\n'). Les noms de caractères supportés sont newline, return, tab, and backslash. Cette fonction est utilisée pour insérer ces caractères dans la sortie des modèles.

check_yes_no

class calibre.utils.formatter_functions.BuiltinCheckYesNo[source]

check_yes_no(field_name, is_undefined, is_false, is_true) – vérifie si la valeur du champ Oui/Non nommé par le nom de la recherche field_name est l’une des valeurs spécifiées par les paramètres, retournant 'Yes' si une correspondance est trouvée sinon retournant une chaîne vide. Mettez 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) retourne 'Yes' si le champ Oui/Non #bool est soit Oui, soit indéfini (ni Oui, ni Non).

Plusieurs des options is_undefined, is_false, ou is_true peuvent être mises à 1.

contains

class calibre.utils.formatter_functions.BuiltinContains[source]

contains(value, pattern, text_if_match, text_if_not_match) – vérifie si la valeur correspond à l’expression régulière pattern. Retourne text_if_match si le motif correspond à la valeur, sinon retourne text_if_not_match.

field_exists

class calibre.utils.formatter_functions.BuiltinFieldExists[source]

field_exists(lookup_name) – vérifie si un champ (colonne) avec le nom de recherche lookup_name existe, retournant '1' si c’est le cas et une chaîne vide si ce n’est pas le cas.

ifempty

class calibre.utils.formatter_functions.BuiltinIfempty[source]

ifempty(value, text_if_empty) – si value n’est pas vide, elle est retournée, sinon s’est text_if_empty qui est retournée.

re

class calibre.utils.formatter_functions.BuiltinRe[source]

re(value, pattern, replacement) – retourne value après application de l’expression régulière. Toutes les instances de pattern dans la valeur sont remplacées par replacement. Le langage modèle utilise des expressions régulières Python insensibles à la casse.

re_group

class calibre.utils.formatter_functions.BuiltinReGroup[source]

re_group(value, pattern [, template_for_group]*) – retourne une chaîne obtenue en appliquant l’expression régulière pattern à value et en remplaçant chaque instance correspondante par la valeur renvoyée par le modèle correspondant. En Mode Programme de Modèles, comme pour les fonctions template et eval, vous utilisez [[ pour { et ]] pour }.

L’exemple suivant recherche une série comportant plus d’un mot et met le premier mot en majuscules :

program: re_group(field('series'), '(\S* )(.*)', '{$:uppercase()}', '{$}')

shorten

class calibre.utils.formatter_functions.BuiltinShorten[source]

shorten(value, left_chars, middle_text, right_chars) – retourne une version abrégée de value, en prenant left_chars caractères eu début de la valeur et right_chars caractères a la fin de la valeur, avec middle_text ajouté entre les deux. left_chars et right_chars doivent être des nombres entiers non négatifs.

Exemple : supposons que vous souhaitiez afficher le titre avec une longueur maximale de 15 caractères. Un modèle qui permet de le faire est {title:shorten(9,-,5)}. Pour un livre dont le titre est Anciennes lois anglaises à l’époque d’Ivanhoé, le résultat sera Ancien E-anhoé : les 9 premiers caractères du titre, un -, puis les 5 derniers caractères. Si la longueur de la valeur est inférieure à la longueur combiné de left_chars + left_chars + middle_text, alors la valeur sera retournée inchangée. Par exemple, le titre Le Dôme ne sera pas modifié.

strcat

class calibre.utils.formatter_functions.BuiltinStrcat[source]

strcat(a [, b]*) – retourne une chaîne formée par la concaténation de tous les arguments. Peut prendre n’importe quel nombre d’arguments. Dans la plupart des cas, vous pouvez utiliser l’opérateur & à la place de cette fonction.

strcat_max

class calibre.utils.formatter_functions.BuiltinStrcatMax[source]

strcat_max(max, string1 [, prefix2, string2]*) – retourne une chaîne formée par la concaténation des arguments. La valeur retournée est initialisée à string1. Les chaînes constituées de paires prefix, string sont ajoutées à la fin de la valeur tant que la longueur de la chaîne résultante est inférieure à max. Les préfixes peuvent être vides. Retourne string1 même si string1 est plus longue que max. Vous pouvez passer autant de paires prefix, string que vous le souhaitez.

strlen

class calibre.utils.formatter_functions.BuiltinStrlen[source]

strlen(value) – retourne la longueur de la chaîne de caractères value.

substr

class calibre.utils.formatter_functions.BuiltinSubstr[source]

substr(value, start, end) – retourne le start jusqu’au end``ème caractère de ``value. Le premier caractère de value est le zéro. Si end est négatif, il indique le nombre de caractères en comptant à partir de la droite. Si end est zéro, il indique le dernier caractère. Par exemple, substr('12345', 1, 0) retourne '2345', et substr('12345', 1, -1) retourne '234'.

swap_around_articles

class calibre.utils.formatter_functions.BuiltinSwapAroundArticles[source]

swap_around_articles(value, separator) – retourne value avec les articles déplacés à la fin. La valeur peut être une liste, auquel cas chaque élément de la liste est traité. Si value est une liste, vous devez fournir le separator. Si aucun separator n’est fourni, value est traitée comme une valeur unique, et non comme une liste. Les articles sont ceux utilisés par Calibre pour générer le title_sort.

swap_around_comma

class calibre.utils.formatter_functions.BuiltinSwapAroundComma[source]

swap_around_comma(value) – étant donné une valeur de la forme B, A, retourne A B. Cette fonction est particulièrement utile pour convertir les noms au format « LN, FN » en « FN LN ». Si la valeur ne contient pas de virgule, la fonction retourne la valeur inchangée.

test

class calibre.utils.formatter_functions.BuiltinTest[source]

test(value, text_if_not_empty, text_if_empty) – retourne text_if_not_empty si la valeur n’est pas vide, sinon retourne text_if_empty.

to_hex

class calibre.utils.formatter_functions.BuiltinToHex[source]

to_hex(val) – retourne la chaîne val encodée en hexadécimal. Ceci est utile lors de la construction d’URLs Calibre.

transliterate

class calibre.utils.formatter_functions.BuiltinTransliterate[source]

transliterate(value) – retourne une chaîne en alphabet latin formée par l’approximation du son des mots de value. Par exemple, si value est Фёдор Миха́йлович Достоевский cette fonction retourne Fiodor Mikhailovich Dostoievskii.

Manipulation de liste

list_count

class calibre.utils.formatter_functions.BuiltinCount[source]

list_count(value, separator) – interprète la valeur comme une liste d’éléments séparés par separator et retourne le nombre d’éléments dans la liste. La plupart des listes utilisent une virgule comme séparateur, mais authors utilise une esperluette (&).

Exemple : {tags:list_count(,)}, {authors:list_count(&)}.

Alias : count(), list_count()

list_count_field

class calibre.utils.formatter_functions.BuiltinFieldListCount[source]

list_count_field(lookup_name)– retourne le nombre d’éléments dans le champ avec le nom de recherche lookup_name. Le champ doit être multi-valeurs comme authors ou tags, sinon la fonction lève une erreur. Cette fonction est beaucoup plus rapide que list_count() car qu’elle opère directement sur les données Calibre sans les convertir d’abord en chaînes de caractères. Exemple : list_count_field('tags')

list_count_matching

class calibre.utils.formatter_functions.BuiltinListCountMatching[source]

list_count_matching(value, pattern, separator) – interprète value comme une liste d’éléments séparés par separator, et retourne le nombre d’éléments de la liste qui correspondent à l’expression régulière pattern.

Alias : list_count_matching(), count_matching()

list_difference

class calibre.utils.formatter_functions.BuiltinListDifference[source]

list_difference(list1, list2, separator) – retourne une liste faite en retirant de list1 tout élément trouvé dans list2 en utilisant une comparaison insensible à la casse. Les éléments de list1 et list2 sont séparés par separator, tout comme les éléments de la liste retournée.

list_equals

class calibre.utils.formatter_functions.BuiltinListEquals[source]

list_equals(list1, sep1, list2, sep2, yes_val, no_val) – retourne yes_val si list1 et list2 contiennent les mêmes éléments, sinon retourne no_val. Les éléments sont déterminés en divisant chaque liste en utilisant le caractère séparateur approprié (sep1 ou sep2). L’ordre des éléments dans les listes n’a pas d’importance. La comparaison est insensible à la casse.

list_intersection

class calibre.utils.formatter_functions.BuiltinListIntersection[source]

list_intersection(list1, list2, separator) – retourne une liste faite en retirant de list1 tout élément non trouvé dans list2, en utilisant une comparaison insensible à la casse. Les éléments de list1 et list2 sont séparés par separator, tout comme les éléments de la liste retournée.

list_join

class calibre.utils.formatter_functions.BuiltinListJoin[source]

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

Exemple :

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

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

program:
    a = list_join('#@#', $authors, '&', $tags, ',');
    b = list_join('#@#', a, '#@#', $#genre, ',', $#people, '&', 'some value', ',')

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 remplacé par le mot « Genre : » suivi de la première lettre du genre, c’est-à-dire que le genre « Fiction » devient « Genre : F ». Voici ce que cela donne :

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

list_re

class calibre.utils.formatter_functions.BuiltinListRe[source]

list_re(src_list, separator, include_re, opt_replace) – Construire une liste en séparant d’abord src_list en éléments en utilisant le caractère separator. Pour chaque élément de la liste, vérifiez s’il correspond à include_re. Si c’est le cas, ajoutez-le à la liste à retourner. Si opt_replace n’est pas une chaîne vide, alors appliquer le remplacement avant d’ajouter l’élément à la liste retournée.

list_re_group

class calibre.utils.formatter_functions.BuiltinListReGroup[source]

list_re_group(src_list, separator, include_re, search_re [,template_for_group]*) – Comme list_re sauf que les remplacements ne sont pas optionnels. Il utilise re_group(item, search_re, template ...) pour effectuer les remplacements.

list_remove_duplicates

class calibre.utils.formatter_functions.BuiltinListRemoveDuplicates[source]

list_remove_duplicates(list, separator) – retourne une liste faite en supprimant les éléments dupliqués dans list. Si les éléments ne diffèrent que par la case, alors le dernier est retourné. Les éléments de list sont séparés par separator, tout comme les éléments de la liste retournée.

list_sort

class calibre.utils.formatter_functions.BuiltinListSort[source]

list_sort(value, direction, separator) – retourne value triée en utilisant un tri lexical insensible à la casse. Si direction est zéro (nombre ou caractère), value est triée de façon ascendante, sinon de façon descendante. Les éléments de la liste sont séparés par separator, comme le sont les éléments de la liste retournée.

list_split

class calibre.utils.formatter_functions.BuiltinListSplit[source]

list_split(list_val, sep, id_prefix) – divise list_val en valeurs séparées en utilisant sep, puis assigne les valeurs à des variables locales nommées id_prefix_N où N est la position de la valeur dans la liste. Le premier élément a la position est 0 (zéro). La fonction retourne le dernier élément de la liste.

Exemple :

list_split('one:two:foo', ':', 'var')

est équivalent à :

var_0 = 'one'
var_1 = 'two'
var_2 = 'foo'

list_union

class calibre.utils.formatter_functions.BuiltinListUnion[source]

list_union(list1, list2, separator) – retourne une liste faite en fusionnant les éléments de list1 et list2, en supprimant les éléments dupliqués en utilisant une comparaison insensible à la casse. Si les éléments ont une casse différente, c’est celui de list1 qui est utilisé. Les éléments de list1 et list2 sont séparés par separator, comme le sont les éléments de la liste retournée.

Alias : merge_lists(), list_union()

range

class calibre.utils.formatter_functions.BuiltinRange[source]

range(start, stop, step, limit) – retourne une liste de nombres générés en bouclant sur l’intervalle spécifié par les paramètres start, stop et step, avec une longueur maximale limit. La première valeur produite est “start”. Les valeurs suivantes sont next_v = current_v + step. La boucle continue tant que next_v < stop en supposant que step est positif, sinon tant que next_v > stop. Une liste vide est produite si start échoue le test : start >= stop si step est positif. Le paramètre limit fixe la longueur maximale de la liste et a une valeur par défaut de 1000. Les paramètres start, step, et limit sont optionnels. Appeler range() avec un argument spécifie stop. Deux arguments spécifient start et stop. Trois arguments spécifient start, stop, et step. Quatre arguments spécifient start, stop, step et limite.

Exemples :

range(5) -> '0, 1, 2, 3, 4'
range(0, 5) -> '0, 1, 2, 3, 4'
range(-1, 5) -> '-1, 0, 1, 2, 3, 4'
range(1, 5) -> '1, 2, 3, 4'
range(1, 5, 2) -> '1, 3'
range(1, 5, 2, 5) -> '1, 3'
range(1, 5, 2, 1) -> error(limit exceeded)

subitems

class calibre.utils.formatter_functions.BuiltinSubitems[source]

subitems(value, start_index, end_index) – cette fonction décompose les listes d’éléments hiérarchiques de type balise, tels que les genres. Elle interprète value comme une liste d’éléments de type balise séparés par des virgules, où chaque élément est une liste séparée par des points. Elle retourne une nouvelle liste faite en extrayant de chaque élément les composants de start_index à end_index, puis en fusionnant les résultats ensemble. Les doublons sont supprimés. Le premier sous-élément d’une liste séparée par un point a un indice de zéro. Si un indice est négatif, il compte à partir de la fin de la liste. Dans un cas particulier, un indice de fin de zéro est supposé correspondre à la longueur de la liste.

Exemples :

  • En supposant un colonne #genre contenant « A.B.C » :

    • {#genre:subitems(0,1)} retourne “A”

    • {#genre:subitems(0,2)} retourne “A.B”

    • {#genre:subitems(1,0)} retourne “B.C”

  • En supposant un colonne #genre contenant « A.B.C, D.E » :

    • {#genre:subitems(0,1)} retourne “A, D”

    • {#genre:subitems(0,2)} retourne “A.B, D.E”

sublist

class calibre.utils.formatter_functions.BuiltinSublist[source]

sublist(value, start_index, end_index, separator) – interprète value comme une liste d’éléments séparés par separator, retournant une nouvelle liste composée des éléments de start_index à end_index. Le premier élément est le numéro zéro. Si un index est négatif, il compte à partir de la fin de la liste. Dans un cas particulier, un end_index de zéro est supposé être la longueur de la liste.

Exemples en supposant que la colonne tags (qui est séparée 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 »

Obtenir des valeurs à partir des métadonnées

annotation_count

class calibre.utils.formatter_functions.BuiltinAnnotationCount[source]

annotation_count() – retourne le nombre total d’annotations de tous types attachées au livre actuel. Cette fonction ne marche que dans l’interface graphique.

approximate_formats

class calibre.utils.formatter_functions.BuiltinApproximateFormats[source]

approximate_formats() – retourne une liste de formats associés au livre, séparés par des virgules. Comme la liste provient de la base de données de Calibre et non du système de fichiers, il n’y a aucune garantie que la liste soit correcte, bien qu’elle le soit probablement. Notez que les noms des formats résultants sont toujours en majuscules, comme dans EPUB. La fonction approximate_formats() est beaucoup plus rapide que les fonctions formats_….

Cette fonction ne marche que dans l’interface graphique. Si vous souhaitez utiliser ces valeurs dans des modèles d’enregistrement sur disque ou d’envoi sur périphérique, vous devez créer une Colonne construite à partir d’autres colonnes personnalisée, utiliser la fonction dans le modèle de cette colonne et utiliser la valeur de cette colonne dans vos modèles d’enregistrement/d’envoi.

author_sorts

class calibre.utils.formatter_functions.BuiltinAuthorSorts[source]

author_sorts(val_separator) – retourne une chaîne contenant une liste de valeurs de tri pour les auteurs du livre. Le tri est celui indiqué dans les métadonnées de l’auteur, qui peut être différent du tri auteur_sort dans les livres. La liste retournée a la forme author_sort_1 val_separator author_sort_2 etc. sans espaces ajoutés. Les valeurs de tri des auteurs dans cette liste sont dans le même ordre que les auteurs du livre. Si vous voulez des espaces autour de val_separator, incluez-les dans la chaîne val_separator.

booksize

class calibre.utils.formatter_functions.BuiltinBooksize[source]

booksize() – retourne la valeur du champ size de Calibre. Retourne '' si le livre n’a pas de format.

Cette fonction ne marche que dans l’interface graphique. Si vous souhaitez utiliser ces valeurs dans des modèles d’enregistrement sur disque ou d’envoi sur périphérique, vous devez créer une Colonne construite à partir d’autres colonnes personnalisée, utiliser la fonction dans le modèle de cette colonne et utiliser la valeur de cette colonne dans vos modèles d’enregistrement/d’envoi.

connected_device_name

class calibre.utils.formatter_functions.BuiltinConnectedDeviceName[source]

connected_device_name(storage_location_key) – si un appareil est connecté, il retourne le nom de l’appareil, sinon il retourne une chaîne vide. Chaque emplacement de stockage sur un périphérique a son propre nom. Les noms storage_location_key sont 'main', 'carda' et 'cardb'. Cette fonction ne marche que dans l’interface graphique.

connected_device_uuid

class calibre.utils.formatter_functions.BuiltinConnectedDeviceUUID[source]

connected_device_uuid(storage_location_key) – si un appareil est connecté, il retourne l’uuid (identifiant unique) de l’appareil, sinon il retourne une chaîne vide. Chaque emplacement de stockage sur un appareil a un uuid différent. Les noms storage_location_key sont 'main', 'carda' et 'cardb'. Cette fonction ne marche que dans l’interface graphique.

current_library_name

class calibre.utils.formatter_functions.BuiltinCurrentLibraryName[source]

current_library_name() – retourne le dernier nom du chemin d’accès de la bibliothèque Calibre actuelle

current_library_path

class calibre.utils.formatter_functions.BuiltinCurrentLibraryPath[source]

current_library_path() – retourne le chemin d’accès complet de la bibliothèque Calibre actuelle.

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 une chaîne vide. La casse du nom de la bibliothèque est préservée. Exemple :

program: current_virtual_library_name()

Cette fonction ne marche que dans l’interface graphique.

field

class calibre.utils.formatter_functions.BuiltinField[source]

field(lookup_name) – retourne la valeur du champ de métadonnées avec le nom de recherche lookup_name. Le préfixe $ peut être utilisé à la place de la fonction, comme dans $tags.

formats_modtimes

class calibre.utils.formatter_functions.BuiltinFormatsModtimes[source]

formats_modtimes(date_format_string) – retourne une liste d’éléments FMT:DATE séparés par des virgules et des deux-points, représentant les dates de modification des formats d’un livre. Le paramètre date_format_string spécifie comment la date doit être formatée. Voir la fonction format_date() pour plus de détails. Vous pouvez utiliser la fonction select() pour obtenir l’heure de modification d’un format spécifique. Notez que les noms de formats sont toujours en majuscules, comme dans EPUB.

formats_paths

class calibre.utils.formatter_functions.BuiltinFormatsPaths[source]

formats_paths() – retourne une liste d’éléments FMT:PATH séparés par des virgules et des deux-points donnant le chemin complet vers les formats d’un livre. Vous pouvez utiliser la fonction select() pour obtenir le chemin d’un format spécifique. Notez que les noms de formats sont toujours en majuscules, comme dans EPUB.

formats_sizes

class calibre.utils.formatter_functions.BuiltinFormatsSizes[source]

formats_sizes() – retourne une liste d’éléments FMT:SIZE séparés par des virgules et des deux-points, donnant les tailles des formats d’un livre en octets. Vous pouvez utiliser la fonction select() pour obtenir la taille d’un format spécifique. Notez que les noms de formats sont toujours en majuscules, comme dans EPUB.

has_cover

class calibre.utils.formatter_functions.BuiltinHasCover[source]

has_cover() – retourne 'Oui' si le livre a une couverture, sinon une chaîne vide.

is_marked

class calibre.utils.formatter_functions.BuiltinIsMarked[source]

is_marked() – vérifie si le livre est marqué dans Calibre. Si c’est le cas, il retourne la valeur de la marque, soit 'true' (en minuscules), soit une liste de marques nommées séparées par des virgules. Retourne '' (chaîne vide) si le livre n’est pas marqué. Cette fonction ne marche que dans l’interface graphique.

language_codes

class calibre.utils.formatter_functions.BuiltinLanguageCodes[source]

language_codes(lang_strings) – retourne le codes de langue pour les noms de langues passés dans lang_strings. Les chaînes doivent être dans la langue de la locale courante. lang_strings est une liste séparée par des virgules.

language_strings

class calibre.utils.formatter_functions.BuiltinLanguageStrings[source]

language_strings(value, localize) – retourne les noms des langue pour les codes de langue (voir ici pour les noms et les codes) passé dans value. Exemple : {languages:language_strings()}. Si lang_codes est égal à zéro, les chaînes sont retournées en Anglais. Si lang_codes est différent de zéro, les chaînes sont retournées dans la langue de la locale courante. lang_codes est une liste séparée par des virgules.

ondevice

class calibre.utils.formatter_functions.BuiltinOndevice[source]

ondevice() – retourne la chaîne 'Oui' si ondevice est défini, sinon retourne une chaîne vide.

Cette fonction ne marche que dans l’interface graphique. Si vous souhaitez utiliser ces valeurs dans des modèles d’enregistrement sur disque ou d’envoi sur périphérique, vous devez créer une Colonne construite à partir d’autres colonnes personnalisée, utiliser la fonction dans le modèle de cette colonne et utiliser la valeur de cette colonne dans vos modèles d’enregistrement/d’envoi.

raw_field

class calibre.utils.formatter_functions.BuiltinRawField[source]

raw_field(lookup_name [, optional_default]) – retourne le champ de métadonnées nommé par lookup_name sans appliquer de formatage. Elle évalue et retourne le second argument optionnel optional_default si la valeur du champ est indéfinie (None). Le préfixe $$ peut être utilisé à la place de la fonction, comme dans $$pubdate.

raw_list

class calibre.utils.formatter_functions.BuiltinRawList[source]

raw_list(lookup_name, separator) – retourne la liste de métadonnées nommée par lookup_name sans appliquer de formatage ou de tri, avec les éléments séparés par separator.

series_sort

class calibre.utils.formatter_functions.BuiltinSeriesSort[source]

series_sort() – retourne la valeur du tri pour la série.

user_categories

class calibre.utils.formatter_functions.BuiltinUserCategories[source]

user_categories() – retourne une liste séparés par des virgules des catégories utilisateur contenant ce livre.

Cette fonction ne marche que dans l’interface graphique. Si vous souhaitez utiliser ces valeurs dans des modèles d’enregistrement sur disque ou d’envoi sur périphérique, vous devez créer une Colonne construite à partir d’autres colonnes personnalisée, utiliser la fonction dans le modèle de cette colonne et utiliser la valeur de cette colonne dans vos modèles d’enregistrement/d’envoi.

virtual_libraries

class calibre.utils.formatter_functions.BuiltinVirtualLibraries[source]

virtual_libraries() – retourne une liste séparés par des virgules de bibliothèques virtuelles qui contiennent ce livre.

Cette fonction ne marche que dans l’interface graphique. Si vous souhaitez utiliser ces valeurs dans des modèles d’enregistrement sur disque ou d’envoi sur périphérique, vous devez créer une Colonne construite à partir d’autres colonnes personnalisée, utiliser la fonction dans le modèle de cette colonne et utiliser la valeur de cette colonne dans vos modèles d’enregistrement/d’envoi.

Relationnel

cmp

class calibre.utils.formatter_functions.BuiltinCmp[source]

cmp(value, y, lt, eq, gt) – compare value et y après les avoir convertis en nombres. Retourne lt si value <# y, eq si value =# y, sinon gt. Cette fonction peut généralement être remplacée par l’un des opérateurs de comparaison numérique (==#, <#, >#, etc).

first_matching_cmp

class calibre.utils.formatter_functions.BuiltinFirstMatchingCmp[source]

first_matching_cmp(val, [cmp, result,]* else_result) – compare val < cmp dans l’ordre, en retournant le result associé à la première comparaison réussie. Retourne else_result si aucune comparaison ne réussit.

Exemple :

i = 10;
first_matching_cmp(i, 5,'petit', 10,'moyen', 15,'large', 'géant')

retourne 'large'. Le même exemple avec comme première valeur 16 retourne 'géant'.

strcmp

class calibre.utils.formatter_functions.BuiltinStrcmp[source]

strcmp(x, y, lt, eq, gt) – effectue une comparaison lexicale insensible à la casse de x et y. Retourne lt si x < y, eq si x == y, sinon gt. Cette fonction peut souvent être remplacée par l’un des opérateurs de comparaison lexicale (==, >, <, etc.)

strcmpcase

class calibre.utils.formatter_functions.BuiltinStrcmpcase[source]

strcmpcase(x, y, lt, eq, gt) – effectue une comparaison lexicale insensible à la casse de x et y. Retourne lt si x < y, eq si x == y, sinon gt.

Note : Ce n’est PAS le comportement par défaut utilisé par Calibre, par exemple, dans les opérateurs de comparaison lexicale (==, >, <, etc.). Cette fonction peut provoquer des résultats inattendus, il est préférable d’utiliser strcmp() dans la mesure du possible.

Récursion

eval

class calibre.utils.formatter_functions.BuiltinEval[source]

eval(string) – évalue la chaîne comme un programme, en passant les variables locales. Cela permet d’utiliser le processeur de modèles pour construire des résultats complexes à partir de variables locales. En Mode Programme de Modèles, parce que les caractères { et } sont interprétés avant l’évaluation du modèle, vous devez utiliser la [[ pour le caractère { et ]]``pour le caractère ``}. Ils sont convertis automatiquement. Notez également que les préfixes et les suffixes (syntaxe |prefixe|suffixe) ne peuvent pas être utilisés dans l’argument de cette fonction lorsque vous utilisez le Mode Programme de Modèles.

template

class calibre.utils.formatter_functions.BuiltinTemplate[source]

template(x) – évalue x comme un modèle. L’évaluation est effectuée dans son propre contexte, ce qui signifie que les variables ne sont pas partagées entre l’appelant et l’évaluation du modèle. Si vous étes en Mode Programme de Modèles, parce que le { and } sont spéciaux, vous devez utiliser [[ pour le charactère { et ]] pour le charactère } ; ils sont convertis automatiquement. Par exemple, template('[[title_sort]]') évaluera le modèle {title_sort} et retourne sa valeur. Notez également que les préfixes et suffixes (la syntaxe |prefixe|suffixe) ne peuvent pas être utilisés dans l’argument de cette fonction lors de l’utilisation du Mode Programme de Modèles.

API of the Metadata objects

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

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

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

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

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

This object also has functions to format fields into strings.

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

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

is_null(field)[source]

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

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

Also returns True if the field does not exist.

deepcopy(class_generator=<function Metadata.<lambda>>)[source]

Do not use this method unless you know what you are doing, if you want to create a simple clone of this object, use deepcopy_metadata() instead. Class_generator must be a function that returns an instance of Metadata or a subclass of it.

get_identifiers()[source]

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

set_identifiers(identifiers)[source]

Set all identifiers. Note that if you previously set ISBN, calling this method will delete it.

set_identifier(typ, val)[source]

If val is empty, deletes identifier of type typ

standard_field_keys()[source]

return a list of all possible keys, even if this book doesn’t have them

custom_field_keys()[source]

return a list of the custom fields in this book

all_field_keys()[source]

All field keys known by this instance, even if their value is None

metadata_for_field(key)[source]

return metadata describing a standard or custom field.

all_non_none_fields()[source]

Return a dictionary containing all non-None metadata fields, including the custom ones.

get_standard_metadata(field, make_copy)[source]

return field metadata from the field if it is there. Otherwise return None. field is the key name, not the label. Return a copy if requested, just in case the user wants to change values in the dict.

get_all_standard_metadata(make_copy)[source]

return a dict containing all the standard field metadata associated with the book.

get_all_user_metadata(make_copy)[source]

return a dict containing all the custom field metadata associated with the book.

get_user_metadata(field, make_copy)[source]

return field metadata from the object if it is there. Otherwise return None. field is the key name, not the label. Return a copy if requested, just in case the user wants to change values in the dict.

set_all_user_metadata(metadata)[source]

store custom field metadata into the object. Field is the key name not the label

set_user_metadata(field, metadata)[source]

store custom field metadata for one column into the object. Field is the key name not the label

remove_stale_user_metadata(other_mi)[source]

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

template_to_attribute(other, ops)[source]

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

smart_update(other, replace_metadata=False)[source]

Merge the information in other into self. In case of conflicts, the information in other takes precedence, unless the information in other is NULL.

format_field(key, series_with_index=True)[source]

Returns the tuple (display_name, formatted_value)

to_html()[source]

A HTML representation of this object.

calibre.ebooks.metadata.book.base.STANDARD_METADATA_FIELDS

The set of standard metadata fields.


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

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

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

TOP_LEVEL_IDENTIFIERS = frozenset((
    'isbn',
))

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

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

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

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

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

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

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

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

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

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

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