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) – 返回 x + y. 如果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) – 返回小数点后的值。例如,fractional_part(3.14)返回0.14。如果x不是数字,则引发异常。

mod(x)

class calibre.utils.formatter_functions.BuiltinMod[源代码]

mod(x) – 返回x/y的余数,其中x、y和结果都是整数。如果x或y不是数字,则引发异常。

multiply(x, y)

class calibre.utils.formatter_functions.BuiltinMultiply[源代码]

multiply(x, y) – 返回x的y次方。如果x或y不是数字,返回异常。

round(x)

class calibre.utils.formatter_functions.BuiltinRound[源代码]

round(x) – 返回最接近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, …) – 如果所有的值不为空则返回字符串, 否则返回空字符串. 这个函数和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

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

finish_formatting(val, fmt, prefix, suffix)

class calibre.utils.formatter_functions.BuiltinFinishFormatting[源代码]

finish_formatting(val, fmt, prefix, suffix) – 将格式、前缀和后缀应用于一个值,就像在模板中使用`{Series_index:05.2f-x-}‘作用一样。例如,以下程序产生与上述模板相同的输出:程序: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:本地化月份的缩写名称(例如,“ Jan”到“ Dec”)。 MMMM:本地化的长月份名称(例如,“ January”到“ December”)。 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”替换为am或pm AP的本地化字符串:使用12个小时的时钟而不是24小时时钟,用“ AP”替换为AM或PM iso的本地化字符串iso:带时间和时区的日期。必须是唯一的格式

format_number(v, template)

class calibre.utils.formatter_functions.BuiltinFormatNumber[源代码]

format_number(v, template) –使用Python格式模板(例如“ {0:5.2f}”或“ {0:,d}”或“ $ {0:5,.2f}”)格式化数字v。 模板的field_name部分必须为0(zero)(即以上示例中的“ {0:”)。 有关更多示例,请参见模板语言和Python文档。 如果模板只包含一个格式,则可以省略开头的“ {0:”和结尾的“}”。 如果无法格式化,则返回空字符串。

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

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元数据中的排序(不同于书籍中的author_sort)。返回的列表的格式为author、sort 1、val_separator、author sort 2等。此列表中的author排序值与图书作者的顺序相同。如果您希望val_paricator周围有空格,则将它们包括在分隔符字符串中

booksize()

class calibre.utils.formatter_functions.BuiltinBooksize[源代码]

booksize() – 返回字段的大小。这个函数只在图形界面中工作。如果要在保存到磁盘或发送到设备模板中使用这些值,则必须定制“从其它栏目生成的新栏”,使用该列的模板中的函数,并在保存/发送模板中使用该列的值

connected_device_name(storage_location)

class calibre.utils.formatter_functions.BuiltinConnectedDeviceName[源代码]

connected_device_name(storage_location) – 如果设备已连接,则返回设备名称,否则返回空字符串。设备上的每个存储位置可以有不同的名称。位置名称为’main’、’carda’和’cardb’。此函数仅在GUI中工作。

current_library_name()

class calibre.utils.formatter_functions.BuiltinCurrentLibraryName[源代码]

current_library_name() – 返回当前 calibre 库路径上的最后一个名称。这个函数可以在模板程序模式下被调用,使用模板”{:’current_library_name()’}”。

current_library_path()

class calibre.utils.formatter_functions.BuiltinCurrentLibraryPath[源代码]

current_library_path() – 返回当前 calibre 库的路径。这个函数可以在模板程序模式下被调用,使用模板”{:’current_library_path()’}”。

field(name)

class calibre.utils.formatter_functions.BuiltinField[源代码]

field(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() –如果书有封面,则返回“是”,否则返回空字符串

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() – 如果设置了设备则返回“是”,否则返回空字符串。这个函数只在图形界面中工作。如果要在保存到磁盘或发送到设备模板中使用这些值,则必须定制“从其它栏目生成的新栏”,使用该列的模板中的函数,并在保存/发送模板中使用该列的值

raw_field(name)

class calibre.utils.formatter_functions.BuiltinRawField[源代码]

raw_field(name) – 通过名称来返回元数据字段命名而不使用任何格式。

raw_list(name, separator)

class calibre.utils.formatter_functions.BuiltinRawList[源代码]

raw_list(name, separator) – 返回按名称命名的元数据列表,不应用任何格式或排序,并用分隔符分隔项。

series_sort()

class calibre.utils.formatter_functions.BuiltinSeriesSort[源代码]

series_sort() – 返回丛书排序值

user_categories()

class calibre.utils.formatter_functions.BuiltinUserCategories[源代码]

user_categories() – 返回由逗号分隔的包含这本书用户类别的列表。这个函数只在图形界面中工作。如果要在保存到磁盘或发送到设备模板中使用这些值,则必须定制“从其它栏目生成的新栏”,使用该列的模板中的函数,并在保存/发送模板中使用该列的值

virtual_libraries()

class calibre.utils.formatter_functions.BuiltinVirtualLibraries[源代码]

virtual_libraries() – 返回包含这本书的以逗号分隔的虚拟书库列表。此功能仅在GUI中有效。如果要在保存到磁盘或发送到设备模板中使用这些值,则必须自定义“从其它栏目生成的新栏”,使用该列模板中的函数,并在保存/发送模板中使用该列的值

If-then-else

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”的匹配项。如果找到匹配项则返回”文本,如果匹配”,否则,返回”文本,如果不匹配”

ifempty(val, text if empty)

class calibre.utils.formatter_functions.BuiltinIfempty[源代码]

ifempty(val, text if empty) –如果val非空值则返回val,否则返回文本。

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

class calibre.utils.formatter_functions.BuiltinTest[源代码]

test(val, text if not empty, 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, pattern, field, …, else_field)

class calibre.utils.formatter_functions.BuiltinLookup[源代码]

lookup(val, pattern, field, pattern, field, …, else_field) – 与switch类似,只不过参数是字段(元数据)名称,而不是文本。将获取并使用相应字段的值。请注意,因为复合列是字段,所以您可以在一个复合字段中使用此函数来使用其他一些复合字段的值。这在构建可变保存路径时非常有用

switch(val, pattern, value, pattern, value, …, else_value)

class calibre.utils.formatter_functions.BuiltinSwitch[源代码]

switch(val, pattern, value, 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) – 将val视为逗号分隔的标识符列表,将字符串与列表中的每个值进行比较。标识符的格式为“identifier:value”。如果存在具有该id的任何标识符,则第一种情况匹配。 如果正则表达式regexp匹配标识符的值value,则第二种情况匹配。如果存在匹配项,则返回“已找到值(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_VALUE可以根据需要重复多次,允许根据搜索返回不同的值。图案是按顺序检查的。返回第一个匹配项。

list_item(val, index, separator)

class calibre.utils.formatter_functions.BuiltinListitem[源代码]

list_item(val, index, separator) – 将该值解释为由`分隔符`分隔的项目列表,返回第`index`项。第一个项目是零号。最后一项可以使用`List_Item(-1,分隔符)`返回。如果该项不在列表中,则返回空值。分隔符的含义与COUNT函数中的相同。

select(val, key)

class calibre.utils.formatter_functions.BuiltinSelect[源代码]

select(val, key) –将值解释为以逗号分隔的项目列表,其中项目为”id:value”。找到id等于 key的配对,并返回相应的值。

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_VALUE可以根据需要重复多次,允许根据搜索返回不同的值。按顺序检查字符串。返回第一个匹配项。

List manipulation

count(val, separator)

class calibre.utils.formatter_functions.BuiltinCount[源代码]

count(val, separator) –将该值解释为由`分隔符`分隔的项列表,返回列表中的项数。大多数列表使用逗号作为分隔符,但作者使用与号。示例: {tags:count(,)}, {authors:count(&)}

list_difference(list1, list2, separator)

class calibre.utils.formatter_functions.BuiltinListDifference[源代码]

list_difference(list1, list2, separator) – 使用不区分大小写的比较从list1中删除在list2中找到的任何项,从而返回一个列表。list1和list2中的项用分隔符分隔,返回的列表中的项也是如此。

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) – 如果list1和list2包含相同的项,则返回yes_val,否则返回no_val。这些项目是通过使用适当的分隔符(Sep1或Sep2)拆分每个列表来确定的。列表中项目的顺序无关紧要。该比较不区分大小写。

list_intersection(list1, list2, separator)

class calibre.utils.formatter_functions.BuiltinListIntersection[源代码]

list_intersection(list1, list2, separator) – 使用不区分大小写的比较从list1中删除在list2中找不到的任何项,从而返回一个列表。list1和list2中的项用分隔符分隔,返回的列表中的项也是如此。

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分成多个项来构造列表。对于列表中的每一项,检查它是否与include_re匹配。如果是,则将其添加到要返回的列表中。如果opt_place不是空字符串,在将项目添加到返回列表之前先应用替换。

list_re_group(src_list, separator, include_re, search_re, group_1_template, …)

class calibre.utils.formatter_functions.BuiltinListReGroup[源代码]

list_re_group(src_list, separator, include_re, search_re, group_1_template, …) – 除替换项之外的类似列表list_re不是可选的。当对结果列表进行替换时,它使用re_group(list_item,search_re,group_1_template,…)。

list_sort(list, direction, separator)

class calibre.utils.formatter_functions.BuiltinListSort[源代码]

list_sort(list, direction, separator) – 返回使用不区分大小写的排序的列表。如果排序方向为零,则列表按升序排序,否则按降序排序。列表项与返回列表中的项一样,用分隔符分隔。

list_union(list1, list2, separator)

class calibre.utils.formatter_functions.BuiltinListUnion[源代码]

list_union(list1, list2, separator) – 通过合并list1和list2中的项,在不区分大小写的比较后,删除其中重复项,返回一个列表。如果项的大小写不同,则使用list1中的项。list1和list2中的项用分隔符分隔,返回的列表中的项也是如此。

subitems(val, start_index, end_index)

class calibre.utils.formatter_functions.BuiltinSubitems[源代码]

subitems(val, start_index, end_index) – 此函数用于拆分诸如题材等类型的项目列表。它将该值解释为逗号分隔的项列表,其中每个项都是句点分隔的列表。返回一个新列表,该列表首先找到所有用句点分隔的项目,然后将每个这样的项目从start_index提取到end_index组件,然后将结果一起返回。句点分隔列表中的第一个组件的索引为零。如果索引为负数,则从列表末尾开始计数。作为一种特殊情况,假定end_index为零是列表的长度。使用基本模板模式并假定#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) –将该值解释为以`分隔符`分隔的项目列表,将从`start_index`生成的新列表返回给`end_index`项目。第一个项目是零号。如果索引为负数,则从列表末尾开始计数。作为一种特殊情况,假定end_index为零是列表的长度。示例:使用基本模板模式,并假定标签列(用逗号分隔)包含“ A,B,C”,{tags:sublist(0,1,\,)}返回“ A”。{tags:sublist(0,1,\,)}返回“ C”。 {tags:sublist(-1,0,\,)} 返回“ A,B”。

Other

assign(id, val)

class calibre.utils.formatter_functions.BuiltinAssign[源代码]

assign(id, val) – 将val分配给id,然后返回的val. id必须是标识符,而不是表达式。

Recursion

eval(template)

class calibre.utils.formatter_functions.BuiltinEval[源代码]

eval(template) – 评估模板,传递局部变量(那些“赋值”给的变量)而不是书籍元数据。这允许使用模板处理器从局部变量构造复杂的结果。由于{ and }字符是特殊字符,因此必须使用[[表示{字符,and]]表示}字符;它们会自动转换。还要注意,在使用模板程序模式时,不能在此函数的参数中使用前缀和后缀(`| prefix | suffix`语法)。

template(x)

class calibre.utils.formatter_functions.BuiltinTemplate[源代码]

template(x) – x作为模板进行评估。评估是在其自己的上下文中完成的,这意味着变量不会在调用方和模板评估之间共享。因为{ and }字符是特殊的,所以必须使用[[表示{字符,使用]]表示}字符; 它们会自动转换。例如,template (‘[[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,不区分大小写。当 x < y 时返回 lt,x = y 时返回 eq,否则返回 gt。

first_matching_cmp(val, cmp1, result1, cmp2, r2, …, else_result)

class calibre.utils.formatter_functions.BuiltinFirstMatchingCmp[源代码]

first_matching_cmp(val, cmp1, result1, cmp2, r2, …, else_result) – 依次比较“ val <cmpN”,如第一次比较满足(即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,不区分大小写。当 x < y 时返回 lt,x = y 时返回 eq,否则返回 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

re(val, pattern, replacement)

class calibre.utils.formatter_functions.BuiltinRe[源代码]

re(val, pattern, replacement) –应用正则表达式后返回val。所有`pattern`实例都将以`replacement`替换。与所有calibre中的使用相同,这些是与Python兼容的正则表达式。

re_group(val, pattern, template_for_group_1, for_group_2, …)

class calibre.utils.formatter_functions.BuiltinReGroup[源代码]

re_group(val, pattern, template_for_group_1, for_group_2, …) – 返回一个字符串,该字符串是通过将正则表达式模式应用于val,并将每个匹配的实例替换为通过将每个匹配的组替换为相应模板返回的值计算的字符串而生成的字符串。 该组的原始匹配值可用$表示。 在模板程序模式下,与模板和eval函数一样,您可以使用[[for{and]]for}。下面的示例表示在模板程序模式下查找具有多个单词的序列,并将第一个单词大写:{序列:’re_group($, “(S* )(.*)”, “[[$:大写()]]”, “[[$]]”)’}

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

class calibre.utils.formatter_functions.BuiltinShorten[源代码]

shorten(val, left chars, middle text, right chars) – 返回val的缩写版本,由val开头的“左字符”字符组成,后跟“中间文本”,然后是字符串末尾的“右字符”字符。左字符`和`右字符`必须是整数。例如,假设书名为《艾芬豪时代的古代英国法律》(Ancient English Laws in the Times of Ivanhoe)”,您希望它最多只能容纳15个字符。如果使用{title:Shorten(9,-,5)},则结果为`Ancient E-nhoe。如果该字段的长度小于左字符+右字符+`中间文本`的长度,则该字段将被原封不动地使用。例如,标题‘The Dome`不会改变。

