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[código fonte]¶
add(x [,y]*) – devolve a soma dos seus argumentos. Lança uma exceção se um argumento não for um número. Esta função pode, muitas vezes, ser substituída pelo operador +.
ceiling(x)¶
- class calibre.utils.formatter_functions.BuiltinCeiling[código fonte]¶
ceiling(x) – devolve o menor inteiro maior que ou igual a x. Devolve uma exceção se x não for um número.
divide(x, y)¶
- class calibre.utils.formatter_functions.BuiltinDivide[código fonte]¶
divide(x, y) – devolve x - y. Devolve uma exceção se x ou y não forem números. Muitas vezes, esta função pode ser substituída pelo operador / .
floor(x)¶
- class calibre.utils.formatter_functions.BuiltinFloor[código fonte]¶
floor(x) – devolve o maior inteiro que seja menor que ou igual a x . Devolve uma exceção se x não for um número.
fraction_part(x)¶
- class calibre.utils.formatter_functions.BuiltinFractionalPart[código fonte]¶
fraction_part(x) – devolve o valor existente depois da casa decimal. Por exemplo, fractional_part(3.14) devolve 0.14. Lança uma exceção caso x não seja um número.
mod(x)¶
- class calibre.utils.formatter_functions.BuiltinMod[código fonte]¶
mod(x) – devolve floor(remainder of x / y). Devolve uma exceção se x ou y não forem números.
multiply(x [, y]*)¶
- class calibre.utils.formatter_functions.BuiltinMultiply[código fonte]¶
multiply(x [, y]*) – devolve x - y. Devolve uma exceção se algum dos argumentos não forem números. Muitas vezes, esta função pode ser substituída pelo operador * .
round(x)¶
- class calibre.utils.formatter_functions.BuiltinRound[código fonte]¶
round(x) – devolve o inteiro mais próximo de x. Devolve uma exceção se x não for um número.
subtract(x, y)¶
- class calibre.utils.formatter_functions.BuiltinSubtract[código fonte]¶
subtract(x, y) – devolve x - y. Devolve uma exceção se x ou y não forem números. Muitas vezes, esta função pode ser substituída pelo operador - .
Boolean¶
and(value [, value]*)¶
- class calibre.utils.formatter_functions.BuiltinAnd[código fonte]¶
and(value [, value]*) – devolve a string «1» se todos os valores não estiverem vazios, caso contrário, devolve a string vazia. Esta função funciona bem com o teste ou first_non_empty. Pode ter quantos valores quiser. Em muitos casos o operador && pode substituir esta função.
not(value)¶
- class calibre.utils.formatter_functions.BuiltinNot[código fonte]¶
not(value) – devolve a string «1» se o valor estiver vazio, caso contrário, devolve a string vazia. Esta função funciona bem com o teste ou first_non_empty. Em muitos casos o operador ! pode substituir esta função.
or(value [, value]*)¶
- class calibre.utils.formatter_functions.BuiltinOr[código fonte]¶
or(value [, value]*) – devolve a string «1» se algum valor não estiver vazio, caso contrário, devolve a string vazia. Esta função funciona bem com o teste ou first_non_empty. Em muitos casos o operador || pode substituir esta função.
Date functions¶
date_arithmetic(data, calc_spec, fmt)¶
- class calibre.utils.formatter_functions.BuiltinDateArithmetic[código fonte]¶
date_arithmetic(data, calc_spec, fmt) – Calcula uma nova data a partir de “data” usando “calc_spec”. Devolve a nova data formatada de acordo com o parâmetro opcional “fmt”: se não fornecido, então o resultado estará no formato iso. O “calc_spec” é uma sequência formada pela concatenação de pares de “vQ” (valorQue), onde “v” é número que pode ser negativo e Q é uma das letras a seguir: s: adiciona “v” segundos à “data” m: adiciona “v” minutos à “data” h: adiciona “v” horas à “data” d: adiciona “v” dias à “data” w: adiciona “v” semanas à “data” y: adiciona “v” anos à “data”, em que um ano são 365 dias. Exemplo: “1s3d-1m” irá adicionar 1 segundo e 3 dias, e subtrai 1 minuto a partir da “data”.
days_between(date1, date2)¶
- class calibre.utils.formatter_functions.BuiltinDaysBetween[código fonte]¶
days_between(date1, date2) – devolve o número de dias entre date1 e date2. O número é positivo se date1 for maior do que date2, caso contrário, é negativo. Se date1 ou date2 não forem datas, a função devolve a string vazia.
today()¶
- class calibre.utils.formatter_functions.BuiltinToday[código fonte]¶
today() – devolve um string com a data de hoje. Este valor é destinado ao uso em format_date e days_between, mas pode ser manipulado como cualquer outro string. A data está em formato ISO.
Formatting values¶
finish_formatting(val, fmt, prefix, suffix)¶
- class calibre.utils.formatter_functions.BuiltinFinishFormatting[código fonte]¶
finish_formatting(val, fmt, prefix, suffix) – aplicar o formato, de prefixo, sufixo e para um valor da mesma forma como foi feito num modelo como {series_index:05.2f| - |- }. Por exemplo, o seguinte programa produz a mesma saída que o modelo acima: programa: finish_formatting(field(«series_index»), «05.2f», « - «, « - «)
format_date(val, format_string)¶
- class calibre.utils.formatter_functions.BuiltinFormatDate[código fonte]¶
format_date(val, format_string) – formato do valor, o qual deve ser uma data, usando a_string do formato, retornando uma string. Os formatos dos códigos são: d : dia sem o número zero à esquerda (1 à 31); dd : dia como número e com um zero à esquerda (01 à 31); ddd : nome do dia traduzido abreviado (por exemplo, «Seg» a «Dom»); dddd : nome longo do dia traduzido abreviado (por exemplo, «Segunda» a «Domingo»); M : mês como um número e sem o zero à esquerda (1 à 12); MM : mês como número e com um zero à esquerda (01 à 12); MMM : nome do mês traduzido abreviado (por exemplo, «Jan» a «Dez»); MMMM : nome longo do mês traduzido (por exemplo, «Janeiro» a «Dezembro»); yy : ano como dois dígitos numerais (00 à 99); yyyy : ano como quatro dígitos numerais. h : horas sem 0 à esquerda (0 a 11 ou 0 a 23, dependendo de am/pm); hh : horas com 0 à esquerda (00 a 11 ou 00 a 23, dependendo de am/pm); m : minutos sem 0 à esquerda (0 a 59); mm : minutos com 0 à esquerda (00 a 59) s : segundos sem 0 à esquerda (0 a 59); ss : segundos com 0 à esquerda (00 à 59); ap : usar um relógio de 12-horas em vez de um relógio de 24-horas, com «ap» substituído pela string traduzida por am ou pm; AP : usar um relógio de 12-horas em vez de um relógio de 24-horas, com «AP» substituído pela string traduzida por AM ou PM; iso : data com hora e fuso-horário. Deve ser o único formato presente: to_number - data como número de ponto flutuante; from_number[:fmt] - formatar o carimbo de data usando fmt se presente, ou usar iso se ausente.
format_date_field(nome_do_campo, string_de_formatacao)¶
- class calibre.utils.formatter_functions.BuiltinFormatDateField[código fonte]¶
format_date_field(nome_do_campo, string_de_formatacao) – formata o valor no campo “nome_do_campo”, o qual deve ser o nome para pesquisa da coluna de data, seja ela padrão ou personalizada. Veja “format_date” para os códigos de formatação. Esta função é muito mais rápida do que “format_date” e deve ser utilizada quando você estiver a formatar o valor de um campo (coluna). Ela não pode ser usada para datas computadas ou datas em variáveis de texto. Exemplo: format_date_field(“pubdate”, “yyyy.MM.dd”)
format_number(v, template)¶
- class calibre.utils.formatter_functions.BuiltinFormatNumber[código fonte]¶
format_number(v, template) – formatar o número v usando um modelo de formatação Python como «{0:5.2f}» ou «{0:,d}» ou «${0:5,.2f}». A parte field_name do modelo deve ser um 0 (zero) (o «{0:» nos exemplos acima). Consulte a documentação do modelo de linguagem e do Python para mais exemplos. Você pode deixar de fora o «{0:» inicial e o «}» final se o modelo contiver apenas um formato. Devolve a string vazia se a formatação falhar.
human_readable(v)¶
- class calibre.utils.formatter_functions.BuiltinHumanReadable[código fonte]¶
human_readable(v) – devolve o string que representa o número v em KB, MB, GB, etc.
rating_to_stars(value, use_half_stars)¶
- class calibre.utils.formatter_functions.BuiltinRatingToStars[código fonte]¶
rating_to_stars(value, use_half_stars) – Devolve a classificação como sequência de caracteres de estrelas. O valor é um número entre 0 e 5. Defina use_half_stars como 1 se desejar caracteres de meia estrela para colunas de classificações personalizadas que suportem classificações não inteiras, por exemplo 2.5.
urls_from_identifiers(identificadores, ordenar_resultados)¶
- class calibre.utils.formatter_functions.BuiltinUrlsFromIdentifiers[código fonte]¶
urls_from_identifiers(identificadores, ordenar_resultados) – dada uma lista separada por vírgulas de identificadores, onde um identificador é um par de valores separado por dois pontos (nome:valor_do_id), devolve uma lista separada por vírgulas com URL HTML, gerada a partir dos identificadores. A lista não será ordenada caso ordenar_resultados for 0 (caractere ou número). Caso contrário, será ordenada alfabeticamente pelo nome do identificador. Os URL são gerados da mesma forma que a coluna de identificadores predefinidos ao ser exibida no painel de detalhes do livro.
Get values from metadata¶
annotation_count ()¶
- class calibre.utils.formatter_functions.BuiltinAnnotationCount[código fonte]¶
annotation_count () - devolve o número total de anotações de todos os tipos anexados ao livro atual. Esta função funciona apenas na IGU.
approximate_formats()¶
- class calibre.utils.formatter_functions.BuiltinApproximateFormats[código fonte]¶
approximate_formats() – devolve uma lista de valores, separados por vírgulas, de formatos que numa determinada altura foram associados ao livro. Não há garantia de que esta lista esteja correta, embora provavelmente o esteja. Esta função pode ser chamada no Modo de programa por modelos usando o modelo «{:”approximate_formats()”}». Note que os nomes de formato são sempre maiúsculas, como em EPUB. Esta função só funciona na IGU. Se quiser usar estes valores nos modelos exportar-para-disco ou enviar-para-dispositivo, então deve criar uma coluna personalizada «Coluna obtida a partir de outras colunas». Use a função no modelo dessa coluna e use o valor dessa coluna nos seus modelos de exportar/enviar
booksize()¶
- class calibre.utils.formatter_functions.BuiltinBooksize[código fonte]¶
booksize() – devolve o valor do campo de tamanho. Esta função funciona apenas na IGU. Se quiser usar este valor nos modelos exportar-para-disco ou enviar-para-dispositivo, então deve fazer uma coluna personalizada «Coluna obtida a partir de outras colunas», use a função no modelo da coluna e use o valor dessa coluna nos seus modelos de exportar/enviar
connected_device_name(storage_location)¶
- class calibre.utils.formatter_functions.BuiltinConnectedDeviceName[código fonte]¶
connected_device_name(storage_location) – se um dispositivo estiver conectado, então devolve o nome do dispositivo; caso contrário, devolve uma cadeia de carateres vazia. Cada local de armazenamento num dispositivo pode ter um nome diferente. Os nomes dos locais são “main”, “carda” e “cardb”. Esta função funciona apenas na interface gráfica.
connected_device_uuid(storage_location)¶
- class calibre.utils.formatter_functions.BuiltinConnectedDeviceUUID[código fonte]¶
connected_device_uuid(storage_location) – se um dispositivo estiver conectado, então devolve o uuid (id único) do dispositivo; caso contrário, devolve uma cadeia de carateres vazia. Cada local de armazenamento num dispositivo tem um uuid diferente. Os nomes dos locais são “main”, “carda” e “cardb”. Esta função funciona apenas na interface gráfica.
current_library_name()¶
- class calibre.utils.formatter_functions.BuiltinCurrentLibraryName[código fonte]¶
current_library_name() – retorna o último nome do caminho para a biblioteca atual do Calibre. Esta função pode ser chamada no Modo de programa por modelos usando o modelo «{:”current_library_name()”}».
current_library_path()¶
- class calibre.utils.formatter_functions.BuiltinCurrentLibraryPath[código fonte]¶
current_library_path() – devolve o caminho para a biblioteca atual do Calibre. Esta função pode ser chamada no Modo de programa por modelos usando o modelo «{:”current_library_path()”}».
current_virtual_library_name()¶
- class calibre.utils.formatter_functions.BuiltinCurrentVirtualLibraryName[código fonte]¶
current_virtual_library_name() – devolve o nome da biblioteca virtual atual (se existir uma), ou então a string vazia. A maiusculização do nome da biblioteca são preservadas. Exemplo: «program: current_virtual_library_name()».
field(lookup_name)¶
- class calibre.utils.formatter_functions.BuiltinField[código fonte]¶
field(lookup_name) – devolve o campo de metadados nomeado pelo nome de pesquisa.
formats_modtimes(date_format)¶
- class calibre.utils.formatter_functions.BuiltinFormatsModtimes[código fonte]¶
formats_modtimes(date_format) – cria uma lista, separada por vírgulas, de itens separados por dois pontos que representam horas de alteração para os formatos de um livro. O parâmetro date_format especifica como a data deve ser formatada. Ver a função date_format para mais detalhes. Pode usar a função de seleção para obter a hora de alteração para um formato específico. Note que os nomes dos formatos são sempre em maiúsculas, tal como em EPUB.
formats_paths()¶
- class calibre.utils.formatter_functions.BuiltinFormatsPaths[código fonte]¶
formats_paths() – cria uma lista de itens, separados por dois pontos, que representam o caminho completo para os formatos de um livro. Pode usar a função de seleção para obter o caminho para um formato específico. Note que os nomes dos formatos são sempre em maiúsculas, tal como em EPUB.
formats_sizes()¶
- class calibre.utils.formatter_functions.BuiltinFormatsSizes[código fonte]¶
formats_sizes() – cria uma lista de itens separados por dois pontos que representam tamanhos em bytes dos formatos de um livro. Pode usar a função de seleção para obter o tamanho de um formato específico. Note que os nomes dos formatos são sempre em maiúsculas, tal como em EPUB.
has_cover()¶
- class calibre.utils.formatter_functions.BuiltinHasCover[código fonte]¶
has_cover() – devolve Sim se o livro tiver capa, caso contrário devolve um string vazio
is_marked()¶
- class calibre.utils.formatter_functions.BuiltinIsMarked[código fonte]¶
is_marked() – verifica se o livro está marcado (“marked”) no Calibre. Se estiver, então devolve o valor da marcação, que será “true” ou uma lista separada por vírgulas de nomes das marcações. Devolve “” se o livro não estiver marcado.
language_codes(lang_strings)¶
- class calibre.utils.formatter_functions.BuiltinLanguageCodes[código fonte]¶
language_codes(lang_strings) – mostra os códigos de idioma para as «strings» enviados a lang_strings. Estas strings tem de ser no mesmo idioma do idioma atual. Lang_strings é uma lista separada por vírgulas.
language_strings(lang_codes, localize)¶
- class calibre.utils.formatter_functions.BuiltinLanguageStrings[código fonte]¶
language_strings(lang_codes, localize) – retornar as strings para os códigos de idioma passados em lang_codes. Se localize é zero, retornar as strings em Inglês. Se localize não é zero, retornar as strings no idioma da localidade atual. Lang_codes é uma lista separada por vírgula.
ondevice()¶
- class calibre.utils.formatter_functions.BuiltinOndevice[código fonte]¶
ondevice() – devolve Yes se ondevice estiver definido, caso contrário devolve uma string vazia. Esta função aplica-se apenas à IGU. Se quiser usar este valor nos modelos exportar-para-disco ou enviar-para-dispositivo, então deve criar uma coluna personalizada «Coluna obtida a partir de outras colunas», usar a função no modelo dessa coluna, e usar o valor dessa coluna nos seus modelos de exportar/enviar
raw_field(lookup_name [, optional_default])¶
- class calibre.utils.formatter_functions.BuiltinRawField[código fonte]¶
raw_field(lookup_name [, optional_default]) – devolve a lista de metadados nomeada por nome de pesquisa mas sem aplicar qualquer formatação. Irá avaliar e devolver o segundo argumento opcional “default” se o campo estiver como indefinido (“None”)
raw_list(lookup_name, separator)¶
- class calibre.utils.formatter_functions.BuiltinRawList[código fonte]¶
raw_list(lookup_name, separator) – devolve a lista de metadados nomeada por nome de pesquisa mas sem aplicar qualquer formatação ou ordenação e com itens separados por separator.
series_sort()¶
- class calibre.utils.formatter_functions.BuiltinSeriesSort[código fonte]¶
series_sort() – devolve o valor de ordenação da série
user_categories()¶
- class calibre.utils.formatter_functions.BuiltinUserCategories[código fonte]¶
user_categories() – obter uma lista de categorias do utilizador que contenham este livro, separados por vírgulas. Esta função funciona apenas na GUI. Se quiser usar esses valores nos modelos exportar-para-disco ou enviar-para-dispositivo então deve criar uma «Coluna obtida a partir de outras colunas» personalizada: use a função no modelo da coluna e use o valor dessa coluna nos seus modelos de exportar/enviar
virtual_libraries()¶
- class calibre.utils.formatter_functions.BuiltinVirtualLibraries[código fonte]¶
virtual_libraries() – devolve uma lista de bibliotecas virtuais, separadas por vírgulas, que contenham este livro. Esta função aplica-se apenas à IGU. Se quiser usar estes valores nos modelos exportar-para-disco ou enviar-para-dispositivo então deve criar uma coluna personalizada «Coluna obtida a partir de outras colunas», usar a função no modelo dessa coluna, e usar o valor dessa coluna nos seus modelos de exportar/enviar
If-then-else¶
check_yes_no(nome_do_campo, é_indefinido, é_falso, é_verdadeiro)¶
- class calibre.utils.formatter_functions.BuiltinCheckYesNo[código fonte]¶
check_yes_no(nome_do_campo, é_indefinido, é_falso, é_verdadeiro) – verifica o valor do campo sim/não definido pela chave de pesquisa nome_do_campo de acordo com os valores especificados pelos parâmetros, devolvendo «sim» se uma correspondência for encontrada, ou devolvendo vazio caso contrário. Defina os parâmetros é_indefinido, é_falso, ou é_verdadeiro como 1 (o número) para verificar essa condição; caso contrário, defina como 0. Exemplo: check_yes_no(«#bool», 1, 0, 1) devolve «sim» se o campo sim/não «#bool» estiver não definido (nem Verdadeiro, nem Falso) ou Verdadeiro. Mais de um parâmetro (é_indefinido, é_falso ou é_verdadeiro) podem ser definidos como 1. Esta função geralmente é utilizada pelas funções test() ou is_empty().
contains(val, pattern, text if match, text if not match)¶
- class calibre.utils.formatter_functions.BuiltinContains[código fonte]¶
contains(val, pattern, text if match, text if not match) – verifica se o val contém correspondências para a expressão regular pattern. Devolve text if match se forem encontradas combinações, caso contrário devolve text if no match
field_exists(nome_campo)¶
- class calibre.utils.formatter_functions.BuiltinFieldExists[código fonte]¶
field_exists(nome_campo) – verifica se um campo (coluna) com o nome “nome_campo” existe, devolvendo “1” se sim e “” se não.
ifempty(val, texto se vazio)¶
- class calibre.utils.formatter_functions.BuiltinIfempty[código fonte]¶
ifempty(val, texto se vazio) – devolve val se val não estiver vazio, caso contrário devolve o texto definido para «texto se vazio»
test(val, texto se não vazio, texto se vazio)¶
- class calibre.utils.formatter_functions.BuiltinTest[código fonte]¶
test(val, texto se não vazio, texto se vazio) – devolve texto se não vazio se o val não estiver vazio, caso contrário devolve “texto se vazio”.
Iterating over values¶
first_non_empty(value, value, …)¶
- class calibre.utils.formatter_functions.BuiltinFirstNonEmpty[código fonte]¶
first_non_empty(value, value, …) – devolve o primeiro valor que não esteja vazio. Se todos os valores estiverem vazios, então é devolvida a string vazia. Pode ter quantos valores quiser.
lookup(val, [pattern, field,]+ else_field)¶
- class calibre.utils.formatter_functions.BuiltinLookup[código fonte]¶
lookup(val, [pattern, field,]+ else_field) – como comando adicional, exceto que os argumentos são nomes de campos (metadados) e não texto. O valor do campo apropriado será obtido e usado. Note que, como as colunas compostas são campos, pode usar esta função num campo composto para usar o valor de algum outro campo composto. Isto é extremamente útil quando construir variáveis de caminhos para onde guardar
switch(val, [pattern, value,]+ else_value)¶
- class calibre.utils.formatter_functions.BuiltinSwitch[código fonte]¶
switch(val, [pattern, value,]+ else_value) – para cada par pattern, value, verifica se val corresponde à expressão regular pattern e se assim for, devolve value. Se nenhum padrão for correspondido, então é devolvido else_value. Pode ter quantos pares pattern, value quiser
switch_if([expressao_teste, expressao_valor,]+ expressão_senao)¶
- class calibre.utils.formatter_functions.BuiltinSwitchIf[código fonte]¶
switch_if([expressao_teste, expressao_valor,]+ expressão_senao) – para cada par «expressao_teste, expressao_valor», verifica se a expressao_teste é Verdadeira (não-vazia) e, se sim, devolve o resultado da expressao_valor. Se nenhuma expressao_teste for Verdadeira, então é devolvido o resultado da expressao_senao. Você pode ter tantos pares «expressao_teste, expressao_valor» quantos queira.
List lookup¶
identifier_in_list(val, nome_id [, val_encontrado, val_nao_encontrado])¶
- class calibre.utils.formatter_functions.BuiltinIdentifierInList[código fonte]¶
identifier_in_list(val, nome_id [, val_encontrado, val_nao_encontrado]) – trata VAL como uma lista de identificadores separados por vírgulas. Um identificador tem o formato «nome_id: valor». O parâmetro nome_id é o texto a ser procurado, pode ser «nome_id» ou «nome_id:regexp». O primeiro caso irá fazer correspondência se houver um qualquer identificador correspondente a nome_id. O segundo caso irá fazer correspondência se nome_id corresponder a um identificador e a expressão regular (regexp) corresponder com o valor do identificador. Se forem indicados val_encontrado e val_nao_encontrado, então se houver correspondência será devolvido val_encontrado, de contrário irá devolver val_nao_encontrado. Se não forem indicados val_encontrado e val_nao_encontrado, então se houver uma correspondência, será devolvido o par identificador:valor, de contrário obterá uma string vazia.
in_list(val, separador, [ padrao, val_encontrado, ]+ val_nao_encontrado)¶
- class calibre.utils.formatter_functions.BuiltinInList[código fonte]¶
in_list(val, separador, [ padrao, val_encontrado, ]+ val_nao_encontrado) – tratando val como uma lista de itens separados por separador, caso o padrão corresponda a algum dos valores da lista, então devolve val_encontrado. Caso o padrão não corresponda a nenhum valor da lista, então devolve val_nao_encontrado. Os pares “padrao” e “val_encontrado” podem ser repetidos quantas vezes desejar. Os padrões são verificados por ordem. O val_encontrado para a primeira correspondência é devolvido. Variantes: in_list(), list_contains()
list_item(val, index, separator)¶
- class calibre.utils.formatter_functions.BuiltinListitem[código fonte]¶
list_item(val, index, separator) – interpreta o valor como uma lista de itens separados por separator, devolvendo o item index. O primeiro item é o número zero. O último item pode ser obtido usando list_item(-1,separator). Se o item não estiver na lista, então é devolvido o valor vazio. O separador tem o mesmo significado que na função de contagem.
select(key)¶
- class calibre.utils.formatter_functions.BuiltinSelect[código fonte]¶
select(key) – interpreta o campo como uma lista de itens separados por vírgulas, com os itens na forma «id:value». Encontra o emparelhamento do ID igual a KEY, e devolve o valor correspondente. Devolve um valor vazio se nenhuma correspondência for encontrada.
str_in_list(val, separador, [string, val_encontrado, ]+ val_nao_encontrado)¶
- class calibre.utils.formatter_functions.BuiltinStrInList[código fonte]¶
str_in_list(val, separador, [string, val_encontrado, ]+ val_nao_encontrado) – tratando “val” como uma lista de itens separados por “separador”, caso a string corresponda a algum dos valores da lista, então devolve val_encontrado. Caso a string não corresponda a nenhum dos valores da lista, então devolve val_nao_encontrado. A comparação é do tipo exata (não contém) e não diferencia maiúsculas/minúsculas. Os pares “string” and “val_encontrado” podem ser repetidos quantas vezes desejar. Os padrões são verificados por ordem. É devolvido o “val_encontrado” para a primeira correspondência.
List manipulation¶
count(val, separator)¶
- class calibre.utils.formatter_functions.BuiltinCount[código fonte]¶
count(val, separator) – interpreta o valor como uma lista de itens separados por separator, devolvendo o número de itens na lista. A maioria das listas usam uma vírgula como separador, mas em autores usa-se um E comercial. Exemplos: {tags:count(,)}, {authors:count(&)}. Nome curto: count(), list_count()
list_count_matching(lista, padrao, separador)¶
- class calibre.utils.formatter_functions.BuiltinListCountMatching[código fonte]¶
list_count_matching(lista, padrao, separador) – interpreta “lista” como uma lista de itens separados por “separador”, devolvendo o número de itens na lista que correspondam à expressão regular “padrao”. Variantes: list_count_matching(), count_matching()
list_difference(list1, list2, separator)¶
- class calibre.utils.formatter_functions.BuiltinListDifference[código fonte]¶
list_difference(list1, list2, separator) – devolve uma lista feita ao remover da list1 qualquer item encontrado em list2, usando uma comparação não sensível a maiúsculas. Os itens em list1 e list2 são separados por separador, tal como estão os itens da lista devolvida.
list_equals(list1, sep1, list2, sep2, yes_val, no_val)¶
- class calibre.utils.formatter_functions.BuiltinListEquals[código fonte]¶
list_equals(list1, sep1, list2, sep2, yes_val, no_val) – devolverá yes_val se list1 e list2 contiverem os mesmos itens, caso contrário devolverá no_val. Os itens são determinados dividindo cada lista usando o carácter separador apropriado (sep1 ou sep2). A ordem dos itens das listas não é relevante. A comparação não diferencia maiúsculas.
list_intersection(list1, list2, separator)¶
- class calibre.utils.formatter_functions.BuiltinListIntersection[código fonte]¶
list_intersection(list1, list2, separator) – devolve uma lista feita ao remover da list1 qualquer item não encontrado em list2, usando uma comparação não sensível a maiúsculas. Os itens em list1 e list2 são separados por separador, tal como estão os itens da lista devolvida.
list_join(com_separador, lista1, separador1 [, lista2, separador2]*)¶
- class calibre.utils.formatter_functions.BuiltinListJoin[código fonte]¶
list_join(com_separador, lista1, separador1 [, lista2, separador2]*) – frvolvr uma lista criada pela união dos itens das listas fonte (lista1, etc) usando o com_separador entre os itens na lista resultante. Itens em cada lista fonte [123…] são separados pelo separador associado [123…]. Uma lista pode conter zero valores. Ela pode ser um campo, como Editora, que tem valor único, efetivamente uma lista de item único. Serão removidas duplicações usando uma comparação que diferencia entre maiúsculas e minúsculas. Itens são devolvidos pela ordem em que aparecem nas listas fonte. Se os itens nas listas diferem apenas por maiúsculas/minúsculas, então é utilizado o último item. Todos os separadores podem ter mais de um carácter. Exemplo:
- program:
list_join(“#@#”, $authors, “&”, $tags, “,”)
- Pode usar list_join nos resultados de chamadas anteriores a list_join da seguinte forma:
program:
a = list_join(“#@#”, $authors, “&”, $tags, “,”); b = list_join(“#@#”, a, “#@#”, $#genre, “,”, $#people, “&”)
- Pode usar expressões para gerar uma lista. Por exemplo, imagine que você queira encontrar itens de autores e #genero. Com o género alterado para a palavra “Género: “ seguida da primeira letra do género, ou seja, o género “Ficção” torna-se “Género: F”. A expressão abaixo fará isto:
- program:
list_join(“#@#”, $authors, “&”, list_re($#genre, “,”, “^(.).*$”, “Genre: 1”), “,”)
list_re(src_list, separator, include_re, opt_replace)¶
- class calibre.utils.formatter_functions.BuiltinListRe[código fonte]¶
list_re(src_list, separator, include_re, opt_replace) – Construir uma lista, primeiro pela separação de src_list em itens usando o carácter separador. Para cada item da lista, verificar se ele corresponde a include_re. Se isso acontecer, então adicioná-lo à lista a ser obtida. Se opt_replace não é a string vazia, então aplicar a substituição antes de adicionar o item à lista obtida.
list_re_group(src_list, separador, include_re, search_re [, group_template]+)¶
- class calibre.utils.formatter_functions.BuiltinListReGroup[código fonte]¶
list_re_group(src_list, separador, include_re, search_re [, group_template]+) – Como list_re exceto que as substituições não são opcionais. Usa re_group(list_item, search_re, group_template, …) ao fazer as substituições na lista resultante.
list_remove_duplicates(lista, separador)¶
- class calibre.utils.formatter_functions.BuiltinListRemoveDuplicates[código fonte]¶
list_remove_duplicates(lista, separador) – devolve uma lista construída pela remoção de itens duplicados na lista fonte. Se os itens diferem apenas em minúsculas/maiúsculas, o último deles é devolvido. Os itens na lista fonte são separados pelo separador, assim como os itens na lista obtida.
list_sort(list, direction, separator)¶
- class calibre.utils.formatter_functions.BuiltinListSort[código fonte]¶
list_sort(list, direction, separator) – devolve uma lista ordenada usando uma ordenação que não diferencia maiúsculas. Se a direção é zero, a lista é ordenada de forma crescente, caso contrário será por ordem decrescente. Os itens da lista são separados por separador, tal como o são os itens na lista devolvida.
list_split(list_val, sep, id_prefix)¶
- class calibre.utils.formatter_functions.BuiltinListSplit[código fonte]¶
list_split(list_val, sep, id_prefix) – separa list_val em valores separados usando “sep”, e então atribui os valores a variáveis nomeadas “id_prefix_N”, onde N é a posição do valor na lista. O primeiro item tem uma posição 0 (zero). A função devolve o último elemento da lista. Exemplo: split(“um:dois:blah”, “:”, “var”) é o equivalente a var_0 = “um”; var_1 = “dois”; var_2 = “blah”.
list_union(list1, list2, separator)¶
- class calibre.utils.formatter_functions.BuiltinListUnion[código fonte]¶
list_union(list1, list2, separator) – devolve uma lista feita pela fusão dos itens da list1 e list2, removendo itens duplicados e sendo usada uma comparação não sensível a maiúsculas. Se os itens diferirem em maiúsculas é usado o primeiro da list1. Os itens em list1 e list2 são separados pelo separador, tal como estão os itens da lista devolvida. Nomes alternativos: list_union(), merge_lists()
range(início, fim, passo, limite)¶
- class calibre.utils.formatter_functions.BuiltinRange[código fonte]¶
range(início, fim, passo, limite) – devolve uma lista de números gerada ao percorrer o intervalo especificado pelos parâmetros “início”, “fim” e “passo”, com um comprimento máximo de “limite”. O primeiro valor produzido é “início”. Os valores subsequentes v_seguinte são v_atual+passo. O loop continua enquanto v_seguinte < “fim”, caso “passo” seja positivo, de contrário v_seguinte > “fim”. Uma lista vazia é produzida caso “início” falhe no teste: “início” >= “fim” caso o “passo” seja positivo. O “limite” define o comprimento máximo da lista e tem um valor predefinido de 1000. O parâmetro “início”, “passo” e “limite” são opcionais. Chamar range() com um argumento especifica o “fim”. Dois argumentos especificam “início” e “fim”. Três argumentos especificam “início”, “fim”, e “passo”. Quatro argumentos especificam “início”, “fim”, “passo” e “limite”. Exemplos: 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)-> erro(limite excedido).
subitems(val, start_index, end_index)¶
- class calibre.utils.formatter_functions.BuiltinSubitems[código fonte]¶
subitems(val, start_index, end_index) – Esta função é usada para quebrar as listas de itens, tais como géneros. Ela interpreta o valor como uma lista de itens, onde cada item é uma lista separada por período separados por vírgula. Retorna uma nova lista feita pela primeira encontrando todos os itens separados por pontos, em seguida, para cada um desses itens extrair os componentes start_index para end_index, em seguida, combinando os resultados de volta juntos. O primeiro componente numa lista separada por período tem um índice de zero. Se o índice é negativo, então conta do fim da lista. Conforme um caso especial, um end_index de zero é considerado como o comprimento da lista. Exemplo usando o modo de tema básico e assumindo um valor de #genre «A.B.C»: {#genre:subitems(0,1)} retorna «A». {#genre:subitems(0,2)} retorna «A.B». {#genre:subitems(1,0)} retorna «B.C». Assumindo um valor de #genre «A.B.C, D.E.F», {#genre:subitems(0,1)} retorna «A, D». {#genre:subitems(0,2)} retorna «A.B, D.E»
sublist(val, start_index, end_index, separator)¶
- class calibre.utils.formatter_functions.BuiltinSublist[código fonte]¶
sublist(val, start_index, end_index, separator) – interpretar o valor como uma lista de itens separados por separator, devolvendo uma nova lista criada a partir de start_index ao item end_index. O primeiro item é o número zero. Se o índice for negativo, então será contado a partir do fim da lista. Sendo um caso especial, um end_index de zero é considerado como o comprimento da lista. Exemplos, usando o modo de modelo básico, assumindo que a coluna de etiquetas (que é separada por vírgulas) contém «A, B, C»: {tags:sublist(0,1,\,)} devolve «A»; {tags:sublist(-1,0,\,)} devolve»C»; {tags:sublist(0,-1,\,)} retorna «A, B».
Other¶
arguments(id[=expressao] [, id[=expressao]]*)¶
- class calibre.utils.formatter_functions.BuiltinArguments[código fonte]¶
arguments(id[=expressao] [, id[=expressao]]*) – Usada, num modelo guardado, para recuperar os argumentos passados na chamada. Tanto declara como inicializa variáveis locais, efetivamente parâmetros. As variáveis são posicionais; recebem o valor do parâmetro dado na chamada na mesma posição. Se o parâmetro correspondente não for indicado na chamada, então a função arguments atribui àquela variável o valor predefinido indicado. Caso não haja valor predefinido, então a variável será definida como uma cadeia de carateres vazia.
assign(id, val)¶
- class calibre.utils.formatter_functions.BuiltinAssign[código fonte]¶
assign(id, val) – atribui VAL a ID, e depois devolve VAL. O ID deve ser um identificador e não uma expressão. Esta função pode, muitas vezes, ser substituída pelo operador =
globals(id[=expressão] [, id[=expressão]]*)¶
- class calibre.utils.formatter_functions.BuiltinGlobals[código fonte]¶
globals(id[=expressão] [, id[=expressão]]*) – Recupera «variáveis globais» que podem ser passadas para o formatador. Tanto declara como inicializa variáveis locais com os nomes das variáveis globais passadas. Se a variável correspondente não for fornecida nas variáveis globais passadas, então atribui à variável o valor predefinido fornecido. Caso não haja valor predefinido, então a variável será definida como uma cadeia de carateres vazia.
print(a[, b]*)¶
- class calibre.utils.formatter_functions.BuiltinPrint[código fonte]¶
print(a[, b]*) – imprime os argumentos para a saída predefinida. A menos que inicie o Calibre a partir da linha de comandos (calibre-debug -g), a saída irá para um buraco negro.
Recursion¶
eval(template)¶
- class calibre.utils.formatter_functions.BuiltinEval[código fonte]¶
eval(template) – avalia o tema, passando as variáveis locais (those “assign’ed to) em vez dos metadados do livro. Isto permite usar o processador de tema para a construção de resultados complexos de variáveis locais. Como os caracteres { and } são especiais, deve usar o carácter [[ for the { character and ]] for the }; então eles serão convertidos automaticamente. Note também que prefixos e sufixos (the |prefix|suffix syntax) não podem ser usados no argumento para esta função ao usar o Modo de programa por modelos.
template(x)¶
- class calibre.utils.formatter_functions.BuiltinTemplate[código fonte]¶
template(x) – analisa x como um modelo. A analise é feita em seu próprio contexto, o que significa que as variáveis não são compartilhadas entre a chamador e a análise do modelo. Como os caracteres { and } são especiais, deve usar o carácter [[ for the { character and ]] for the }. Eles serão convertidos automaticamente. Por exemplo, template(“[[title_sort]]”) irá analisar o tema {title_sort} e devolver o seu valor. Note também que prefixos e sufixos (the |prefix|suffix syntax) não podem ser usados no argumento para esta função ao usar o Modo de programa por modelos.
Relational¶
cmp(x, y, lt, eq, gt)¶
- class calibre.utils.formatter_functions.BuiltinCmp[código fonte]¶
cmp(x, y, lt, eq, gt) – compara x com y depois de os converter para números. Devolve lt se x < y. Devolve eq se x == y. Caso contrário devolve gt. Em muitos casos os operadores de comparação lexical (>#, <#, ==# etc) podem substituir esta função.
first_matching_cmp(val, cmp1, result1,]+, else_result)¶
- class calibre.utils.formatter_functions.BuiltinFirstMatchingCmp[código fonte]¶
first_matching_cmp(val, cmp1, result1,]+, else_result) – compara «val < cmpN» em sequência, devolvendo resultN para a primeira comparação com sucesso. Devolve else_result se não houver comparações com sucesso. Exemplo: first_matching_cmp(10,5,»small»,10,»middle»,15,»large»,»giant») devolve «large». O mesmo exemplo em que o primeiro valor seja 16 devolve «giant».
strcmp(x, y, lt, eq, gt)¶
- class calibre.utils.formatter_functions.BuiltinStrcmp[código fonte]¶
strcmp(x, y, lt, eq, gt) – faz uma comparação intensiva não diferenciadora de maiúsculas de x e y como strings. Devolve lt se x < y. Devolve eq se x == y. Caso contrário devolve gt. Em muitos casos os operadores de comparação lexical (>, <, == etc) podem substituir esta função.
strcmpcase(x, y, lt, eq, gt)¶
- class calibre.utils.formatter_functions.BuiltinStrcmpcase[código fonte]¶
strcmpcase(x, y, lt, eq, gt) – faz uma comparação entre x e y como sequências de caracteres, com diferenciação entre maiúsculas e minúsculas. Devolve lt se x < y. Devolve eq se x == y. De contrário devolve gt. Nota: Este NÃO é o comportamento predefinido usado pelo Calibre, por exemplo, nos operadores de comparação léxica (==, >, <, etc.). Esta função pode causar resultados inesperados. Utilize strcmp() sempre que possível.
String case changes¶
capitalize(val)¶
- class calibre.utils.formatter_functions.BuiltinCapitalize[código fonte]¶
capitalize(val) – devolve o val maiusculizado
lowercase(val)¶
- class calibre.utils.formatter_functions.BuiltinLowercase[código fonte]¶
lowercase(val) – devolve o val em minúsculas
titlecase(val)¶
- class calibre.utils.formatter_functions.BuiltinTitlecase[código fonte]¶
titlecase(val) – devolve o val em maiusculização de título
uppercase(val)¶
- class calibre.utils.formatter_functions.BuiltinUppercase[código fonte]¶
uppercase(val) – devolve o val em maiúsculas
String manipulation¶
character(character_name)¶
- class calibre.utils.formatter_functions.BuiltinCharacter[código fonte]¶
character(character_name) – devolve o carácter nomeado por character_name. Por exemplo, character(“newline”) devolve o carácter de nova linha (”n”). Os nomes de caracteres suportados são “newline”, “return”, “tab”, e “backslash”.
re(val, pattern, replacement)¶
- class calibre.utils.formatter_functions.BuiltinRe[código fonte]¶
re(val, pattern, replacement) – devolve o val depois de aplicar a expressão regular. Todas as instâncias de pattern são substituídas por replacement. Como em tudo no Calibre, estas são expressões regulares compatíveis com Python
re_group(val, pattern [, template_for_group]*)¶
- class calibre.utils.formatter_functions.BuiltinReGroup[código fonte]¶
re_group(val, pattern [, template_for_group]*) – devolve uma string criada aplicando o padrão de expressão regular a val e substituindo cada instância correspondente com a string calculada ao substituir cada grupo correspondente pelo valor devolvido pelo modelo correspondente. O valor correspondente original para o grupo está disponível como $. No modo de programa por modelo, como para o tema e funções eval, você usa [[ for { and ]] for }. O exemplo seguinte, no modo de programação por modelo procura por séries com mais de uma palavra e a primeira palavra em maiúsculas: {series:”re_group($, «(S* )(.*)», «[[$:uppercase()]]», «[[$]]»)”}
shorten(val, left chars, middle text, right chars)¶
- class calibre.utils.formatter_functions.BuiltinShorten[código fonte]¶
shorten(val, left chars, middle text, right chars) – Devolve uma versão abreviada de val, que consiste em caracteres left chars do início de val, seguido por middle text, seguido pelos caracteres right chars do fim da string. Left chars e right chars devem ser inteiros. Por exemplo, suponha que o título do livro é Antigas leis inglesas nos tempos de Ivanhoe, e quer que ele se ajuste a uma dimensão de, no máximo, 15 caracteres. Se usar {title:shorten(9,-,5)}, o resultado será Antigas I-anhoe. Se o comprimento do campo for menor que os caracteres à esquerda + caracteres à direita + comprimento de middle text, então o campo será usado intacto. Por exemplo, o título A Cúpula não pode ser alterado.
strcat(a [, b]*)¶
- class calibre.utils.formatter_functions.BuiltinStrcat[código fonte]¶
strcat(a [, b]*) – pode receber qualquer número de argumentos. Devolve uma expressão formada pela concatenação de todos os argumentos.
strcat_max(max, string1 [, prefix2, string2]*)¶
- class calibre.utils.formatter_functions.BuiltinStrcatMax[código fonte]¶
strcat_max(max, string1 [, prefix2, string2]*) – Devolve uma expressão formada pela concatenação dos argumentos. O valor devolvido é inicializado para string1. Pares Prefix, string são adicionados ao final do valor desde que o comprimento da expressão resultante seja inferior a max. String1 será devolvida mesmo se string1 for maior que max. Pode passar quantos pares prefix, string quiser.
strlen(a)¶
- class calibre.utils.formatter_functions.BuiltinStrlen[código fonte]¶
strlen(a) – Devolve o comprimento do texto passando-o como um argumento.
substr(str, start, end)¶
- class calibre.utils.formatter_functions.BuiltinSubstr[código fonte]¶
substr(str, start, end) – retorna start’th pelos caracteres end’th de str. O primeiro carácter str é o carácter zero’th. Se end é negativo, então isso indica que muitos caracteres são contados à direita. Se end é zero, então isso indica o último carácter . Por exemplo, substr(“12345”, 1, 0) retorna “2345”, e substr(“12345”, 1, -1) retorna “234”.
swap_around_articles(val, separator)¶
- class calibre.utils.formatter_functions.BuiltinSwapAroundArticles[código fonte]¶
swap_around_articles(val, separator) – devolve o valor dos artigos movidos para o final. O valor pode ser uma lista, caso em que cada membro da lista será processado. Se o valor for uma lista, então você deve indicar o separador da lista de valores. Se não for indicado um separador, então o valor será tratado como sendo um valor único e não uma lista.
swap_around_comma(val)¶
- class calibre.utils.formatter_functions.BuiltinSwapAroundComma[código fonte]¶
swap_around_comma(val) – determinar um valor de forma «B, A», retorna «A B». Isto é muito útil para a conversão de nomes em formatos LN, FN para FN LN. Se não houver nenhuma vírgula, a função val retorna sem alteração
to_hex(val)¶
- class calibre.utils.formatter_functions.BuiltinToHex[código fonte]¶
to_hex(val) – devolve a string codificada em hex. Isto é útil ao construir os URL do Calibre.
transliterate(a)¶
- class calibre.utils.formatter_functions.BuiltinTransliterate[código fonte]¶
transliterate(a) – Retorna uma string no alfabeto latino formado pelo som aproximado das palavras na sequência de origem. Por exemplo, se a origem for «Фёдор Миха́йлович Достоевский» a função retorna «Fiodor Mikhailovich Dostoievskii».
Template database functions¶
book_count(termo_pesquisa, usar_bv)¶
- class calibre.utils.formatter_functions.BuiltinBookCount[código fonte]¶
book_count(termo_pesquisa, usar_bv) – devolve a contagem de livros encontrados ao pesquisar por termo_pesquisa. Caso usar_bv seja 0 (zero), então as bibliotecas virtuais são ignoradas. Esta função pode ser usada apenas na Interface gráfica.
book_values(coluna, termo_pesquisa, sep, usar_bv)¶
- class calibre.utils.formatter_functions.BuiltinBookValues[código fonte]¶
book_values(coluna, termo_pesquisa, sep, usar_bv) – devolve uma lista de valores contidos na coluna «coluna», separados por «sep», nos livros encontrados ao pesquisar por «termo_pesquisa». Caso usar_bv seja 0 (zero), então as bibliotecas virtuais serão ignoradas. Esta função pode ser usada apenas na Interface gráfica.
extra_file_modtime(nome_ficheiro, formato_string)¶
- class calibre.utils.formatter_functions.BuiltinExtraFileModtime[código fonte]¶
extra_file_modtime(nome_ficheiro, formato_string) – devolve a data de alteração do ficheiro extra “nome_ficheiro” na pasta “data/” do livro, caso exista; de contrário devolve -1.0. A data de alteração é formatada de acordo com “format_string” (veja format_date()). Se “format_string” estiver vazio, devolve a data de alteração como o número de ponto flutuante dos segundos desde a “epoch”. A “epoch” depende do sistema operativo. Esta função só pode ser usada na IGU (Interface gráfica).
extra_file_names(sep [, pattern])¶
- class calibre.utils.formatter_functions.BuiltinExtraFileNames[código fonte]¶
extra_file_names(sep [, pattern]) – devolve uma lista de ficheiros extras separados por “sep” na pasta “data/” do livro. Se for fornecido o parâmetro opcional “pattern”, uma expressão regular, então a lista é filtrada pelos ficheiros que correspondam a esse padrão. A correspondência ao padrão não diferencia maiúsculas. Esta função apenas pode ser usada na IGU (Interface gráfica).
extra_file_size(nome_arquivo)¶
- class calibre.utils.formatter_functions.BuiltinExtraFileSize[código fonte]¶
extra_file_size(nome_arquivo) – devolve o tamanho em bytes do ficheiro extra “nome_ficheiro” na pasta “data/” do livro caso exista; de contrário devolve -1. Esta função só pode ser usada na IGU (Interface gráfica).
get_link(field_name, field_value)¶
- class calibre.utils.formatter_functions.BuiltinGetLink[código fonte]¶
get_link(field_name, field_value) – obtém a ligação para o campo “field_name” com o valor “field_value”. Se não existir nenhuma ligação anexada, devolve “”. Exemplo: get_link(“tags”, “Fiction”) devolve uma ligação anexada para a etiqueta “Fiction”.
get_note(field_name, field_value, plain_text)¶
- class calibre.utils.formatter_functions.BuiltinGetNote[código fonte]¶
get_note(field_name, field_value, plain_text) – obtém a nota do campo “field_name” com o valor “field_value”. Se “plain_text” for vazio, devolve o TML da nota. Se “plain_text” não for vazio, devolve a nota em texto sem formatação. Se a nota não existe, devolve “” em ambos os casos. Exemplo: get_note(“tags”, “Fiction”, “”) devolve o HTML da nova anexada à etiqueta “Fiction”.
has_extra_files([padrao])¶
- class calibre.utils.formatter_functions.BuiltinHasExtraFiles[código fonte]¶
has_extra_files([padrao]) – devolve a contagem de ficheiros extras, de contrário “” (a sequência vazia). Se for fornecido o parâmetro opcional “padrao” (uma expressão regular), então a lista é filtrada pelos ficheiros que correspondam a esse padrão antes de os ficheiros serem contados. A correspondência ao padrão não diferencia maiúsculas. Esta função apenas pode ser usada na Interface gráfica.
has_note(field_name, field_value)¶
- class calibre.utils.formatter_functions.BuiltinHasNote[código fonte]¶
has_note(field_name, field_value) – devolve “1” se o valor “field_value” no campo “field_name” tiver uma nota anexada, de contrário devolve “” . Exemplo: has_note(“tags”, “Fiction”) devolve “1” se a etiqueta “fiction” tiver uma nota anexada, de contrário devolve “” .
other¶
set_globals(id[=expressão] [, id[=expressão]]*)¶
- class calibre.utils.formatter_functions.BuiltinSetGlobals[código fonte]¶
set_globals(id[=expressão] [, id[=expressão]]*) – Define «variáveis globais» que podem ser passadas para o formatador. As variáveis globais recebem o nome do ID passado. É usado o valor do ID a não ser que seja fornecida uma expressão.
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=('Desconhecido',), other=None, template_cache=None, formatter=None)[código fonte]¶
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)[código fonte]¶
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>>)[código fonte]¶
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()[código fonte]¶
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)[código fonte]¶
Set all identifiers. Note that if you previously set ISBN, calling this method will delete it.
- set_identifier(typ, val)[código fonte]¶
If val is empty, deletes identifier of type typ
- standard_field_keys()[código fonte]¶
return a list of all possible keys, even if this book doesn’t have them
- custom_field_keys()[código fonte]¶
return a list of the custom fields in this book
- all_field_keys()[código fonte]¶
All field keys known by this instance, even if their value is None
- metadata_for_field(key)[código fonte]¶
return metadata describing a standard or custom field.
- all_non_none_fields()[código fonte]¶
Return a dictionary containing all non-None metadata fields, including the custom ones.
- get_standard_metadata(field, make_copy)[código fonte]¶
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)[código fonte]¶
return a dict containing all the standard field metadata associated with the book.
- get_all_user_metadata(make_copy)[código fonte]¶
return a dict containing all the custom field metadata associated with the book.
- get_user_metadata(field, make_copy)[código fonte]¶
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)[código fonte]¶
store custom field metadata into the object. Field is the key name not the label
- set_user_metadata(field, metadata)[código fonte]¶
store custom field metadata for one column into the object. Field is the key name not the label
- remove_stale_user_metadata(other_mi)[código fonte]¶
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)[código fonte]¶
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)[código fonte]¶
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)[código fonte]¶
Returns the tuple (display_name, formatted_value)
- to_html()[código fonte]¶
A HTML representation of this object.
- calibre.ebooks.metadata.book.base.STANDARD_METADATA_FIELDS¶
The set of standard metadata fields.
'''
All fields must have a NULL value represented as None for simple types,
an empty list/dictionary for complex types and (None, None) for cover_data
'''
SOCIAL_METADATA_FIELDS = frozenset((
'tags', # Ordered list
'rating', # A floating point number between 0 and 10
'comments', # A simple HTML enabled string
'series', # A simple string
'series_index', # A floating point number
# Of the form { scheme1:value1, scheme2:value2}
# For example: {'isbn':'123456789', 'doi':'xxxx', ... }
'identifiers',
))
'''
The list of names that convert to identifiers when in get and set.
'''
TOP_LEVEL_IDENTIFIERS = frozenset((
'isbn',
))
PUBLICATION_METADATA_FIELDS = frozenset((
'title', # title must never be None. Should be _('Unknown')
# Pseudo field that can be set, but if not set is auto generated
# from title and languages
'title_sort',
'authors', # Ordered list. Must never be None, can be [_('Unknown')]
'author_sort_map', # Map of sort strings for each author
# Pseudo field that can be set, but if not set is auto generated
# from authors and languages
'author_sort',
'book_producer',
'timestamp', # Dates and times must be timezone aware
'pubdate',
'last_modified',
'rights',
# So far only known publication type is periodical:calibre
# If None, means book
'publication_type',
'uuid', # A UUID usually of type 4
'languages', # ordered list of languages in this publication
'publisher', # Simple string, no special semantics
# Absolute path to image file encoded in filesystem_encoding
'cover',
# Of the form (format, data) where format is, e.g. 'jpeg', 'png', 'gif'...
'cover_data',
# Either thumbnail data, or an object with the attribute
# image_path which is the path to an image file, encoded
# in filesystem_encoding
'thumbnail',
))
BOOK_STRUCTURE_FIELDS = frozenset((
# These are used by code, Null values are None.
'toc', 'spine', 'guide', 'manifest',
))
USER_METADATA_FIELDS = frozenset((
# A dict of dicts similar to field_metadata. Each field description dict
# also contains a value field with the key #value#.
'user_metadata',
))
DEVICE_METADATA_FIELDS = frozenset((
'device_collections', # Ordered list of strings
'lpath', # Unicode, / separated
'size', # In bytes
'mime', # Mimetype of the book file being represented
))
CALIBRE_METADATA_FIELDS = frozenset((
'application_id', # An application id, currently set to the db_id.
'db_id', # the calibre primary key of the item.
'formats', # list of formats (extensions) for this book
# a dict of user category names, where the value is a list of item names
# from the book that are in that category
'user_categories',
# a dict of items to associated hyperlink
'link_maps',
))
ALL_METADATA_FIELDS = SOCIAL_METADATA_FIELDS.union(
PUBLICATION_METADATA_FIELDS).union(
BOOK_STRUCTURE_FIELDS).union(
USER_METADATA_FIELDS).union(
DEVICE_METADATA_FIELDS).union(
CALIBRE_METADATA_FIELDS)
# All fields except custom fields
STANDARD_METADATA_FIELDS = SOCIAL_METADATA_FIELDS.union(
PUBLICATION_METADATA_FIELDS).union(
BOOK_STRUCTURE_FIELDS).union(
DEVICE_METADATA_FIELDS).union(
CALIBRE_METADATA_FIELDS)
# Metadata fields that smart update must do special processing to copy.
SC_FIELDS_NOT_COPIED = frozenset(('title', 'title_sort', 'authors',
'author_sort', 'author_sort_map',
'cover_data', 'tags', 'languages',
'identifiers'))
# Metadata fields that smart update should copy only if the source is not None
SC_FIELDS_COPY_NOT_NULL = frozenset(('device_collections', 'lpath', 'size', 'comments', 'thumbnail'))
# Metadata fields that smart update should copy without special handling
SC_COPYABLE_FIELDS = SOCIAL_METADATA_FIELDS.union(
PUBLICATION_METADATA_FIELDS).union(
BOOK_STRUCTURE_FIELDS).union(
DEVICE_METADATA_FIELDS).union(
CALIBRE_METADATA_FIELDS) - \
SC_FIELDS_NOT_COPIED.union(
SC_FIELDS_COPY_NOT_NULL)
SERIALIZABLE_FIELDS = SOCIAL_METADATA_FIELDS.union(
USER_METADATA_FIELDS).union(
PUBLICATION_METADATA_FIELDS).union(
CALIBRE_METADATA_FIELDS).union(
DEVICE_METADATA_FIELDS) - \
frozenset(('device_collections', 'formats',
'cover_data'))
# these are rebuilt when needed