Reference for all built-in template language functions

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

Arithmetic

add(x [, y]*)

class calibre.utils.formatter_functions.BuiltinAdd[sorgente]

add(x [, y]*) – restituisce la somma dei suoi argomenti. Genera un’eccezione se un argomento non è un numero. Questa funzione può spesso essere sostituita dall’operatore +.

ceiling(x)

class calibre.utils.formatter_functions.BuiltinCeiling[sorgente]

ceiling(x) – restituisce il più piccolo intero maggiore di o uguale a x. Genera un’eccezione se x non è un numero.

divide(x, y)

class calibre.utils.formatter_functions.BuiltinDivide[sorgente]

divide(x, y) – restituisce x / y. Genera un’eccezione se uno tra x e y non è un numero. Questa funzione può spesso essere sostituita dall’operatore /.

floor(x)

class calibre.utils.formatter_functions.BuiltinFloor[sorgente]

floor(x) – restituisce il più grande intero minore di o uguale a x. Genera un’eccezione se x non è un numero.

fractional_part(x)

class calibre.utils.formatter_functions.BuiltinFractionalPart[sorgente]

fractional_part(x) – restituisce il valore dopo la virgola. Per esempio fractional_part(3.14) restituisce 0.14. Genera un’eccezione se x non è un numero.

mod(x)

class calibre.utils.formatter_functions.BuiltinMod[sorgente]

mod(x) – restituisce floor(resto di x / y). Genera un’eccezione se x oppure y non sono numeri.

multiply(x [, y]*)

class calibre.utils.formatter_functions.BuiltinMultiply[sorgente]

multiply(x [, y]*) – restituisce il prodotto dei suoi argomenti. Genera un’eccezione se uno dei suoi argomenti non è un numero. Questa funzione può spesso essere sostituita dall’operatore *.

round(x)

class calibre.utils.formatter_functions.BuiltinRound[sorgente]

round(x) – restituisce l’intero più vicino a x. Genera un’eccezione se x non è un numero.

subtract(x, y)

class calibre.utils.formatter_functions.BuiltinSubtract[sorgente]

subtract(x, y) – restituisce x - y. Genera un’eccezione se uno tra x e y non è un numero. Questa funzione può spesso essere sostituita dall’operatore -.

Boolean

and(valore [, valore]*)

class calibre.utils.formatter_functions.BuiltinAnd[sorgente]

and(valore [, valore]*) – restituisce la stringa «1» se tutti i valori non sono vuoti, altrimenti restituisce la stringa vuota. Questa funzione lavora correttamente con test o first_non_empty. Puoi avere quanti valori desideri. In molti casi l’operatore && può sostituire questa funzione.

not(valore)

class calibre.utils.formatter_functions.BuiltinNot[sorgente]

not(valore) – restituisce la stringa «1» se il valore è vuoto, altrimenti restituisce la stringa vuota. Questa funzione lavora correttamente con test o first_non_empty. In molti casi l’operatore ! può sostituire questa funzione.

or(valore [, valore]*)

class calibre.utils.formatter_functions.BuiltinOr[sorgente]

or(valore [, valore]*) – restituisce la stringa «1» se un qualunque valore non è vuoto, altrimenti restituisce la stringa vuota. Questa funzione lavora correttamente con test o first_non_empty. Puoi avere quanti valori desideri. In molti casi l’operatore || può sostituire questa funzione.

Date functions

date_arithmetic(date, calc_spec, fmt)

class calibre.utils.formatter_functions.BuiltinDateArithmetic[sorgente]

date_arithmetic(date, calc_spec, fmt) – Calculate a new date from “date” using “calc_spec”. Return the new date formatted according to optional “fmt”: if not supplied then the result will be in iso format. The calc_spec is a string formed by concatenating pairs of “vW” (valueWhat) where “v” is a possibly-negative number and W is one of the following letters: s: add “v” seconds to “date” m: add “v” minutes to “date” h: add “v” hours to “date” d: add “v” days to “date” w: add “v” weeks to “date” y: add “v” years to “date”, where a year is 365 days. Example: “1s3d-1m” will add 1 second, add 3 days, and subtract 1 minute from “date”.

days_between(data1, data2)

class calibre.utils.formatter_functions.BuiltinDaysBetween[sorgente]

days_between(data1, data2) – restituisce il numero di giorni tra data1 e data2. Il numero è positivo se data1 è maggiore di data2, altrimenti è negativo. Se data1 o data2 non sono date, la funzione restituisce la stringa vuota.

today()

class calibre.utils.formatter_functions.BuiltinToday[sorgente]

today() – restituisce una stringa della data odierna. Questo valore è pensato per l’utilizzo in format_date o days_between, ma può essere manipolato come qualsiasi altra stringa. La data è espressa in formato ISO.

Formatting values

finish_formatting(val, fmt, prefisso, suffisso)