strcat_max(max, string1, prefix2, string2, …)

class calibre.utils.formatter_functions.BuiltinStrcatMax[源代码]

strcat_max(max, string1, prefix2, string2, …) – 返回通过连接参数形成的字符串。返回的值初始化为string1。只要得到的字符串长度小于’max’,`Prefix,string`字符串对就会添加到值的末尾。即使String1比max长,也会返回String1。可以根据需要传递任意多个“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的开始字符到结束字符。str中的第一个字符是第零个字符。如果end为负数,则表示许多字符从右边开始计数。如果end为零,则表示最后一个字符。例如,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与文章一起移到末尾。该值可以是一个列表,在这种情况下,将处理列表的每个成员。如果值是列表,则必须提供列表值分隔符。如果没有提供分隔符,则将该值视为单个值,而不是列表。

swap_around_comma(val)

class calibre.utils.formatter_functions.BuiltinSwapAroundComma[源代码]

swap_around_comma(val) – 如果给定值的形式为“B,A”,则返回“A、B”。这对于将LN、FN格式的名称转换为FN LN非常有用。如果没有逗号,则函数返回未更改的val

transliterate(a)

class calibre.utils.formatter_functions.BuiltinTransliterate[源代码]

transliterate(a) – 返回一个拉丁字母表中的字符串,该字符串是通过近似源字符串中的单词的声音而形成的。例如,如果源是”Фёдор Миха́йлович Достоевский” ,则函数返回 “Fiodor Mikhailovich Dostoievskii”。

API of the Metadata objects

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

class calibre.ebooks.metadata.book.base.Metadata(title, authors='未知', 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