Reference for all built-in template language functions

Here, we document all the built-in functions available in the calibre template language. Every function is implemented as a class in python and you can click the source links to see the source code, in case the documentation is insufficient. The functions are arranged in logical groups by type.

Arithmetic

add(x [, y]*)

class calibre.utils.formatter_functions.BuiltinAdd[ソース]

add(x [, y]*) -- 引数の和を返します。引数が数字でない場合にエラーを発生します。この関数は、しばしば + 演算子で置き換えることが可能です。

ceiling(x)

class calibre.utils.formatter_functions.BuiltinCeiling[ソース]

ceiling(x) -- x で指定された値以上の最小値となる整数を返します。x が数字でない場合に、エラーを発生します。

divide(x, y)

class calibre.utils.formatter_functions.BuiltinDivide[ソース]

divide(x, y) -- x / y を返します。x または y が数字でない場合には、エラーを発生します。この関数は / 演算子で置き換えることができます。

floor(x)

class calibre.utils.formatter_functions.BuiltinFloor[ソース]

floor(x) -- x 以下の整数のうち最大のものを返します。x が数字でない場合に、エラーを発生します。

fractional_part(x)

class calibre.utils.formatter_functions.BuiltinFractionalPart[ソース]

fractional_part(x) -- 小数点以下の値を返します。 たとえば、fractional_part(3.14) は 0.14 を返します。x が数値でない場合は例外を起こします。

mod(x)

class calibre.utils.formatter_functions.BuiltinMod[ソース]

mod(x) -- 余剰 (x / y の余り) を返します。x または y が数字でない場合に、エラーを発生します。

multiply(x [, y]*)

class calibre.utils.formatter_functions.BuiltinMultiply[ソース]

multiply(x [, y]*) -- 引数の積を返します。引数の中に数字でないものがあれば、エラーを発生します。この関数は * 演算子で置き換えることができます。

round(x)

class calibre.utils.formatter_functions.BuiltinRound[ソース]

round(x) -- x に一番近い整数を返します。x が数字でない場合には、例外を発生します。

subtract(x, y)

class calibre.utils.formatter_functions.BuiltinSubtract[ソース]

subtract(x, y) -- x - y を返します。x または y が数字でない場合には、例外を発生します。この関数は - 演算子で置き換えることが可能です。

Boolean

and(value [, value]*)

class calibre.utils.formatter_functions.BuiltinAnd[ソース]

and(value [, value]*) -- 指定された文字列に空でないものがあれば文字列 "1" を返し、そうでなければ空の文字列を返します。tes t関数やfirst_non_empty 関数と組み合わせて利用できます。引数には、文字列をいくつでも指定できます。たいていの場合には、&& 演算子でこの関数を置き換えることが可能です。

not(value)

class calibre.utils.formatter_functions.BuiltinNot[ソース]

not(value) -- value が空なら "1" を返し、そうでなければ空の文字列を返します。test 関数や first_non_empty 関数と一緒に利用できます。多くの場合 ! 演算子で置き換えることが可能です。

or(value [, value]*)

class calibre.utils.formatter_functions.BuiltinOr[ソース]

or(value [, value]*) -- value が空でなければ "1" を返し、そうでなければ空の文字列を返します。この関数は test 関数や first_non_empty 関数と一緒に利用できます。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)

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) -- format、prefix、suffix を {series_index:05.2f| - |- } と同じ方法で適用します。例えば、以下のプログラムは上記のテンプレートと同じ結果を返します。program: finish_formatting(field("series_index"), "05.2f", " - ", " - ")

format_date(val, format_string)

class calibre.utils.formatter_functions.BuiltinFormatDate[ソース]

format_date(val, format_string) -- format 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)

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) -- 評価を星の文字で返します。value は0から5までの数字です。2.5 のような整数以外の評価をサポートするカスタム評価列を利用したい場合には use_half_stars に 1 を指定します。

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()

class calibre.utils.formatter_functions.BuiltinAnnotationCount[ソース]

annotation_count() -- 現在の本に付けられたすべての注釈の合計数を返します。この関数は GUI 上でのみ利用可能です。

approximate_formats()

class calibre.utils.formatter_functions.BuiltinApproximateFormats[ソース]

