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[fuente]

add(x, y) – devuelve x + y. Da un error si «x» o «y» no son números.

divide(x, y)

class calibre.utils.formatter_functions.BuiltinDivide[fuente]

divide(x, y) – devuelve x / y. Da un error si «x» o «y» no son números.

multiply(x, y)

class calibre.utils.formatter_functions.BuiltinMultiply[fuente]

multiply(x, y) – devuelve x * y. Da un error si «x» o «y» no son números.

subtract(x, y)

class calibre.utils.formatter_functions.BuiltinSubtract[fuente]

subtract(x, y) – devuelve x - y. Da un error si «x» o «y» no son números.

Boolean

and(valor, valor, …)

class calibre.utils.formatter_functions.BuiltinAnd[fuente]

and(valor, valor, …) – devuelve el texto «1» si ninguno de los valores está vacío, en caso contrario, devuelve un texto vacío. Esta función funciona bien con «first_non_empty». Puede incluir tantos valores como quiera.

not(valor)

class calibre.utils.formatter_functions.BuiltinNot[fuente]

not(valor) – devuelve el texto «1» si el valor está vacío, en caso contrario, devuelve un texto vacío. Esta función opera bien con «test» o «first_non_empty».

or(valor, valor, …)

class calibre.utils.formatter_functions.BuiltinOr[fuente]

or(valor, valor, …) – devuelve el texto «1» si alguno de los valores no está vacío, en caso contrario, devuelve un texto vacío. Esta función funciona bien con «first_non_empty». Puede incluir tantos valores como quiera.

Date functions

days_between(fecha1, fecha2)

class calibre.utils.formatter_functions.BuiltinDaysBetween[fuente]

days_between(fecha1, fecha2) – devuelve el número de días entre «fecha1» y «fecha2». El número es positivo si «fecha1» es posterior a «fecha2», en caso contrario es negativo. Si «fecha1» o «fecha2» no son fechas, la función devuelve un texto vacío.

today()

class calibre.utils.formatter_functions.BuiltinToday[fuente]

today() – devuelve un texto para la fecha de hoy. Este valor está preparado para usarse con «format_date» o «days_between», pero puede manipularse como cualquier otro texto. La fecha está en formato ISO.

Formatting values

finish_formatting(val, fmt, prefijo, sufijo)

class calibre.utils.formatter_functions.BuiltinFinishFormatting[fuente]

finish_formatting(val, fmt, prefijo, sufijo) – aplica el formato, prefijo y sufijo a un valor de la misma manera que se haría en una plantilla como «{series_index:05.2f| - |- }». Por ejemplo, el siguiente programa produce la misma salida que la plantilla anterior: program: finish_formatting(field(«series_index»), «05.2f», » - «, » - «)

format_date(val, texto_formato)

class calibre.utils.formatter_functions.BuiltinFormatDate[fuente]

format_date(val, texto_formato) – da formato a un valor, que debe ser un campo de fecha, según «texto_formato» y devuelve un texto. Los códigos de formato son: «d»: el día como un número, sin cero inicial (de 1 a 31). «dd»: el día como un número, con un cero inicial si es necesario (de 01 a 31). «ddd»: el día de la semana abreviado según el idioma local (p. ej. de «lun» a «dom»). «dddd»: el nombre local completo del día de la semana (p. ej. de «lunes» a «domingo»). «M»: el mes como un número sin cero inicial (de 1 a 12). «MM»: el mes como un número, con un cero inicial si es necesario (de 01 a 12). «MMM»: el mes abreviado según el idioma local (p. ej. de «ene» a «dic»). «MMMM»: el nombre local completo del mes (p. ej. de «enero» a «diciembre»). «yy»: el año como un número de dos cifras (de 00 a 99). «yyyy»: el año como un número de cuatro cifras. «h»: la hora sin cero inicial (de 0 a 11 o de 0 a 23, según am/pm). «hh»: la hora con un cero inicial si es necesario (de 00 a 11 o de 00 a 23, según am/pm). «m»: los minutos sin cero inicial (de 0 a 59). «mm»: los minutos con un cero inicial si es necesaro (de 00 a 59). «s»: los segundos sin cero inicial (de 0 a 59). «ss»: los segundos con un cero inicial si es necesario (de 00 a 59). «ap»: se escribe la hora en formato de 12 horas en lugar de 24, con «ap» sustituido por la forma local para am o pm. «AP»: se escribe la hora en formato de 12 horas en lugar de 24, con «AP» sustituido por la forma local para AM o PM. «iso»: la fecha con hora y zona horaria. Debe ser el único formato presente.

