我的书签
添加书签
移除书签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.
class calibre.utils.formatter_functions.BuiltinAdd[source]
add(x [, y]*) – returns the sum of its arguments. Throws an exception if an argument is not a number. In most cases you can use the + operator instead of this function.
class calibre.utils.formatter_functions.BuiltinCeiling[source]
ceiling(value) – returns the smallest integer greater than or equal to value. Throws an exception if value is not a number.
class calibre.utils.formatter_functions.BuiltinDivide[source]
divide(x, y) – returns x / y. Throws an exception if either x or y are not numbers. This function can usually be replaced by the / operator.
class calibre.utils.formatter_functions.BuiltinFloor[source]
floor(value) – returns the largest integer less than or equal to value. Throws an exception if value is not a number.
class calibre.utils.formatter_functions.BuiltinFractionalPart[source]
fractional_part(value) – returns the part of the value after the decimal point. For example, fractional_part(3.14) returns 0.14. Throws an exception if value is not a number.
class calibre.utils.formatter_functions.BuiltinMod[source]
mod(value, y) – returns the floor of the remainder of value / y. Throws an exception if either value or y is not a number.
class calibre.utils.formatter_functions.BuiltinMultiply[source]
multiply(x [, y]*) – returns the product of its arguments. Throws an exception if any argument is not a number. This function can usually be replaced by the * operator.
class calibre.utils.formatter_functions.BuiltinRound[source]
round(value) – returns the nearest integer to value. Throws an exception if value is not a number.
class calibre.utils.formatter_functions.BuiltinSubtract[source]
subtract(x, y) – returns x - y. Throws an exception if either x or y are not numbers. This function can usually be replaced by the - operator.
class calibre.utils.formatter_functions.BuiltinAnd[source]
and(value [, value]*) – returns the string '1' if all values are not empty, otherwise returns the empty string. You can have as many values as you want. In most cases you can use the && operator instead of this function. One reason not to replace and() with && is when short-circuiting can change the results because of side effects. For example, and(a='',b=5) will always do both assignments, where the && operator won’t do the second.
class calibre.utils.formatter_functions.BuiltinNot[source]
not(value) – returns the string '1' if the value is empty, otherwise returns the empty string. This function can usually be replaced with the unary not (!) operator.
class calibre.utils.formatter_functions.BuiltinOr[source]
or(value [, value]*) – returns the string '1' if any value is not empty, otherwise returns the empty string. You can have as many values as you want. This function can usually be replaced by the || operator. A reason it cannot be replaced is if short-circuiting will change the results because of side effects.
class calibre.utils.formatter_functions.BuiltinCapitalize[source]
capitalize(value) – returns the value with the first letter in upper case and the rest lower case.
class calibre.utils.formatter_functions.BuiltinLowercase[source]
lowercase(value) – returns the value in lower case.
class calibre.utils.formatter_functions.BuiltinTitlecase[source]
titlecase(value) – returns the value in title case.
class calibre.utils.formatter_functions.BuiltinUppercase[source]
uppercase(value) – returns the value in upper case.
class calibre.utils.formatter_functions.BuiltinAnnotationCount[source]
annotation_count() – return the total number of annotations of all types attached to the current book. This function works only in the GUI and the content server.
class calibre.utils.formatter_functions.BuiltinApproximateFormats[source]
approximate_formats() – return a comma-separated list of formats associated with the book. Because the list comes from calibre’s database instead of the file system, there is no guarantee that the list is correct, although it probably is. Note that resulting format names are always uppercase, as in EPUB. The approximate_formats() function is much faster than the formats_... functions.
This function works only in the GUI. If you want to use these values in save-to-disk or send-to-device templates then you must make a custom “Column built from other columns”, use the function in that column’s template, and use that column’s value in your save/send templates.
class calibre.utils.formatter_functions.BuiltinBookCount[source]
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 and its companion book_values() are particularly useful in template searches, supporting searches that combine information from many books such as looking for series with only one book. It cannot be used in composite columns unless the tweak allow_template_database_functions_in_composites is set to True. It can be used only in the GUI.
For example this template search uses this function and its companion to find all series with only one book:
- Define a stored template (using Preferences → Advanced → Template functions) named
series_only_one_book(the name is arbitrary). The template is:
program:
vals = globals(vals='');
if !vals then
all_series = book_values('series', 'series:true', ',', 0);
for series in all_series:
if book_count('series:="' & series & '"', 0) == 1 then
vals = list_join(',', vals, ',', series, ',')
fi
rof;
set_globals(vals)
fi;
str_in_list(vals, ',', $series, 1, '')
The first time the template runs (the first book checked) it stores the results of the database lookups in a global template variable named vals. These results are used to check subsequent books without redoing the lookups.
- Use the stored template in a template search:
template:"program: series_only_one_book()#@#:n:1"Using a stored template instead of putting the template into the search eliminates problems caused by the requirement to escape quotes in search expressions.
This function can be used only in the GUI and the content server.
class calibre.utils.formatter_functions.BuiltinBookValues[source]
book_values(column, query, sep, use_vl) – returns a list of the unique values contained in the column column (a lookup name), separated by sep, in the books found by searching for query. If use_vl is 0 (zero) then virtual libraries are ignored. This function and its companion book_count() are particularly useful in template searches, supporting searches that combine information from many books such as looking for series with only one book. It cannot be used in composite columns unless the tweak allow_template_database_functions_in_composites is set to True. This function can be used only in the GUI and the content server.
class calibre.utils.formatter_functions.BuiltinExtraFileModtime[source]
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. The modtime is formatted according to format_string (see format_date() for details). If format_string is the empty string, returns the modtime as the floating point number of seconds since the epoch. See also the functions has_extra_files(), extra_file_names() and extra_file_size(). The epoch is OS dependent. This function can be used only in the GUI and the content server.
class calibre.utils.formatter_functions.BuiltinExtraFileNames[source]
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. See also the functions has_extra_files(), extra_file_modtime() and extra_file_size(). This function can be used only in the GUI and the content server.
class calibre.utils.formatter_functions.BuiltinExtraFileSize[source]
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. See also the functions has_extra_files(), extra_file_names() and extra_file_modtime(). This function can be used only in the GUI and the content server.
class calibre.utils.formatter_functions.BuiltinFormatsModtimes[source]
formats_modtimes(date_format_string) – return a comma-separated list of colon-separated items FMT:DATE representing modification times for the formats of a book. The date_format_string parameter specifies how the date is to be formatted. See the format_date() function for details. You can use the select() function to get the modification time for a specific format. Note that format names are always uppercase, as in EPUB.
class calibre.utils.formatter_functions.BuiltinFormatsPathSegments[source]
formats_path_segments(with_author, with_title, with_format, with_ext, sep) – return parts of the path to a book format in the calibre library separated by sep. The parameter sep should usually be a slash ('/'). One use is to be sure that paths generated in Save to disk and Send to device templates are shortened consistently. Another is to be sure the paths on the device match the paths in the calibre library.
A book path consists of 3 segments: the author, the title including the calibre database id in parentheses, and the format (author - title). Calibre can shorten any of the three because of file name length limitations. You choose which segments to include by passing 1 for that segment. If you don’t want a segment then pass 0 or the empty string for that segment. For example, the following returns just the format name without the extension:
formats_path_segments(0, 0, 1, 0, '/')
Because there is only one segment the separator is ignored.
If there are multiple formats (multiple extensions) then one of the extensions will be picked at random. If you care about which extension is used then get the path without the extension then add the desired extension to it.
Examples: Assume there is a book in the calibre library with an epub format by Joe Blogs with title ‘Help’. It would have the path
Joe Blogs/Help - (calibre_id)/Help - Joe Blogs.epub
The following shows what is returned for various parameters:
formats_path_segments(0, 0, 1, 0, '/')returns Help - Joe Blogsformats_path_segments(0, 0, 1, 1, '/')returns Help - Joe Blogs.epubformats_path_segments(1, 0, 1, 1, '/')returns Joe Blogs/Help - Joe Blogs.epubformats_path_segments(1, 0, 1, 0, '/')returns Joe Blogs/Help - Joe Blogsformats_path_segments(0, 1, 0, 0, '/')returns Help - (calibre_id)
class calibre.utils.formatter_functions.BuiltinFormatsPaths[source]
formats_paths([separator]) – return a separator-separated list of colon-separated items FMT:PATH giving the full path to the formats of a book. The separator argument is optional. If not supplied then the separator is ', ' (comma space). If the separator is a comma then you can use the select() function to get the path for a specific format. Note that format names are always uppercase, as in EPUB.
class calibre.utils.formatter_functions.BuiltinFormatsSizes[source]
formats_sizes() – return a comma-separated list of colon-separated FMT:SIZE items giving the sizes of the formats of a book in bytes. You can use the select() function to get the size for a specific format. Note that format names are always uppercase, as in EPUB.
class calibre.utils.formatter_functions.BuiltinGetLink[source]
get_link(field_name, field_value) – fetch the link for field field_name with value field_value. If there is no attached link, return the empty string. Examples:
- The following returns the link attached to the tag
Fiction:
get_link('tags', 'Fiction')
- This template makes a list of the links for all the tags associated with a book in the form value:link, ...:
program:
ans = '';
for t in $tags:
l = get_link('tags', t);
if l then
ans = list_join(', ', ans, ',', t & ':' & get_link('tags', t), ',')
fi
rof;
ans
This function works only in the GUI and the content server.
class calibre.utils.formatter_functions.BuiltinGetNote[source]
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:
- Return the HTML of the note attached to the tag Fiction:
program:
get_note('tags', 'Fiction', '')
- Return the plain text of the note attached to the author Isaac Asimov:
program:
get_note('authors', 'Isaac Asimov', 1)
This function works only in the GUI and the content server.
class calibre.utils.formatter_functions.BuiltinHasExtraFiles[source]
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. See also the functions extra_file_names(), extra_file_size() and extra_file_modtime(). This function can be used only in the GUI and the content server.
class calibre.utils.formatter_functions.BuiltinHasNote[source]
has_note(field_name, field_value). Check if a field has a note. This function has two variants:
- if
field_valueis not''(the empty string) return'1'if the valuefield_valuein the fieldfield_namehas a note, otherwise''.
Example: has_note('tags', 'Fiction') returns '1' if the tag fiction has an attached 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 ''. This variant is useful for showing column icons if any value in the field has a note, rather than a specific value.
Example: has_note('authors', '') returns a list of authors that have notes, or '' if no author has a note.
You can test if all the values in field_name have a note by comparing the list length of this function’s return value against the list length of the values in field_name. Example:
list_count(has_note('authors', ''), '&') ==# list_count_field('authors')
This function works only in the GUI and the content server.
class calibre.utils.formatter_functions.BuiltinReadingProgress[source]
reading_progress(book_id, [user, output_fmt, which, fmt]) – returns the reading progress, in the specified output format.The user parameter defaults to match any user. Use the value local to match reading progress in the calibre e-book viewer. Use _ to match reading progress for anonymous users of the Content server viewer. Any other value matches the corresponding username as used in the Content server.
The output_fmt parameter controls the format of the text returned by this function. It takes any of the following values:
page_count- the default, outputspages read / total pages. If page counting is not enabled outputs percent read instead.percent- outputs percent readpercent_number- outputs percent read as a number without the trailing percent sign, useful for sorting.pos_frac- outputs a fraction between zero and one.
The which parameter controls how the specific reading progress record for the specified user is selected. There can be more than one record if no user is specified or if the book has been read in multiple formats or on multiple devices. It accepts two values:
most_recent- the progress of the most recent reader of the book (the default value)furthest- the furthest progress of all matching records
The fmt parameter controls which book format is used. The default is to return records for all formats, the specific record is then selected by the which parameter.
Some examples:
{id:reading_progress()} -- the reading progress as pages read / total pages
for the most recent reading session of this book
{id:reading_progress(,percent)} -- same as above, but as a percentage
{id:reading_progress(,pos_frac,furthest)} -- same as above, but as a fraction and using the
furthest progress on this book.
{id:reading_progress(bob,pos_frac,furthest,EPUB)} -- for the user "bob" and the "EPUB" format.
class calibre.utils.formatter_functions.BuiltinDateArithmetic[source]
date_arithmetic(value, calc_spec, fmt) – Calculate a new date from value using calc_spec. Return the new date formatted according to optional fmt: if not supplied then the result will be in ISO format. The calc_spec is a string formed by concatenating pairs of vW (valueWhat) where v is a possibly-negative number and W is one of the following letters:
s: addvseconds todatem: addvminutes todateh: addvhours todated: addvdays todatew: addvweeks todatey: addvyears todate, where a year is 365 days.
Example: '1s3d-1m' will add 1 second, add 3 days, and subtract 1 minute from date.
class calibre.utils.formatter_functions.BuiltinDaysBetween[source]
days_between(date1, date2) – return the number of days between date1 and date2. The number is positive if date1 is greater than date2, otherwise negative. If either date1 or date2 are not dates, the function returns the empty string.
class calibre.utils.formatter_functions.BuiltinToday[source]
today() – return a date+time string for today (now). This value is designed for use in format_date or days_between, but can be manipulated like any other string. The date is in ISO date/time format.
class calibre.utils.formatter_functions.BuiltinFString[source]
f_string(string) – interpret string similar to how python interprets f strings. The intended use is to simplify long sequences of str & str or strcat(a,b,c) expressions.
Text between braces ({ and }) must be General Program Mode template expressions. The expressions, which can be expression lists, are evaluated in the current context (current book and local variables). Text not between braces is passed through unchanged.
Examples:
f_string('Here is the title: {$title}')- returns the string with{$title}replaced with the title of the current book. For example, if the book’s title is 20,000 Leagues Under the Sea then thef_string()returns Here is the title: 20,000 Leagues Under the Sea.- Assuming the current date is 18 Sept 2025, this
f_string()
f_string("Today's date: the {d = today(); format_date(d, 'd')} of {format_date(d, 'MMMM')}, {format_date(d, 'yyyy')}")
returns the string Today’s date: the 18 of September, 2025. Note the expression list (an assignment then an if statement) used in the first { ... } group to assign today’s date to a local variable.
- If the book is book #3 in a series named Foo that has 5 books then this template
program:
if $series then
series_count = book_count('series:"""=' & $series & '"""', 0);
return f_string("{$series}, book {$series_index} of {series_count}")
fi;
return 'This book is not in a series'
returns Foo, book 3 of 5
class calibre.utils.formatter_functions.BuiltinFinishFormatting[source]
finish_formatting(value, format, prefix, suffix) – apply the format, prefix, and suffix to the value in the same way as done in a template like {series_index:05.2f| - |- }. This function is provided to ease conversion of complex single-function- or template-program-mode templates to GPM Templates. For example, the following program produces the same output as the above template:
program: finish_formatting(field("series_index"), "05.2f", " - ", " - ")
Another example: for the template:
{series:re(([^\s])[^\s]+(\s|$),\1)}{series_index:0>2s| - | - }{title}
use:
program:
strcat(
re(field('series'), '([^\s])[^\s]+(\s|$)', '\1'),
finish_formatting(field('series_index'), '0>2s', ' - ', ' - '),
field('title')
)
class calibre.utils.formatter_functions.BuiltinFormatDate[source]
format_date(value, format_string) – format the value, which must be a date string, using the format_string, returning a string. It is best if the date is in ISO format as 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 lowercase localized string for am or pmAP :use a 12-hour clock instead of a 24-hour clock, with ‘AP’ replaced by the uppercase localized string for AM or PMaP :use a 12-hour clock instead of a 24-hour clock, with ‘aP’ replaced by the localized string for AM or PMAp :use a 12-hour clock instead of a 24-hour clock, with ‘Ap’ replaced by the localized string for AM or PMiso :the date with time and timezone. Must be the only format presentto_number :convert the date & time into a floating point number (a timestamp)from_number :convert a floating point number (a timestamp) into an ISO-formatted date. If you want a different date format then add the desired formatting string afterfrom_numberand a colon (:). Example:
format_date(val, 'from_number:MMM dd yyyy')
You might get unexpected results if the date you are formatting contains localized month names, which can happen if you changed the date format to contain MMMM. Using format_date_field() avoids this problem.
class calibre.utils.formatter_functions.BuiltinFormatDateField[source]
format_date_field(field_name, format_string) – format the value in the field field_name, which must be the lookup name of a 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 is also more reliable because it works directly on the underlying date. It can’t be used for computed dates or dates in string variables. Examples:
format_date_field('pubdate', 'yyyy.MM.dd')
format_date_field('#date_read', 'MMM dd, yyyy')
class calibre.utils.formatter_functions.BuiltinFormatDuration[source]
format_duration(value, template, [largest_unit]) – format the value, a number of seconds, into a string showing weeks, days, hours, minutes, and seconds. If the value is a float then it is rounded to the nearest integer. You choose how to format the value using a template consisting of value selectors surrounded by [ and ] characters. The selectors are:
[w]: weeks[d]: days[h]: hours[m]: minutes[s]: seconds
You can put arbitrary text between selectors.
The following examples use a duration of 2 days (172,800 seconds) 1 hour (3,600 seconds) and 20 seconds, which totals to 176,420 seconds.
format_duration(176420, '[d][h][m][s]')will return the value2d 1h 0m 20s.format_duration(176420, '[h][m][s]')will return the value49h 0m 20s.format_duration(176420, 'Your reading time is [d][h][m][s]')returns the valueYour reading time is 49h 0m 20s.format_duration(176420, '[w][d][h][m][s]')will return the value2d 1h 0m 20s. Note that the zero weeks value is not returned.
If you want to see zero values for items such as weeks in the above example, use an uppercase selector. For example, the following uses 'W' to show zero weeks:
format_duration(176420, '[W][d][h][m][s]') returns 0w 2d 1h 0m 20s.
By default the text following a value is the selector followed by a space. You can change that to whatever text you want. The format for a selector with your text is the selector followed by a colon followed by text segments separated by '|' characters. You must include any space characters you want in the output.
You can provide from one to three text segments.
- If you provide one segment, as in
[w: weeks ]then that segment is used for all values. - If you provide two segments, as in
[w: weeks | week ]then the first segment is used for 0 and more than 1. The second segment is used for 1. - If you provide three segments, as in
[w: weeks | week | weeks ]then the first segment is used for 0, the second segment is used for 1, and the third segment is used for more than 1.
The second form is equivalent to the third form in many languages.
For example, the selector:
[w: weeks | week | weeks ]produces'0 weeks ','1 week ', or'2 weeks '.[w: weeks | week ]produces'0 weeks ','1 week ', or'2 weeks '.[w: weeks ]produces0 weeks ',1 weeks ', or2 weeks '.
The optional largest_unit parameter specifies the largest of weeks, days, hours, minutes, and seconds that will be produced by the template. It must be one of the value selectors. This can be useful to truncate a value.
format_duration(176420, '[h][m][s]', 'd') will return the value 1h 0m 20s instead of 49h 0m 20s.
class calibre.utils.formatter_functions.BuiltinFormatNumber[source]
format_number(value, template) – interprets the value as a number and formats that number using a Python formatting template such as {0:5.2f} or {0:,d} or ${0:5,.2f}. The formatting template must begin with {0: and end with } as in the above examples. Exception: you can leave off the leading “{0:” and trailing “}” if the format template contains only a format. See the Template Language and the Python documentation for more examples. Returns the empty string if formatting fails.
class calibre.utils.formatter_functions.BuiltinHumanReadable[source]
human_readable(value) – expects the value to be a number and returns a string representing that number in KB, MB, GB, etc.
class calibre.utils.formatter_functions.BuiltinRatingToStars[source]
rating_to_stars(value, use_half_stars) – Returns the value as string of star (★) characters. The value must be a number between 0 and 5. Set use_half_stars to 1 if you want half star characters for fractional numbers available with custom ratings columns.
class calibre.utils.formatter_functions.BuiltinSelectedBooks[source]
selected_books([sorted_by, ascending]) – returns a list of book ids in selection order for the currently selected books.
This function can be used only in the GUI.
class calibre.utils.formatter_functions.BuiltinSelectedColumn[source]
selected_column() – returns the lookup name of the column containing the currently selected cell. It returns '' if no cell is selected.
This function can be used only in the GUI.
class calibre.utils.formatter_functions.BuiltinShowDialog[source]
show_dialog(html_or_text) – show a dialog containing the html or text. The function returns '1' if the user presses OK, '' if Cancel.
This function can be used only in the GUI.
class calibre.utils.formatter_functions.BuiltinSortBookIds[source]
sort_book_ids(book_ids, sorted_by, ascending [, sorted_by, ascending]*) – returns the list of book ids sorted by the column specified by the lookup name in sorted_by in the order specified by ascending. If ascending is '1' then the books are sorted by the value in the ‘sorted_by’ column in ascending order, otherwise in descending order. You can have multiple pairs of sorted_by, ascending. The first pair specifies the major order.
This function can be used only in the GUI.
class calibre.utils.formatter_functions.BuiltinWidthFromPages[source]
width_from_pages(value [, num_of_pages_for_max_width, logarithmic_factor, default_width]) – return the width of the book spine as a fraction between '0' and '1' given a number of pages. This is used to calculate the width of the spine in the Bookshelf view, from a page count. The optional arguments control how the width is calculated.
num_of_pages_for_max_width– controls the widest books, any book with at least the specified number of pages is given width 1. Defaults to1500.logarithmic_factor– controls how quickly width varies as pages range from 0 to the maximum. Defaults to2.default_width– is the width for books with an invalid number of pages.
class calibre.utils.formatter_functions.BuiltinAuthorLinks[source]
author_links(val_separator, pair_separator) – returns a string containing a list of authors and those authors’ link values in the form: author1 val_separator author1_link pair_separator author2 val_separator author2_link etc.
An author is separated from its link value by the val_separator string with no added spaces. Assuming the val_separator is a colon, author:link value pairs are separated by the pair_separator string argument with no added spaces. It is up to you to choose separators that do not occur in author names or links. An author is included even if the author link is empty.
class calibre.utils.formatter_functions.BuiltinAuthorSorts[source]
author_sorts(val_separator) – returns a string containing a list of author’s sort values for the authors of the book. The sort is the one in the author metadata information, which can be different from the author_sort in books. The returned list has the form author sort 1 val_separator author sort 2 etc. with no added spaces. The author sort values in this list are in the same order as the authors of the book. If you want spaces around val_separator then include them in the val_separator string.
class calibre.utils.formatter_functions.BuiltinBooksize[source]
booksize() – returns the value of the calibre size field. Returns ‘’ if the book has no formats.
This function works only in the GUI. If you want to use this value in save-to-disk or send-to-device templates then you must make a custom “Column built from other columns”, use the function in that column’s template, and use that column’s value in your save/send templates
class calibre.utils.formatter_functions.BuiltinConnectedDeviceName[source]
connected_device_name(storage_location_key) – if a device is connected then return the device name, otherwise return the empty string. Each storage location on a device has its own device name. The storage_location_key names are 'main', 'carda' and 'cardb'. This function works only in the GUI.
class calibre.utils.formatter_functions.BuiltinConnectedDeviceUUID[source]
connected_device_uuid(storage_location_key) – if a device is connected then return the device uuid (unique id), otherwise return the empty string. Each storage location on a device has a different uuid. The storage_location_key location names are 'main', 'carda' and 'cardb'. This function works only in the GUI.
class calibre.utils.formatter_functions.BuiltinCurrentLibraryName[source]
current_library_name() – return the last name on the path to the current calibre library.
class calibre.utils.formatter_functions.BuiltinCurrentLibraryPath[source]
current_library_path() – return the full path to the current calibre library.
class calibre.utils.formatter_functions.BuiltinCurrentVirtualLibraryName[source]
current_virtual_library_name() – return the name of the current virtual library if there is one, otherwise the empty string. Library name case is preserved. Example:
program: current_virtual_library_name()
This function works only in the GUI.
class calibre.utils.formatter_functions.BuiltinField[source]
field(lookup_name) – returns the value of the metadata field with lookup name lookup_name. The $ prefix can be used instead of the function, as in $tags.
class calibre.utils.formatter_functions.BuiltinHasCover[source]
has_cover() – return 'Yes' if the book has a cover, otherwise the empty string.
class calibre.utils.formatter_functions.BuiltinIsMarked[source]
is_marked() – check whether the book is marked in calibre. If it is then return the value of the mark, either 'true' (lower case) or a comma-separated list of named marks. Returns '' (the empty string) if the book is not marked. This function works only in the GUI.
class calibre.utils.formatter_functions.BuiltinLanguageCodes[source]
language_codes(lang_strings) – return the language codes for the language names passed in lang_strings. The strings must be in the language of the current locale. lang_strings is a comma-separated list.
class calibre.utils.formatter_functions.BuiltinLanguageStrings[source]
language_strings(value, localize) – return the language names for the language codes (see here for names and codes) passed in value. Example: {languages:language_strings()}. If localize is zero, return the strings in English. If localize is not zero, return the strings in the language of the current locale. lang_codes is a comma-separated list.
class calibre.utils.formatter_functions.BuiltinOndevice[source]
ondevice() – return the string 'Yes' if ondevice is set, otherwise return the empty string. This function works only in the GUI. If you want to use this value in save-to-disk or send-to-device templates then you must make a custom “Column built from other columns”, use the function in that column’s template, and use that column’s value in your save/send templates.
class calibre.utils.formatter_functions.BuiltinRawField[source]
raw_field(lookup_name [, optional_default]) – returns the metadata field named by lookup_name without applying any formatting. It evaluates and returns the optional second argument optional_default if the field’s value is undefined (None). The $$ prefix can be used instead of the function, as in $$pubdate.
class calibre.utils.formatter_functions.BuiltinRawList[source]
raw_list(lookup_name, separator) – returns the metadata list named by lookup_name without applying any formatting or sorting, with the items separated by separator.
class calibre.utils.formatter_functions.BuiltinSeriesSort[source]
series_sort() – returns the series sort value.
class calibre.utils.formatter_functions.BuiltinUserCategories[source]
user_categories() – return a comma-separated list of the user categories that contain this book. This function works only in the GUI. If you want to use these values in save-to-disk or send-to-device templates then you must make a custom Column built from other columns, use the function in that column’s template, and use that column’s value in your save/send templates
class calibre.utils.formatter_functions.BuiltinVirtualLibraries[source]
virtual_libraries() – return a comma-separated list of Virtual libraries that contain this book. This function works only in the GUI. If you want to use these values in save-to-disk or send-to-device templates then you must make a custom Column built from other columns, use the function in that column’s template, and use that column’s value in your save/send templates.
class calibre.utils.formatter_functions.BuiltinFirstNonEmpty[source]
first_non_empty(value [, value]*) – returns the first value that is not empty. If all values are empty, then the empty string is returned. You can have as many values as you want.
class calibre.utils.formatter_functions.BuiltinLookup[source]
lookup(value, [ pattern, key, ]* else_key) – The patterns will be checked against the value in order. If a pattern matches then the value of the field named by key is returned. If no pattern matches then the value of the field named by else_key is returned. See also the switch() function.
class calibre.utils.formatter_functions.BuiltinSwitch[source]
switch(value, [patternN, valueN,]+ else_value) – for each patternN, valueN pair, checks if the value matches the regular expression patternN and if so returns the associated valueN. If no patternN matches, then else_value is returned. You can have as many patternN, valueN pairs as you wish. The first match is returned.
class calibre.utils.formatter_functions.BuiltinSwitchIf[source]
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.
class calibre.utils.formatter_functions.BuiltinIdentifierInList[[source]](../../_module
（本文超出站点单文档体积上限，已截断）