approximate_formats() -- ある時点で本と関連づけられていた形式を、カンマ区切りのリストにして返します。このリストが正しいことは保証されていませんが、概ね正しいでしょう。この関数は、テンプレートプログラムモードで "{:'approximate_formats()'}" のように呼び出すことができます。形式名は、EPUBのように常に大文字になることに注意してください。この関数はGUI上でのみ機能します。この値を「ディスクに保存」や「ディスクに送る」のテンプレートで使用したい場合には、「他の列から作られる列」でこの関数を使用したカスタム列を作成し、その列の値を「ディスクに保存」や「ディスクに送る」のテンプレートで参照するようにしてください。

author_sorts(val_separator)

class calibre.utils.formatter_functions.BuiltinAuthorSorts[ソース]

author_sorts(val_separator) -- 本の著者の著者読みの値を、リストにして返します。返される著者読みは、書誌の著者から取得したものです(本の著者読みの値とは異なる場合があります)。返されるリストは、author sort 1 val_separator author sort 2 のような形式になります。リストの著者読みの並び順は、本の著者の並び順と同じになります。val_separator にスペースで囲いたい場合には、separator 文字列に含めてください。

booksize()

class calibre.utils.formatter_functions.BuiltinBooksize[ソース]

booksize() -- 本のサイズを返します。この関数はGUI上でのみ機能します。この値を「ディスクに保存」や「ディスクに送る」のテンプレートで使用したい場合には、「他の列から作られる列」でこの関数を使用したカスタム列を作成し、その列の値を「ディスクに保存」や「ディスクに送る」のテンプレートで参照するようにしてください。

connected_device_name(storage_location)

class calibre.utils.formatter_functions.BuiltinConnectedDeviceName[ソース]

connected_device_name(storage_location) -- デバイスが接続されていればデバイス名を返し、それ以外のときには空の文字列を返します。デバイス上の格納場所ごとに異なる名前を持つことができます。格納場所の名前は 'main', 'carda' および 'cardb' です。この関数はGUI上でのみ動作します。

connected_device_uuid(storage_location)

class calibre.utils.formatter_functions.BuiltinConnectedDeviceUUID[ソース]

connected_device_uuid(storage_location) -- デバイスが接続されているときにはデバイスのuuid(ユニークID)を返し、そうでなければ空の文字列を返します。デバイス上の格納場所はそれぞれ異なるuuidを持ちます。格納場所の名前は 'main'、'carda'、および 'cardb' です。この関数はGUI上でのみ動作します。

current_library_name()

class calibre.utils.formatter_functions.BuiltinCurrentLibraryName[ソース]

current_library_name() -- 現在のライブラリのパスの最後のフォルダ名を返します。この関数はテンプレートプログラムモードで以下のように呼び出すことができます 。"{:'current_library_name()'}"

current_library_path()

class calibre.utils.formatter_functions.BuiltinCurrentLibraryPath[ソース]

current_library_path() -- 現在のライブラリのパスを返します。この関数はテンプレートプログラムモードで以下のように呼び出すことができます。"{:'current_library_path()'}".

field(lookup_name)

class calibre.utils.formatter_functions.BuiltinField[ソース]

field(lookup_name) -- lookup_name で指定された書誌の値を返します。

formats_modtimes(date_format)

class calibre.utils.formatter_functions.BuiltinFormatsModtimes[ソース]

formats_modtimes(date_format) -- 本の各形式の修正時刻(コロン区切り)を、カンマ区切りのリストで返します。date_formatパラメータは、日付がどのようにフォーマットされるかを指定します。詳細はformat_date関数の説明を参照してください。特定の形式の修正時刻を取り出すにはselect関数を使ってください。注:形式名は(EPUBの様に)必ず大文字です。

formats_paths()

class calibre.utils.formatter_functions.BuiltinFormatsPaths[ソース]

formats_paths() -- 形式名とその形式のファイルのフルパスをコロンで区切ったものを、カンマ区切りのリストにして返します。特定の形式のパスを取得するにはselect関数を使ってください。注:形式名は(EPUBの様に)必ず大文字です。

formats_sizes()

class calibre.utils.formatter_functions.BuiltinFormatsSizes[ソース]

formats_sizes() -- 本の各形式のサイズ(バイト・コロン区切り)を、カンマ区切りのリストで返します。特定の形式のサイズを取得するにはselect関数を使ってください。注:形式名は(EPUBの様に)必ず大文字です。

has_cover()

class calibre.utils.formatter_functions.BuiltinHasCover[ソース]

