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.

Арифметический ¶

add ¶

class calibre.utils.formatter_functions.BuiltinAdd[исходный код]¶

add(x [, y]*) – возвращает сумму своих аргументов. Выдает исключение, если аргумент не является числом. В большинстве случаев вместо этой функции можно использовать оператор +.

ceiling ¶

class calibre.utils.formatter_functions.BuiltinCeiling[исходный код]¶

ceiling(value) – возвращает наименьшее целое число, большее или равное value. Выдаёт исключение, если value не является числом.

divide ¶

class calibre.utils.formatter_functions.BuiltinDivide[исходный код]¶

divide(x, y) – возвращает x / y. Выдает исключение, если x или y не являются числами. Эту функцию часто можно заменить оператором /.

floor ¶

class calibre.utils.formatter_functions.BuiltinFloor[исходный код]¶

floor(value) – возвращает наибольшее целое число, меньшее или равное value. Выдаёт исключение, если value не является числом.

fractional_part ¶

class calibre.utils.formatter_functions.BuiltinFractionalPart[исходный код]¶

fractional_part(value) – returns the part of the value after the decimal point. For example, fractional_part(3.14) returns 0.14. Throws an exception if value is not a number.

Отображение документации на английском языке из-за ошибки FFML: Missing closing «``» for CODE_TEXT on line 1 in «fractional_part»

mod ¶

class calibre.utils.formatter_functions.BuiltinMod[исходный код]¶

mod(value, y) – возвращает floor остаток от value / y. Выдаёт исключение, если value или y не является числом.

multiply ¶

class calibre.utils.formatter_functions.BuiltinMultiply[исходный код]¶

multiply(x [, y]*) – возвращает произведение своих аргументов. Выдает исключение, если какой-либо аргумент не является числом. Эту функцию часто можно заменить оператором *.

round ¶

class calibre.utils.formatter_functions.BuiltinRound[исходный код]¶

round(value) – возвращает ближайшее к value целое число. Выдаёт исключение, если value не является числом.

subtract ¶

class calibre.utils.formatter_functions.BuiltinSubtract[исходный код]¶

subtract(x, y) – возвращает x - y. Выдает исключение, если x или y не являются числами. Эту функцию часто можно заменить оператором -.

Булево ¶

and ¶

class calibre.utils.formatter_functions.BuiltinAnd[исходный код]¶

and(value [, value]*) – возвращает строку «1», если все значения не пустые, в противном случае возвращает пустую строку. Значения - сколько захотите. Обычно можно заменить на оператор &&. Одна из причин не заменять and на && заключается в том, что короткое замыкание может изменить результаты из-за побочных эффектов. Например, and(a='',b=5) всегда будет выполнять оба присваивания, а оператор && не будет выполнять второе.

not ¶

class calibre.utils.formatter_functions.BuiltinNot[исходный код]¶

not(value) – возвращает строку 1, если значение пустое, иначе возвращает пустую строку. Эту функцию обычно можно заменить унарным оператором not (!).

or ¶

class calibre.utils.formatter_functions.BuiltinOr[исходный код]¶

or(value [, value]*) – возвращает строку «1», если все значения не пустые, в противном случае возвращает пустую строку. Значения - сколько захотите. Во многих случаях оператор || может заменить эту функцию. Причина, по которой нельзя заменить - короткое замыкание изменит результаты из-за побочных эффектов.

Другое ¶

arguments ¶

class calibre.utils.formatter_functions.BuiltinArguments[исходный код]¶

arguments(id[=expression] [, id [=expression]]*) – используется в сохранённом шаблоне для извлечения аргументов, переданных в вызове. Как объявляет так и инициализирует локальные переменные, фактически параметры. Переменные позиционные; они получают значение, указанное в вызове, в той же позиции. Если соответствующий параметр не указан в вызове, то аргументы присваивают этой переменной заданное значение по умолчанию. Если значение по умолчанию отсутствует, переменная устанавливается в пустую строку.

assign ¶

class calibre.utils.formatter_functions.BuiltinAssign[исходный код]¶

assign(id, value) – assigns value to id, then returns value. id must be an identifier, not an expression. In most cases you can use the = operator instead of this function.

Отображение документации на английском языке из-за ошибки FFML: Missing closing «``» for CODE_TEXT on line 1 in «assign»

globals ¶

class calibre.utils.formatter_functions.BuiltinGlobals[исходный код]¶

globals(id[=expression] [, id[=expression]]*) – Retrieves «global variables» that can be passed into the formatter. The name id is the name of the global variable. It both declares and initializes local variables with the names of the global variables passed in the id parameters. If the corresponding variable is not provided in the globals then it assigns that variable the provided default value. If there is no default value then the variable is set to the empty string.

is_dark_mode ¶

class calibre.utils.formatter_functions.BuiltinIsDarkMode[исходный код]¶

is_dark_mode() – вернуть '1' если calibre запущен в тёмном режиме, иначе '' (пустая строка). Эту функцию можно использовать в расширенных настройках цвета и правилах выбора значков для выбора различных цветов / значков в зависимости от режима. Пример:

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

print ¶

class calibre.utils.formatter_functions.BuiltinPrint[исходный код]¶

print(a [, b]*) – выводит аргументы на стандартный вывод. Пока вы не запустите calibre из командной строки (calibre-debug -g), вывод идёт в чёрную дыру (black hole). Функция print всегда возвращает свой первый аргумент.

set_globals ¶

class calibre.utils.formatter_functions.BuiltinSetGlobals[исходный код]¶

set_globals(id[=expression] [, id[=expression]]*) – Sets globalvariables that can be passed into the formatter. The globals are given the name of the id passed in. The value of the id is used unless an expression is provided.

Отображение документации на английском языке из-за ошибки FFML: Missing closing «``» for CODE_TEXT on line 1 in «set_globals»

Манипулирование строками ¶

character ¶

class calibre.utils.formatter_functions.BuiltinCharacter[исходный код]¶

