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]*)¶
ceiling(x)¶
divide(x, y)¶
floor(x)¶
fractional_part(x)¶
mod(x)¶
multiply(x [, y]*)¶
round(x)¶
subtract(x, y)¶
Boolean¶
and(value [, value]*)¶
not(value)¶
or(value [, value]*)¶
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: 'v' 分を 'date' に加算、h: 'v' 時間を 'date' に加算、d: 'v' 日を 'date' に加算、w: 'v' 週を 'date' に加算、y: 'v' 年を加算、ただし1年を365日とします。使用例: '1s3d-1m' は 'date' に1秒加算、3日加算、そして1分を減算します。
days_between(date1, date2)¶
today()¶
Formatting values¶
finish_formatting(val, fmt, prefix, suffix)¶
format_date(val, format_string)¶
- class calibre.utils.formatter_functions.BuiltinFormatDate[ソース]¶
format_date(val, format_string) -- format the value, which must be a date, using the format_string, returning a string. It is best if the date is in ISO format because using other date formats often causes errors because the actual date value cannot be unambiguously determined. Note that the format_date_field() function is both faster and more reliable. The formatting codes are: d : the day as number without a leading zero (1 to 31) dd : the day as number with a leading zero (01 to 31) ddd : the abbreviated localized day name (e.g. "Mon" to "Sun"). dddd : the long localized day name (e.g. "Monday" to "Sunday"). M : the month as number without a leading zero (1 to 12). MM : the month as number with a leading zero (01 to 12) MMM : the abbreviated localized month name (e.g. "Jan" to "Dec"). MMMM : the long localized month name (e.g. "January" to "December"). yy : the year as two digit number (00 to 99). yyyy : the year as four digit number. h : the hours without a leading 0 (0 to 11 or 0 to 23, depending on am/pm) hh : the hours with a leading 0 (00 to 11 or 00 to 23, depending on am/pm) m : the minutes without a leading 0 (0 to 59) mm : the minutes with a leading 0 (00 to 59) s : the seconds without a leading 0 (0 to 59) ss : the seconds with a leading 0 (00 to 59) ap : use a 12-hour clock instead of a 24-hour clock, with "ap" replaced by the localized string for am or pm AP : use a 12-hour clock instead of a 24-hour clock, with "AP" replaced by the localized string for AM or PM iso : the date with time and timezone. Must be the only format present to_number: the date as a floating point number from_number[:fmt]: format the timestamp using fmt if present otherwise iso
format_date_field(field_name, format_string)¶
- class calibre.utils.formatter_functions.BuiltinFormatDateField[ソース]¶
format_date_field(field_name, format_string) -- format the value in the field 'field_name', which must be the lookup name of date field, either standard or custom. See 'format_date' for the formatting codes. This function is much faster than format_date and should be used when you are formatting the value in a field (column). It can't be used for computed dates or dates in string variables. Example: format_date_field('pubdate', 'yyyy.MM.dd')
format_number(v, template)¶
- class calibre.utils.formatter_functions.BuiltinFormatNumber[ソース]¶
format_number(v, template) -- 数値 v を "{0:5.2f}" や "{0:,d}" や "${0:5,.2f}" などPythonのフォーマットテンプレートを使ってフォーマットします。テンプレートの一部であるfield_nameは0 (ゼロ) (上記例では "{0:" ) でなくてはなりません。もっと詳しい例についてはテンプレート言語とPythonのドキュメントを参照してください。テンプレートにフォーマットがひとつしか指定されていない場合には、先頭の "{0:" と最後の "}" は省略可能です。フォーマットに失敗したときには空のstringを返します。
human_readable(v)¶
rating_to_stars(value, use_half_stars)¶
urls_from_identifiers(identifiers, sort_results)¶
- class calibre.utils.formatter_functions.BuiltinUrlsFromIdentifiers[ソース]¶
urls_from_identifiers(identifiers, sort_results) -- 識別子のカンマ区切りリストを指定すると、識別子から生成されたHTML URLのカンマ区切りリストを返します。識別子はコロンで区切られた値のペア (name:id_value) です。sort_results が 0 (文字または数字) の場合、リストはソートされません。それ以外の場合は、識別子名のアルファベット順にソートされます。URL は、本の詳細に表示される場合、組み込みの識別子列と同じ方法で生成されます。
Get values from metadata¶
annotation_count()¶
approximate_formats()¶
- class calibre.utils.formatter_functions.BuiltinApproximateFormats[ソース]¶
approximate_formats() -- ある時点で本と関連づけられていた形式を、カンマ区切りのリストにして返します。このリストが正しいことは保証されていませんが、概ね正しいでしょう。この関数は、テンプレートプログラムモードで "{:'approximate_formats()'}" のように呼び出すことができます。形式名は、EPUBのように常に大文字になることに注意してください。この関数はGUI上でのみ機能します。この値を「ディスクに保存」や「ディスクに送る」のテンプレートで使用したい場合には、「他の列から作られる列」でこの関数を使用したカスタム列を作成し、その列の値を「ディスクに保存」や「ディスクに送る」のテンプレートで参照するようにしてください。
booksize()¶
connected_device_name(storage_location)¶
connected_device_uuid(storage_location)¶
current_library_name()¶
current_library_path()¶
field(lookup_name)¶
formats_modtimes(date_format)¶
formats_paths()¶
formats_sizes()¶
has_cover()¶
is_marked()¶
language_codes(lang_strings)¶
language_strings(lang_codes, localize)¶
ondevice()¶
raw_field(lookup_name [, optional_default])¶
raw_list(lookup_name, separator)¶
series_sort()¶
user_categories()¶
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) -- 引数で指定された検索キー field_name に一致する yes/no フィールドをチェックし、一致するものが見つかれば "yes" を返し、そうでなければ空の文字列を返します。引数 is_undefined, is_false, または is_true を 1 (数字) を設定すると、その条件をチェックします。チェックしない場合には 0 を設定します。使用例: check_yes_no("#bool", 1, 0, 1) は yes/no フィールド "#bool" が未定義 (True でも Falseでもない) または True のときに"yes" を返します。is_undefined, is_false, または is_true can のうちひとつ以上に 1 を設定できます。この関数は通常 test() 関数、または is_empty() 関数から利用されます。
contains(val, pattern, text if match, text if not match)¶
field_exists(field_name)¶
ifempty(val, text if empty)¶
test(val, text if not empty, text if empty)¶
Iterating over values¶
first_non_empty(value [, value]*)¶
lookup(val, [pattern, field,]+ else_field)¶
switch(val, [pattern, value,]+ else_value)¶
switch_if([test_expression, value_expression,]+ else_expression)¶
- class calibre.utils.formatter_functions.BuiltinSwitchIf[ソース]¶
switch_if([test_expression, value_expression,]+ else_expression) -- for each "test_expression, value_expression" pair, checks if test_expression is True (non-empty) and if so returns the result of value_expression. If no test_expression is True then the result of else_expression is returned. You can have as many "test_expression, value_expression" pairs as you want.
List lookup¶
identifier_in_list(val, id_name [, found_val, not_found_val])¶
- class calibre.utils.formatter_functions.BuiltinIdentifierInList[ソース]¶
identifier_in_list(val, id_name [, found_val, not_found_val]) -- treat val as a list of identifiers separated by commas. An identifier has the format "id_name:value". The id_name parameter is the id_name text to search for, either "id_name" or "id_name:regexp". The first case matches if there is any identifier matching that id_name. The second case matches if id_name matches an identifier and the regexp matches the identifier's value. If found_val and not_found_val are provided then if there is a match then return found_val, otherwise return not_found_val. If found_val and not_found_val are not provided then if there is a match then return the identifier:value pair, otherwise the empty string.
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 のペアは、必要な回数だけ繰り返すことができます。パターンは順番にチェックされます。最初に一致した found_val が返されます。別名: in_list()、list_contains()
list_item(val, index, separator)¶
select(val, 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 を separator で区切られた項目のリストとして扱い、文字列がリスト値のいずれかと一致する場合は found_val を返します。文字列がリスト値と一致しない場合niは、not_found_val を返します。比較は完全一致 (「含む」ではない) であり、大文字と小文字は区別されません。文字列と found_value のペアは、必要な回数だけ繰り返すことができます。パターンは順番にチェックされます。最初に一致した found_val が返されます。
List manipulation¶
count(val, separator)¶
list_count_field(field_name)¶
- class calibre.utils.formatter_functions.BuiltinFieldListCount[ソース]¶
list_count_field(field_name) -- returns the count of items in the field with the lookup name 'field_name'. The field must be multi-valued such as authors or tags, otherwise the function raises an error. This function is much faster than list_count() because it operates directly on calibre data without converting it to a string first. Example: list_count_field('tags')
list_count_matching(list, pattern, separator)¶
list_difference(list1, list2, separator)¶
list_equals(list1, sep1, list2, sep2, yes_val, no_val)¶
list_intersection(list1, list2, separator)¶
list_join(with_separator, list1, separator1 [, list2, separator2]*)¶
- class calibre.utils.formatter_functions.BuiltinListJoin[ソース]¶
list_join(with_separator, list1, separator1 [, list2, separator2]*) -- return a list made by joining the items in the source lists (list1, etc) using with_separator between the items in the result list. Items in each source list[123...] are separated by the associated separator[123...]. A list can contain zero values. It can be a field like publisher that is single-valued, effectively a one-item list. Duplicates are removed using a case-insensitive comparison. Items are returned in the order they appear in the source lists. If items on lists differ only in letter case then the last is used. All separators can be more than one character. Example:
- program:
list_join('#@#', $authors, '&', $tags, ',')
- 次のようにすると、ひとつ前の list_join の実行結果に対して list_join を使用できます:
program:
a = list_join('#@#', $authors, '&', $tags, ','); b = list_join('#@#', a, '#@#', $#genre, ',', $#people, '&')
- リストの生成には式が使えます。たとえば 'authors' と '#genre' の項目が必要で、ただしジャンルは 'Genre: ' という単語に変更され、その後ろにジャンルの最初の文字が続く、つまりジャンル 'Fiction' が 'Genre: F' にしたいものとします。次のようにすると、それが実現できます:
- program:
list_join('#@#', $authors, '&', list_re($#genre, ',', '^(.).*$', 'Genre: 1'), ',')
list_re(src_list, separator, include_re, opt_replace)¶
list_re_group(src_list, separator, include_re, search_re [, group_template]+)¶
list_remove_duplicates(list, separator)¶
list_sort(list, direction, separator)¶
list_split(list_val, sep, id_prefix)¶
- class calibre.utils.formatter_functions.BuiltinListSplit[ソース]¶
list_split(list_val, sep, id_prefix) -- 'sep' を使用してlist_valを別々の値に分割し、その値を 'id_prefix_N' という名前の変数に割り当てます (N はリスト内の値の位置)。最初の項目の位置は 0 (ゼロ) です。この関数は、リストの最後の要素を返します。例: split('one:two:foo', ':', 'var') は var_0 = 'one'; var_1 = 'two'; var_2 = 'foo' と等価です。
list_union(list1, list2, separator)¶
range(start, stop, step, limit)¶
- class calibre.utils.formatter_functions.BuiltinRange[ソース]¶
range(start, stop, step, limit) -- returns a list of numbers generated by looping over the range specified by the parameters start, stop, and step, with a maximum length of limit. The first value produced is 'start'. Subsequent values next_v are current_v+step. The loop continues while next_v < stop assuming step is positive, otherwise while next_v > stop. An empty list is produced if start fails the test: start>=stop if step is positive. The limit sets the maximum length of the list and has a default of 1000. The parameters start, step, and limit are optional. Calling range() with one argument specifies stop. Two arguments specify start and stop. Three arguments specify start, stop, and step. Four arguments specify start, stop, step and limit. Examples: range(5) -> '0,1,2,3,4'. range(0,5) -> '0,1,2,3,4'. range(-1,5) -> '-1,0,1,2,3,4'. range(1,5) -> '1,2,3,4'. range(1,5,2) -> '1,3'. range(1,5,2,5) -> '1,3'. range(1,5,2,1) -> error(limit exceeded).
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) -- valをseparatorで区切られた項目のリストとして解釈し、start_index から end_index の項目のリストを返す。最初の項目は0です。もしインデックスが負の場合には、リストの最後から数えます。特別なケースとしてend_indexが0の時にはリストの長さをあらわします。例えば、ベーシックテンプレートモードでタグ列(それはカンマ区切りのリスト)を扱う場合、 "A, B, C": {tags:sublist(0,1,\,)} は "A" を返します。 {tags:sublist(-1,0,\,)} は "C"を返します。 {tags:sublist(0,-1,\,)} は "A, B"を返します。
Other¶
arguments(id[=expression] [, id[=expression]]*)¶
- class calibre.utils.formatter_functions.BuiltinArguments[ソース]¶
arguments(id[=expression] [, id[=expression]]*) -- Used in a stored template to retrieve the arguments passed in the call. It both declares and initializes local variables, effectively parameters. The variables are positional; they get the value of the parameter given in the call in the same position. If the corresponding parameter is not provided in the call then arguments assigns that variable the provided default value. If there is no default value then the variable is set to the empty string.
assign(id, val)¶
globals(id[=expression] [, id[=expression]]*)¶
print(a[, b]*)¶
Recursion¶
eval(template)¶
- class calibre.utils.formatter_functions.BuiltinEval[ソース]¶
eval(template) -- 本の書誌の代わりにローカル変数(あらかじめ 'assign' された変数)を渡して、template を評価します。これにより、テンプレート処理でローカル変数を使ったより複雑な結果を生成することができます。{ と } は特殊文字であるため、{ の代わりに [[ を、 } の代わりに ]] を使わなければなりません。これらの文字は自動的に変換されます。例, template('[[title_sort]]') は、テンプレート {title_sort} を評価してその値を返します。テンプレートプログラムモードを使用している場合は、引数に prefixes と suffixes (|prefix|suffix の書式) が使用できないことに注意してください。
template(x)¶
- class calibre.utils.formatter_functions.BuiltinTemplate[ソース]¶
template(x) -- x をテンプレートとして評価します。それぞれの評価はそれぞれ独自のコンテキストで行われます。つまり変数は呼出元とそれぞれの評価で共有されません。{ と } は特殊文字であるため、{ の代わりに [[ を、 } の代わりに ]] を使わなければなりません。これらの文字は自動的に変換されます。例, template('[[title_sort]]') は、テンプレート {title_sort} を評価してその値を返します。テンプレートプログラムモードを使用している場合は、引数に prefixes と suffixes (|prefix|suffix の書式) が使用できないことに注意してください。
Relational¶
cmp(x, y, lt, eq, 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)¶
strcmpcase(x, y, lt, eq, gt)¶
- class calibre.utils.formatter_functions.BuiltinStrcmpcase[ソース]¶
strcmpcase(x, y, lt, eq, gt) -- does a case-sensitive comparison of x and y as strings. Returns lt if x < y. Returns eq if x == y. Otherwise returns gt. Note: This is NOT the default behavior used by calibre, for example, in the lexical comparison operators (==, >, <, etc.). This function could cause unexpected results, preferably use strcmp() whenever possible.
String case changes¶
capitalize(val)¶
lowercase(val)¶
titlecase(val)¶
uppercase(val)¶
String manipulation¶
character(character_name)¶
re(val, pattern, replacement)¶
re_group(val, pattern [, template_for_group]*)¶
- class calibre.utils.formatter_functions.BuiltinReGroup[ソース]¶
re_group(val, pattern [, template_for_group]*) -- pattern で指定した正規表現を val に適用し、それぞれのマッチを指定されたテンプレートから返された値で置換します。マッチした元の値は $ で利用可能です。テンプレートプラグラムモードでは、 { の代わりに [[ を、} の代わりに ]] を使用します。テンプレートプログラムモードの次の例では、ひとつ以上の単語を含み、最初の文字が大文字であるシリーズを検索します: {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 を短くしたバージョンを返します。これは 'val の先頭から 'left chars' 個の文字、次に 'middle text'、さらに末尾から 'right hars' 個の文字で構成された値です。'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]*)¶
strcat_max(max, string1 [, prefix2, string2]*)¶
strlen(a)¶
substr(str, start, end)¶
swap_around_articles(val, separator)¶
swap_around_comma(val)¶
to_hex(val)¶
transliterate(a)¶
Template database functions¶
book_count(query, use_vl)¶
book_values(column, query, sep, use_vl)¶
- class calibre.utils.formatter_functions.BuiltinBookValues[ソース]¶
book_values(column, query, sep, use_vl) -- returns a list of the values contained in the column "column", separated by "sep", in the books found by searching for "query". If use_vl is 0 (zero) then virtual libraries are ignored. This function can be used only in the GUI.
extra_file_modtime(file_name, format_string)¶
- class calibre.utils.formatter_functions.BuiltinExtraFileModtime[ソース]¶
extra_file_modtime(file_name, format_string) -- returns the modification time of the extra file 'file_name' in the book's 'data/' folder if it exists, otherwise -1.0. The modtime is formatted according to 'format_string' (see format_date()). If 'format_string' is empty, returns the modtime as the floating point number of seconds since the epoch. The epoch is OS dependent. This function can be used only in the GUI.
extra_file_names(sep [, pattern])¶
- class calibre.utils.formatter_functions.BuiltinExtraFileNames[ソース]¶
extra_file_names(sep [, pattern]) -- returns a sep-separated list of extra files in the book's 'data/' folder. If the optional parameter 'pattern', a regular expression, is supplied then the list is filtered to files that match pattern. The pattern match is case insensitive. This function can be used only in the GUI.
extra_file_size(file_name)¶
get_link(field_name, field_value)¶
get_note(field_name, field_value, plain_text)¶
- class calibre.utils.formatter_functions.BuiltinGetNote[ソース]¶
get_note(field_name, field_value, plain_text) -- fetch the note for field 'field_name' with value 'field_value'. If 'plain_text' is empty, return the note's HTML including images. If 'plain_text' is 1 (or '1'), return the note's plain text. If the note doesn't exist, return the empty string in both cases. Example: get_note('tags', 'Fiction', '') returns the HTML of the note attached to the tag 'Fiction'.
has_extra_files([pattern])¶
- class calibre.utils.formatter_functions.BuiltinHasExtraFiles[ソース]¶
has_extra_files([pattern]) -- returns the count of extra files, otherwise '' (the empty string). If the optional parameter 'pattern' (a regular expression) is supplied then the list is filtered to files that match pattern before the files are counted. The pattern match is case insensitive. This function can be used only in the GUI.
has_note(field_name, field_value)¶
- class calibre.utils.formatter_functions.BuiltinHasNote[ソース]¶
has_note(field_name, field_value) -- if field_value is not '' (the empty string) , return '1' if the value 'field_value' in the field 'field_name' has an attached note, otherwise ''. Example: has_note('tags', 'Fiction') returns '1' if the tag 'fiction' has a note, otherwise ''. If field_value is '' then return a list of values in field_name that have a note. If no item in the field has a note, return ''. Example: has_note('authors', '') returns a list of authors that have notes, or '' if no author has a note. The second variant is useful for showing column icons icons if any value in the field has a note, rather than a specific value. You can also test if all the values have a note by comparing the list length of this function's return value against the list length of the values in field_name.
other¶
is_dark_mode()¶
- class calibre.utils.formatter_functions.BuiltinIsDarkMode[ソース]¶
is_dark_mode() -- Returns '1' if calibre is running in dark mode, '' (the empty string) otherwise. This function can be used in advanced color and icon rules to choose different colors/icons according to the mode. Example: if is_dark_mode() then 'dark.png' else 'light.png' fi
set_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.
- 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.
- 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