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

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

ceiling(x)

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

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

divide(x, y)

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

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

floor(x)

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

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

fractional_part(x)

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

fractional_part(x) – возвращает значение после десятичной точки. Например, дробная_часть (3.14) возвращает 0.14. Выдает исключение, если x не является числом.

mod (x)

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

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

multiply(x [, y]*)

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

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

round(x)

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

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

subtract(x, y)

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

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

Boolean

and(value [, value]*)

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

and(value [, value]*) – возвращает строку «1», если все значения не пустые, в противном случае возвращает пустую строку. Эта функция хорошо работает с test или first_non_empty. Вы можете иметь сколько угодно значений. Во многих случаях оператор && может заменить эту функцию.

not(value)

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

not(value) – возвращает строку «1», если значение пусто, в противном случае возвращает пустую строку. Эта функция хорошо работает с test или first_non_empty. Во многих случаях ! оператор может заменить эту функцию.

or(value [, value]*)

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

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

Date functions

date_arithmetic(date, calc_spec, fmt)

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

date_arithmetic(date, calc_spec, fmt) – вычислить новую дату от „date“ с помощью „calc_spec“. Вернуть новую дату, отформатированную в соответствии с необязательным „fmt“: если не указано, то результат будет в формате iso. Calc_spec - это строка, образованная конкатенацией пар „vW“ (valueWhat), где „v“ - возможно отрицательное число, а W - одна из следующих букв: s: добавить „v“ секунд к „date“ m: add „ v „минут до“ date „h: добавить“ v „часов к“ date „d: добавить“ v „дней к“ date „w: добавить“ v „недель к“ date „y: добавить“ v „лет к“ date „, где в году 365 дней. Пример: «1s3d-1m» добавит 1 секунду, прибавит 3 дня и вычтет 1 минуту из „date“.

days_between(date1, date2)

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.

Formatting values

Format_number (v, template)

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

