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¶
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¶
ceiling(value)
– retourne le plus petit entier supérieur ou égal à value
. Lance une exception si value
n’est pas un nombre.
divide¶
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¶
floor(value)
– retourne le plus grand entier inférieur ou égal à value
. Lance une exception si value
n’est pas un nombre.
fractional_part¶
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¶
mod(value, y)
– retourne floor
du reste de value / y
. Lance une exception si value
ou y
ne sont pas des nombres.
multiply¶
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¶
round(value)
– retourne l’entier le plus proche de value
. Lance une exception si value
n’est pas un nombre.
subtract¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
capitalize(value)
– retourne value
avec la première lettre en majuscule et le reste en minuscule.
lowercase¶
lowercase(value)
– retourne value
en minuscules.
titlecase¶
titlecase(value)
– retourne value
en case de titre (premiére lettre de chaque mot en majuscule).
uppercase¶
uppercase(value)
– retourne value
en majuscules.
Consultation de liste¶
identifier_in_list¶
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¶
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¶
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¶
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¶
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¶
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
: ajoutev
secondes adate
m
: ajoutev
minutes adate
h
: ajoutev
heures adate
d
: ajoutev
jours adate
w
: ajoutev
semaines adate
y
: ajoutev
années adate
, où une année compte 365 jours.
Exemple : '1s3d-1m'
ajoutera 1 seconde, ajoutera 3 jours et soustraira 1 minute de date
.
days_between¶
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¶
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¶
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éevals
. 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¶
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¶
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¶
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¶
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_link¶
get_link(field_name, field_value)
– récupère le lien pour le champ field_name
avec la valeur field_value
. S’il n’y a pas de lien attaché, une chaîne vide est retournée. Exemples :
Le texte suivant retourne le lien attaché à l’étiquette
Fiction
:get_link('tags', 'Fiction')
Ce modèle crée une liste de liens pour tous les tags associés à un livre sous la forme suivante
value:link, ...
:program: ans = ''; for t in $tags: l = get_link('tags', t); if l then ans = list_join(', ', ans, ',', t & ':' & get_link('tags', t), ',') fi rof; ans
get_note¶
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¶
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¶
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 valeurfield_value
dans le champfield_name
a une note, sinon''
.Exemple :
has_note('tags', 'Fiction')
retourne'1'
si le tagfiction
a une note jointe, sinon''
.Si
field_value
est''
alors retourne une liste de valeurs dansfield_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¶
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¶
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èsfrom_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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
strlen(value)
– retourne la longueur de la chaîne de caractères value
.
substr¶
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¶
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¶
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¶
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¶
to_hex(val)
– retourne la chaîne val
encodée en hexadécimal. Ceci est utile lors de la construction d’URLs Calibre.
transliterate¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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.
booksize¶
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¶
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¶
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¶
current_library_name()
– retourne le dernier nom du chemin d’accès de la bibliothèque Calibre actuelle
current_library_path¶
current_library_path()
– retourne le chemin d’accès complet de la bibliothèque Calibre actuelle.
current_virtual_library_name¶
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¶
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¶
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¶
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¶
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¶
has_cover()
– retourne 'Oui'
si le livre a une couverture, sinon une chaîne vide.
is_marked¶
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¶
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¶
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¶
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¶
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¶
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¶
series_sort()
– retourne la valeur du tri pour la série.
user_categories¶
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¶
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¶
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¶
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¶
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¶
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¶
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¶
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.
- standard_field_keys()[source]¶
return a list of all possible keys, even if this book doesn’t have them
- 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.
- 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