has_cover() -- もし本が表紙を持っていればYesを返し、それ以外では空文字列を返す。

is_marked()

class calibre.utils.formatter_functions.BuiltinIsMarked[ソース]

is_marked() -- 本が calibre で「マーク」されているかどうかを確認します。マークされていればマークの値を返します。マークの値は 'true' または名前付きマークのカンマ区切りリストです。本にマークが付いていない場合は '' を返します。

language_codes(lang_strings)

class calibre.utils.formatter_functions.BuiltinLanguageCodes[ソース]

language_codes(lang_strings) -- lang_stringsで渡された文字列に対応する言語コードを返します。文字列は現在のロケールの言語の物でなければなりません。Lang_strings はカンマ区切りのリストです。

language_strings(lang_codes, localize)

class calibre.utils.formatter_functions.BuiltinLanguageStrings[ソース]

language_strings(lang_codes, localize) -- lang_codesで渡される言語コードに対応する文字列を返します。もし localize がゼロならば、文字列を英語で返します。もし localize がゼロでなければ、現在のローケールに従った言語の文字列で返します。Lang_codes はカンマ区切りのリストです。

ondevice()

class calibre.utils.formatter_functions.BuiltinOndevice[ソース]

ondevice() -- ondevice が設定されている場合に Yes を返し、その他の場合は空文字列を返します。この関数はGUI上でのみ機能します。この値を「ディスクに保存」や「ディスクに送る」のテンプレートで使用したい場合には、「他の列から作られる列」でこの関数を使用したカスタム列を作成し、その列の値を「ディスクに保存」や「ディスクに送る」のテンプレートで参照するようにしてください。

raw_field(lookup_name [, optional_default])

class calibre.utils.formatter_functions.BuiltinRawField[ソース]

raw_field(lookup_name [, optional_default]) -- lookup_name で名前を指定された書籍情報のフィールドを整形する前の状態で返します。フィールドが定義されていない場合 ('None') には、オプションで指定する2番目の引数をデフォルトとして返します。

raw_list(lookup_name, separator)

class calibre.utils.formatter_functions.BuiltinRawList[ソース]

raw_list(lookup_name, separator) -- lookup_name と名付けた書誌リストを返す。書式設定や並べ替えを行わず、項目は separator で区切られる。

series_sort()

class calibre.utils.formatter_functions.BuiltinSeriesSort[ソース]

series_sort() -- シリーズのソート値を返します

user_categories()

class calibre.utils.formatter_functions.BuiltinUserCategories[ソース]

user_categories() -- この本が含まれるユーザカテゴリをカンマ区切りリストで返します。この関数はGUI上でのみ機能します。この値を「ディスクに保存」や「ディスクに送る」のテンプレートで使用したい場合には、「他の列から作られる列」でこの関数を使用したカスタム列を作成し、その列の値を「ディスクに保存」や「ディスクに送る」のテンプレートで参照するようにしてください。

virtual_libraries()

class calibre.utils.formatter_functions.BuiltinVirtualLibraries[ソース]

virtual_libraries() -- この本を含む仮想ライブラリのリストをカンマ区切りで返します。この関数はGUI上でのみ利用可能です。この値を save-to-disk テンプレートや send-to-device テンプレートで利用したい場合には、カスタムで "別の列から生成された列" を作成し、その列のテンプレート内で関数を使用し、列の値を save / send テンプレートで利用する必要があります。

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)

class calibre.utils.formatter_functions.BuiltinContains[ソース]

contains(val, pattern, text if match, text if not match) -- フィールドに正規表現'pattern'が含まれているかをチェックします。マッチした場合`text if match`を、それ以外の場合には `text if no match`を返します。

field_exists(field_name)

class calibre.utils.formatter_functions.BuiltinFieldExists[ソース]

field_exists(field_name) -- field_name で指定された名前のフィールド (列) が存在するかチェックし、存在すれば '1'、そうでなければ '' を返します。

ifempty(val, text if empty)

class calibre.utils.formatter_functions.BuiltinIfempty[ソース]

ifempty(val, text if empty) -- valが空でない場合valを返します。それ以外の場合は `text if empty`を返します。

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

class calibre.utils.formatter_functions.BuiltinTest[ソース]

test(val, text if not empty, text if empty) -- もし 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]*) -- 空ではない最初の値を返します。すべての値が空だっった場合には、空の文字列を返します。value の値はいくつでも指定できます。

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

