Змінити мову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.
Інше¶
arguments¶
arguments(ідентифікатор[=вираз] [, ідентифікатор[=вираз]]*) — використовується у збереженому шаблоні для отримання аргументів за допомогою виклику. Ця функція одразу оголошує і ініціалізує локальні змінні, які виконують роль параметрів. Ці змінні є позиційними — їм надається значення, яке стоїть у виклику на відповідній позиції. Якщо відповідне значення змінної не було надано у виклику, arguments() надає параметру типового значення. Якщо типове значення не вказано, змінній буде надано значення порожнього рядка.
assign¶
assign(ідентифікатор, значення) — надає ідентифікатору значення, потім повертає значення. ідентифікатор має бути ідентифікатором, а не виразом. У більшості випадків можна замість цієї функції використовувати оператор =.
globals¶
globals(ідентифікатор[=вираз] [, ідентифікатор[=вираз]]*) — отримує «загальні змінні», які можна передати засобу форматування. Ця функція одразу оголошує і ініціалізує локальні змінні назвами переданих загальних змінних. Якщо відповідне значення змінної не було надано у у переданих загальних змінних, надає змінній типового значення. Якщо типове значення не вказано, змінній буде надано значення порожнього рядка.
is_dark_mode¶
is_dark_mode() – повертає 1' якщо calibre запущено у темному режимі, і '' (порожній рядок) в усіх інших випадках. Цією функцією можна скористатися у розгорнутих правилах використання кольорів і піктограм для вибору інших кольорів/піктограм, відповідно до режиму. Приклад:
if is_dark_mode() then 'dark.png' else 'light.png' fi
print¶
print(a [, b]*) — виводить аргументи до стандартного виведення. Якщо ви не запускали calibre з командного рядка (calibre-debug -g), дані нікуди не буде виведено. Функція print завжди повертає свій перший аргумент.
set_globals¶
set_globals(ідентифікатор[=вираз] [, ідентифікатор[=вираз]]*) — встановлює значення для «загальних змінних», які можна передавати засобу форматування. Загальні змінні вказують за назвою переданого ідентифікатора. Буде використано значення ідентифікатора, якщо не вказано виразу.
Ітерація значеннями¶
first_non_empty¶
first_non_empty(значення [, значення]*) — повертає перше значення, яке не є порожнім.. Якщо всі значення є порожніми, повертає порожній рядок. Ви можете вказати довільну кількість значень.
lookup¶
lookup(значення, [ взірець, ключ, ]* інший_ключ) — буде виконано встановлення відповідності значення взірцям за порядком. Якщо взірець є відповідним, буде повернуто значення поля, яке вказано назвою key. Якщо взірець не є відповідним, буде повернуто значення поля інший_ключ. Див. switch().
switch¶
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 CODE_TEXT on line 2 in «switch»
switch_if¶
switch_if([вираз_перевірки, вираз_значення,]+ альтернативний_вираз) — для кожної пари вираз_перевірки, вираз_значення перевіряє, чи дорівнює вираз_перевірки True (непорожнє значення) і, якщо це так, повертає результат вираз_значення. Якщо жоден вираз_перевірки не дорівнює True, буде повернуто альтернативний_вираз. Можлива кількість пар вираз_перевірки, вираз_значення є необмеженою.
Арифметичні¶
add¶
add(x [, y]*) — повертає суму своїх аргументів. Видає виключення, якщо аргумент не є числом. У більшості випадків ви можете скористатися замість цієї функції оператором +.
ceiling¶
ceiling(значення) — повертає найменше ціле число, яке є більшим або рівним значення. Надсилає виключення, якщо значення не є числом.
divide¶
divide(x, y) — повертає частку x / y. Повідомляє про виключення, якщо x або y не є числом. Зазвичай, цю функцію можна замінити оператором /.
floor¶
floor(значення) — повертає найбільше ціле число, яке є меншим або рівним значення. Надсилає виключення, якщо значення не є числом.
fractional_part¶
fractional_part(значення) — повертає дробову частину десяткового числа. Наприклад, fractional_part(3.14) дорівнює 0.14. Надсилає виключення, якщо значення не є числом.
mod¶
mod(значення, y) — повертає floor від лишку від ділення значення / y. Повідомляє про виключення, якщо значення або y не є числом.
multiply¶
multiply(x [, y]*) — повертає добуток аргументів. Надсилає повідомлення про виключення, якщо аргумент не є числом. Зазвичай, цю функцію можна замінити оператором *.
round¶
round(значення) — повертає найближче до значення ціле число. Надсилає виключення, якщо значення не є числом.
subtract¶
subtract(x, y) — повертає різницю x - y. Повідомляє про виключення, якщо x або y не є числом. Зазвичай, цю функцію можна замінити оператором -.
База даних¶
book_count¶
book_count(запит, вик_вб) – повертає кількість книг, які було знайдено під час пошуку за запитом запит. Якщо значенням вик_вб є 0 (нуль) віртуальні бібліотеки буде проігноровано. Ця функція і її двійник book_values(), зокрема, корисні у шаблонних пошуках, реалізуючи підтримку пошуків, у яких поєднуються дані з багатьох книг, зокрема пошуку циклів з лише однієї книги. Не можна використовувати у складених стовпчиках, якщо для allow_template_database_functions_in_composites не встановлено значення True. Можна використовувати лише з графічного інтерфейсу.
Наприклад, у цьому шаблонному пошуку використано цю функцію і її двійника для пошуку усіх циклів з лише однією книгою:
Визначіть збережений шаблон (за допомогою пункту Налаштування → Додатково → Шаблонні функції) із назвою
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"Використання збереженого шаблона замість вставлення шаблона до пошуку усуває проблеми, які спричинено потребою в екрануванні лапок у виразах для пошуку.
book_values¶
book_values(стовпчик, запит, роздільник, використати_віртуальні) — повертає список неповторюваних значень, що містяться у стовпчику стовпчик (назві пошуку), відокремлені роздільником роздільник, у книгах, які було знайдено за запитом запит. Якщо значенням використати_віртуальні є 0 (нуль), віртуальні бібліотеки буде проігноровано. Ця функція і подібна до неї функція book_count() корисні, зокрема, у шаблонних пошуках, де передбачено підтримку пошуків, які поєднують відомості з багатьох книг, наприклад, пошуків циклів, де є лише одна книга. Функцією не можна користуватися у складених стовпчиках, якщо для коригування allow_template_database_functions_in_composites не встановлено значення True. Можна використовувати лише у графічному інтерфейсі.
extra_file_modtime¶
extra_file_modtime(назва_файла, рядок_формату) — повертає час внесення змін до додаткового файла назва_файла у теці data/ книги, якщо він існує. Якщо файла не існує, повертає -1. Час внесення змін буде форматовано відповідно до рядка формату (див. format_date()). Якщо специфікатор формату є порожнім, повертає час внесення змін як десятковий дріб секунд з початку епохи. Див. також функції has_extra_files(), extra_file_names() та extra_file_size(). Значення епохи є специфічним для операційної системи. Цією функцією можна скористатися лише у графічному інтерфейсі.
extra_file_names¶
extra_file_names(роздільник[, взірець]) — список відокремлених роздільником назв файлів у теці data/ книги. Якщо вказано необов’язковий параметр «взірець», формальний вираз, список буде відфільтровано до файлів, які відповідають взірцю. Відповідність визначатиметься без врахування регістру символів. Див. також функції has_extra_files(), extra_file_modtime() та extra_file_size(). Цією функцією можна скористатися лише у графічному інтерфейсі.
extra_file_size¶
extra_file_size(назва_файла) — повертає розмір у байтах додаткового файла «назва_файла» у теці «data/» книги, якщо він існує. Якщо файла не існує, повертає -1. Див. також функції has_extra_files(), extra_file_names() та extra_file_modtime().. Цією функцією можна скористатися лише у графічному інтерфейсі.
get_link¶
get_link(назва_поля, значення_поля) – отримати посилання для поля назва_поля зі значенням значення_поля. Якщо пов’язаного посилання немає, буде повернуто порожній рядок. Приклади:
Повертає посилання, яке пов’язано із міткою
Fiction:get_link('tags', 'Fiction')
Цей шаблон створює список посилань для усіх міток, які пов’язано із книгою, у форматі
значення:посилання, ...: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¶
get_note(назва_поля, значення_поля, звичайний_текст) — отримати нотатку для поля назва_поля зі значенням значення_поля. Якщо «звичайний_текст» є порожнім, повертає HTML нотатки із включеними зображеннями. Якщо «звичайний_текст» дорівнює 1 (або „1“), повертає звичайний текст нотатки. Якщо нотатки не існує, повертає порожній рядок в обох випадках. Приклад:
Повертає HTML-код нотатки, яку пов’язано із міткою Fiction:
program: get_note('tags', 'Fiction', '')
Повертає звичайний текст нотатки, яку пов’язано із автором Isaac Asimov:
program: get_note('authors', 'Isaac Asimov', 1)
has_extra_files¶
has_extra_files([взірець]) — повертає кількість додаткових файлів, якщо такі є. Якщо файлів немає, повертає „“ (порожній рядок). Якщо вказано необов’язковий параметр «взірець» (формальний вираз), список, перш ніж буде виконано обчислення кількості, буде відфільтровано до файлів, які відповідають взірцю. Відповідність визначатиметься без врахування регістру символів. Див. також функції extra_file_names(), extra_file_size() та extra_file_modtime(). Цією функцією можна скористатися лише у графічному інтерфейсі.
has_note¶
has_note(назва_поля, значення_поля). Ця функція має два варіанти:
якщо
значення_поляне дорівнює''(порожньому рядку), повертає „1“, якщо значення „значення_поля“ у полі „назва_поля“ має долучену нотатку. Якщо це не так, повертає''.Приклад:
has_note('tags', 'Fiction')повертає'1', якщо міткаfictionмає нотатку, інакше повертає''.якщо
значення_полядорівнює'', повертає список значень у поліназва_поля, які містять нотатки. Якщо жодний запис у полі не містить нотатки, повертає''.Приклад:
has_note('authors', '')повертає список авторів, записи яких мають нотатки або'', якщо жоден запис не має нотатки.
Ви можете перевірити, чи всі значення мають нотатку шляхом порівняння довжини списку з повернутого цією функцією із довжиною списку значень поля назва_поля. Приклад:
list_count(has_note('authors', ''), '&') ==# list_count_field('authors')
Булеві¶
and¶
and(значення [, значення]*) — повертає рядок «1», якщо усі значення не є порожніми, інакше повертає порожній рядок.. Кількість значень може бути довільною. У більшості випадків замість цієї функції можна скористатися оператором &&. Однією з причин не замінювати and на && є випадки, коли оптимізація обчислення може змінити результати через сторонні ефекти. Наприклад, and(a='',b=5) виконує обидва записи значень, а оператор && не виконає другого з них.
not¶
not(значення) — повертає рядок «1», якщо значення не є порожнім. Якщо значення є порожнім, повертає порожній рядок.. Зазвичай, цю функцію можна замінити на унарний оператор «НІ» (!).
or¶
or(значення [, значення]*) — повертає рядок "'1", якщо хоч одне значення не є порожнім. Якщо всі значення є порожніми, повертає порожній рядок.. Кількість значень може бути довільною. Зазвичай, цю функцію можна замінити оператором ||. Причиною того, що її не можна замінити, є те, що при оптимізації обчислення може бути змінено результати через сторонні ефекти.
Відносні¶
cmp¶
cmp(value, y, lt, eq, gt) – compares value and y after converting both to numbers. Returns lt if value <# y, eq if value ==# y, otherwise gt. This function can usually be replaced with one of the numeric compare operators (==#, <#, >#, etc).
Буде показано документацію англійською через помилку FFML: Missing closing «`» for italics on line 2 in «cmp»
first_matching_cmp¶
first_matching_cmp(значення, [умова, результат,]* інший_результат) — послідовно виконує порівняння «значення < умова», повертаючи результат для першої з виконаних умов у послідовності. Повертає інший_результат, якщо жодну з умов не буде виконано.
Приклад:
i = 10;
first_matching_cmp(i,5,"small",10,"middle",15,"large","giant")
повертає "large". Якщо у тому самому прикладі перше зі значень дорівнюватиме 16, буде повернуто "giant".
strcmp¶
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 CODE_TEXT on line 2 in «strcmp»
strcmpcase¶
strcmpcase(x, y, lt, eq, gt) – виконує лексичне порівнння x і y із врахуванням регістру символів. Повертає``lt``, якщо x < y, eq, якщо x == y, інакше повертає gt.
Зауваження: ця поведінка НЕ є типовою для calibre, наприклад в операторах лексичного порівняння (==, >, < тощо). Використання цієї функції може призвести до несподіваних результатів; варто користуватися strcmp() там, де це можливе.
Дата і час¶
date_arithmetic¶
date_arithmetic(дата, специфікація_обчислень, формат) — обчислення нової дати на основі дати «дата» з використанням «специфікації_обчислень».. Повертає нову дату, форматовану відповідно до додаткового параметра «формат». Якщо формат не вказано, результат буде виведено у форматі ISO. Параметр специфікація_обчислень є рядком, який сформовано поєднанням пар «зО» (значенняОперація), де «з» є можливо від’ємним числом, а «О» є однією з таких літер:
s— додати «з» секунд до значення «дата»;m— додати «з» хвилин до значення «дата»;h— додати «з» годин до значення «дата»;d— додати «з» днів до значення «дата»;w— додати «з» тижнів до значення «дата»;y— додати «з» років до значення «дата», де роком вважаються 365 днів.
Приклад: «1s3d-1m» — додати 1 секунду, додати 3 дні і відняти 1 хвилину від дати «дата».
days_between¶
days_between(date1, date2) – return the number of days between date1 and date2. The number is positive if date1 is greater than date2, otherwise negative. If either date1 or date2 are not dates, the function returns the empty string.
Буде показано документацію англійською через помилку FFML: Missing closing «``» for CODE_TEXT on line 2 in «days_between»
today¶
today() — повертає сьогоднішню дату і час (зараз).. Це значення створено для використання у format_date або days_between, але з ним можна працювати як зі звичайним рядком. Дату буде повернуто у форматі ISO.
Зміна регістру символів¶
capitalize¶
capitalize() – повертає значення поля так, що кожне слово у результаті починатиметься з великої літери, а решта літер слів будуть малими.
lowercase¶
lowercase(значення) — повернути значення малими літерами.
titlecase¶
titlecase(значення) — повернути значення у регістрі заголовка.
uppercase¶
„“uppercase(значення)““ — повернути значення великими літерами.
Отримання значень з метаданих¶
annotation_count¶
annotation_count() — повертає загальну кількість анотацій усіх типів, які пов’язано із поточною книгою.. Ця функція працює лише із графічним інтерфейсом користувача.
approximate_formats¶
approximate_formats() — повернути розділений комами список форматів, які на певному етапі було пов’язано з книгою. Гарантувати чинність такого списку не можна, хоча, ймовірно, він залишається чинним. Зауважте, що назви форматів завжди слід вказувати великими літерами, ось так: EPUB. Функція approximate_formats() є набагато швидшою за функції formats_.... Скористатися цією функцією можна лише за використання графічного інтерфейсу. Якщо ви хочете скористатися отриманими значенням у шаблонах збереження на диск або надсилання на пристрій, вам слід створити нетиповий стовпчик «Стовпчик, створений на основі інших стовпчиків», скористатися у шаблоні створеного стовпчика цією функцією, а потім скористатися значенням у стовпчику у вашому шаблоні збереження або надсилання.
booksize¶
booksize() – returns the value of the calibre size field. Returns „“ if the book has no formats.
This function works only in the GUI. If you want to use this value in save-to-disk or send-to-device templates then you must make a custom «Column built from other columns», use the function in that column’s template, and use that column’s value in your save/send templates
Буде показано документацію англійською через помилку FFML: Missing closing «``» for CODE_TEXT on line 2 in «booksize»
connected_device_name¶
connected_device_name(ключ_розташування_сховища) — якщо пристрій з’єднано, повертає назву пристрою, якщо ні — порожній рядок. Кожне розташування сховища даних на пристрої має власну назву. Значення параметра ключ_розташування_сховища: 'main', 'card' і 'cardb'. Ця функція працює лише у графічному інтерфейсі користувача.
connected_device_uuid¶
connected_device_uuid(ключ_розташування_сховища) — якщо пристрій з’єднано, повертає UUID (унікальний ідентифікатор) пристрою, якщо ні — порожній рядок. Кожне розташування сховища даних на пристрої має власний UUID. Значення параметра ключ_розташування_сховища: 'main', 'carda' і 'cardb'. Ця функція працює лише у графічному інтерфейсі користувача.
current_library_name¶
current_library_name() — повертає останню адресу поточної бібліотеки calibre.
current_library_path¶
current_library_path() — повертає повний шлях до поточної бібліотеки calibre.
current_virtual_library_name¶
current_virtual_library_name() — повертає назву поточної віртуальної бібліотеки, якщо така є, і порожній рядок, якщо такої немає. Регістр символів назви бібліотеки буде збережено. Приклад:
program: current_virtual_library_name()
Ця функція працює лише у режимі графічного інтерфейсу користувача.
field¶
field(назва_для_пошуку) — повертає значення поля метаданих із назвою для пошуку назва_для_пошуку. Замість функції можна скористатися префіксом $, ось так: $tags.
formats_modtimes¶
formats_modtimes(рядок_формату_дати) — повертає відокремлений комами список відокремлених двокрапками пунктів ФОРМАТ:ДАТА, які відповідають часу внесення змін до файлів форматів книги. Параметр рядок_формату_дати визначає спосіб форматування дати. Докладніше про цей формат можна дізнатися з опису функції format_date(). Для отримання даних щодо часу внесення змін до одного з форматів ви можете скористатися функцією select(). Зауважте, що назви форматів буде вказано великими літерами, наприклад EPUB.
formats_paths¶
formats_paths() — повернути розділений комами список розділених двокрапками записів ФОРМАТ:ШЛЯХ, щоб відповідають шляхам до файлів книги у різних форматах. Для отримання шляху до файла певного формату ви можете скористатися функцією select(). Зауважте, що назви форматів слід вказувати великими літерами, ось так: EPUB.
formats_sizes¶
formats_sizes() — повертає відокремлений комами список відокремлених двокрапками пунктів ФОРМАТ:РОЗМІР, які відповідають об’єму у байтах файлів форматів книги. Для отримання даних щодо об’єму файла у одному з форматів ви можете скористатися функцією select(). Зауважте, що назви форматів буде вказано великими літерами, наприклад EPUB.
has_cover¶
hascover() — повертає «Yes», якщо у книги є зображення обкладинки, інакше повертає порожній рядок.
is_marked¶
is_marked() — перевірити, чи має книга стан marked у calibre.. Якщо це так, буде повернуто значення позначки, або 'true' (у нижньому регістрі), або список іменованих позначок, які відокремлено комами. Повертає '' (порожній рядок), якщо книгу не позначено. Ця функція працює лише у графічному інтерфейсі.
language_codes¶
language_codes(рядки_мов) — повертає коди мов для назв мов, які передано за допомогою аргументу рядки_мов.. Рядки має бути вказано мовою поточної локалі. Аргумент рядки_мов є списком значень, які відокремлено комами.
language_strings¶
language_strings(коди_мов, локалізація) — повертає назви мов для кодів мов (назви і коди), які передано як значення.. Приклад: {languages:language_strings()}. Якщо коди_мов дорівнює нулеві, повертає рядки англійською. Якщо коди_мов не дорівнює нулеві, повертає рядки мовою поточної локалі. Значення коди_мов є списком значень, які відокремлено комами.
ondevice¶
ondevice() — повертає «Yes», якщо встановлено «ondevice», інакше повертає порожній рядок.. Скористатися цією функцією можна лише за використання графічного інтерфейсу. Якщо ви хочете скористатися отриманими значенням у шаблонах збереження на диск або надсилання на пристрій, вам слід створити нетиповий стовпчик «Стовпчик, створений на основі інших стовпчиків», скористатися у шаблоні створеного стовпчика цією функцією, а потім скористатися значенням у стовпчику у вашому шаблоні збереження або надсилання.
raw_field¶
raw_field(назва_для_пошуку [, необов'язкове_типове_значення]) — повертає вміст іменованого поля метаданих без застосування форматування. Обробляє і повертає додатковий другий аргумент, необов'язкове_типове_значення, якщо значення поля не визначено (None). Замість цієї функції можна скористатися префіксом $$, ось так: $$pubdate.
raw_list¶
raw_list(назва_для_пошуку, роздільник) — повертає список метаданих з назвою «назва_для_пошуку» без застосування будь-якого форматування або упорядковування. Записи у списку буде відокремлено значенням «роздільник».
series_sort¶
series_sort() — повертає значення впорядкування циклу..
user_categories¶
user_categories() — повертає список категорій користувача, що містять цю книгу, відокремлених комами. Скористатися цією функцією можна лише за використання графічного інтерфейсу. Якщо ви хочете скористатися отриманими значенням у шаблонах збереження на диск або надсилання на пристрій, вам слід створити нетиповий стовпчик «Стовпчик, створений на основі інших стовпчиків», скористатися у шаблоні створеного стовпчика цією функцією, а потім скористатися значенням у стовпчику у вашому шаблоні збереження або надсилання.
virtual_libraries¶
virtual_libraries() — повертає список віртуальних бібліотек, до яких включено вказану книгу, відокремлених комами. Скористатися цією функцією можна лише за використання графічного інтерфейсу. Якщо ви хочете скористатися отриманими значенням у шаблонах збереження на диск або надсилання на пристрій, вам слід створити нетиповий стовпчик «Стовпчик, створений на основі інших стовпчиків», скористатися у шаблоні створеного стовпчика цією функцією, а потім скористатися значенням у стовпчику у вашому шаблоні збереження або надсилання.
Пошук у списку¶
identifier_in_list¶
identifier_in_list(значення, назва_ідентифікатора [, значення_якщо_знайдено, значення_якщо_не_знайдено]) — обробити значення як список відокремлених комами ідентифікаторів. Ідентифікатор слід записувати у форматі «назва_ідентифікатора:значення». Параметр назва_ідентифікатора є текстом назви ідентифікатора, який слід знайти, або у форматі «назва_ідентифікатора» або «назва_ідентифікатора:формальний_вираз». Відповідність у першому випадку буде встановлено, якщо буде виявлено будь-який ідентифікатор, що відповідає критерію «назва_ідентифікатора». У другому випадку відповідність буде встановлено, якщо «назва_ідентифікатора» відповідає ідентифікатору, а «формальний_вираз» відповідає значенню ідентифікатора. Якщо задано значення_якщо_знайдено і значення_якщо_не_знайдено, якщо буде встановлено відповідність, програма поверне значення_якщо_знайдено. Якщо нічого не буде знайдено, програма поверне значення_якщо_не_знайдено. Якщо не задано значення_якщо_знайдено і значення_якщо_не_знайдено, якщо буде встановлено відповідність, програма поверне пару ідентифікатор:значення. Якщо значення не задано, буде повернуто порожній рядок ('').
list_contains¶
list_contains(значення, роздільник, [ взірець, значення_якщо_знайдено, ]* значення_якщо_не_знайдено) — обробляє значення як список пунктів, відокремлених роздільником, порівнює взірець з кожним зі значень у списку. Якщо рядок збігається зі значенням, повертає значення_якщо_знайдено, інакше повертає значення_якщо_не_знайдено. Значення взірець і значення_якщо_знайдено можна повторювати довільну кількість разів, залежно від значення запису. Перевірка взірців виконується послідовно. Функція повертає перший знайдений відповідник.
Альтернативи: in_list(), list_contains()
list_item¶
list_item(значення, номер, роздільник) — обробляє значення як список пунктів, відокремлених роздільником «роздільник», повертає пункт з номером «номер». Перший пункт має номер нуль. Останній з пунктів можна отримати за допомогою «list_item(-1, роздільник)». Якщо пункту немає у списку, буде повернуто порожнє значення. Роздільник має те саме значення, що і у функції count, зазвичай кома, але може бути амперсанд для списків, подібних до списків авторів.
select¶
select(значення, ключ) — обробляє значення як список записів, які відокремлено комами. Кожен запис має форму ідентифікатор:значення_ідентифікатора (формат identifier calibre). Функція знаходить першу пару із ідентифікатором, який рівний ключеві, і повертає відповідне значення. Якщо відповідних ідентифікаторів не буде виявлено, функція поверне порожній рядок.
str_in_list¶
str_in_list(роздільник, [ рядок, значення_якщо_знайдено, ]* значення_якщо_не_знайдено) — обробити значення як список записів, які відокремлено символом роздільник, потім порівняти рядок із кожним значенням у списку. Значення рядок не є формальним виразом. Якщо рядок дорівнює будь-якому запису (без врахування регістру символів), повертає відповідне значення_якщо_знайдено. Якщо рядок містить роздільник, його також буде оброблено як список із перевіркою для кожного із вбудованих значень. Можна вказати довільній кількість пар рядок і значення_якщо_знайдено, що дає змогу повертати різні значення, залежно від значення рядка. Якщо не буде встановлено відповідності жодному з рядків, буде повернуто значення_якщо_не_знайдено. Перевірка рядків виконується у вказаному порядку. Повернуто буде перший з відповідників.
Рекурсія¶
eval¶
eval(string) – evaluates the string as a program, passing the local variables. This permits using the template processor to construct complex results from local variables. In Template Program Mode, because the { and } characters are interpreted before the template is evaluated you must use [[ for the { character and ]] for the } character. They are converted automatically. Note also that prefixes and suffixes (the |prefix|suffix syntax) cannot be used in the argument to this function when using Template Program Mode.
Буде показано документацію англійською через помилку FFML: Missing closing «``» for CODE_TEXT on line 2 in «eval»
template¶
template(x) — обробляє x як шаблон. Обробку буде виконано у власному контексті, тобто змінні не використовуватимуться як спільні для функції виклику і обробки шаблону. Оскільки символи «{» і «}» є особливими, вам слід використовувати «[[» для позначення символу «{» і «]]» для позначення символу «}». Перетворення буде виконано автоматично. Наприклад, template('[[title_sort]]') буде оброблено як шаблон {title_sort} і повернуто відповідне значення. Також слід зауважити, що у аргументі цієї функції не можна використовувати префікси і суфікси (тобто синтаксичні конструкції, подібні до «|префікс|суфікс»), якщо використовується режим програмного шаблона.
Робота з рядками¶
character¶
character(назва_символу) — повертає символ із назвою «назва_символу». Наприклад, character('newline') повертає символ розриву рядка ('\n'). Передбачено підтримку таки назв символів: newline, return, tab і backslash. Цю функцію використовують для виведення символів у результатах дії шаблонів.
check_yes_no¶
check_yes_no(назва_поля, is_undefined, is_false, is_true) — перевіряє, чи дорівнює значення поля «так/ні», вказаного ключем пошуку назва_поля, значенню, вказаному параметрами, повертає «yes», якщо знайдено відповідник, інакше, повертає порожній рядок. Встановіть для параметрів is_undefined, is_false або is_true значення 1 (число), щоб перевірити відповідну умову, інакше, встановіть 0.
Приклад: check_yes_no("#bool", 1, 0, 1) повертає «yes», якщо у полі «так/ні» «#bool» значення або не визначено (ні True, ні False) або дорівнює True.
Можна встановлювати рівне 1 значення для декількох параметрів з набору is_undefined, is_false та is_true.
contains¶
contains(значення, взірець, текст для відповідності, текст для невідповідності) — перевіряє, чи міститься у значенні відповідник формального виразу взірець. Повертає текст для відповідності, якщо буде знайдено відповідник, інакше повертає текст для невідповідності.
field_exists¶
field_exists(назва_пошуку) — перевіряє, чи існує поле (стовпчик) із назвою для пошуку назва_пошуку. Повертає '1', якщо поле існує, і порожній рядок, якщо не існує.
ifempty¶
ifempty(значення, текст для порожнього) — якщо значення не є порожнім, повертає значення поля, інакше повертає текст для порожнього.
re¶
re(значення, взірець, замінник) — повертає значення після застосування формального виразу. Усі екземпляри взірця у значенні буде замінено на замінник. У мові шаблонів використано формальні вирази Python без врахування регістру символів.
re_group¶
re_group(значення, взірець [, шаблон_для_групи]*) — повертає рядок, створений за допомогою застосування формального виразу заданого взірцем до значення та заміною кожного з відповідників значенням, повернутим відповідним шаблоном. У режимі шаблонного програмування, як і у функціях template та eval, замість { слід використовувати [[, замість } — ]].
У наведеному нижче прикладі буде виконано пошук циклів із назвами у декілька слів і замінено перше слово на слово великими літерами:
program: re_group(field('series'), "(\S* )(.*)", "{$:uppercase()}", "{$}")'}
shorten¶
shorten(значення символи ліворуч, текст посередині, символи праворуч) — повертає скорочену версію значення, яка складається із вказаної кількості символи ліворуч символів на початку значення, далі з тексту посередині, і далі кількості символи праворуч символів наприкінці значення. Символи ліворуч і символи праворуч мають бути невід’ємними цілими значеннями. Приклад: припустімо, ви хочете показати заголовок довжиною не більше 15 символів у довжину. Одним шаблоном, який виконує це завдання є {title:shorten(9,-,5)}. Для книги із заголовком Ancient English Laws in the Times of Ivanhoe результатом буде Ancient E-anhoe: перші 9 символів заголовка, -, далі останні 5 символів. Якщо довжина значення є меншою за символи ліворуч + символи праворуч + довжина текст посередині, значення буде повернуто без змін. Наприклад, заголовок The Dome не буде змінено.
strcat¶
strcat(a [, b]*) — повертає рядок, отриманий з’єднанням всіх аргументів. Може приймати довільну кількість аргументів. У більшості випадків ви можете скористатися замість цієї функції оператором &.
strcat_max¶
strcat_max(максимум, рядок1 [, префікс2, рядок2]*) — повертає рядок, утворений об’єднанням аргументів функції. Початковим значенням результату буде рядок1. Пари префікс, рядок додаватимуться в кінець результату, якщо довжина рядка-результату не перевищуватиме значення максимум. Префікси можуть бути порожніми. Значення рядок1 буде повернуто, навіть якщо довжина рядка рядок1 перевищує максимум. Функції можна передавати довільну кількість пар префікс, рядок.
strlen¶
strlen(значення) — повертає довжину рядка значення.
substr¶
substr(рядок, початок, кінець) — повертає символи від символу з номером початок до символу з номером кінець у рядку рядок. Вважається, що у рядок починається з нульового символу. Якщо значення кінець є від’ємним, символи буде відраховано у напрямку до початку рядка. Якщо значенням кінець є нуль, кінцем вважатиметься останній символ. Приклади: substr('12345', 1, 0) повертає '2345', а substr('12345', 1, -1) повертає '234'.
swap_around_articles¶
swap_around_articles(роздільник) — повертає значення із артиклями, які пересунуто в кінець. Значенням може бути список, елементи якого буде оброблено окремо. Якщо значенням є список, вам слід вказати роздільник значень у списку. Якщо значення роздільник вказано не буде, значення вважатиметься одним рядком, а не списком. Артиклями вважаються рядки, які використовуються calibre для створення title_sort.
swap_around_comma¶
swap_around_comma(значення) — за заданим значенням у форматі B, A повертає значення A B. Найкорисніше для перетворення імен у форматі «Прізвище, Ім’я» на імена у форматі «Ім’я Прізвище». Якщо коми у значенні не буде виявлено, функція поверне значення без змін.
test¶
test(значення, текст для непорожнього, текст для порожнього) — повертає «текст для непорожнього», якщо значення не є порожнім. Якщо це не так, повертає текст для порожнього.
to_hex¶
to_hex(значення) — повертає рядок значення, який закодовано шістнадцятковими числами. Корисно при побудові адрес calibre..
transliterate¶
transliterate(значення) — повертає такий рядок латинською абеткою, який при читанні за звуком літер звучить приблизно так само, як і початковий рядок. Наприклад, якщо початковим рядком є «Фёдор Миха́йлович Достоевский», функцією буде повернуто Fiodor Mikhailovich Dostoievskii.
Робота зі списками¶
list_count¶
count(значення, роздільник) — за заданим значенням списком пунктів, відокремлених роздільником роздільник, повертає кількість пунктів у списку. У більшості списків як роздільник використовується кома, для авторів може використовуватися амперсанд.
Приклади: {tags:count(,)}, {authors:count(&)}.
Варіанти: count(), list_count()
list_count_field¶
list_count_field(назва_пошуку)— повертає кількість записів у полі із назвою пошуку назва_пошуку. Поле має бути таким, що містить багато значень, зокрема authors або tags, інакше виконання функції призведе до помилки. Ця функція є набагато швидшою за list_count(), оскільки працює безпосередньо з даними calibre без початкового перетворення на рядок. Приклад: list_count_field('tags')
list_count_matching¶
list_count_matching(список, взірець, роздільник) — за заданим значенням списком пунктів, відокремлених роздільником «роздільник», повертає кількість пунктів у списку, які відповідають заданому формальним виразом взірцю.
Варіанти: list_count_matching(), count_matching()
list_difference¶
list_difference(список1, список2, роздільник) — повертає список, створений вилученням зі списку список1 всіх пунктів, які містяться у списку список2, на основі порівняння без врахування регістру.. Пункти у списках список1 і список2 відокремлюються роздільником роздільник, як і пункти у повернутому функцією списку.
list_equals¶
list_equals(list1, sep1, list2, sep2, yes_val, no_val) – return yes_val if list1 and list2 contain the same items, otherwise return no_val. The items are determined by splitting each list using the appropriate separator character (sep1 or sep2). The order of items in the lists is not relevant. The comparison is case-insensitive.
Буде показано документацію англійською через помилку FFML: Missing closing «``» for CODE_TEXT on line 2 in «list_equals»
list_intersection¶
list_intersection(список1, список2, роздільник) — повертає список, створений вилученням зі списку список1 всіх пунктів, яких немає у списку список2, на основі порівняння без врахування регістру.. Пункти у списках список1 і список2 відокремлюються роздільником роздільник, як і пункти у повернутому функцією списку.
list_join¶
list_join(із_роздільником, список1, роздільник1 [, список2, роздільник2]*) — повертає список, створений об’єднанням записів у початкових списках. (список1, список2 тощо) з використанням роздільника із_роздільником між записами у списку-результаті. Записи у кожному із початкових списків список[123…] розділено відповідним роздільником роздільник[123…]. У списку можуть міститися нульові значення. Він може бути полем, подібним до поля видавця, яке має одне значення, фактично, списком з одного запису. Дублікати буде вилучено з використанням порівняння без врахування регістру символів. Записи буде повернуто у порядку, у якому їх вказано у початкових списках. Якщо записи у списках відрізняються лише регістром символів, буде використано останній з них. Усі роздільники можуть складатися з декількох символів. Приклад:
program:
list_join('#@#', $authors, '&', $tags, ',')
Ви можете скористатися list_join для обробки результатів попередніх викликів list_join ось так
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¶
list_re(початковий_список, роздільник, фв_пошуку, пар_заміни) — будує список таким чином: спочатку поділяє початковий_список на запис на основі вказаного символу роздільник.. Для кожного з записів у списку перевіряє відповідність формальному виразу фв_пошуку. Якщо відповідність буде встановлено, запис буде додано до повернутого списку. Якщо параметр пар_заміни не буде порожнім, заміну буде виконано до додавання запису до повернутого списку.
list_re_group¶
list_re_group(список_джерел, роздільник, фв_включення, фв_пошуку [, шаблон_групи]*) — Подібне до list_re, але замінники є обов’язковими. Використовує re_group(пункт_списку, фв_пошуку, шаблон ...) під час виконання замін у остаточному списку.
list_remove_duplicates¶
list_remove_duplicatesunion(список, роздільник) — повертає список, створений вилученням дублікатів з початкового списку.. Якщо записи пунктів відрізнятимуться лише регістром символів, буде повернуто лише останній з них. Пункти у списку має бути відокремлено роздільником, який також буде використано під час формування списку-результату.
list_sort¶
list_sort(список, напрямок, роздільник) — повертає список, впорядкований без врахування регістру.. Якщо значенням параметра напрямок є нуль (число або символ), список буде впорядковано за зростанням. Якщо значення буде іншим, список впорядковуватиметься за спаданням. Записи у початковому списку має бути відокремлено роздільником, як і записи у списку-результаті.
list_split¶
list_split(значення_список, роздільник, префікс_ідентифікатора) — ділить значення_список на окремі значення з використанням роздільника «роздільник», а потім надає значення змінним із назвами «префікс_ідентифікатора_N», де N — позиція значення у списку. Перший запис має позицію 0 (нуль). Функція повертає останній елемент у списку.
Приклад:
list_split('one:two:foo', ':', 'var')
те саме, що і
var_0 = 'one'
var_1 = 'two'
var_2 = 'foo'
list_union¶
list_union(список1, список2, роздільник) — повертає список, створений за допомогою об’єднання пунктів у списках список1 і список2`.[/] з вилученням дублікатів, виявлених шляхом порівняння без врахування регістру символів. Якщо записи пунктів відрізнятимуться лише регістром символів, використовуватиметься пункт зі списку``список1. Пункти у списках``список1`` і``список2`` має бути відокремлено``роздільником``, який також буде використано під час формування списку-результату. Варіанти: merge_lists()`, list_union()
range¶
range(початок, кінець, крок, обмеження) — повертає список, який створено циклічним проходженням діапазону, який вказано параметрами «початок», «кінець» та «крок» із максимальною довжиною «обмеження».. Першим значенням у списку буде «початок». Наступними значеннями будуть «наступне_значення = поточне_значення + крок». Проходження циклу триватиме, доки «наступне_значення < кінець» , якщо «крок» є додатним, інакше, доки «наступне_значення > кінець». Буде виведено порожній список, якщо не буде виконано умову «початок >= кінець» і «крок» є додатним. Значення «обмеження» встановлює максимальну довжину списку. Типовим значенням є 1000. Параметри «початок», «крок» і «обмеження» є необов’язковими. Виклик «range()» із одним аргументом задає «кінець». Два аргументи задають «початок» і «кінець». Три аргументи задають «початок», «кінець» і «крок». Чотири аргументи задають «початок», «кінець», «крок» і «обмеження».
Приклади:
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)
subitems¶
subitems(значення, початковий_номер, кінцевий_номер) — цією функцією користуються для розбиття списків пунктів, зокрема списків жанрів. Функція обробляє значення як відокремлений комами список записів, у якому кожен з записів є відокремленим крапками списком. Повертає новий список, створений таким чином: спочатку буде знайдено всі відокремлені крапками запис, потім для кожного такого запису буде видобуто компоненти від номера «початковий_номер» до «кінцевий_номер», а потім всі видобуті записи знову буде поєднано для отримання результату. Перший компонент у відокремленому крапками списку матиме номер нуль. Якщо номер буде від’ємним, його буде відраховано від кінця списку. Якщо буде вказано «кінцевий_номер» рівний нулеві, номер вважатиметься кінцевим у списку.
Приклади:
Припускаємо, що у стовпчику #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»:
{#genre:subitems(0,1)}повертає «A, D»{#genre:subitems(0,2)}повертає «A.B, D.E»
sublist¶
sublist(значення, початковий_номер, кінцевий_номер, роздільник) — обробляє значення як список пунктів, відокремлених роздільником «роздільник», повертає новий список, створений з пунктів з номера «початковий_номер» до номера «кінцевий_номер». Перший пункт має нульовий номер. Якщо вказано від’ємний номер, його буде відраховано від кінця списку. Якщо буде вказано «кінцевий_номер» рівний нулеві, номер вважатиметься кінцевим у списку.
Приклади у основному режимі шаблонів зі стовпчиком міток (значення у якому відокремлено комами), що містить значення «A, B, C»:
{tags:sublist(0,1,\,)}повертає «A»{tags:sublist(-1,0,\,)}повертає «C»{tags:sublist(0,-1,\,)}повертає «A, B»
Форматування значень¶
finish_formatting¶
finish_formatting(значення, формат, префікс, суфікс) – застосовує формат, префікс і суфікс до значення так само, як у шаблоні, подібному до {series_index:05.2f| - |- }. Цю функцію створено для полегшення перетворення складних шаблонів окремих функцій та шаблонів режиму шаблонного програмування на шаблони GPM. Наприклад, наведена нижче програма дає ті самі результати, що і шаблон вище:
program: finish_formatting(field("series_index"), "05.2f", " - ", " - ")
Ще приклад: для шаблона:
{series:re(([^\s])[^\s]+(\s|$),\1)}{series_index:0>2s| - | - }{title}
скористайтеся:
program:
strcat(
re(field('series'), '([^\s])[^\s]+(\s|$)', '\1'),
finish_formatting(field('series_index'), '0>2s', ' - ', ' - '),
field('title')
)
format_date¶
format_date(значення, рядок_формату) — виконує форматування значення, яким має бути запис дати, на основі рядка рядок_формату, повертає рядок. Найкращим варіантом є записування дати у форматі ISO, оскільки використання інших форматів дати часто призводить до помилок, оскільки неможливо однозначно визначити дату. Зауважте, що функція format_date_field() є і швидшою і надійнішою.
Коди форматування:
d :номер дня без початкового нуля (від 1 до 31)dd :номер дня з початковим нулем (від 01 до 31)ddd :скорочена локалізована назва дня (тобто від «пн» до «нд»).dddd :повна локалізована назва дня (тобто від «понеділок» до «неділя»).M :номер місяця без початкового нуля (від 1 до 12).MM :номер місяця з початковим нулем (від 01 до 12).MMM :скорочена локалізована назва місяця (тобто від «січ» до «гру»).MMMM :повна локалізована назва місяця (тобто від «січень» до «грудень»).yy :двоцифровий номер року (від 00 до 99).yyyy :чотирицифровий номер року.h :кількість годин без початкового 0 (від 0 до 11 або від 0 до 23, залежно від значення am/pm).hh :кількість годин з початковим 0 (від 00 до 11 або від 00 до 23, залежно від значення am/pm)m :кількість хвилин без початкового 0 (від 0 до 59).mm :кількість хвилин з початковим 0 (від 00 до 59).s :кількість секунд без початкового 0 (від 0 до 59).ss :кількість секунд з початковим 0 (від 00 до 59).ap :використовувати 12-годинні періоди відліку замість 24-годинних, «ap» буде замінено на локалізований рядок для значень «ранку» і «вечора».AP :використовувати 12-годинні періоди відліку замість 24-годинних, «ap» буде замінено на локалізований рядок для значень «ранку» і «вечора».iso :дата з часом і часовим поясом. Вказувати можна лише одне значення формату.to_number:дата у форматі числа із рухомою крапкою. from_number[:формат]: перетворити число з рухомою крапкою (часову позначку) на дату у форматі ISO. Якщо вам потрібна дата в іншому форматі, додайте бажаний рядок формату післяfrom_numberі двокрапки (:). Приклад:format_date(val, 'from_number:MMM dd yyyy')
Результати перетворення дати, яка містить локалізовані назви місяців, можуть бути несподіваними, якщо ви змінюєте формат дати на такий, що містить MMMM. Щоб уникнути цієї проблеми, скористайтеся format_date_field().
format_date_field¶
format_date_field(назва_поля, рядок_форматування) — форматувати значення у полі назва_поля, яке має бути фільтром поля дати, стандартного або нетипового. Див. format_date(), щоб дізнатися більше про коди форматування. Ця функція є набагато швидшою за format_date(). Нею слід користуватися, якщо ви форматуєте значення у полі (стовпчику). Вона також є надійнішою, оскільки працює безпосередньо з базовою датою. Нею не можна користуватися для обчислених дат або дат у рядкових змінних. Приклади:
::
format_date_field(„pubdate“, „yyyy.MM.dd“) format_date_field(„#date_read“, „MMM dd, yyyy“)
format_number¶
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 [/URL] near text документац on line 3 in «format_number»
human_readable¶
human_readable(значення) — очікує, що значення є числом, і повертає рядкове представлення числа у кілобайтах, мегабайтах, гігабайтах тощо.
rating_to_stars¶
rating_to_stars(використання_пів_зірок) — повертає оцінку як рядок з символів зірок (★). Значення має бути числом від 0 до 5. Встановіть значення використання_пів_зірок рівним 1, якщо ви хочете, щоб у стовпчиках нетипових оцінок, було показано символи пів зірок для нецілих оцінок.
urls_from_identifiers¶
urls_from_identifiers(ідентифікатори, упорядкувати_результати) — за заданим списком відокремлених комами ідентифікаторів, де ідентифікатором є пара відокремлених двокрапкою значень (назва:значення_ідентифікатора), повертає список відокремлених комами адрес HTML на основі ідентифікаторів. Список лишиться неупорядкованим, якщо упорядкувати_результати має значення 0 (символ або число), інакше, список буде упорядковано за назвами ідентифікаторів. Адреси буде створено у той самий спосіб, що і для вбудованого стовпчика ідентифікаторів, який показано на панелі подробиць щодо книги.
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)[source]¶
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)[source]¶
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>>)[source]¶
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()[source]¶
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)[source]¶
Set all identifiers. Note that if you previously set ISBN, calling this method will delete it.
- standard_field_keys()[source]¶
return a list of all possible keys, even if this book doesn’t have them
- all_non_none_fields()[source]¶
Return a dictionary containing all non-None metadata fields, including the custom ones.
- get_standard_metadata(field, make_copy)[source]¶
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)[source]¶
return a dict containing all the standard field metadata associated with the book.
- get_all_user_metadata(make_copy)[source]¶
return a dict containing all the custom field metadata associated with the book.
- get_user_metadata(field, make_copy)[source]¶
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)[source]¶
store custom field metadata into the object. Field is the key name not the label
- set_user_metadata(field, metadata)[source]¶
store custom field metadata for one column into the object. Field is the key name not the label
- remove_stale_user_metadata(other_mi)[source]¶
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)[source]¶
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)[source]¶
Merge the information in other into self. In case of conflicts, the information in other takes precedence, unless the information in other is NULL.
- 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