class calibre.utils.formatter_functions.BuiltinFinishFormatting[sorgente]

finish_formatting(val, fmt, prefisso, suffisso) – applica formato, prefisso e suffisso a un valore nello stesso modo in cui viene fatto in un modello come {series_index:05.2f| - |- }. Per esempio, il seguente programma produce lo stesso output del modello precedente: program: finish_formatting(field(«series_index»), «05.2f», » - «, » - «)

format_number(v, template)

class calibre.utils.formatter_functions.BuiltinFormatNumber[sorgente]

format_number(v, template) – formatta il numero v usando uno schema di formattazione in Python come «{0:5.2f}» o «{0:,d}» o «${0:5,.2f}». La parte field_name dello schema deve essere uno 0 (zero) (lo «{0:» negli esempi precedenti). Vedi il linguaggio dei modelli e la documentazione di Python per più esempi. Puoi tralasciare lo «{0:» iniziale e il «}» finale se lo schema contiene solo un formato. Restituisce la stringa vuota se la formattazione fallisce.

human_readable(v)

class calibre.utils.formatter_functions.BuiltinHumanReadable[sorgente]

human_readable(v) – restituisce una stringa che rappresenta il numero v in KB, MB, GB, ecc.

rating_to_stars(value, use_half_stars)

class calibre.utils.formatter_functions.BuiltinRatingToStars[sorgente]

rating_to_stars(value, use_half_stars) – Restituisce la valutazione come stringa di caratteri stella. value è un numero tra 0 e 5. Imposta use_half_stars a 1 se vuoi caratteri mezza stella per colonne di valutazione personalizzate che supportano valutazioni non intere, come 2.5.

Get values from metadata

annotation_count()

class calibre.utils.formatter_functions.BuiltinAnnotationCount[sorgente]

annotation_count() – restituisce il numero totale di annotazioni di ogni tipo allegate al libro corrente. Questa funzione può essere usata solo nell’interfaccia grafica.

approximate_formats()

class calibre.utils.formatter_functions.BuiltinApproximateFormats[sorgente]

approximate_formats() – restituisce una lista separata da virgole di formati che in un dato momento erano associati al libro. Non c’è garanzia che questa lista sia corretta, sebbene probabilmente sia così. Questa funzione può essere invocata in modalità programma di modello usando lo schema «{:”approximate_formats()”}». Tieni presente che i nomi di formato sono sempre in maiuscolo, come in EPUB. Questa funzione può essere usata solo nell’interfaccia grafica. Se vuoi usare questi valori negli schemi di salvataggio su disco o di invio al dispositivo devi creare una «Colonna costruita da altre colonne» personalizzata, usare la funzione dello schema di quella colonna, e usare il valore di quella colonna nei tuoi schemi di salvataggio/invio

author_sorts(separatore_val)

class calibre.utils.formatter_functions.BuiltinAuthorSorts[sorgente]

author_sorts(separatore_val) – restituisce una stringa contenente un elenco di valori di ordinamento autore per gli autori del libro. L’ordinamento è quello del metadato autore (diverso dall’author_sort dei libri). L’elenco è restituito nella forma ordinamento autore 1 separatore_val ordinamento autore 2 ecc. I valori di ordinamento autore di questo elenco sono nello stesso ordine degli autori del libro. Se desideri avere spazi attorno a separatore_val includili nella stringa del separatore

booksize()

class calibre.utils.formatter_functions.BuiltinBooksize[sorgente]

booksize() – restituisce il valore del campo dimensione. Questa funzione può essere usata solo nell’interfaccia grafica. Se vuoi usare questo valore negli schemi di salvataggio su disco o di invio al dispositivo devi creare una «Colonna costruita da altre colonne» personalizzata, usare la funzione dello schema di quella colonna, e usare il valore di quella colonna nei tuoi schemi di salvataggio/invio

connected_device_name(posizione_memoria)

class calibre.utils.formatter_functions.BuiltinConnectedDeviceName[sorgente]

connected_device_name(posizione_memoria) – se un dispositivo è connesso restituisce il suo nome, altrimenti restituisce la stringa vuota. Ognuna delle posizioni di memoria di un dispositivo può avere un nome differente. I nomi delle posizioni sono “main”, “carda” e “cardb”. Questa funzione può essere usata solo nell’interfaccia grafica.

connected_device_uuid(posizione_memoria)

class calibre.utils.formatter_functions.BuiltinConnectedDeviceUUID[sorgente]

connected_device_uuid(posizione_memoria) – se un dispositivo è connesso restituisce il suo uuid (id univoco), altrimenti restituisce la stringa vuota. Ognuna delle posizioni di memoria di un dispositivo ha un uuid differente. I nomi delle posizioni sono “main”, “carda” e “cardb”. Questa funzione può essere usata solo nell’interfaccia grafica.

current_library_name()

class calibre.utils.formatter_functions.BuiltinCurrentLibraryName[sorgente]

current_library_name() – restituisce l’ultimo nome nel percorso della biblioteca di calibre corrente. Questa funzione può essere invocata in modalità programma di modello usando lo schema «{:”current_library_name()”}».

current_library_path()

class calibre.utils.formatter_functions.BuiltinCurrentLibraryPath[sorgente]

current_library_path() – restituisce il percorso della biblioteca di calibre corrente. Questa funzione può essere invocata in modalità programma di modello usando lo schema «{:”current_library_path()”}».

current_virtual_library_name()

class calibre.utils.formatter_functions.BuiltinCurrentVirtualLibraryName[sorgente]

current_virtual_library_name() – restituisce il nome della biblioteca virtuale attuale se ce n’è una, altrimenti la stringa vuota. Le maiuscole del nome della biblioteca sono conservate. Esempio: «program: current_virtual_library_name()».

field(nome_di_riferimento)

class calibre.utils.formatter_functions.BuiltinField[sorgente]

field(nome_di_riferimento) – restituisce il campo metadati identificato da nome_di_riferimento

formats_modtimes(formato_data)

class calibre.utils.formatter_functions.BuiltinFormatsModtimes[sorgente]

formats_modtimes(formato_data) – restituisce una lista separata da virgole di elementi separati da due punti (:) che rappresentano le date di modifica dei formati di un libro. Il parametro formato_data specifica quale sarà il formato della data. Vedi la funzione format_date per dettagli. Puoi usare la funzione select per ottenere la data di modifica di un formato specifico. Tieni presente che i nomi dei formati sono sempre in maiuscolo, come in EPUB.

formats_paths()

class calibre.utils.formatter_functions.BuiltinFormatsPaths[sorgente]

formats_paths() – restituisce una lista separata da virgole di elementi separati da due punti (:) che rappresentano il percorso completo ai formati di un libro. Puoi usare la funzione select per ottenere il percorso di un formato specifico. Tieni presente che i nomi di formato sono sempre in maiuscolo, come in EPUB.

formats_sizes()

class calibre.utils.formatter_functions.BuiltinFormatsSizes[sorgente]

formats_sizes() – restituisce una lista separata da virgole di elementi separati da due punti (:) che rappresentano la dimensione in byte dei formati di un libro. Puoi usare la funzione select per ottenere la dimensione di un formato specifico. Tieni presente che i nomi di formato sono sempre in maiuscolo, come in EPUB.

has_cover()

class calibre.utils.formatter_functions.BuiltinHasCover[sorgente]

has_cover() – restituisce Yes se il libro ha una copertina, altrimenti restituisce una stringa vuota

is_marked()

class calibre.utils.formatter_functions.BuiltinIsMarked[sorgente]

is_marked() – controlla se il libro è “marcato” in calibre. Se lo è restituisce il valore della marcatura, o “true” o la lista separata da virgole di marcature con nome. Restituisce “” se il libro non è marcato.

language_codes(stringhe_lingua)

class calibre.utils.formatter_functions.BuiltinLanguageCodes[sorgente]

language_codes(stringhe_lingua) – restituisce i codici lingua per le stringhe fornite in stringhe_lingua. Le stringhe devono essere nella lingua corrente di calibre. stringhe_lingua è una lista separata da virgole.

language_strings(codici_lingua, localizza)

class calibre.utils.formatter_functions.BuiltinLanguageStrings[sorgente]

language_strings(codici_lingua, localizza) – restituisce le stringhe dei codici lingua forniti in codici_lingua. Se localizza è zero, restituisce le stringhe in inglese. Se localizza non è zero, restituisce le stringhe nella lingua corrente. codici_lingua è una lista separata da virgole.

ondevice()

class calibre.utils.formatter_functions.BuiltinOndevice[sorgente]

ondevice() – restituisce Yes se ondevice è impostato, altrimenti restituisce la stringa vuota. Questa funzione può essere usata solo nell’interfaccia grafica. Se vuoi usare questo valore negli schemi di salvataggio su disco o di invio al dispositivo devi creare una «Colonna costruita da altre colonne» personalizzata, usare la funzione dello schema di quella colonna, e usare il valore di quella colonna nei tuoi schemi di salvataggio/invio

raw_field(nome_di_riferimento [, optional_default])

class calibre.utils.formatter_functions.BuiltinRawField[sorgente]

raw_field(nome_di_riferimento [, optional_default]) – restituisce il campo metadati identificato da nome_di_riferimento senza applicare alcuna formattazione. Valuta e restituisce il secondo argomento opzionale “default” se il campo non è definito (“None”).

raw_list(nome_di_riferimento, separatore)

class calibre.utils.formatter_functions.BuiltinRawList[sorgente]

raw_list(nome_di_riferimento, separatore) – restituisce la lista di metadati identificata da nome_di_riferimento senza applicare alcuna formattazione od ordinamento e con gli elementi separati dal separatore.

series_sort()

class calibre.utils.formatter_functions.BuiltinSeriesSort[sorgente]

series_sort() – restituisce il valore di ordinamento delle serie

user_categories()

class calibre.utils.formatter_functions.BuiltinUserCategories[sorgente]

user_categories() – restituisce una lista separata da virgole delle categorie utente che contengono questo libro. Questa funzione può essere usata solo nell’interfaccia grafica. Se vuoi usare questi valori negli schemi di salvataggio su disco o di invio al dispositivo devi creare una «Colonna costruita da altre colonne» personalizzata, usare la funzione dello schema di quella colonna, e usare il valore di quella colonna nei tuoi schemi di salvataggio/invio

virtual_libraries()

class calibre.utils.formatter_functions.BuiltinVirtualLibraries[sorgente]

virtual_libraries() – restituisce una lista separata da virgole delle Biblioteche Virtuali che contengono questo libro. Questa funzione può essere usata solo nell’interfaccia grafica. Se vuoi usare questi valori negli schemi di salvataggio su disco o di invio al dispositivo devi creare una «Colonna costruita da altre colonne» personalizzata, usare la funzione dello schema di quella colonna, e usare il valore di quella colonna nei tuoi schemi di salvataggio/invio

If-then-else

check_yes_no(field_name, is_undefined, is_false, is_true)

class calibre.utils.formatter_functions.BuiltinCheckYesNo[sorgente]

check_yes_no(field_name, is_undefined, is_false, is_true) – checks the value of the yes/no field named by the lookup key field_name for a value specified by the parameters, returning «yes» if a match is found, otherwise returning an empty string. Set the parameter is_undefined, is_false, or is_true to 1 (the number) to check that condition, otherwise set it to 0. Example: check_yes_no(«#bool», 1, 0, 1) returns «yes» if the yes/no field «#bool» is either undefined (neither True nor False) or True. More than one of is_undefined, is_false, or is_true can be set to 1. This function is usually used by the test() or is_empty() functions.

contains(val, schema, testo con risultati, testo senza risultati)

class calibre.utils.formatter_functions.BuiltinContains[sorgente]

contains(val, schema, testo con risultati, testo senza risultati) – controlla se val contiene corrispondenze con l’espressione regolare schema. Restituisce testo con risultati se vengono trovati dei risultati, altrimenti restituisce testo senza risultati

field_exists(nome_campo)

class calibre.utils.formatter_functions.BuiltinFieldExists[sorgente]

field_exists(nome_campo) – controlla se esiste un campo (colonna) chiamato nome_campo, restituisce 1 se esiste e “” se no.

ifempty(val, text if empty)

class calibre.utils.formatter_functions.BuiltinIfempty[sorgente]

ifempty(val, text if empty) – restituisce val se val non è vuoto, altrimenti restituisce text if empty

test(val, testo se non vuoto, testo se vuoto)

class calibre.utils.formatter_functions.BuiltinTest[sorgente]

test(val, testo se non vuoto, testo se vuoto) – restituisce “testo se non vuoto” se val non è vuoto, altrimenti restituisce “testo se vuoto”

Iterating over values

first_non_empty(valore [, valore]*)

class calibre.utils.formatter_functions.BuiltinFirstNonEmpty[sorgente]

first_non_empty(valore [, valore]*) – restituisce il primo valore non vuoto. Se tutti i valori sono vuoti, viene restituita la stringa vuota. Puoi avere un numero qualsiasi di valori.

lookup(val, [schema, campo,]+ campo_alternativo)

class calibre.utils.formatter_functions.BuiltinLookup[sorgente]

lookup(val, [schema, campo,]+ campo_alternativo) – come switch, a parte gli argomenti che sono nomi di campo (metadati), non testo. Il valore del campo appropriato sarà recuperato e usato. Nota che visto che le colonne composte sono campi, puoi usare questa funzione in un campo composto per utilizzare il valore di un altro campo composto. È estremamente utile per costruire percorsi di salvataggio variabili

switch(val, [schema, valore,]+ valore_alternativo)

class calibre.utils.formatter_functions.BuiltinSwitch[sorgente]

switch(val, [schema, valore,]+ valore_alternativo) – per ogni coppia schema, valore, verifica se val corrisponde all’espressione regolare schema e, se è così, restituisce quel valore. Se non c’è alcuna corrispondenza con gli schemi, viene restituito valore_alternativo. Puoi avere quante coppie schema, valore vuoi

List lookup

identifier_in_list(val, id, found_val, not_found_val)

class calibre.utils.formatter_functions.BuiltinIdentifierInList[sorgente]

identifier_in_list(val, id, found_val, not_found_val) – tratta val come lista di identificatori separati da virgola, confrontando la stringa con ognuno dei valori nella lista. Un identificatore ha il formato «identificatore:valore». Il parametro id dovrebbe essere «id» oppure «id:regex». Nel primo caso si ha corrispondenza se c’è un identificatore con quell’id. Nel secondo caso si ha corrispondenza se l’espressione regolare trova corrispondenza con il valore dell’identificatore. Se c’è una corrispondenza, restituisce found_val, altrimenti restituisce not_found_val.

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

class calibre.utils.formatter_functions.BuiltinInList[sorgente]

in_list(val, separator, [ pattern, found_val, ]+ not_found_val) – tratta val come una lista di elementi separati da separator, se pattern corrisponde ad uno qualsiasi dei valori della lista restituisce found_val. Se pattern non corrisponde ad alcun valore della lista restituisce not_found_val. Le coppie pattern e found_value possono essere ripetute quante volte si desidera. I pattern sono controllati in ordine. Viene restituito il found_val della prima corrispondenza. Alias: in_list(), list_contains()

list_item(val, indice, separatore)

class calibre.utils.formatter_functions.BuiltinListitem[sorgente]

list_item(val, indice, separatore) – interpreta il valore come lista di elementi separati da separatore e restituisce l’elemento n`indice`-simo. Il primo elemento è il numero zero. L’ultimo elemento può essere restituito usando list_item(-1,separatore). Se l’elemento non è nella lista, è restituito il valore vuoto. Il separatore ha lo stesso significato che nella funzione count.

select(val, key)

class calibre.utils.formatter_functions.BuiltinSelect[sorgente]

select(val, key) – interpreta il valore come lista separata da virgole di elementi, con elementi della forma «id:valore». Trova la coppia con l’id uguale a key, e restituisce il valore corrispondente. Restituisce la stringa vuota se nessuna corrispondenza viene trovata.

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

class calibre.utils.formatter_functions.BuiltinStrInList[sorgente]

str_in_list(val, separator, [string, found_val, ]+ not_found_val) – tratta val come una lista di elementi separati da separator, se la stringa corrisponde ad uno qualsiasi dei valori della lista restituisce found_val. Se la stringa non corrisponde ad alcun valore della lista restituisce not_found_val. Il confronto è per corrispondenza esatta (non «contiene») e non distingue le maiuscole. Le coppie string e found_value possono essere ripetute quante volte si desidera. I pattern sono controllati in ordine. Viene restituito il found_val della prima corrispondenza.

List manipulation

count(val, separatore)

class calibre.utils.formatter_functions.BuiltinCount[sorgente]

count(val, separatore) – interpreta il valore come una lista di elementi separati da separatore e restituisce il numero di elementi della lista. La maggior parte delle liste usa una virgola come separatore, ma gli autori usano la e commerciale. Esempi: {tags:count(,)}, {authors:count(&)}. Alias: count(), list_count()

list_count_matching(list, pattern, separator)

class calibre.utils.formatter_functions.BuiltinListCountMatching[sorgente]

list_count_matching(list, pattern, separator) – interpreta “list” come una lista di elementi separati da “separator” e restituisce il numero di elementi nella lista che corrispondono all’espressione regolare “pattern”. Alias: list_count_matching(), count_matching()

list_difference(lista1, lista2, separatore)

class calibre.utils.formatter_functions.BuiltinListDifference[sorgente]

list_difference(lista1, lista2, separatore) – restituisce una lista creata rimuovendo da lista1 tutti gli elementi trovati nella lista2, facendo un confronto senza distinzione di maiuscole. Gli elementi in lista1 e in lista2 sono separati da separatore, come anche gli elementi nella lista restituita.

list_equals(lista1, sep1, lista2, sep2, val_si, val_no)

class calibre.utils.formatter_functions.BuiltinListEquals[sorgente]

list_equals(lista1, sep1, lista2, sep2, val_si, val_no) – restituisce val_si se lista1 e lista2 contengono gli stessi elementi, altrimenti restituisce val_no. Gli elementi sono determinati dividendo ogni lista usando il carattere separatore appropriato (sep1 o sep2). L’ordine degli elementi nelle liste non è rilevante. Il confronto non tiene conto delle maiuscole.

list_intersection(lista1, lista2, separatore)

class calibre.utils.formatter_functions.BuiltinListIntersection[sorgente]

list_intersection(lista1, lista2, separatore) – restituisce una lista creata rimuovendo da lista1 tutti gli elementi non trovati nella lista2, facendo un confronto senza distinzione di maiuscole. Gli elementi in lista1 e in lista2 sono separati da separatore, come anche gli elementi nella lista restituita.

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

class calibre.utils.formatter_functions.BuiltinListJoin[sorgente]

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

program:

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

You can use list_join on the results of previous calls to list_join as follows
program:

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

You can use expressions to generate a list. For example, assume you want items for authors and #genre, but with the genre changed to the word “Genre: “ followed by the first letter of the genre, i.e. the genre “Fiction” becomes “Genre: F”. The following will do that
program:

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

list_re(lista_sorg, separatore, includi_re, sost_opz)

class calibre.utils.formatter_functions.BuiltinListRe[sorgente]

list_re(lista_sorg, separatore, includi_re, sost_opz) – Costruisce una lista, separando come prima cosa lista_sorg in elementi singoli usando il carattere separatore. Per ogni elemento nella lista, controlla se ha corrispondenze con includi_re. Se ne ha, viene aggiunto alla lista da restituire. Se sost_opz non è la stringa vuota, applica la sostituzione prima di aggiungere l’elemento alla lista restituita.

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

class calibre.utils.formatter_functions.BuiltinListReGroup[sorgente]

list_re_group(src_list, separator, include_re, search_re [, group_template]+) – Come list_re se non che le sostituzioni non sono opzionali. Usa re_group(list_item, search_re, group_template, …) per fare le sostituzioni nella lista risultante.

list_remove_duplicates(lista, separatore)

class calibre.utils.formatter_functions.BuiltinListRemoveDuplicates[sorgente]

list_remove_duplicates(lista, separatore) – restituisce una lista creata rimuovendo gli elementi duplicati della lista sorgente. Se gli elementi sono diversi solo per le maiuscole, è restituito l’ultimo di essi. Gli elementi nella lista sorgente sono separati da separatore, come anche gli elementi nella lista restituita.

list_sort(lista, direzione, separatore)

class calibre.utils.formatter_functions.BuiltinListSort[sorgente]

list_sort(lista, direzione, separatore) – restituisce la lista ordinata usando un metodo che non tiene conto delle maiuscole. Se direzione è zero, la lista è in ordine ascendente, altrimenti discendente. Gli elementi della lista sono separati da separatore, come anche gli elementi della lista restituita.

list_split(elenca_val, sep, prefisso_id)

class calibre.utils.formatter_functions.BuiltinListSplit[sorgente]

list_split(elenca_val, sep, prefisso_id) – divide elenca_val in valori separati usando “sep”, poi assegna i valori alle variabili chiamate “prefisso_id_N” dove N è la posizione del valore nella lista. Il primo elemento ha posizione 0 (zero). La funzione restituisce l’ultimo elemento della lista. Esempio: split(“uno:due:ciao”, “:”, “var”) è equivalente a var_0 = “uno”; var_1 = “due”; var_2 = “ciao”.

list_union(lista1, lista2, separatore)

class calibre.utils.formatter_functions.BuiltinListUnion[sorgente]

list_union(lista1, lista2, separatore) – restituisce una lista creata unendo gli elementi nella lista 1 e nella lista 2, e rimuove gli elementi duplicati facendo un confronto senza distinzione di maiuscole. Se degli elementi sono diversi come maiuscole, viene usato quello della lista1. Gli elementi in lista1 e in lista2 sono separati da separatore, come anche gli elementi nella lista restituita. Alias: list_union(), merge_lists()

subitems(val, start_index, end_index)

class calibre.utils.formatter_functions.BuiltinSubitems[sorgente]

subitems(val, start_index, end_index) – This function is used to break apart lists of items such as genres. It interprets the value as a comma-separated list of items, where each item is a period-separated list. Returns a new list made by first finding all the period-separated items, then for each such item extracting the start_index to the end_index components, then combining the results back together. The first component in a period-separated list has an index of zero. If an index is negative, then it counts from the end of the list. As a special case, an end_index of zero is assumed to be the length of the list. Example using basic template mode and assuming a #genre value of «A.B.C»: {#genre:subitems(0,1)} returns «A». {#genre:subitems(0,2)} returns «A.B». {#genre:subitems(1,0)} returns «B.C». Assuming a #genre value of «A.B.C, D.E.F», {#genre:subitems(0,1)} returns «A, D». {#genre:subitems(0,2)} returns «A.B, D.E»

sublist(val, start_index, end_index, separator)

class calibre.utils.formatter_functions.BuiltinSublist[sorgente]

sublist(val, start_index, end_index, separator) – interpret the value as a list of items separated by separator, returning a new list made from the start_index to the end_index item. The first item is number zero. If an index is negative, then it counts from the end of the list. As a special case, an end_index of zero is assumed to be the length of the list. Examples using basic template mode and assuming that the tags column (which is comma-separated) contains «A, B, C»: {tags:sublist(0,1,\,)} returns «A». {tags:sublist(-1,0,\,)} returns «C». {tags:sublist(0,-1,\,)} returns «A, B».

Other

assign(id, val)

class calibre.utils.formatter_functions.BuiltinAssign[sorgente]

assign(id, val) – assegna val a id, quindi restituisce val. id deve essere un identificatore, non un’espressione. Questa funzione può spesso essere sostituita con l’operatore =.

Recursion

eval(modello)

class calibre.utils.formatter_functions.BuiltinEval[sorgente]

eval(modello) – valuta il modello, passando le variabili locali (quelle assegnate con “assign”) al posto dei metadati del libro. Questo permette di usare l’elaborazione dei modelli per costruire risultati complessi dalle variabili locali. Dato che i caratteri { e } sono speciali, bisogna usare [[ per il carattere { e ]] per il carattere }; vengono convertiti automaticamente. Tieni anche presente che non possono essere usati prefissi e suffissi (la sintassi |prefisso|suffisso) nell’argomento di questa funzione quando è utilizzata in modalità programma di modello.

template(x)

class calibre.utils.formatter_functions.BuiltinTemplate[sorgente]

template(x) – valuta x come modello. La valutazione è fatta solo nel suo contesto, che significa che le variabili non sono condivise tra chiamante e valutazione del modello. Dato che i caratteri { e } sono speciali, bisogna usare [[ per il carattere { e ]] per il carattere }; vengono convertiti automaticamente. Per esempio, template(“[[title_sort]]”) valuterà il modello {title_sort} è restituirà il suo valore. Tieni anche presente che non possono essere usati prefissi e suffissi (la sintassi |prefisso|suffisso) nell’argomento di questa funzione quando è utilizzata in modalità programma di modello.

Relational

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

class calibre.utils.formatter_functions.BuiltinCmp[sorgente]

cmp(x, y, lt, eq, gt) – fa un confronto tra x e y dopo averli convertiti entrambi in numeri. Restituisce lt se x < y. Restituisce eq se x == y. Altrimenti restituisce gt. In molti casi gli operatori di confronto numerico (>#, <#, ==# ecc.) possono sostituire questa funzione.

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

class calibre.utils.formatter_functions.BuiltinFirstMatchingCmp[sorgente]

first_matching_cmp(val, [cmp1, result1,]+, else_result) – confronta «val < cmpN» in sequenza, restituendo resultN per il primo confronto che ha successo. Esempio: first_matching_cmp(10,5,»small»,10,»middle»,15,»large»,»giant»)  restituisce «large». Lo stesso esempio con 16 come primo valore restituisce «giant».

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

class calibre.utils.formatter_functions.BuiltinStrcmp[sorgente]

strcmp(x, y, lt, eq, gt) – fa un confronto tra x e y come stringhe senza distinguere tra maiuscole e minuscole. Restituisce lt se x < y. Restituisce eq se x == y. Altrimenti restituisce gt. In molti casi possono essere usati direttamente gli operatori di confronto (>, <, == ecc.) al posto di questa funzione.

String case changes

capitalize(val)

class calibre.utils.formatter_functions.BuiltinCapitalize[sorgente]

capitalize(val) – restituisce il valore del campo con l’iniziale maiuscola

lowercase(val)

class calibre.utils.formatter_functions.BuiltinLowercase[sorgente]

lowercase(val) – restituisce in minuscolo il valore del campo

titlecase(val)

class calibre.utils.formatter_functions.BuiltinTitlecase[sorgente]

titlecase(val) – restituisce iniziali parole di val in maiuscolo

uppercase(val)

class calibre.utils.formatter_functions.BuiltinUppercase[sorgente]

uppercase(val) – restituisce in maiuscolo il valore del campo

String manipulation

character(nome_carattere)

class calibre.utils.formatter_functions.BuiltinCharacter[sorgente]

character(nome_carattere) – restituisce il carattere con nome nome_carattere. Per esempio, character(“newline”) restituisce un carattere nuova riga (“n”). I nomi di carattere supportati sono “newline”, “return”, “tab”, e “backslash”.

re(val, pattern, replacement)

class calibre.utils.formatter_functions.BuiltinRe[sorgente]

re(val, pattern, replacement) – restituisce val dopo aver applicato l’espressione regolare. Tutti le occorrenze di pattern sono sostituite con replacement. Come in tutto calibre, queste sono espressioni regolari compatibili con Python

re_group(val, schema [, modello_del_gruppo]*)

class calibre.utils.formatter_functions.BuiltinReGroup[sorgente]

re_group(val, schema [, modello_del_gruppo]*) – restituisce una stringa creata applicando lo schema dell’espressione regolare a val e sostituendo ognuna delle corrispondenze con la stringa costruita sostituendo ogni gruppo trovato con il valore restituito dal modello corrispondente. Il valore inizialmente trovato del gruppo è disponibile come $. In modalità programma di modello, come per le funzioni template ed eval, si usano [[ per { e ]] per }. Il seguente esempio in modalità programma di modello cerca le serie con più di una parola e rende maiuscola la prima parola: {series:”re_group($, «(S* )(.*)», «[[$:uppercase()]]», «[[$]]»)”}

shorten(val, car sin, testo cent, car dest)

class calibre.utils.formatter_functions.BuiltinShorten[sorgente]

shorten(val, car sin, testo cent, car dest) – Restituisce una versione accorciata di val, che consiste dei caratteri car sin dell’inizio di val, seguiti da testo cent, seguiti dai caratteri car dest della fine della stringa. car sin e car dest devono essere interi. Per esempio, immagina che il titolo del libro sia Antiche Leggi Inglesi ai Tempi di Ivanhoe, e di voler fare in modo che il titolo occupi al più 15 caratteri. Se usi {title:shorten(9,-,5)}, il risultato sarà Antiche L-anhoe. Se la lunghezza del campo è minore di car sin + car dest + la lunghezza di testo cent, il campo sarà lasciato intatto. Per esempio, il titolo La Cupola non verrebbe cambiato.

strcat(a [, b]*)

class calibre.utils.formatter_functions.BuiltinStrcat[sorgente]

strcat(a [, b]*) – può accettare un qualsiasi numero di argomenti. Restituisce la stringa formata concatenando tutti gli argomenti

strcat_max(max, stringa1 [, prefisso2, stringa2]*)

class calibre.utils.formatter_functions.BuiltinStrcatMax[sorgente]

strcat_max(max, stringa1 [, prefisso2, stringa2]*) – Restituisce una stringa formata concatenando gli argomenti. Il valore restituito è inizializzato come stringa1. Le coppie prefisso, stringa sono aggiunte alla fine del valore purché la lunghezza della stringa risultante sia minore di max. Stringa 1 viene restituita anche se risulta più lunga di max. Puoi fornire quante coppie prefisso, stringa desideri.

strlen(a)

class calibre.utils.formatter_functions.BuiltinStrlen[sorgente]

strlen(a) – restituisce la lunghezza della stringa fornita come argomento

substr(str, inizio, fine)

class calibre.utils.formatter_functions.BuiltinSubstr[sorgente]

substr(str, inizio, fine) – restituisce i caratteri di str da «inizio» a «fine». Il primo carattere in str è il carattere zero. Se fine è un numero negativo, indica quel numero di caratteri contando da destra. Se fine è zero, indica l’ultimo carattere. Ad esempio, substr(“12345”, 1, 0) restituisce “2345” e substr(“12345”, 1, -1) restituisce “234”.

swap_around_articles(val, separatore)

class calibre.utils.formatter_functions.BuiltinSwapAroundArticles[sorgente]

swap_around_articles(val, separatore) – restituisce val con gli articoli spostati alla fine. Il valore può essere un elenco, nel qual caso ognuno dei suoi membri è elaborato. Se il valore è un elenco, devi fornire il separatore di valori. Se nessun separatore è fornito, il valore è trattato come singolo e non come elenco.

swap_around_comma(val)

class calibre.utils.formatter_functions.BuiltinSwapAroundComma[sorgente]

swap_around_comma(val) – dato un valore in formato «B, A», restituisce «A B». Utile soprattutto per convertire nomi dal formato CG, NM a NM CG. Se non c’è virgola, la funzione restituisce val senza cambiamenti

transliterate(a)

class calibre.utils.formatter_functions.BuiltinTransliterate[sorgente]

transliterate(a) – Restituisce una stringa in alfabeto latino creata in modo da approssimare il suono delle parole nella stringa sorgente. Per esempio, se la sorgente è «Фёдор Миха́йлович Достоевский» la funzione restituisce «Fiodor Mikhailovich Dostoievskii».

other

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

class calibre.utils.formatter_functions.BuiltinArguments[sorgente]

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

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

class calibre.utils.formatter_functions.BuiltinSetGlobals[sorgente]

globals(id[=expression] [, id[=expression]]*) – Recupera le «variabili globali» che possono essere passate alla funzione di formattazione. Dichiara e inizializza le variabili locali con i nomi delle variabili globali passate. Se la variabile corrispondente non è presente in quelle globali passate, assegna a quella variabile il valore predefinito fornito. Se non è presente alcun valore predefinito la variabile è impostata a stringa vuota.

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=('Sconosciuto',), other=None, template_cache=None, formatter=None)[sorgente]

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)[sorgente]

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>>)[sorgente]

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()[sorgente]

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)[sorgente]

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

set_identifier(typ, val)[sorgente]

If val is empty, deletes identifier of type typ

standard_field_keys()[sorgente]

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

custom_field_keys()[sorgente]

return a list of the custom fields in this book

all_field_keys()[sorgente]

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

metadata_for_field(key)[sorgente]

return metadata describing a standard or custom field.

all_non_none_fields()[sorgente]

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

get_standard_metadata(field, make_copy)[sorgente]

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)[sorgente]

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

get_all_user_metadata(make_copy)[sorgente]

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

get_user_metadata(field, make_copy)[sorgente]

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)[sorgente]

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

set_user_metadata(field, metadata)[sorgente]

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

remove_stale_user_metadata(other_mi)[sorgente]

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)[sorgente]

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)[sorgente]

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)[sorgente]

Returns the tuple (display_name, formatted_value)

to_html()[sorgente]

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

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

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

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

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

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

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