character(character_name) - возвращает символ, названный character_name. Например, character('newline) возвращает символ новой строки ('\n'). Поддерживаемые имена символов: newline, return, tab, и backslash. Эта функция используется для ввода этих символов в выходные данные шаблонов.

check_yes_no ¶

class calibre.utils.formatter_functions.BuiltinCheckYesNo[исходный код]¶

check_yes_no(field_name, is_undefined, is_false, is_true) – проверяет значение поля yes/no, названного ключом поиска field_name, на значение, указанное в параметрах, возвращая 'Yes', если совпадение найдено, иначе возвращает пустую строку. Установите параметр is_undefined, is_false или is_true в 1 (число), чтобы проверить это условие, иначе установите его равным 0 (ноль).

Пример: check_yes_no("# bool", 1, 0, 1) возвращает 'Yes', если yes/no поле #bool не определено (ни True, ни False), или True.

Более одного из is_undefined, is_false или is_true может быть установлено в 1.

contains ¶

class calibre.utils.formatter_functions.BuiltinContains[исходный код]¶

contains(value, pattern, text_if_match, text_if_not_match) – checks if the value is matched by the regular expression pattern. Returns text_if_match if the pattern matches the value, otherwise returns text_if_not_match.

field_exists ¶

class calibre.utils.formatter_functions.BuiltinFieldExists[исходный код]¶

field_exists(field_name) – проверяет, существует ли поле (столбец) с именем field_name, возвращая '1', если это так, и пустую строку, если нет.

ifempty ¶

class calibre.utils.formatter_functions.BuiltinIfempty[исходный код]¶

ifempty(value, text_if_empty) – если value не пустое, то вернуть это value, иначе вернуть text_if_empty.

re ¶

class calibre.utils.formatter_functions.BuiltinRe[исходный код]¶

re(value, pattern, replacement) – вернуть значение value после применения регулярного выражения. Все вхождения pattern в значении value заменяются на replacement. Язык шаблонов не регистрозависим Python regular expressions.

re_group ¶

class calibre.utils.formatter_functions.BuiltinReGroup[исходный код]¶

re_group(value, pattern [, template_for_group]*) – return a string made by applying the regular expression pattern to value and replacing each matched instance with the value returned by the corresponding template. In Template Program Mode, like for the template and the eval functions, you use [[ for { and ]] for }.

The following example looks for a series with more than one word and uppercases the first word:

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

Отображение документации на английском языке из-за ошибки FFML: Missing closing [/URL] near text программн on line 2 in «re_group»

shorten ¶

class calibre.utils.formatter_functions.BuiltinShorten[исходный код]¶

shorten(value, left chars, middle text, right chars) – Возвращает сокращённую версию значения``value``, состоящую из символов left chars с начала значения, за которыми следует middle text, за которыми следуют символы right chars с конца значения. left chars и right chars должны быть неотрицательными целыми числами.

Пример: предположим, что вы хотите отобразить заголовок длиной не более 15 символов. Один из шаблонов, который делает это, - {title:short(9,-,5)}. Для книги с названием «Ancient English Laws in the Times of Ivanhoe» результатом будет Ancient E-nhoe: первые 9 символов названия, -, затем последние 5 символов. Если длина значения меньше, чем left chars + right chars + длина middle text, то значение будет возвращено без изменений. Например, название The Dome не изменится.

strcat ¶

class calibre.utils.formatter_functions.BuiltinStrcat[исходный код]¶

strcat(a [, b]*) – возвращает строку объединяющую все аргументы. Может принимать любое количество аргументов. В большинстве случаев эту функцию может заменить оператор & .

strcat_max ¶

class calibre.utils.formatter_functions.BuiltinStrcatMax[исходный код]¶

strcat_max(max, string1 [, prefix2, string2]*) – Возвращает строку, образованную объединением аргументов. Возвращаемое значение инициализируется string1. Пары prefix, string добавляются в конец значения, если результирующая длина строки меньше, чем max. string1 возвращается, даже если string1 длиннее max. Вы можете передать сколько угодно пар prefix, string.

strlen ¶

class calibre.utils.formatter_functions.BuiltinStrlen[исходный код]¶

strlen(value) – Возвращает длину строки value.

substr ¶

class calibre.utils.formatter_functions.BuiltinSubstr[исходный код]¶

substr(value, start, end) – returns the start’th through the end’th characters of value. The first character in value is the zero’th character. If end is negative then it indicates that many characters counting from the right. If end is zero, then it indicates the last character. For example, substr('12345', 1, 0) returns '2345', and substr('12345', 1, -1) returns '234'.

swap_around_articles ¶

class calibre.utils.formatter_functions.BuiltinSwapAroundArticles[исходный код]¶

swap_around_articles(value, separator) – returns the value with articles moved to the end, separated by a semicolon. The value can be a list, in which case each item in the list is processed. If the value is a list then you must provide the separator. If no separator is provided or the separator is the empty string then the value is treated as being a single value, not a list. The articles are those used by calibre to generate the title_sort.

Отображение документации на английском языке из-за ошибки FFML: Missing closing «``» for CODE_TEXT on line 1 in «swap_around_articles»

swap_around_comma ¶

class calibre.utils.formatter_functions.BuiltinSwapAroundComma[исходный код]¶

swap_around_comma(value) – если значение value имеет вид B, A, возвращает A B. Это наиболее полезно для преобразования имён вида LN, FN (Ф, И О) к виду FN LN (И О Ф). Если значение не содержит запятой в value, то оно возвращается без изменений.

test ¶

class calibre.utils.formatter_functions.BuiltinTest[исходный код]¶

test(value, text_if_not_empty, text_if_empty) – возвращает text_if_not_empty если значение не пусто, иначе возвращает text_if_empty.

transliterate ¶

class calibre.utils.formatter_functions.BuiltinTransliterate[исходный код]¶

transliterate(value) – возвращает строку в латинском алфавите, которая по звучанию похожа на слова исходной строки. Например, если value было Фёдор Миха́йлович Достоевский, то функция вернёт Fiodor Mikhailovich Dostoievskii.

Манипуляция списком ¶

list_count ¶

class calibre.utils.formatter_functions.BuiltinCount[исходный код]¶

list_count(value, separator) – интерпретирует значение как список элементов, разделенных символом separator и возвращает количество элементов в списке. В большинстве списков используется запятая в качестве разделителя, но authors используют амперсанд (&).

Примеры: {tags:list_count(,)}, {authors:list_count(&)}.

Псевдонимы: count(), list_count()

list_count_field ¶

class calibre.utils.formatter_functions.BuiltinFieldListCount[исходный код]¶

list_count_field(lookup_name)– вернуть количество элементов в поле с именем для поиска lookup_name. Поле должно быть многозначным, например authors или tags, в противном случае функция выдаст ошибку. Эта функция намного быстрее, чем list_count(), потому что она работает непосредственно с данными calibre без предварительного преобразования их в строку. Пример: list_count_field('tags').

list_count_matching ¶

class calibre.utils.formatter_functions.BuiltinListCountMatching[исходный код]¶

list_count_matching(value, pattern, separator) – интерпретирует value``как список элементов, разделённых ``separator, возвращая количество элементов в списке, которые соответствуют регулярному выражению pattern.

Псевдонимы: list_count_matching(), count_matching()

list_difference ¶

class calibre.utils.formatter_functions.BuiltinListDifference[исходный код]¶

list_difference(list1, list2, separator) – возвращает список, созданный удалением из списка list1 любого элемента, найденного в списке list2, используя регистронезависимое сравнение. Элементы в списках list1 и list2 разделяются разделителем separator, так же как и элементы в возвращаемом списке.

list_equals ¶

class calibre.utils.formatter_functions.BuiltinListEquals[исходный код]¶

list_equals(list1, sep1, list2, sep2, yes_val, no_val) – возвращает yes_val если list1 и list2 содержат одинаковые элементы, иначе возвращает no_val. Элементы определяются разделением каждого списка с использованием соответствующего символа разделителя (sep1 или sep2). Порядок элементов в списке не важен. Сравнение регистронезависимое.

list_intersection ¶

class calibre.utils.formatter_functions.BuiltinListIntersection[исходный код]¶

list_intersection(list1, list2, separator) – return a list made by removing from list1 any item not found in list2 using a case-insensitive comparison. The items in list1 and list2 are separated by separator, as are the items in the returned list.

list_join ¶

class calibre.utils.formatter_functions.BuiltinListJoin[исходный код]¶

list_join(с_separator, list1, separator1 [, list2, separator2]*) – возвращает список, созданный путем объединения элементов в исходных списках (list1 и т.д.) используя with_separator между элементами в результирующем списке. Элементы в каждом из исходных списков list[123...] разделён соответствующим разделителем separator[123 ...]. Список может содержать нулевые значения. Это может быть поле типа publisher (издатель), которое является однозначным, фактически списком из одного элемента. Дубликаты удаляются с помощью сравнения без учета регистра. Детали возвращены в том порядке, как они появляются в списке источников. Если элементы в списках, отличаются только регистром букв, то используется последнее. Все разделители может быть больше, чем один символ.

Example:

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

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

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

Вы можете использовать выражения для создания списка. Например, предположим, что вам нужны элементы для authors и #genre, но с изменением жанра на слово «Genre: « далее следует первая буква жанра, т.е. «Fiction» станет «Genre: F». Получится следующее:

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

list_re ¶

class calibre.utils.formatter_functions.BuiltinListRe[исходный код]¶

list_re(src_list, separator, include_re, opt_replace) – создать список, вначале разделив src_list на элементы с помощью символа разделителя. Для каждого элемента в списке проверить, соответствует ли он include_re. Если это так, добавить его в список для возврата. Если opt_replace не является пустой строкой, применить замену перед добавлением элемента в возвращаемый список.

list_re_group ¶

class calibre.utils.formatter_functions.BuiltinListReGroup[исходный код]¶

list_re_group(src_list, separator, include_re, search_re [,template_for_group]*) – Like list_re() except replacements are not optional. It uses re_group(item, search_re, template ...) when doing the replacements.

list_remove_duplicates ¶

class calibre.utils.formatter_functions.BuiltinListRemoveDuplicates[исходный код]¶

list_remove_duplicates(list, separator) – вернуть список, созданный удалением повторяющихся элементов в list. Если элементы отличаются только регистром, возвращается последний. Элементы в списке list разделены разделителем separator, как и элементы в возвращаемом списке``list``.

list_sort ¶

class calibre.utils.formatter_functions.BuiltinListSort[исходный код]¶

list_sort(list, direction, separator) – вернуть список, отсортированный с использованием лексической сортировки без учета регистра. Если direction равно нулю, список сортируется по возрастанию, иначе по убыванию. Элементы списка разделены разделителем separator, как и элементы в возвращаемом списке.

list_split ¶

class calibre.utils.formatter_functions.BuiltinListSplit[исходный код]¶

list_split(list_val, sep, id_prefix) – разделяет list_val на отдельные значения с помощью sep, затем присваивает значения переменным с именем id_prefix_N, где N — позиция значения в списке. Первый элемент имеет позицию 0 (ноль). Функция возвращает последний элемент в списке.

Пример:

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

is equivalent to:

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

list_union ¶

class calibre.utils.formatter_functions.BuiltinListUnion[исходный код]¶

list_union(list1, list2, separator) – return a list made by merging the items in list1 and list2, removing duplicate items using a case-insensitive comparison. If items differ in case, the one in list1 is used. The items in list1 and list2 are separated by separator, as are the items in the returned list.

Aliases: merge_lists(), list_union()

range ¶

class calibre.utils.formatter_functions.BuiltinRange[исходный код]¶

range(start, stop, step, limit) – returns a list of numbers generated by looping over the range specified by the parameters start, stop, and step, with a maximum length of limit. The first value produced is „start“. Subsequent values next_v = current_v + step. The loop continues while next_v < stop assuming step is positive, otherwise while next_v > stop. An empty list is produced if start fails the test: start >= stop if step is positive. The limit sets the maximum length of the list and has a default of 1000. The parameters start, step, and limit are optional. Calling range() with one argument specifies stop. Two arguments specify start and stop. Three arguments specify start, stop, and step. Four arguments specify start, stop, step and limit.

Examples:

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

Отображение документации на английском языке из-за ошибки FFML: Missing closing «`» for italics on line 2 in «range»

subitems ¶

class calibre.utils.formatter_functions.BuiltinSubitems[исходный код]¶

subitems(value, start_index, end_index) – Эта функция разделяет списки на иерархические элементы, подобные тегам, такие как жанры. Она интерпретирует значение как разделенный запятыми список элементов, похожих на теги, где каждый элемент представляет собой список, разделённый точкой. Возвращает новый список, созданный путем извлечения из каждого элемента компонентов от start_index до end_index, затем результаты объединяются обратно. Дубликаты удаляются. Первый подпункт в списке, разделенном точкой, имеет нулевой индекс. Если индекс отрицательный, то он отсчитывается от конца списка. В качестве особого случая предполагается, что end_index , равный нулю, равен длине списка.

Примеры:

Assuming a #genre column containing «A.B.C»:
- {#genre:subitems(0,1)} returns «A»
- {#genre:subitems(0,2)} returns «A.B»
- {#genre:subitems(1,0)} returns «B.C»
Assuming a #genre column containing «A.B.C, D.E»:
- {#genre:subitems(0,1)} returns «A, D»
- {#genre:subitems(0,2)} returns «A.B, D.E»

sublist ¶

class calibre.utils.formatter_functions.BuiltinSublist[исходный код]¶

sublist(value, start_index, end_index, separator) – интерпретирует value как список значений, разделённых separator, возвращая новый список с началом в start_index с концом в end_index. Первый пункт - номер 0 (ноль). Если индекс - отрицательный, то его начало - от конца списка. В особых случаях end_index нуля считается длиной списка.

Примеры, использующие режим базового шаблона и предополагающие что столбец тегов (разделённый запятыми) содержит «A, B, C»:

{tags:sublist(0,1,\,)} returns «A»
{tags:sublist(-1,0,\,)} returns «C»
{tags:sublist(0,-1,\,)} returns «A, B»

Относящийся ¶

cmp ¶

class calibre.utils.formatter_functions.BuiltinCmp[исходный код]¶

cmp(value, y, lt, eq, gt) – сравнивает value и y после преобразования обоих в числа. Возвращает lt если value <# y, eq если value ==# y, иначе gt.Во многих случаях операторы числового сравнения (==#, <#, ># и т. п.) могут заменить эту функцию.

first_matching_cmp ¶

class calibre.utils.formatter_functions.BuiltinFirstMatchingCmp[исходный код]¶

first_matching_cmp(val, [cmp1, result1,]+, else_result) – последовательно сравнивает val < cmp, возвращая ассоциированный result для первого успешного сравнения. Если сравнение не удалось, возвращает else_result. Пример:

i = 10;
first_matching_cmp(i,5,"small",10,"middle",15,"large","giant")

вернёт "large". В том же примере с первым значением 16 возвращается "giant".

strcmp ¶

class calibre.utils.formatter_functions.BuiltinStrcmp[исходный код]¶

strcmp(x, y, lt, eq, gt) – does a case-insensitive lexical comparison of x and y. Returns lt if x < y, eq if x == y, otherwise gt. This function can often be replaced by one of the lexical comparison operators (==, >, <, etc.)

Отображение документации на английском языке из-за ошибки FFML: Missing closing «`» for italics on line 1 in «strcmp»

strcmpcase ¶

class calibre.utils.formatter_functions.BuiltinStrcmpcase[исходный код]¶

strcmpcase(x, y, lt, eq, gt) – выполняет сравнение строк x и y с учетом регистра. Возвращает lt, если x < y, eq если x == y, иначе gt.

Примечание. Это НЕ поведение по умолчанию, используемое calibre, например, в операторах лексического сравнения (==, >, < и т. д.). Эта функция может привести к неожиданным результатам, желательно использовать strcmp(), когда это возможно.

Перебор значений ¶

first_non_empty ¶

class calibre.utils.formatter_functions.BuiltinFirstNonEmpty[исходный код]¶

first_non_empty(value [, value]*) – возвращает первое непустое значение. Если все значения пусты, возвращается пустая строка. Вы можете иметь сколько угодно значений.

lookup ¶

class calibre.utils.formatter_functions.BuiltinLookup[исходный код]¶

lookup(value, [ pattern, key, ]* else_key) – The patterns will be checked against the value in order. If a pattern matches then the value of the field named by key is returned. If no pattern matches then the value of the field named by else_key is returned. See also the switch() function.

switch ¶

class calibre.utils.formatter_functions.BuiltinSwitch[исходный код]¶

switch(value, [patternN, valueN,]+ else_value) – for each patternN, valueN pair, checks if the value matches the regular expression patternN and if so returns the associated valueN. If no patternN matches, then else_value is returned. You can have as many patternN, valueN pairs as you wish. The first match is returned.

Отображение документации на английском языке из-за ошибки FFML: Missing closing «`» for italics on line 1 in «switch»

switch_if ¶

class calibre.utils.formatter_functions.BuiltinSwitchIf[исходный код]¶

switch_if([test_expression, value_expression,]+ else_expression) – для каждой пары test_expression, value_expression проверяет, является ли test_expression True (непустым), и если да, то возвращает результат value_expression. Если ни одно из test_expression не равно True, возвращается результат else_expression. У вас может быть столько пар test_expression, value_expression, сколько вы хотите.

Поиск по списку ¶

identifier_in_list ¶

class calibre.utils.formatter_functions.BuiltinIdentifierInList[исходный код]¶

identifier_in_list(val, id_name [, found_val, not_found_val]) – рассматривает val как список идентификаторов, разделённый запятыми. Идентификатор имеет формат id_name:value. id_name параметр - id_name текст для поиска, или id_name или id_name:regexp. Первый случай соответствует, если есть какой-либо идентификатор, соответствующий этому id_name. Второй случай соответствует, если id_name соответствует идентификатору, а регулярное выражение соответствует значению идентификатора. Если указаны found_val и not_found_val, то, если есть совпадение, возвращается found_val, в противном случае возвращается not_found_val. Если found_val и not_found_val не указаны, то, если есть совпадение, возвращается пара identfier:value, иначе пустая строка ('').

list_contains ¶

class calibre.utils.formatter_functions.BuiltinInList[исходный код]¶

list_contains(value, separator, [ pattern, found_val, ]* not_found_val) – интерпретирует value как список элементов, разделенных разделителем separator, проверяя pattern``для каждого элемента в списке. Если ``pattern соответствует элементу, возвращает found_val, иначе not_found_val. Пара pattern и found_value могут повторяться столько раз, сколько требуется, что позволяет возвращать разные значения в зависимости от значения элемента. Шаблоны проверяются по порядку и возвращается первое совпадение.

Псевдонимы: in_list(), list_contains()

list_item ¶

class calibre.utils.formatter_functions.BuiltinListitem[исходный код]¶

list_item(value, index, separator) – обрабатывает значение как список элементов, разделённых separator, возвращая элемент с номером index. Первый элемент имеет номер ноль. Последний элемент с номером индекса -1 как list_item(-1,separator). Если элемент не в списке, то возвращается пустое значение. Разделитель (separator) работает так же, как и в функции count, обычно запятая, но амперсанд для списков, вроде author.

select ¶

class calibre.utils.formatter_functions.BuiltinSelect[исходный код]¶

select(value, key) – обрабатывает value как разделённый запятыми список элементов вида id:id_value (формат identifier calibre). Функция находит первую пару с совпадающим с key идентификатором, и возвращает соответствующее id_value. При отсутствии совпадений возвращается пустая строка.

str_in_list ¶

class calibre.utils.formatter_functions.BuiltinStrInList[исходный код]¶

str_in_list(separator, [ string, found_val, ]+ not_found_val) – интерпретирует значение как список элементов, разделенных separator, затем сравнивает string с каждым значением в списке. string не является регулярным выражением. Если string равна любому элементу (без учета регистра), вернуть соответствующее значение found_val. Если string содержит разделители separator, она также рассматривается как список, и каждое подзначение проверяется. Пары string и found_value могут повторяться сколько угодно раз, что позволяет возвращать разные значения в зависимости от значения строки. Если ни одна из строк не совпадает, возвращается not_found_value. Строки проверяются по порядку. Возвращается первое совпадение.

Получить значения из метаданных ¶

annotation_count ¶

class calibre.utils.formatter_functions.BuiltinAnnotationCount[исходный код]¶

annotation_count() – вернуть общее количество аннотаций всех типов, прикрепленных к текущей книге. Эта функция работает только в графическом интерфейсе и контент-сервере.

approximate_formats ¶

class calibre.utils.formatter_functions.BuiltinApproximateFormats[исходный код]¶

approximate_formats() – возвращает разделенный запятыми список форматов, связанных с книгой. Поскольку список берется из базы данных calibre, а не из файловой системы, нет гарантии, что список правильный, но обычно это верно. Обратите внимание, что результирующие названия форматов всегда написаны заглавными буквами, как в EPUB.

Эта функция работает только в графическом интерфейсе. Если нужно использовать эти значения в шаблоне для сохранения на диск или отправки на устройство, то создайте пользовательский столбец типа «Столбец состоящий из других столбцов» и используйте функцию в нём, а затем используйте значение этого столбца в ваших шаблонах сохранения/отправки.

author_links ¶

class calibre.utils.formatter_functions.BuiltinAuthorLinks[исходный код]¶

author_links(val_separator, pair_separator) – возвращает строку, содержащую список авторов и значения ссылок на этих авторов в форме: author1 val_separator author1_link pair_separator author2 val_separator author2_link и т.д.

Автор отделяется от значения ссылки строкой val_separator``без добавленных пробелов. Предполагая, что ``val_separator является двоеточием, пары author:link value разделяются строковым аргументом pair_separator без добавленных пробелов. Выберите разделители, которые не встречаются в именах авторов или ссылках. Автор будет указан, даже если ссылка на автора пуста.

author_sorts ¶

class calibre.utils.formatter_functions.BuiltinAuthorSorts[исходный код]¶

author_sorts(val_separator) – возвращает строку, содержащую список значений сортировок автора для авторов книги. Сортировка - метаданные автора (отличающиеся от author_sort в книгах). Возвращаемый список имет формат author_sort1 val_separator author_sort2 и т.д. без добавляемых пробелов. Значения author_sort в этом списке в том же порядке, как и авторы в книге. Если вам нужны пробелы вокруг разделителя val_separator, включите их в строку val_separator.

booksize ¶

class calibre.utils.formatter_functions.BuiltinBooksize[исходный код]¶

booksize() — возвращает значение поля size. Возвращает „“, если книга не имеет форматов.

Эта функция работает только в графическом интерфейсе. Если вы желаете использовать её значение в шаблоне для сохранения на диск или отправки на устройство, то создайте пользовательский столбец типа Столбец, состоящий из других столбцов и используйте функцию в нём, а затем используйте значение этого столбца в ваших шаблонах сохранения/отправки.

connected_device_name ¶

class calibre.utils.formatter_functions.BuiltinConnectedDeviceName[исходный код]¶

connected_device_name(storage_location_key) – если устройство подключено, вернуть имя устройства, в противном случае вернуть пустую строку. Каждое место хранения на устройстве может иметь другое имя. Названия storage_location_key - 'main', 'carda' и 'cardb'. Эта функция работает только в графическом интерфейсе.

connected_device_uuid ¶

class calibre.utils.formatter_functions.BuiltinConnectedDeviceUUID[исходный код]¶

connected_device_uuid(storage_location_key) – если устройство подключено, вернуть uuid устройства (уникальный идентификатор), иначе вернуть пустую строку. У каждого места хранения на устройстве свой uuid. Названия локаций - 'main', 'carda' и 'cardb'. Эта функция работает только в графическом интерфейсе.

current_library_name ¶

class calibre.utils.formatter_functions.BuiltinCurrentLibraryName[исходный код]¶

current_library_name() – возвращает последнее имя в пути к текущей библиотеке calibre.

current_library_path ¶

class calibre.utils.formatter_functions.BuiltinCurrentLibraryPath[исходный код]¶

current_library_path() – возвращает полный путь к текущей библиотеке calibre.

current_virtual_library_name ¶

class calibre.utils.formatter_functions.BuiltinCurrentVirtualLibraryName[исходный код]¶

current_virtual_library_name() – return the name of the current virtual library if there is one, otherwise the empty string. Library name case is preserved. Example:

program: current_virtual_library_name()

This function works only in the GUI.

Отображение документации на английском языке из-за ошибки FFML: Missing closing «`» for italics on line 1 in «current_virtual_library_name»

field ¶

class calibre.utils.formatter_functions.BuiltinField[исходный код]¶

field(lookup_name) – returns the value of the metadata field with lookup name lookup_name. The $ prefix can be used instead of the function, as in $tags.

Отображение документации на английском языке из-за ошибки FFML: Missing closing «``» for CODE_TEXT on line 1 in «field»

formats_modtimes ¶

class calibre.utils.formatter_functions.BuiltinFormatsModtimes[исходный код]¶

formats_modtimes(date_format_string) – возвращает разделённый запятыми список разделённых двоеточиями элементов FMT:DATE, представляющих собой время изменения форматов книги. Параметр date_format_string задаёт формат даты. Смотрите функцию format_date() для подробностей. Вы можете использовать функцию select() для получения времени модификации в заданном формате. Названия форматов всегда в верхнем регистре, как в EPUB.

formats_path_segments ¶

class calibre.utils.formatter_functions.BuiltinFormatsPathSegments[исходный код]¶

formats_path_segments(with_author, with_title, with_format, with_ext, sep) – return parts of the path to a book format in the calibre library separated by sep. The parameter sep should usually be a slash ('/'). One use is to be sure that paths generated in Save to disk and Send to device templates are shortened consistently. Another is to be sure the paths on the device match the paths in the calibre library.

A book path consists of 3 segments: the author, the title including the calibre database id in parentheses, and the format (author - title). Calibre can shorten any of the three because of file name length limitations. You choose which segments to include by passing 1 for that segment. If you don’t want a segment then pass 0 or the empty string for that segment. For example, the following returns just the format name without the extension:

formats_path_segments(0, 0, 1, 0, '/')

Because there is only one segment the separator is ignored.

If there are multiple formats (multiple extensions) then one of the extensions will be picked at random. If you care about which extension is used then get the path without the extension then add the desired extension to it.

Examples: Assume there is a book in the calibre library with an epub format by Joe Blogs with title „Help“. It would have the path

Joe Blogs/Help - (calibre_id)/Help - Joe Blogs.epub

The following shows what is returned for various parameters:

formats_path_segments(0, 0, 1, 0, '/') returns Help - Joe Blogs
formats_path_segments(0, 0, 1, 1, '/') returns Help - Joe Blogs.epub
formats_path_segments(1, 0, 1, 1, '/') returns Joe Blogs/Help - Joe Blogs.epub
formats_path_segments(1, 0, 1, 0, '/') returns Joe Blogs/Help - Joe Blogs
formats_path_segments(0, 1, 0, 0, '/') returns Help - (calibre_id)

Отображение документации на английском языке из-за ошибки FFML: Missing closing «``» for CODE_TEXT on line 21 in «formats_path_segments»

formats_paths ¶

class calibre.utils.formatter_functions.BuiltinFormatsPaths[исходный код]¶

formats_paths([separator]) – return a separator-separated list of colon-separated items FMT:PATH giving the full path to the formats of a book. The separator argument is optional. If not supplied then the separator is ', ' (comma space). If the separator is a comma then you can use the select() function to get the path for a specific format. Note that format names are always uppercase, as in EPUB.

Отображение документации на английском языке из-за ошибки FFML: Missing closing «``» for CODE_TEXT on line 1 in «formats_paths»

formats_sizes ¶

class calibre.utils.formatter_functions.BuiltinFormatsSizes[исходный код]¶

formats_sizes() – возвращает разделённый запятыми список элементов, разделённых двоеточиями``FMT:SIZE``, представляющих собой размеры в байтах форматов книги. Вы можете использовать функцию select() для получения размера для заданного формата. Названия форматов всегда в верхнем регистре, как в EPUB.

has_cover ¶

class calibre.utils.formatter_functions.BuiltinHasCover[исходный код]¶

has_cover() – возвращает 'Yes', если у книги есть обложка, иначе возвращает пустую строку

is_marked ¶

class calibre.utils.formatter_functions.BuiltinIsMarked[исходный код]¶

is_marked() – проверить, помечена ли (marked) книга в calibre. Если это так, то вернуть значение метки, либо 'true'``(lower case), либо список именованных меток, разделенных запятыми. Возврат ``'', если книга не отмечена. Эта функция работает только в графическом интерфейсе.

language_codes ¶

class calibre.utils.formatter_functions.BuiltinLanguageCodes[исходный код]¶

language_codes(lang_strings) – возвращает коды языка language codes для строк, взятых из lang_strings. Строки должны быть на языке текущей локализации. lang_strings - это список, разделённый запятыми.

language_strings ¶

class calibre.utils.formatter_functions.BuiltinLanguageStrings[исходный код]¶

language_strings(value, localize) – вернуть значение названий языков для языковых кодов (см. здесь имена и коды) , переданных в качестве значения value. Пример: {languages:language_strings()}. Если localize равно нулю, вернуть строки на английском языке. Если localize не равно нулю, вернуть строки на языке текущей локали. lang_codes - это список, разделённый запятыми.

ondevice ¶

class calibre.utils.formatter_functions.BuiltinOndevice[исходный код]¶

ondevice() – возвращает строку 'Yes' если параметр ondevice установлен, иначе возвращает пустую строку. Эта функция работает только в графическом интерфейсе. Если вы желаете использовать её значение в шаблоне для сохранения на диск или отправки на устройство, то создайте пользовательский столбец типа Столбец, состоящий из других столбцов и используйте функцию в нём, а затем используйте значение этого столбца в ваших шаблонах сохранения/отправки.

raw_field ¶

class calibre.utils.formatter_functions.BuiltinRawField[исходный код]¶

raw_field(lookup_name [, optional_default]) – возвращает поле метаданных с именем lookup_name без применения форматирования. Вычисляет и возвращает необязательный второй аргумент optional_default, если значение поля не определено (None). Префикс $$ может использоваться вместо функции, как в $$pubdate.

raw_list ¶

class calibre.utils.formatter_functions.BuiltinRawList[исходный код]¶

raw_list(lookup_name, separator) – возвращает список метаданных с именем lookup_name без применения какого-либо форматирования или сортировки и с элементами, разделёнными разделителем separator.

series_sort ¶

class calibre.utils.formatter_functions.BuiltinSeriesSort[исходный код]¶

series_sort() – возвращает сортировочное значение серии

user_categories ¶

class calibre.utils.formatter_functions.BuiltinUserCategories[исходный код]¶

user_categories() – возвращает разделённый запятыми список категорий пользователя, которые содержат эту книгу. Эта функция работает только в GUI. Если вы хотите использовать эти значения в шаблонах save-to-disk или send-to-device, вы должны создать пользовательский «Столбец, состоящий из других столбцов», использовать функцию в шаблоне этого столбца и использовать значение этого столбца в ваших шаблонах сохранения/отправки

virtual_libraries ¶

class calibre.utils.formatter_functions.BuiltinVirtualLibraries[исходный код]¶

virtual_libraries() – возвращает разделённый запятыми список виртуальных библиотек, которые содержат эту книгу. Эта функция работает только в графическом интерфейсе. Если вы желаете использовать её значение в шаблоне для сохранения на диск или отправки на устройство, то нужно создать пользовательский столбец типа «Столбец, состоящий из других столбцов» и использовать функцию в нём, а затем использовать значение этого столбца в своих шаблонах сохранения/отправки.

Рекурсия ¶

eval ¶

class calibre.utils.formatter_functions.BuiltinEval[исходный код]¶

eval(string) – оценивает строку как программу, передавая локальные переменные. Это позволяет использовать шаблонный процессор для построения сложных результатов из локальных переменных. В Template Program Mode, поскольку символы { и } интерпретируются до вычисления шаблона, вы должны использовать``[[`` для символа { и ]] для } . Они конвертируются автоматически. Также обратите внимание, что префиксы и суффиксы (синтаксис |prefix|suffix ) не могут использоваться в аргументе этой функции при использовании Template Program Mode.

template ¶

class calibre.utils.formatter_functions.BuiltinTemplate[исходный код]¶

template(x) – обрабатывает x как шаблон. Сравнение выполняется в контексте, то есть переменные не передаются между вызовом и обработкой шаблона. Если не используется General Program Mode, поскольку символы { и } являются специальными, вы должны использовать [[ для символа { и ]] для символа }; они преобразуются автоматически. Например,``template('[[title_sort]]')`` вычислит шаблон {title_sort} и вернёт его значение. Обратите также внимание, что префиксы и суффиксы (синтаксис |prefix |suffix) не могут использоваться в аргументе этой функции при использовании template program mode.

Смена регистра ¶

capitalize ¶

class calibre.utils.formatter_functions.BuiltinCapitalize[исходный код]¶

capitalize(value) – возвращает значение, в котором первая буква в верхнем регистре, а остальные в нижнем регистре.

lowercase ¶

class calibre.utils.formatter_functions.BuiltinLowercase[исходный код]¶

lowercase(value) – возвращает value в нижнем регистре.

titlecase ¶

class calibre.utils.formatter_functions.BuiltinTitlecase[исходный код]¶

titlecase(value) – возвращает value в регистре ЗАГОЛОВКОВ.

uppercase ¶

class calibre.utils.formatter_functions.BuiltinUppercase[исходный код]¶

uppercase(value) – возвращает value в верхнем регистре

Форматирование значений ¶

finish_formatting ¶

class calibre.utils.formatter_functions.BuiltinFinishFormatting[исходный код]¶

finish_formatting(value, format, prefix, suffix) – применяет format, prefix и suffix к value так же как в шаблонах finish_formatting(value, format, prefix, suffix) {series_index:05.2f| - |- }. Эта функция предусмотрена для упрощения преобразования сложных шаблонов с одной функцией или шаблонного программного режима в шаблоны GPM. Например, следующая программа выдает тот же результат, что и вышеупомянутый шаблон:

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

Другой пример: для шаблона:

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

use:

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

format_date ¶

class calibre.utils.formatter_functions.BuiltinFormatDate[исходный код]¶

format_date(value, format_string) – форматирует value, которое должно быть строкой даты, используя format_string, возвращающую строку. Лучше всего, если дата указана в формате ISO, поскольку использование других форматов даты часто приводит к ошибкам, поскольку фактическое значение даты не может быть определено однозначно. Обратите внимание, что функция format_date_field() работает быстрее и надёжнее.

Коды форматирования:

d : день как число без начального нуля (1 до 31)
dd : день как число с начальным нулём (01 до 31)
ddd : локализованная аббревиатура названия дня (Напр. «Пн» до «Вскр»)
dddd : полное локализованное название дня недели (напр. «Понедельник» до «Воскресенье»)
M : номер месяца в году без начального нуля (1 to 12)
MM : номер месяца в году с начальным нулём (01 to 12)
MMM : сокращённое локализованное название месяца (напр. «Янв» до «Дек»)
MMMM : полное локализованное название месяца (от «Январь» до «Декабрь»)
yy : две последние цифры года (от 00 до 99
yyyy : полный номер года из четырёх цифр
h : часы без начального 0 (от 0 до 11 или от 0 до 23, в зависимости от am/pm (12/24) формата времени
hh : часы с начальным 0 (от 00 до 11 или от 00 до 23, в зависимости от am/pm)
m : минуты без начального 0 (от 0 до 59)
mm : минуты с начальным 0 (00 to 59)
s : секунды без начального 0 (0 to 59)
ss : секунды с начальным 0 (00 to 59)
ap : использовать 12-часовой формат вместо 24-часового, с «ap» заменённым на локализованную строку для am или pm
AP : использовать 12-часовой формат вместо 24-часового, с «AP» заменённым на локализованную строку для AM или PM
aP : использовать 12-часовой формат вместо 24-часового, с «aP» заменённым на локализованную строку для AM или PM
Ap : использовать 12-часовой формат вместо 24-часового, с «Ap» заменённым на локализованную строку для AM или PM
iso : дата, время и временная зона (должен быть единственным форматом)
to_number : преобразовать дату & время в число с плаввающей запятой (timestamp)
from_number : преобразуйте число с плавающей запятой (timestamp) в дату в формате ISO. Если вам нужен другой формат даты, добавьте желаемую строку форматирования после from_number и двоеточия (:). Пример:
```
format_date(val, 'from_number:MMM dd yyyy')
```

Вы можете получить неожиданные результаты, если форматируемая дата содержит локализованные названия месяцев, что может произойти, если вы изменили формат даты на содержащий``MMMM``. Используйте format_date_field() для предотвращения этой проблемы.

format_date_field ¶

class calibre.utils.formatter_functions.BuiltinFormatDateField[исходный код]¶

format_date_field(field_name, format_string) – форматирует значение в поле field_name, которое должно быть искомым именем поля даты, стандартным или настраиваемым. См. format_date() для кодов форматирования. Эта функция намного быстрее, чем format_date(), и её следует использовать при форматировании значения в поле (столбце). Её нельзя использовать для вычисляемых дат или дат в строковых переменных. Примеры:

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

format_duration ¶

class calibre.utils.formatter_functions.BuiltinFormatDuration[исходный код]¶

format_duration(value, template, [largest_unit]) – format the value, a number of seconds, into a string showing weeks, days, hours, minutes, and seconds. If the value is a float then it is rounded to the nearest integer. You choose how to format the value using a template consisting of value selectors surrounded by [ and ] characters. The selectors are:

[w]: weeks
[d]: days
[h]: hours
[m]: minutes
[s]: seconds

You can put arbitrary text between selectors.

The following examples use a duration of 2 days (172,800 seconds) 1 hour (3,600 seconds) and 20 seconds, which totals to 176,420 seconds.

format_duration(176420, '[d][h][m][s]') will return the value 2d 1h 0m 20s.
format_duration(176420, '[h][m][s]') will return the value 49h 0m 20s.
format_duration(176420, 'Your reading time is [d][h][m][s]') returns the value Your reading time is 49h 0m 20s.
format_duration(176420, '[w][d][h][m][s]') will return the value 2d 1h 0m 20s. Note that the zero weeks value is not returned.

If you want to see zero values for items such as weeks in the above example, use an uppercase selector. For example, the following uses 'W' to show zero weeks:

format_duration(176420, '[W][d][h][m][s]') returns 0w 2d 1h 0m 20s.

By default the text following a value is the selector followed by a space. You can change that to whatever text you want. The format for a selector with your text is the selector followed by a colon followed by text segments separated by '|' characters. You must include any space characters you want in the output.

You can provide from one to three text segments.

If you provide one segment, as in [w: weeks ] then that segment is used for all values.
If you provide two segments, as in [w: weeks | week ] then the first segment is used for 0 and more than 1. The second segment is used for 1.
If you provide three segments, as in [w: weeks | week | weeks ] then the first segment is used for 0, the second segment is used for 1, and the third segment is used for more than 1.

The second form is equivalent to the third form in many languages.

For example, the selector:

[w: weeks | week | weeks ] produces '0 weeks ', '1 week ', or '2 weeks '.
[w: weeks | week ] produces '0 weeks ', '1 week ', or '2 weeks '.
[w: weeks ] produces 0 weeks ', 1 weeks ', or 2 weeks '.

The optional largest_unit parameter specifies the largest of weeks, days, hours, minutes, and seconds that will be produced by the template. It must be one of the value selectors. This can be useful to truncate a value.

format_duration(176420, '[h][m][s]', 'd') will return the value 1h 0m 20s instead of 49h 0m 20s.

Отображение документации на английском языке из-за ошибки FFML: Missing closing «`» for italics on line 38 in «format_duration»

format_number ¶

class calibre.utils.formatter_functions.BuiltinFormatNumber[исходный код]¶

format_number(value, template) – interprets the value as a number and formats that number using a Python formatting template such as {0:5.2f} or {0:,d} or ${0:5,.2f}. The formatting template must begin with {0: and end with } as in the above examples. Exception: you can leave off the leading «{0:» and trailing «}» if the format template contains only a format. See the Template Language and the Python documentation for more examples. Returns the empty string if formatting fails.

Отображение документации на английском языке из-за ошибки FFML: Missing closing «``» for CODE_TEXT on line 2 in «format_number»

human_readable ¶

class calibre.utils.formatter_functions.BuiltinHumanReadable[исходный код]¶

human_readable(value) – ожидает, что значение будет числом, и возвращает строку, представляющую это число в КБ, МБ, ГБ и т. д.

rating_to_stars ¶

class calibre.utils.formatter_functions.BuiltinRatingToStars[исходный код]¶

rating_to_stars(value, use_half_stars) – Возвращает рейтинг как value в виде строки, состоящей из звездочек (★“). Значение должно быть числом от 0 до 5. Задайте для use_half_stars значение 1, если вы хотите, чтобы символы половинной звезды для дробных чисел были доступны в настраиваемых столбцах рейтингов.

Функции URL ¶

encode_for_url ¶

class calibre.utils.formatter_functions.BuiltinEncodeForURL[исходный код]¶

encode_for_url(value, use_plus) – возвращает значение value закодированное для использования в URL, как указанно с use_plus. Значение URL-кодированное. Далее, если use_plus равно 0, то пробелы заменяются знаками '+' (плюс). Если это 1, то пробелы заменяются %20.

Если вы не хотите, чтобы значение было кодированным, но чтобы пробелы были заменены, используйте функцию re() , как в re ($ series, ' ', '%20')

Смотрите также функции make_url(), make_url_extended() и query_string().

make_url ¶

class calibre.utils.formatter_functions.BuiltinMakeUrl[исходный код]¶

make_url(path, [query_name, query_value]+) – эта функция - простейший способ создания URL-адреса запроса. Она использует path, веб-сайт и страницу, которые вы хотите запросить и пары query_name, query_value, из которых строится запрос. Как правило, query_value должно быть закодировано в URL. С помощью этой функции оно всегда закодировано, пробелы всегда заменяются знаками „+“.

Должна быть предоставлена хотя бы одна пара query_name, query_value.

Пример: конструирование поискового URL-запроса в Wikipedia для автора Niccolò Machiavelli:

make_url('https://en.wikipedia.org/w/index.php', 'search', 'Niccolò Machiavelli')

returns

https://en.wikipedia.org/w/index.php?search=Niccol%C3%B2+Machiavelli

Если вы пишете пользовательский URL-шаблон сведений о книге столбцов, используйте $item_name или field('item_name') чтобы получить значение поля, на которое был нажат клик. Пример: если Niccolò Machiavelli было нажато затем можно сконструировать запрос URL:

make_url('https://en.wikipedia.org/w/index.php', 'search', $item_name)

См. функции make_url_extended(), query_string() и encode_for_url().

make_url_extended ¶

class calibre.utils.formatter_functions.BuiltinMakeUrlExtended[исходный код]¶

make_url_extended(...) – эта функция аналогична make_url(), но даёт вам больше контроля над компонентами URL. Компонентами URL являются

scheme:://authority/path?query string.

См. Uniform Resource Locator в Wikipedia.

У функции два варианта:

make_url_extended(scheme, authority, path, [query_name, query_value]+)

и

make_url_extended(scheme, authority, path, query_string)

Эта функция возвращает URL-адрес, созданный на основе scheme, authority, path, и либо query_string либо строки запроса, построенной из пар аргументов запроса. authority можен быть пустым, в случае calibre scheme URL. Вы должны указать либо query_string, либо хотя бы одну пару query_name, query_value. Если вы укажете query_string и оно будет пустым, то результирующий URL-адрес не будет содержать раздела строки запроса.

Пример 1: constructing a Wikipedia search URL for the author Niccolò Machiavelli:

make_url_extended('https', 'en.wikipedia.org', '/w/index.php', 'search', 'Niccolò Machiavelli')

returns

https://en.wikipedia.org/w/index.php?search=Niccol%C3%B2+Machiavelli

См. функцию query_string() для примера ипользующего make_url_extended() с query_string.

Если вы создаёте пользовательский шаблон URL-адреса сведений о столбцах книги, используйте $item_name или field ('item_name'), чтобы получить значение нажатого поля. Пример: если был нажат Niccolò Machiavelli, то вы можете создать URL-адрес, используя :

make_url_extended('https', 'en.wikipedia.org', '/w/index.php', 'search', $item_name')

См. функции make_url(), query_string() and encode_for_url().

query_string ¶

class calibre.utils.formatter_functions.BuiltinQueryString[исходный код]¶

query_string([query_name, query_value, how_to_encode]+)– возвращает строку запроса URL сконструированную из триад query_name, query_value, how_to_encode. Строка запроса это серия элементов выглядящих как query_name=query_value, где query_value это URL-кодирование. Элементы запроса разделяются символами '&' (ampersand).

Если how_to_encode это 0 затем query_value это кодированное и пробелы заменяются символом '+' (plus). Если how_to_encode это 1 затем query_value это кодированное с пробелами заменёнными на %20. Если how_to_encode это 2 затем query_value возвращается неизменным; нет кодирования и пробелы не заменяются. Если вы хотите чтобы query_value не кодировалась но пробелы заменялись используйте re() function, как в re($series, ' ', '%20')

Вы используете эту функцию, если вам нужен конкретный контроль над тем, как создаются части строки запроса. Затем вы могли бы использовать результирующую строку запроса в make_url_extended(), как в

make_url_extended(
       'https', 'your_host', 'your_path',
       query_string('encoded', 'Hendrik Bäßler', 0, 'unencoded', 'Hendrik Bäßler', 2))

даёт вам

https://your_host/your_path?encoded=Hendrik+B%C3%A4%C3%9Fler&unencoded=Hendrik Bäßler

У вас должен быть хотя бы одна триада query_name, query_value, how_to_encode, но можете использовать их столько, сколько пожелаете.

Возвращаемое значение представляет собой строку запроса URL со всеми указанными элементами, например: name1=val1[&nameN=valN]*. Заметьте что '?' path / query string разделитель не включён в возвращаемый результат.

Если вы пишете пользовательский URL-шаблон сведений о столбцах книги, используйте $item_name or field('item_name') чтобы получить некодированное значение поля, по которому был произведен щелчок. У вас также есть item_value_quoted, где значение уже закодировано со знаками плюс замена пробелов и item_value_no_plus, где значение уже закодировано с заменой пробелов %20.

См. функции make_url(), make_url_extended() и encode_for_url().

to_hex ¶

class calibre.utils.formatter_functions.BuiltinToHex[исходный код]¶

to_hex(val) – возвращает строку val, закодированную в шестнадцатеричном формате. Полезно при создании URL-ов calibre.

urls_from_identifiers ¶

class calibre.utils.formatter_functions.BuiltinUrlsFromIdentifiers[исходный код]¶

urls_from_identifiers(identifiers, sort_results) – задаёт список идентификаторов, разделённых запятыми, где identifier (идентификато)р представляет собой пару значений, разделённых двоеточиями (id_name:id_value), возвращает список URL-адресов HTML, разделённых запятыми, сгенерированных из идентификаторов. Список не отсортирован, если sort_results равен 0 (символ или число), в противном случае он сортируется в алфавитном порядке по имени идентификатора. URL-адреса генерируются так же, как столбец встроенных идентификаторов, когда они отображаются в Подробности книги.

Функции базы данных ¶

book_count ¶

class calibre.utils.formatter_functions.BuiltinBookCount[исходный код]¶

book_count(query, use_vl) – возвращает количество книг, найденных с помощью поиска для query. Если use_vl равно 0 (нулю), то виртуальные библиотеки игнорируются. Эта функция и её компаньон book_values() особенно полезны в поиске по шаблону, поддерживающем поиск, объединяющий информацию из многих книг, например, поиск серий только по одной книге. Его нельзя использовать в составных столбцах если для настройки allow_template_database_functions_in_composites не задано значение True. Можно использовать только в GUI. Например, этот поиск по шаблону использует эту функцию и её дополнение для поиска всех серий, содержащих только одну книгу:

Определить хранимый шаблон (используя Preferences → Advanced → Template functions) названный series_only_one_book (имя - произвольное). Шаблон:
```
program:
vals = globals(vals='');
if !vals then
all_series = book_values('series', 'series:true', ',', 0);
for series in all_series:
if book_count('series:="' & series & '"', 0) == 1 then
vals = list_join(',', vals, ',', series, ',')
fi
rof;
set_globals(vals)
fi;
str_in_list(vals, ',', $series, 1, '')
```
При первом запуске шаблона (первая проверенная книга) он сохраняет результаты поиска в базе данных в global глобальной переменной шаблона с именем vals. Эти результаты используются для проверки последующих книг без повторного поиска.
Использовать сохранённый шаблон при поиске по шаблону:

template:"program: series_only_one_book()#@#:n:1"
Использование сохранённого шаблона вместо помещения шаблона в поиск устраняет проблемы, вызванные требованием экранировать кавычки в поисковом выражении.

Функция используется только в GUI и контент-сервере.

book_values ¶

class calibre.utils.formatter_functions.BuiltinBookValues[исходный код]¶

book_values(column, query, sep, use_vl) – возвращает список уникальных значений, содержащихся в столбце column (имя поиска), разделенных sep, в найденных книгах путем поиска query. Если use_vl равно 0 (ноль), тогда виртуальные библиотеки игнорируются. Эта функция и её компаньон book_count() особенно полезны при поиске по шаблону, поддерживая поиск, объединяющий информацию из многих книг, например, поиск серий только с одной книгой. Нельзя использовать в составных столбцах, если для настройки allow_template_database_functions_in_composites установлено значение True. Можно использовать только в GUI и контент-сервере.

extra_file_modtime ¶

class calibre.utils.formatter_functions.BuiltinExtraFileModtime[исходный код]¶

extra_file_modtime(file_name, format_spec) – возвращает время модификации дополнительного файла file_name в папке data/ книги, если он существует, иначе -1. Modtime форматируется в соответствии с format_spec (см. format_date()). Если format_string пусто, возвращает modtime как количество секунд с плавающей запятой с начала эпохи. См. также функции has_extra_files(), extra_file_names() и extra_file_size(). Эпоха зависит от ОС. Эту функцию можно использовать только в GUI и контент-сервере.

extra_file_names ¶

class calibre.utils.formatter_functions.BuiltinExtraFileNames[исходный код]¶

extra_file_names(sep [, pattern]) – возвращает разделенный сепараторами (sep) список дополнительных файлов в папке книги data/. Если указан необязательный параметр pattern, регулярное выражение, то список фильтруется для файлов, соответствующих pattern. Сопоставление с pattern нечувствительно к регистру. См. также функции has_extra_files(), extra_file_modtime() и extra_file_size(). Эту функцию можно использовать только в GUI и контент-сервере.

extra_file_size ¶

class calibre.utils.formatter_functions.BuiltinExtraFileSize[исходный код]¶

extra_file_size(file_name) – возвращает размер в байтах дополнительного файла file_name в папке data/ книги, если он существует, иначе -1. См. также функции has_extra_files(), extra_file_names() и extra_file_modtime(). Эту функцию можно использовать только в GUI и контент-сервере.

get_link ¶

class calibre.utils.formatter_functions.BuiltinGetLink[исходный код]¶

get_link(field_name, field_value) – извлечь ссылку для поля field_name со значением field_value. Если прикрепленной ссылки нет, вернуть пустую строку. Примеры:

Следующее возвращает ссылку, прикрепленную к тегу Fiction:
```
get_link('tags', 'Fiction')
```
Этот шаблон создаёт список ссылок для всех тегов, связанных с книгой в форме value:link, ...:
```
program:
ans = '';
for t in $tags:
l = get_link('tags', t);
if l then
ans = list_join(', ', ans, ',', t & ':' & get_link('tags', t), ',')
fi
rof;
ans
```

Эта функция работает только в графическом интерфейсе и на сервере контента.

get_note ¶

class calibre.utils.formatter_functions.BuiltinGetNote[исходный код]¶

get_note(field_name, field_value, plain_text) – получить примечание для поля field_name со значением field_value. Если plain_text пустой, вернуть HTML примечания. Если „plain_text“ 1 (или '1'), вернуть простой текст примечания. Если примечание не существует, вернуть „“ (пустая строка) в обоих случаях. Пример:

has_extra_files ¶

class calibre.utils.formatter_functions.BuiltinHasExtraFiles[исходный код]¶

has_extra_files([pattern]) – возвращает количество дополнительных файлов, иначе „“ (пустая строка). Если указан необязательный параметр pattern (регулярное выражение), то список фильтруется по файлам, которые соответствуют pattern, прежде чем файлы будут подсчитаны. Сопоставление с pattern нечувствительно к регистру. См. также функции extra_file_names(), extra_file_size() и extra_file_modtime(). Можно использовать только в GUI и контент-сервере.

has_note ¶

class calibre.utils.formatter_functions.BuiltinHasNote[исходный код]¶

has_note(field_name, field_value). Проверьте, есть ли в поле примечание. Эта функция имеет два варианта:

если field_value не '' (пустая строка) вернуть '1' если значение field_value в поле field_name имеет примечание, иначе ''. Если field_value равно '', то вернуть список значений в field_name у которых есть примечание. Если ни у одного элемента в поле нет примечания, вернуть ''. Этот вариант полезен для отображения значков столбцов, если какое-либо значение в поле имеет примечание, а не конкретное значение. Пример: has_note('authors', '') возвращает список авторов имеющих примечания или '' если нет авторов с примечаниями.

Вы можете проверить, все ли значения в field_name имеют примечание, сравнив длину списка возвращаемого значения этой функции с длиной списка значений в field_name. Пример:

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

Можно использовать только в GUI и контент-сервере.

Функции даты ¶

date_arithmetic ¶

class calibre.utils.formatter_functions.BuiltinDateArithmetic[исходный код]¶

„“date_arithmetic(value, calc_spec, fmt)““ – вычислить новую дату от value с помощью calc_spec. Вернуть новую дату, отформатированную в соответствии с необязательным fmt: если не указано, то результат будет в формате ISO. Строка calc_spec - конкатенация пар „vW“ (valueWhat), где v - возможно отрицательное число, а W - одна из следующих букв:

s: добавить v добавить к date
m: добавить v минут к date
h: добавить v часов к date
d: добавить v дней к date
w: добавить v недель к date
y: добавить v лет к date, где год это 365 дней.

Пример: '1s3d-1m' добавит 1 секунду, прибавит 3 дня и вычтет 1 минуту из date.

days_between ¶

class calibre.utils.formatter_functions.BuiltinDaysBetween[исходный код]¶

days_between(date1, date2) – возвращает количество дней между date1 и date2. Число положительно, если date1 больше date2, в противном случае отрицательно. Если date1 или date2 не являются датой, функция возвращает пустую строку.

today ¶

class calibre.utils.formatter_functions.BuiltinToday[исходный код]¶

today() – возвращает текущий день в виде строки. Это значение предназначено для использования в format_date или days_between, но можно использовать как и любую другую строку. Дата в формате ISO

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=('Неизвестный',), other=None, template_cache=None, formatter=None)[исходный код]¶

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)[исходный код]¶

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>>)[исходный код]¶: 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()[исходный код]¶: 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)[исходный код]¶: Set all identifiers. Note that if you previously set ISBN, calling this method will delete it.

set_identifier(typ, val)[исходный код]¶: If val is empty, deletes identifier of type typ

standard_field_keys()[исходный код]¶: return a list of all possible keys, even if this book doesn’t have them

custom_field_keys()[исходный код]¶: return a list of the custom fields in this book

all_field_keys()[исходный код]¶: All field keys known by this instance, even if their value is None

metadata_for_field(key)[исходный код]¶: return metadata describing a standard or custom field.

all_non_none_fields()[исходный код]¶: Return a dictionary containing all non-None metadata fields, including the custom ones.

get_standard_metadata(field, make_copy)[исходный код]¶: 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)[исходный код]¶: return a dict containing all the standard field metadata associated with the book.

get_all_user_metadata(make_copy)[исходный код]¶: return a dict containing all the custom field metadata associated with the book.

get_user_metadata(field, make_copy)[исходный код]¶: 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)[исходный код]¶: store custom field metadata into the object. Field is the key name not the label

set_user_metadata(field, metadata)[исходный код]¶: store custom field metadata for one column into the object. Field is the key name not the label

remove_stale_user_metadata(other_mi)[исходный код]¶: 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)[исходный код]¶: 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)[исходный код]¶: 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)[исходный код]¶: Returns the tuple (display_name, formatted_value)

to_html()[исходный код]¶: 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