class calibre.utils.formatter_functions.BuiltinLookup[ソース]

lookup(val, [pattern, field,]+ else_field) -- switchと似ていますが、ただし引数がフィールド(書誌)の名前で、テキストではありません。適切なフィールドの値が取り出され使われます。注: 合成された列もフィールドなので、この関数を合成されたフィールドに使い、他の合成されたフィールドの値を使うことも可能です。これはパスを保存する変数を作成する時に特に便利です。

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

class calibre.utils.formatter_functions.BuiltinSwitch[ソース]

switch(val, [pattern, value,]+ else_value) -- pattern, value のペアごとに 'val' が正規表現 'pattern' に一致するか確認し、一致すれば 'value' を返します。一致するものがなければ、else_value を返します。pattern, value のペアはいくつでも指定することができます。

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)

class calibre.utils.formatter_functions.BuiltinListitem[ソース]

list_item(val, index, separator) -- val を separator で区切られた項目のリストとして解釈し、index 番目の物を返す。最初の項目は0番目です。最後の項目は list_item(-1,separator) とすれば返ります。separator は 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 を separator で区切られた項目のリストとして扱い、文字列がリスト値のいずれかと一致する場合は found_val を返します。文字列がリスト値と一致しない場合niは、not_found_val を返します。比較は完全一致 (「含む」ではない) であり、大文字と小文字は区別されません。文字列と found_value のペアは、必要な回数だけ繰り返すことができます。パターンは順番にチェックされます。最初に一致した found_val が返されます。

List manipulation

count(val, separator)

class calibre.utils.formatter_functions.BuiltinCount[ソース]

count(val, separator) -- value を separator で区切られた項目のリストとして解釈し、リストの中にある項目数を返します。たいていのリストは separator としてカンマを使用しますが、著者名にはアンパーサンドを使用します。使用例: {tags:count(,)}, {authors:count(&)} エイリアス: count(), list_count()

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)

class calibre.utils.formatter_functions.BuiltinListCountMatching[ソース]

list_count_matching(list, pattern, separator) -- 'list' を 'separator' で区切られた項目のリストとして解釈し、リスト内の正規表現 'pattern' に一致する項目の数を返します。別名: list_count_matching()、count_matching()

list_difference(list1, list2, separator)

class calibre.utils.formatter_functions.BuiltinListDifference[ソース]

list_difference(list1, list2, separator) -- 大小文字無視の比較を使い、list1の中からlist2の中に該当する物を取り除いたリストを返します。list1とlist2、そして返されるリストの項目は separator で区切られます。

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

class calibre.utils.formatter_functions.BuiltinListEquals[ソース]

list_equals(list1, sep1, list2, sep2, yes_val, no_val) -- もし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、そして返されるリストの項目は 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)

class calibre.utils.formatter_functions.BuiltinListRe[ソース]

list_re(src_list, separator, include_re, opt_replace) -- まず src_list を separator 文字で分割しリストにします。それぞれの要素について、include_re の正規表現とのマッチを行い、マッチしたもののみ戻り値のリスト加えます。もし opt_replace が空文字列でなかった場合、戻り値のリストに加える前に、それぞれの要素に置換を適用します。

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

class calibre.utils.formatter_functions.BuiltinListReGroup[ソース]

list_re_group(src_list, separator, include_re, search_re [, group_template]+) -- list_re と似ていますが、置換がオプションではありません。結果のリストで置換を行う際に re_group(list_item, search_re, group_template, ...) を使用します。

list_remove_duplicates(list, separator)

class calibre.utils.formatter_functions.BuiltinListRemoveDuplicates[ソース]

list_remove_duplicates(list, separator) -- ソースリスト内の重複項目を削除したリストを返します。大文字と小文字だけが異なる項目の場合は、最後の項目が返されます。ソースリスト内の項目は、戻されたリスト内の項目と同様に、separator で区切られます。

list_sort(list, direction, separator)

class calibre.utils.formatter_functions.BuiltinListSort[ソース]

list_sort(list, direction, separator) -- 大小文字無視の整列を行ったlistを返します。もし direction が0の場合、リストは昇順で、それ以外の時には降順で整列されます。list と返されるリストの項目は 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)

class calibre.utils.formatter_functions.BuiltinListUnion[ソース]