format_number(v, plantilla)

class calibre.utils.formatter_functions.BuiltinFormatNumber[fuente]

format_number(v, plantilla) – da formato al número «v» usando una plantilla de formato de Python como «{0:5.2f}» o «{0:,d}» o «{0:5,.2f}». La parte del nombre de la plantilla debe ser un 0 (cero) (el «{0:» en los ejemplos anteriores). Véase la documentación del lenguaje de plantillas y de Python para más ejemplos. Si la plantilla contiene sólo un formato, puede omitir el «{0:» inicial y el «}» final. Devuelve un texto vacío si el formato falla.

human_readabe(v)

class calibre.utils.formatter_functions.BuiltinHumanReadable[fuente]

human_readabe(v) – devuelve un texto que representa el número «v» en KB, MB, GB, etc.

Get values from metadata

approximate_formats()

class calibre.utils.formatter_functions.BuiltinApproximateFormats[fuente]

approximate_formats() – devuelve una lista separada por comas de formatos que en algún momento estuvieron asociados con el libro. No hay garantía de que esta lista sea correcta, aunque probablemente lo sea. Esta función puede ejecutarse en el modo de programación de plantillas usando la plantilla «{:”approximate_formats()”}». Tenga en cuenta que los nombres de formato están siempre en mayúsculas, como en «EPUB». Esta función funciona sólo en la interfaz gráfica. Si quiere usar estos valores en las plantillas para guardar en el disco o enviar al dispositivo, debe crear una columna personalizada de tipo «Columna generada a partir de otras columnas», usar la función en la plantilla de dicha columna y usar el valor de la columna en las plantillas para guardar o enviar

author_sorts(separador)

class calibre.utils.formatter_functions.BuiltinAuthorSorts[fuente]

author_sorts(separador) – devuelve un texto que contiene la lista de valores de orden de autor para los autores del libro. El orden de autor es el que figura en los metadatos de autores (diferente del valor de orden de autor del libro). La lista devuelta es de la forma orden_de_autor_1 separador orden_de_autor_2 etc. Los valores de orden de autor en la lista están en el mismo orden que los autores del libro. Si quiere espacios alrededor de «separador», inclúyalos en el valor.

booksize()

class calibre.utils.formatter_functions.BuiltinBooksize[fuente]

booksize() – devuelve el valor del campo de tamaño. Esta función funciona sólo en la interfaz gráfica. Si quiere usar estos valores en las plantillas para guardar en el disco o enviar al dispositivo, debe crear una columna personalizada de tipo «Columna generada a partir de otras columnas», usar la función en la plantilla de dicha columna y usar el valor de la columna en las plantillas para guardar o enviar

current_library_name()

class calibre.utils.formatter_functions.BuiltinCurrentLibraryName[fuente]

current_library_name() – devuelve la última parte de la ruta a la biblioteca de calibre actual. Esta función puede llamarse en el modo de programación de plantilla usando la plantilla «{:”current_library_name()”}».

current_library_path()

class calibre.utils.formatter_functions.BuiltinCurrentLibraryPath[fuente]

current_library_path() – devuelve la ruta a la biblioteca de calibre actual. Esta función puede usarse en el modo de programación de plantillas utilizando la plantilla «{:”current_library_path()”}».

field(nombre)

class calibre.utils.formatter_functions.BuiltinField[fuente]

field(nombre) – devuelve el campo de metadatos identificado por «nombre».

formats_modtimes(formato_fecha)

class calibre.utils.formatter_functions.BuiltinFormatsModtimes[fuente]

formats_modtimes(formato_fecha) – devuelve una lista de elementos (separados por dos puntos) separados por comas que representa las fechas de modificación para los formatos de un libro. El argumento «formato_fecha» especifica cómo se da formato a la fecha. Véase la función «format_date» para más detalles. Puede usar la función «select» para obtener la fecha de modificación de un formato específico. Tenga en cuenta que los nombres de formato siempre están en mayúsculas, como en «EPUB».

formats_paths()

class calibre.utils.formatter_functions.BuiltinFormatsPaths[fuente]

formats_paths() – devuelve una lista separada por comas de elementos separados por dos puntos que representan la ruta completa a los formatos de un libro. Puede usar la función «select» para obtener la ruta a un formato específico. Tenga en cuenta que los nombres de formato están siempre en mayúsculas, como en «EPUB».

formats_sizes()

class calibre.utils.formatter_functions.BuiltinFormatsSizes[fuente]

formats_sizes() – devuelve una lista de elementos (separados por dos puntos) separados por comas que representa los tamaños en bytes de los formatos de un libro. Puede usar la función «select» para obtener el tamaño de un formato específico. Tenga en cuenta que los nombres de formato siempre están en mayúsculas, como en «EPUB».

has_cover()

class calibre.utils.formatter_functions.BuiltinHasCover[fuente]

has_cover() – devuelve «Yes» si el libro tiene portada, en caso contrario devuelve un texto vacío.

language_codes(nombres)

class calibre.utils.formatter_functions.BuiltinLanguageCodes[fuente]

language_codes(nombres) – devuelve los códigos de idioma correspondientes a «nombres». Los nombres deben estar en el idioma actual. El argumento «nombres» es una lista separada por comas.

language_strings(códigos, localizar)

class calibre.utils.formatter_functions.BuiltinLanguageStrings[fuente]

language_strings(códigos, localizar) – devuelve los nombres de los idiomas identificados por «códigos». Si «localizar» es cero, devuelve los nombres en inglés. Si «localizar» no es cero, devuelve los nombres en el idioma actual. El argumento «códigos» es una lista separada por comas.

ondevice()

class calibre.utils.formatter_functions.BuiltinOndevice[fuente]

ondevice() – devuelve «Yes» si ondevice está activado, si no, devuelve un texto vacío. Esta función funciona sólo en la interfaz gráfica. Si quiere usar estos valores en las plantillas para guardar en el disco o enviar al dispositivo, debe crear una columna personalizada de tipo «Columna generada a partir de otras columnas», usar la función en la plantilla de dicha columna y usar el valor de la columna en las plantillas para guardar o enviar

raw_field(nombre)

class calibre.utils.formatter_functions.BuiltinRawField[fuente]

raw_field(nombre) – devuelve el campo de metadatos llamado «nombre» sin aplicar ningún formato.

raw_list(nombre, separador)

class calibre.utils.formatter_functions.BuiltinRawList[fuente]

raw_list(nombre, separador) – devuelve la lista de metadatos nombrada por «nombre» sin aplicar ningún formato u ordenación, con los elementos separados por «separador».

series_sort()

class calibre.utils.formatter_functions.BuiltinSeriesSort[fuente]

series_sort() – devuelve el valor del orden de serie

user_categories()

class calibre.utils.formatter_functions.BuiltinUserCategories[fuente]

user_categories() – devuelve una lista separada por comas de las categorías de usuario que contiene este libro. Esta función sólo funciona en la interfaz gráfica. Si desea utilizar estos valores en las plantillas para guardar en el disco o enviar al dispositivo, deberá crear una plantilla personalizada «Columna generada a partir de otras columnas», utilice la función en la plantilla de esa columna y use el valor de esa columna en las plantillas para guardar o enviar

virtual_libraries()

class calibre.utils.formatter_functions.BuiltinVirtualLibraries[fuente]

virtual_libraries() – devuelve una lista separada por comas de bibliotecas virtuales que contienen este libro. Esta función funciona sólo en la interfaz gráfica. Si quiere usar estos valores en las plantillas para guardar en el disco o enviar al dispositivo, debe crear una columna personalizada de tipo «Columna generada a partir de otras columnas», usar la función en la plantilla de dicha columna y usar el valor de la columna en las plantillas para guardar o enviar

If-then-else

contains(val, patrón, texto_si_coincide, texto_si_no_coincide)

class calibre.utils.formatter_functions.BuiltinContains[fuente]

contains(val, patrón, texto_si_coincide, texto_si_no_coincide) – comprueba si «val» contiene coincidencias para la expresión regular «patrón». Devuelve «texto_si_coincide» si se encuentran coincidencias, en caso contrario devuelve «texto_si_no_coincide».

ifempty(val, texto_si_vacío)

class calibre.utils.formatter_functions.BuiltinIfempty[fuente]

ifempty(val, texto_si_vacío) – devuelve «val» si no está vacío, en caso contrario devuelve «texto_si_vacío».

test(val, texto_si_no_vacío, texto_si_vacío)

class calibre.utils.formatter_functions.BuiltinTest[fuente]

test(val, texto_si_no_vacío, texto_si_vacío) – devuelve «texto_si_no_vacío» si «val» no está vacío, «devuelve texto_si_vacío» en caso contrario.

Iterating over values

first_non_empty(valor, valor, …)

class calibre.utils.formatter_functions.BuiltinFirstNonEmpty[fuente]

first_non_empty(valor, valor, …) – devuelve el primer valor que no esté vacío. Si todos los valores están vacíos, se devuelve también un valor vacío. Puede incluir tantos valores como quiera.

lookup(val, patrón, campo, patrón, campo, …, otro_campo)

class calibre.utils.formatter_functions.BuiltinLookup[fuente]

lookup(val, patrón, campo, patrón, campo, …, otro_campo) – como «switch», pero los argumentos son nombres de campo (metadatos), no texto. Se usará el valor del campo apropiado. Tenga en cuenta que puesto que las columnas compuestas son campos, puede usar esta función en un campo compuesto para usar el valor de otro campo compuesto. Esto es muy útil para construir rutas de guardado variables.

switch(val, patrón, valor, patrón, valor, …, otro_valor)

class calibre.utils.formatter_functions.BuiltinSwitch[fuente]

switch(val, patrón, valor, patrón, valor, …, otro_valor) – para cada pareja «patrón, valor», comprueba si «val» contiene coincidencias para la expresión regular «patrón» y, en tal caso, devuelve ese valor. Si no coincide ningún patrón, devuelve «otro_valor». Puede emplear tantas parejas «patrón, valor» como desee.

List lookup

identifier_in_list(val, id, val_encontrado, val_no_encontrado)

class calibre.utils.formatter_functions.BuiltinIdentifierInList[fuente]

identifier_in_list(val, id, val_encontrado, val_no_encontrado) – considera «val» como una lista de identificadores separados por comas, y compara el «id» con cada valor de la lista. Un identificador tiene el formato «id:valor». El argumento «id» debería ser «id» o «id:expreg». El primer caso, selecciona identificadores con dicho «id». El segundo caso, selecciona identificadores cuyo valor coincida con la expresión regular «expreg». Si existe alguna coincidencia, devuelve «val_encontrado», en caso contrario devuelve «val_no_encontrado».

in_list(val, separador, patrón, encontrado, …, no_encontrado)

class calibre.utils.formatter_functions.BuiltinInList[fuente]

in_list(val, separador, patrón, encontrado, …, no_encontrado) – considera «val» como una lista de elementos separados por «separador» y evalúa «patrón» con cada valor de la lista. Si «patrón» coincide con alguno de los elementos de la lista, devuelve «encontrado», en caso contrario devuelve «no_encontrado». Los argumentos «patrón» y «encontrado» pueden repetirse tantas veces como se desee, lo que permite devolver diferentes valores según la búsqueda. Los patrones se evalúan en orden. Se devuelve la primera coincidencia.

list_item(val, índice, separador)

class calibre.utils.formatter_functions.BuiltinListitem[fuente]

list_item(val, índice, separador) – interpreta el campo como una lista de elementos separados por «separador» y devuelve el elemento número «índice». El primer elemento es el número cero. El último elemento puede obtenerse con «list_item(-1, separador)». Si el elemento no está en la lista devuelve un valor vacío. El separador tiene el mismo significado que en la función «count».

select(val, clave)

class calibre.utils.formatter_functions.BuiltinSelect[fuente]

select(val, clave) – interpreta el valor como una lista de elementos separados por comas, con los elementos de la forma «id:valor». Encuentra la pareja con «id» igual a «clave» y devuelve el valor correspondiente.

str_in_list(separador, texto, encontrado, …, no_encontrado)

class calibre.utils.formatter_functions.BuiltinStrInList[fuente]

str_in_list(separador, texto, encontrado, …, no_encontrado) – considera «val» como una lista de elementos separados por «separador», y compara «texto» con cada valor de la lista. Si «texto» coincide con alguno de los valores (sin distinción de mayúsculas y minúsculas), devuelve «encontrado», en caso contrario devuelve «no_encontrado». Si el texto contiene separadores, también se considera como una lista y se comprueba cada elemento. Los argumentos «patrón» y «encontrado» pueden repetirse tantas veces como se desee, lo que permite devolver diferentes valores según la búsqueda. Los patrones se evalúan en orden. Se devuelve la primera coincidencia.

List manipulation

count(val, separador)

class calibre.utils.formatter_functions.BuiltinCount[fuente]

count(val, separador) – interpreta el campo como una lista de elementos separados por ­«separador» y devuelve el número de elementos de la lista. La mayoría de las listas usan una coma como separador, pero «authors» usa un ampersand («&»). Ejemplos: {tags:count(,)}, {authors,count(&)}

list_difference(lista1, lista2, separador)

class calibre.utils.formatter_functions.BuiltinListDifference[fuente]

list_difference(lista1, lista2, separador) – devuelve una lista construida eliminando de lista1 cualquier elemento que aparezca en lista2, sin distinguir mayúsculas y minúsculas. Los elementos de lista1 y lista2 están separados por separador, así como los de la lista resultante.

list_equals(lista1, sep1, lista2, sep2, val_sí, val_no)

class calibre.utils.formatter_functions.BuiltinListEquals[fuente]

list_equals(lista1, sep1, lista2, sep2, val_sí, val_no) – devuelve «val_sí» si «lista1» y «lista2» contienen los mismos elementos, en caso contrario devuelve «val_no». Los elementos se determinan dividiendo cada lista por el correspondiente carácter separador («sep1» o «sep2»). El orden de los elementos no es relevante. La comparación no diferencia mayúsculas y minúsculas.

list_intersection(lista1, lista2, separador)

class calibre.utils.formatter_functions.BuiltinListIntersection[fuente]

list_intersection(lista1, lista2, separador) – devuelve una lista construida eliminando de lista1 cualquier elemento que no aparezca en lista2, sin distinguir mayúsculas y minúsculas. Los elementos de lista1 y lista2 están separados por separador, así como los de la lista resultante.

list_re(lista_orig, separador, incluir, sust_opc)

class calibre.utils.formatter_functions.BuiltinListRe[fuente]

list_re(lista_orig, separador, incluir, sust_opc) – construye una lista separando primero «lista_orig» en elementos usando el carácter «separador». Para cada elemento en la lista, comprueba si coincide con la expresión regular «incluir». Si coincide, se añade a la lista final. Si «sust_opc» no es un texto vacío, se aplica la sustitución antes de añadir el elemento a la lista final.

list_re_group(lista_orig, separador, incluir, búsqueda, plantilla_grupo_1, …)

class calibre.utils.formatter_functions.BuiltinListReGroup[fuente]

list_re_group(lista_orig, separador, incluir, búsqueda, plantilla_grupo_1, …) – como «list_re», pero las sustituciones no son opcionales. Usa re_group(elemento, búsqueda, plantilla_grupo_1, …) al hacer sustituciones en la lista final.

list_sort(lista, dirección, separador)

class calibre.utils.formatter_functions.BuiltinListSort[fuente]

list_sort(lista, dirección, separador) – devuelve «lista» ordenada sin distinción de mayúsculas y minúsculas. Si «dirección» es cero, la lista se ordena de manera ascendente, en caso contrario, de manera descendente. Los elementos de «lista» están separados por «separador», así como los de la lista resultante.

list_union(lista1, lista2, separador)

class calibre.utils.formatter_functions.BuiltinListUnion[fuente]

list_union(lista1, lista2, separador) – devuelve una lista construida por combinación de los elementos en lista1 y lista2, eliminando los duplicados de lista2 (no distingue mayúsculas y minúsculas, se mantiene la versión de lista1). Los elementos de lista1 y lista2 están separados por separador, así como los de la lista resultante.

subitems(val, índice_inicio, índice_fin)

class calibre.utils.formatter_functions.BuiltinSubitems[fuente]

subitems(val, índice_inicio, índice_fin) – Esta función se usa para separar listas de elementos tales como los géneros. Interpreta el valor como una lista de elementos separados por comas, donde cada elemento es a su vez una lista de elementos separados por puntos. Devuelve una nueva lista formada tomando, de cada lista de elementos separados por puntos, los elementos situados entre las posiciones «índice_inicio» e «índice_fin» y combinando los resultados. El primer elemento de cada lista separada por puntos ocupa la posición cero. Si un índice es negativo, se cuenta desde el final de la lista. Como caso especial, si «índice_fin» es cero, se considera que es el final de la lista. Ejemplos en el modo básico de plantilla y suponiendo que la columna #género contiene el valor «A.B.C»: {#género:subitems(0,1)} devuelve «A», {#género:subitems(0,2)} devuelve «A.B», {#género:subitems(1,0)} devuelve «B.C». Suponiendo que #género contiene el valor «A.B.C, D.E.F»: {#género:subitems(0,1)} devuelve «A, D», {#género:subitems(0,2)} devuelve «A.B, D.E».

sublist(val, índice_inicio, índice_fin, separador)

class calibre.utils.formatter_functions.BuiltinSublist[fuente]

sublist(val, índice_inicio, índice_fin, separador) – interpreta el valor como una lista de elementos separados por «separador» y devuelve una nueva lista con los elementos comprendidos entre la posición «índice_inicio» e «índice_fin». El primer elemento ocupa la posición cero. Si un índice es negativo, se cuenta desde el final de la lista. Como caso especial, si «índice_fin» es cero, se considera que es el final de la lista. Ejemplos en el modo básico de plantilla y suponiendo que la columna de etiquetas (definida como valores separados por comas) contiene «A, B, C»: {tags:sublist{0,1,\,)} devuelve «A», {tags:sublist(-1,0,\,)} devuelve «C», {tags:sublist(0,-1,\,)} devuelve «A, B».

Other

assign(id, val)

class calibre.utils.formatter_functions.BuiltinAssign[fuente]

assign(id, val) – asigna «val» a «id» y devuelve «val». «id» debe ser un identificador, no una expresión

Recursion

eval(plantilla)

class calibre.utils.formatter_functions.BuiltinEval[fuente]

eval(plantilla) – evalúa la plantilla, pasando las variables locales (las definidas con «assign») en lugar de los metadatos del libro. Esto permite usar el procesador de plantillas para elaborar resultados complejos a partir de variables locales. Dado que los caracteres «{» y «}» tienen un uso especial, debe usar «[[» en lugar de «{» y «]]» para «}»; se convertirán automáticamente. Tenga en cuenta que los prefijos y sufijos (la sintaxis «|prefijo|sufijo|») no puede usarse en el argumento de esta función en el modo de programación de plantilla.

template(x)

class calibre.utils.formatter_functions.BuiltinTemplate[fuente]

template(x) – evalúa x como una plantilla. La evaluación se realiza en un contexto propio, lo que significa que las variables no se comparten entre el proceso que llama a la función y la evaluación de la plantilla. Dado que los caracteres «{» y «}» tienen un uso especial, debe usar «[[» en lugar de «{» y «]]» para «}»; se convertirán automáticamente. Por ejemplo, «template(“[[orden_de_título]]”)» evaluará la plantilla {orden_de_título} y devolverá su valor. Tenga en cuenta que los prefijos y sufijos (la sintaxis «|prefijo|sufijo|») no puede usarse en el argumento de esta función en el modo de programación de plantilla.

Relational

cmp(x, y, mn, ig, my)

class calibre.utils.formatter_functions.BuiltinCmp[fuente]

cmp(x, y, mn, ig, my) – compara x e y después de convertirlas en números. Devuelve mn si x < y. Devuelve ig si x = y. Devuelve my en otros casos.

first_matching_cmp(val, cmp1, resultado1, cmp2, resultado2, …, otro_resultado)

class calibre.utils.formatter_functions.BuiltinFirstMatchingCmp[fuente]

first_matching_cmp(val, cmp1, resultado1, cmp2, resultado2, …, otro_resultado) – compara «val < cmpN» consecutivamente y devuelve «resultadoN» para la primera comparación que sea cierta. Devuelve «otro_resultado» si ninguna comparación es cierta. Ejemplo: first_matching_cmp(10,5,»pequeño»,10,»mediano»,15,»grande»,»enorme») devuelve «grande». El mismo ejemplo con un primer valor de 16 devuelve «enorme».

strcmp(x, y, mn, ig, my)

class calibre.utils.formatter_functions.BuiltinStrcmp[fuente]

strcmp(x, y, mn, ig, my) – compara «x» e «y» como textos sin distinguir mayúsculas y minúsculas. Devuelve «mn» si x < y. Devuelve «ig» si x = y. Devuelve «my» en otros casos.

String case changes

capitalize(val)

class calibre.utils.formatter_functions.BuiltinCapitalize[fuente]

capitalize(val) – devuelve «val» con la primera letra mayúscula

lowercase(val)

class calibre.utils.formatter_functions.BuiltinLowercase[fuente]

lowercase(val) – devuelve «val» en minúsculas

titlecase(val)

class calibre.utils.formatter_functions.BuiltinTitlecase[fuente]

titlecase(val) – devuelve «val» con las iniciales en mayúscula

uppercase(val)

class calibre.utils.formatter_functions.BuiltinUppercase[fuente]

uppercase(val) – devuelve «val» en mayúsculas

String manipulation

re(val, patrón, sustitución)

class calibre.utils.formatter_functions.BuiltinRe[fuente]

re(val, patrón, sustitución) – devuelve «val» después de aplicar la expresión regular. Todas las veces que aparezca «patrón» se sustituirá por «sustitución». Como en todo calibre, se trata de expresiones regulares compatibles con Python.

re_group(val, patrón, plantilla_para_grupo_1, para_grupo_2, …)

class calibre.utils.formatter_functions.BuiltinReGroup[fuente]

re_group(val, patrón, plantilla_para_grupo_1, para_grupo_2, …) – devuelve un texto formado por aplicación de la expresión regular «patrón» al valor «val», sustituyendo cada coincidencia con el texto calculado al sustituir cada grupo por el valor devuelto por la correspondiente plantilla. El valor de correspondencia original del grupo está disponible como «$». En el modo de programación de plantillas, como en las funciones «template» y «eval», use «[[» en lugar de «{» y «]]» en lugar de «}». El siguiente ejemplo en modo de programación de plantillas busca un nombre de serie con más de una palabra y pone la primera palabra en mayúsculas: {series:”re_group($, «(S* )(.*)», «[[$:uppercase()]]», «[[$]]»)”}

shorten(val, car_izq, texto_medio, car_der)

class calibre.utils.formatter_functions.BuiltinShorten[fuente]

shorten(val, car_izq, texto_medio, car_der) – devuelve una versión abreviada de «val», consistente en un número «car_izq» de caracteres del principio del «val», seguidos de «texto_medio», seguido de un número «car_der» de caracteres del fina de «val». «car_izq» y «car_der» deben ser números enteros. Por ejemplo, supongamos que el título del libro es «Novísima recopilación de las leyes de España» y que quiere que quepa en un espacio de 15 caracteres a lo sumo. Si usa {title:shorten(8,-,6)}, el resultado será «Novísima-España». Si la longitud del campo es menor que «car_izq» + «car_der» + la longitud de «texto_medio», se usará el campo intacto. Por ejemplo, el título «La colmena» no se cambiará.

strcat(a, b, …)

class calibre.utils.formatter_functions.BuiltinStrcat[fuente]

strcat(a, b, …) – admite un número arbitrario de argumentos. Devuelve un texto consistente en la unión de todos los argumentos consecutivamente.

strcat_max(máx, texto1, prefijo2, texto2, …)

class calibre.utils.formatter_functions.BuiltinStrcatMax[fuente]

strcat_max(máx, texto1, prefijo2, texto2, …) – devuelve un texto formado por concatenación de los argumentos. El valor devuelto es inicialmente «texto1». Se van añadiendo parejas «prefijo, texto» al final del valor mientras la longitud del resultado sea menor que «máx». El resultado es siempre al menos «texto1», aunque su longitud sea mayor que «máx». Puede especificar tantas parejas «prefijo, texto» como desee.

strlen(a)

class calibre.utils.formatter_functions.BuiltinStrlen[fuente]

strlen(a) – devuelve la longitud del texto pasado como argumento.

substr(texto, inicio, fin)

class calibre.utils.formatter_functions.BuiltinSubstr[fuente]

substr(texto, inicio, fin) – devuelve los caracteres entre la posición «inicio» y «fin» de «texto». El primer carácter de «texto» está en la posición cero. Si «fin» es negativo, entonces indica la posición contando desde la derecha. Si «fin» es cero, indica el último carácter. Por ejemplo, «substr(“12345”, 1, 0)» devuelve «2345», y «substr(“12345”, 1, -1)» devuelve «234».

swap_around_comma(val)

class calibre.utils.formatter_functions.BuiltinSwapAroundComma[fuente]

swap_around_comma(val) – dado un valor de la forma «B, A», devuelve «A B». Esto es útil para convertir nombres en formato APELLIDO, NOMBRE a NOMBRE APELLIDO. Si no hay ninguna coma, la función devuelve «val» sin cambios.

transliterate(a)

class calibre.utils.formatter_functions.BuiltinTransliterate[fuente]

transliterate(a) – Devuelve un texto en el alfabeto latino formado por aproximación del sonido de las palabras en el texto origen. Por ejemplo, si el origen es «Фёдор Миха́йлович Достоевский» la función devuelve «Fiodor Mikhailovich Dostoievskii».

API of the Metadata objects

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

class calibre.ebooks.metadata.book.base.Metadata(title, authors=(u'Desconocido', ), other=None, template_cache=None, formatter=None)[fuente]

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

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

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

Also returns True if the field does not exist.

deepcopy(class_generator=<function <lambda>>)[fuente]

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

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

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

set_identifier(typ, val)[fuente]

If val is empty, deletes identifier of type typ

standard_field_keys()[fuente]

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

custom_field_keys()[fuente]

return a list of the custom fields in this book

all_field_keys()[fuente]

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

metadata_for_field(key)[fuente]

return metadata describing a standard or custom field.

all_non_none_fields()[fuente]

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

get_standard_metadata(field, make_copy)[fuente]

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

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

get_all_user_metadata(make_copy)[fuente]

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

get_user_metadata(field, make_copy)[fuente]

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

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

set_user_metadata(field, metadata)[fuente]

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

template_to_attribute(other, ops)[fuente]

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

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

Returns the tuple (display_name, formatted_value)

to_html()[fuente]

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, for e.g. 'jpeg', 'png', 'gif'...
    'cover_data',
    # Either thumbnail data, or an object with the attribute
    # image_path which is the path to an image file, encoded
    # in filesystem_encoding
    'thumbnail',
    ])

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

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

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

])

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

    ]
)

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

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

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

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

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

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