Format_number (v, template) – форматирование числа v с использованием шаблона форматирования Python, подобного «{0:5.2f}» или «{0:,d}» или «${0:5,.2f}». Элемент field_name шаблона должен быть 0 (ноль) (см. «{0:» в примерах выше). См. Язык шаблонов и документацию Python для получения более подробной информации. Вы можете оставить ведущий «{0:» и конечный «}» если шаблон содержит только формат. Возвращает пустую строку, если форматирование не выполняется.

finish_formatting(значение, формат, префикс, суффикс)

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

finish_formatting(значение, формат, префикс, суффикс) – применяет формат, префикс и суффикс к значению так же, как в шаблоне вроде {series_index:05.2f| - |- }. Например, следующая программа делает то же, что и указанный шаблон: program: finish_formatting(field(«series_index»), «05.2f», » - «, » - «)

format_date (val, format_string)

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

format_date (val, format_string) - отформатируйте значение, которое должно быть датой, используя format_string, возвращая строку. Коды форматирования: d: день в виде числа без нуля в начале (от 1 до 31) dd: день в виде числа с нулем в начале (от 01 до 31) ddd: сокращенное локализованное название дня (например, от „Mon“ до „Sun“ „). dddd: длинное локализованное название дня (например, с понедельника по воскресенье). M: месяц как число без нуля в начале (от 1 до 12). MM: месяц в виде числа с нулем в начале (от 01 до 12) MMM: сокращенное локализованное название месяца (например, от «Янв» до «Декабрь»). MMMM: длинное локализованное название месяца (например, с января по декабрь). yy: год в виде двузначного числа (от 00 до 99). гггг: год в виде четырехзначного числа. h: часы без начального 0 (от 0 до 11 или от 0 до 23, в зависимости от am / pm) hh: часы с начальным 0 (от 00 до 11 или от 00 до 23, в зависимости от am / pm) m: минуты без ведущего 0 (от 0 до 59) мм: минуты с ведущим 0 (от 00 до 59) s: секунды без ведущего 0 (от 0 до 59) ss: секунды с ведущим 0 (от 00 до 59) ap: используйте 12-часовые часы вместо 24-часовых, с заменой ap на локализованную строку для am или pm AP: используйте 12-часовые часы вместо 24-часовых, с заменой AP на локализованная строка для AM или PM iso: дата с указанием времени и часового пояса. Должен быть единственный присутствующий формат to_number: дата как число с плавающей запятой from_number [: fmt]: форматировать временную метку, используя fmt, если есть, в противном случае iso

human_readable(v)

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

human_readable(v) – возвращает строку, представляющюю число v в виде KB, MB, GB, и т.д.

rating_to_stars(value, use_half_stars)

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

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

Get values from metadata

annotation_count()

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

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

approximate_formats()

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

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

author_sorts(val_separator)

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

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

connected_device_name(storage_location)

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

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

connected_device_uuid(storage_location)

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

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

current_library_name()

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

current_library_name() – возвращает последнее имя в пути к текущей библиотеке. Эта функция может быть вызвана в режиме программирования шаблона с помощью шаблона «{:“current_library_name()“}».

current_library_path()

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

current_library_path() – возвращает путь к текущей библиотеке calibre. Эта функция может быть вызвана в режиме создания шаблона с помощью шаблона «{:“current_library_path()“}».

field(lookup_name)

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

field(lookup_name) – возвращает поле метаданных с именем lookup_name

formats_modtimes(date_format)

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

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

formats_paths()

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

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

formats_sizes()

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

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

has_cover()

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

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

is_marked ()

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

is_marked () - проверить, помечена ли книга calibre. Если это так, то вернуть значение метки, либо «true», либо список именованных меток, разделенных запятыми. Возврат „“, если книга не отмечена.

language_codes(lang_strings)

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

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

language_strings(lang_codes, localize)

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

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

ondevice()

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

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

raw_field(lookup_name [, optional_default])

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

raw_field(lookup_name [, optional_default]) – возвращает поле метаданных с именем lookup_name без применения форматирования. Он оценивает и возвращает необязательный второй аргумент „default“, если поле не определено („None“).

raw_list(lookup_name, separator)

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

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

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

If-then-else

check_yes_no(field_name, is_undefined, is_false, is_true)

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. Эта функция обычно используется функциями test() или is_empty().

contains(val, pattern, text if match, text if not match)

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

contains(val, pattern, text if match, text if not match) – проверяет, содержит ли значение val соответствия с регулярным выражением pattern. Возвращает text if match если найдены соответствия, иначе возвращает text if no match

field_exists (field_name)

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

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

ifempty(val, text if empty)

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

ifempty(val, text if empty) – возвращает значение, если оно не является пустым, иначе возвращает text if empty

test(val, text if not empty, text if empty)

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

test(val, text if not empty, text if empty) – возвращает text if not empty если значение val не пустое, иначе возвращает text if empty

Iterating over values

first_non_empty(value [, value]*)

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

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

lookup(val, [pattern, field,]+ else_field)

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

lookup(val, [pattern, field,]+ else_field) – как switch, за исключением того, что аргументы - это имена полей (метаданных), а не текст. Будет извлечено и использовано значение соответствующего поля. Обратите внимание: поскольку составные столбцы являются полями, вы можете использовать эту функцию в одном составном поле, чтобы использовать значение другого составного поля. Это чрезвычайно полезно при создании переменных путей сохранения.

switch(val, [pattern, value,]+ else_value)

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

switch(val, [pattern, value,]+ else_value) – для каждой пары pattern, value проверяет, соответствует ли val регулярному выражению pattern и, если да, возвращает это value. Если ни один шаблон не совпадает, возвращается else_value. Вы можете иметь столько пар pattern, value, сколько хотите.

List lookup

identifier_in_list(val, id, found_val, not_found_val)

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

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

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

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

in_list(val, separator, [ pattern, found_val, ]+ not_found_val) – обработка val как списка элементов, разделенных разделителем, если шаблон соответствует любому из значений списка, возвращается found_val. Если шаблон не соответствует ни одному значению списка, возвращается not_found_val. Пары шаблон и найденное_значение можно повторять сколько угодно раз. Шаблоны проверяются по порядку. Возвращается found_val для первого совпадения. Псевдонимы: in_list(), list_contains()

list_item(val, index, separator)

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

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

select(val, key)

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

select(val, key) – интерпретировать значение как список элементов, разделенных запятыми, с элементами «id: value». Найти пару с идентификатором, равным ключу, и вернуть соответствующее значение. Возвращает пустую строку, если совпадение не найдено.

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

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

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

List manipulation

count (val, separator)

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

count (val, separator) - интерпретирует значение как список элементов, разделенных separator, возвращая количество элементов в списке. В большинстве списков в качестве разделителя используется запятая, но авторы используют амперсанд. Примеры: {tags:count(,)}, {authors:count (&)}. Псевдонимы: count(), list_count()

list_count_matching (список, шаблон, разделитель)

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

list_count_matching (список, шаблон, разделитель) - интерпретирует «список» как список элементов, разделенных «разделителем», возвращая количество элементов в списке, которые соответствуют регулярному выражению «шаблон». Псевдонимы: list_count_matching(), count_matching()

list_difference(list1, list2, separator)

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

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

list_equals(list1, sep1, list2, sep2, yes_val, no_val)

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(list1, list2, separator)

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

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

list_re(src_list, separator, include_re, opt_replace)

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

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

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

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

list_re_group(src_list, separator, include_re, search_re [, group_template]+) – Как и list_re, за исключением того, что замены не являются обязательными. Он использует re_group (list_item, search_re, group_template, …) при выполнении замен в результирующем списке.

list_remove_duplicates (список, разделитель)

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

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

list_sort(list, direction, separator)

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

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

list_union (list1, list2, separator)

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

list_union (list1, list2, separator) - возвращает список, составленный путем слияния элементов в list1 и list2, удаляя повторяющиеся элементы с помощью сравнения без учета регистра. Если элементы отличаются регистром, используется значение из списка list1. Элементы в списках list1 и list2 разделены разделителем, как и элементы в возвращаемом списке. Псевдонимы: list_union(), merge_lists()

subitems(val, start_index, end_index)

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

subitems(val, start_index, end_index) – разбивает список элементов (например, жанры). Принимает значение в виде списка элементов, разделённых запятой, где каждый элемент — это список элементов разделённых точкой. Возвращает новый список следующим образом: вначале находятся все элементы, разделённые точкой, затем для каждого такого элемента извлекаются компоненты с start_index по end_index, затем объединённый результат возвращается вместе. Первый компонент в списке, разделённом точками, имеет номер индекса - 0 (ноль). Если номер отрицательный, то счёт идёт с конца списка. Если end_index равен 0 (ноль), то обработка идёт до конца списка. Например, используя основной режим шаблона и присвоив #genre (жанру) значение «A.B.C» используя: {#genre:subitems(0,1)} получим «A». {#genre:subitems(0,2)} возвращает «A.B». {#genre:subitems(1,0)} возвращает «B.C». Присвоив #genre (жанру) значение «A.B.C, D.E.F», {#genre:subitems(0,1)} получим «A, D». {#genre:subitems(0,2)} возвращает «A.B, D.E»

sublist(val, start_index, end_index, separator)

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

sublist(val, start_index, end_index, separator) – интерпретирует значение как список значений, разделённых separator, возвращая новый список с началом в start_index с концом в end_index. Первый пункт - номер 0 (ноль). Если индекс - отрицательный, то его начало - от конца списка. В особых случаях end_index нуля считается длиной списка. Примеры, использующие режим базового шаблона и предополагающие что столбец тегов (разделённый запятыми) содержит «A, B, C»: {tags:sublist(0,1,\,)} возвращает «A». {tags:sublist(-1,0,\,)} возвращает «C». {tags:sublist(0,-1,\,)} возвращает «A, B».

Other

assign(id, val)

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

assign(id, val) – присваивает val идентификатору, затем возвращает val. id должен быть идентификатором, а не выражением. Эту функцию часто можно заменить оператором =.

Recursion

eval(template)

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

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

template(x)

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

template(x) – обрабатывает x как шаблон. Сравнение выполняется в контексте, то есть переменные не передаются между вызовом и обрабатываемым шаблоном. Так как символы { и } специальные, вы должны использовать [[ вместо { и ]] вместо }; они преобразуются автоматически. Например, шаблон („[[title_sort]]“) будет опознан как {title_sort} и будет возвращено его значение. Помните также, что префиксы и суффиксы (синтаксис |prefix|suffix) не могут быть использованы в аргументе этой функции в режиме создания шаблона.

Relational

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

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

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

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

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

first_matching_cmp(val, [cmp1, result1,]+, else_result) - последовательно сравнивает «val < cmpN», возвращая resultN для первого успешного сравнения. Если сравнение не удалось, возвращает else_result. Пример: first_matching_cmp(10,5,»small»,10,»middle»,15,»large»,»giant») возвращает значение «large». В том же примере с первым значением 16 возвращается «giant».

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

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

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

String case changes

capitalize(val)

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

capitalize(val) – возвращает val в режиме предложения (первая буква текста заглавная)

lowercase(val)

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

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

titlecase(val)

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

titlecase(val) – возвращает val в титульном регистре (первые буквы каждого слова заглавные)

uppercase(val)

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

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

String manipulation

character(character_name)

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

character(character_name) - возвращает символ, названный character_name. Например, символ („newline) возвращает символ новой строки („n“). Поддерживаемые имена символов: „newline“, „return“, „tab“, и „backslash“.

re(val, pattern, replacement)

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

re(val, pattern, replacement) – возвращает значение после применения регулярного выражения. Все вхождения pattern заменятся на replacement. Как везде в calibre, это Python-совместимые регулярные выражения

re_group(val, pattern [, template_for_group]*)

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

re_group(val, pattern [, template_for_group]*) – вернуть строку, полученную путем применения шаблона регулярного выражения к val и замены каждого сопоставленного экземпляра строкой, вычисленной путем замены каждой сопоставленной группы значением, возвращаемым соответствующим шаблоном. Исходное совпадающее значение для группы доступно как $. В программном режиме шаблона, как и в случае с шаблоном и функциями eval, вы используете [[ for { and ]] for }. В следующем примере в режиме шаблонной программы выполняется поиск серий, содержащих более одного слова, и первое слово заглавными буквами: {series:“re_group($, «(S* )(.*)», «[[$:uppercase()]]», «[[$]]»)“}

shorten(val, left chars, middle text, right chars)

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

shorten(val, left chars, middle text, right chars) – возвращает сокращённую версию значения val, состоящую из left chars символов от начала val, за которыми следует middle text, за которыми следует right chars символов от конца строки. Left chars и right chars должны быть целыми числами. Например, предположим, что заголовок книги - Ancient English Laws in the Times of Ivanhoe, и вы хотите сократить его как минимум до 15 символов. Если вы используете {title:shorten(9,-,5)}, В результате получится Ancient E-nhoe. Если длина поля меньше, чем left chars + right chars + длина middle text, то поле будет использоваться без изменений. Например заголовок The Dome не изменится.

strcat(a [, b]*)

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

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

strcat_max(max, string1 [, prefix2, string2]*)

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

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

strlen(a)

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

strlen(a) – Возвращает длину строки, переданной в качестве аргумента

substr(str, start, end)

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

substr(str, start, end) – возвращает подстроку - символы строки (str) от start до end. Первый символ строки (str) имеет номер ноль. Если конец отрицательный - это сколько символов будет отсчитываться с конца строки (справа). Если конец равен 0 (ноль), то это - последний символ строки. Например, substr(„12345“, 1, 0) вернёт „2345“, и substr(„12345“, 1, -1) вернёт „234“.

swap_around_articles(val, separator)

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

swap_around_articles(val, separator) – возвращает val со статьями, перемещенными в конец. Значением может быть список, в этом случае обрабатывается каждый элемент списка. Если значение является списком, то нужно указать разделитель значений списка (separator). Если разделитель не указан, то указанное значение рассматривается как одно значение, а не как список.

swap_around_comma (значение)

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

swap_around_comma (значение) – получает значение «B, A», возвращает «A B». Это особенно полезно для преобразования имен из «AB, AC» в формат «AC AB». Если нет запятой, то функция возвращает значение без изменений

transliterate(a)

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

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

other

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

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

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

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

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

globals(id[=expression] [, id[=expression]]*) - извлекает «глобальные переменные», которые могут быть переданы в форматтер. Как объявляет, так и инициализирует локальные переменные с именами переданными глобальными переменными. Если соответствующая переменная не предоставляется в переданных глобальных, то этой переменной присваивается предоставленное значение по умолчанию. Если значение по умолчанию отсутствует, переменная устанавливается в пустую строку.

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.

__docformat__ = 'restructuredtext en'

'''
All fields must have a NULL value represented as None for simple types,
an empty list/dictionary for complex types and (None, None) for cover_data
'''

SOCIAL_METADATA_FIELDS = frozenset((
    'tags',             # Ordered list
    'rating',           # A floating point number between 0 and 10
    'comments',         # A simple HTML enabled string
    'series',           # A simple string
    'series_index',     # A floating point number
    # Of the form { scheme1:value1, scheme2:value2}
    # For example: {'isbn':'123456789', 'doi':'xxxx', ... }
    'identifiers',
))

'''
The list of names that convert to identifiers when in get and set.
'''

TOP_LEVEL_IDENTIFIERS = frozenset((
    'isbn',
))

PUBLICATION_METADATA_FIELDS = frozenset((
    'title',            # title must never be None. Should be _('Unknown')
    # Pseudo field that can be set, but if not set is auto generated
    # from title and languages
    'title_sort',
    'authors',          # Ordered list. Must never be None, can be [_('Unknown')]
    'author_sort_map',  # Map of sort strings for each author
    # Pseudo field that can be set, but if not set is auto generated
    # from authors and languages
    'author_sort',
    'book_producer',
    'timestamp',        # Dates and times must be timezone aware
    'pubdate',
    'last_modified',
    'rights',
    # So far only known publication type is periodical:calibre
    # If None, means book
    'publication_type',
    'uuid',             # A UUID usually of type 4
    'languages',        # ordered list of languages in this publication
    'publisher',        # Simple string, no special semantics
    # Absolute path to image file encoded in filesystem_encoding
    'cover',
    # Of the form (format, data) where format is, for e.g. 'jpeg', 'png', 'gif'...
    'cover_data',
    # Either thumbnail data, or an object with the attribute
    # image_path which is the path to an image file, encoded
    # in filesystem_encoding
    'thumbnail',
))

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

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

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

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

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

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

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

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

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

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