list_union(list1, list2, separator) -- list1 と list2 の項目をマージししてできたリストを返します。リストからは重複する項目は削除されます (大文字/小文字を区別しない比較を使用)。項目の大文字と小文字が異なる場合は、list1 の項目が使用されます。list1 と list2 の項目は、返されるリスト内の項目と同様に、separator で区切られます。別名: list_union()、merge_lists()

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)

class calibre.utils.formatter_functions.BuiltinAssign[ソース]

assign(id, val) -- id に val を割り当て、val を返します。id は式ではなく識別子でなくてはなりません。この関数はしばしば=演算子で置き換えられます。

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

class calibre.utils.formatter_functions.BuiltinGlobals[ソース]

globals(id[=expression] [, id[=expression]]*) -- フォーマッタに渡すことができる「グローバル変数」を取得します。渡されたグローバル変数の名前でローカル変数を宣言し、初期化します。渡されたグローバル変数に対応する変数が指定されていない場合は、その変数に指定されたデフォルト値が割り当てられます。デフォルト値がない場合、変数は空の文字列に設定されます。

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)

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,]+, else_result)

class calibre.utils.formatter_functions.BuiltinFirstMatchingCmp[ソース]

first_matching_cmp(val, [cmp1, result1,]+, else_result) -- "val < cmpN" を順に比較し、最初に比較が成功したときの resultN を返します。比較がひとつも成功しなかった場合には else_result を返します。使用例: first_matching_cmp(10,5,"small",10,"middle",15,"large","giant") は "large" を返します。同じ例で最初の値を16にした場合には "giant" を返します。

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

class calibre.utils.formatter_functions.BuiltinStrcmp[ソース]

strcmp(x, y, lt, eq, gt) -- x とy を文字列として、大文字と小文字を区別せずに比較します。x < y のとき lt を返し、x == y のとき 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)

class calibre.utils.formatter_functions.BuiltinCapitalize[ソース]

capitalize(val) -- val をキャピタライズして返します。

lowercase(val)

class calibre.utils.formatter_functions.BuiltinLowercase[ソース]

lowercase(val) -- val を小文字で返します。

titlecase(val)

class calibre.utils.formatter_functions.BuiltinTitlecase[ソース]

titlecase(val) -- val をタイトルケースに変換して返します。

uppercase(val)

class calibre.utils.formatter_functions.BuiltinUppercase[ソース]

uppercase(val) -- val を大文字で返します。

String manipulation

character(character_name)

class calibre.utils.formatter_functions.BuiltinCharacter[ソース]

character(character_name) -- character_name で名付けられた文字を返します。たとえば character('newline') は改行文字 ('n') を返します。サポートする文字名は'newline', 'return', 'tab', および 'backslash' です。

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]*)

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]*)

class calibre.utils.formatter_functions.BuiltinStrcat[ソース]

strcat(a [, b]*) -- 引数はいくつでも指定することができます。すべての引数を連結した文字列を返します。

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

class calibre.utils.formatter_functions.BuiltinStrcatMax[ソース]

strcat_max(max, string1 [, prefix2, string2]*) -- 引数を結合した文字列を返します。戻り値は string1 に初期化されます。'接頭辞, 文字列' のペアは、結果の文字列の長さが 'max' より小さい限り、値の末尾に追加されます。文字列 1 が max より長い場合も、文字列 1 が返されます。'接頭辞, 文字列' のペアはいくつでも渡すことができます。

strlen(a)

class calibre.utils.formatter_functions.BuiltinStrlen[ソース]

strlen(a) -- 引数として渡した文字列の長さを返す。

substr(str, start, end)

class calibre.utils.formatter_functions.BuiltinSubstr[ソース]

substr(str, start, end) -- str文字列中の、start番目からend番目までの文字列を返します。文字列の最初の文字は0番目の文字です。もし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 を返します。val にはリストも指定可能で、リストで指定した場合にはその中のものをひとつずつ処理します。値がリストの場合、separator の値として区切り記号を指定する必要があります。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をそのまま返します。

to_hex(val)

class calibre.utils.formatter_functions.BuiltinToHex[ソース]

to_hex(val) -- 文字列を16進にエンコードして返します。calibre URLを生成する際に有用です

transliterate(a)

class calibre.utils.formatter_functions.BuiltinTransliterate[ソース]

transliterate(a) -- 元の文字列を、概ねその発音に基づいてラテン文字に変換し返します。例えば、変換元が "Фёдор Миха́йлович Достоевский" の場合は、"Fiodor Mikhailovich Dostoievskii" を返します。

Template database functions

book_count(query, use_vl)

class calibre.utils.formatter_functions.BuiltinBookCount[ソース]

book_count(query, use_vl) -- returns the count of 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.

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)

class calibre.utils.formatter_functions.BuiltinExtraFileSize[ソース]

extra_file_size(file_name) -- returns the size in bytes of the extra file 'file_name' in the book's 'data/' folder if it exists, otherwise -1.This function can be used only in the GUI.

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]]*)

class calibre.utils.formatter_functions.BuiltinSetGlobals[ソース]

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

API of the Metadata objects

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

class calibre.ebooks.metadata.book.base.Metadata(title, authors=('不明',), other=None, template_cache=None, formatter=None)[ソース]

A class representing all the metadata for a book. The various standard metadata fields are available as attributes of this object. You can also stick arbitrary attributes onto this object.

Metadata from custom columns should be accessed via the get() method, passing in the lookup name for the column, for example: "#mytags".

Use the is_null() method to test if a field is null.

This object also has functions to format fields into strings.

The list of standard metadata fields grows with time is in STANDARD_METADATA_FIELDS.

Please keep the method based API of this class to a minimum. Every method becomes a reserved field name.

is_null(field)[ソース]

Return True if the value of field is null in this object. 'null' means it is unknown or evaluates to False. So a title of _('Unknown') is null or a language of 'und' is null.

Be careful with numeric fields since this will return True for zero as well as None.

Also returns True if the field does not exist.

deepcopy(class_generator=<function Metadata.<lambda>>)[ソース]

Do not use this method unless you know what you are doing, if you want to create a simple clone of this object, use deepcopy_metadata() instead. Class_generator must be a function that returns an instance of Metadata or a subclass of it.

get_identifiers()[ソース]

Return a copy of the identifiers dictionary. The dict is small, and the penalty for using a reference where a copy is needed is large. Also, we don't want any manipulations of the returned dict to show up in the book.

set_identifiers(identifiers)[ソース]

Set all identifiers. Note that if you previously set ISBN, calling this method will delete it.

set_identifier(typ, val)[ソース]

If val is empty, deletes identifier of type typ

standard_field_keys()[ソース]

return a list of all possible keys, even if this book doesn't have them

custom_field_keys()[ソース]

return a list of the custom fields in this book

all_field_keys()[ソース]

All field keys known by this instance, even if their value is None

metadata_for_field(key)[ソース]

return metadata describing a standard or custom field.

all_non_none_fields()[ソース]

Return a dictionary containing all non-None metadata fields, including the custom ones.

get_standard_metadata(field, make_copy)[ソース]

return field metadata from the field if it is there. Otherwise return None. field is the key name, not the label. Return a copy if requested, just in case the user wants to change values in the dict.

get_all_standard_metadata(make_copy)[ソース]

return a dict containing all the standard field metadata associated with the book.

get_all_user_metadata(make_copy)[ソース]

return a dict containing all the custom field metadata associated with the book.

get_user_metadata(field, make_copy)[ソース]

return field metadata from the object if it is there. Otherwise return None. field is the key name, not the label. Return a copy if requested, just in case the user wants to change values in the dict.

set_all_user_metadata(metadata)[ソース]

store custom field metadata into the object. Field is the key name not the label

set_user_metadata(field, metadata)[ソース]

store custom field metadata for one column into the object. Field is the key name not the label

remove_stale_user_metadata(other_mi)[ソース]

Remove user metadata keys (custom column keys) if they don't exist in 'other_mi', which must be a metadata object

template_to_attribute(other, ops)[ソース]

Takes a list [(src,dest), (src,dest)], evaluates the template in the context of other, then copies the result to self[dest]. This is on a best-efforts basis. Some assignments can make no sense.

smart_update(other, replace_metadata=False)[ソース]

Merge the information in other into self. In case of conflicts, the information in other takes precedence, unless the information in other is NULL.

format_field(key, series_with_index=True)[ソース]

Returns the tuple (display_name, formatted_value)

to_html()[ソース]

A HTML representation of this object.

calibre.ebooks.metadata.book.base.STANDARD_METADATA_FIELDS

The set of standard metadata fields.


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

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

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

TOP_LEVEL_IDENTIFIERS = frozenset((
    'isbn',
))

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

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

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

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

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

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

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

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

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

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

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