48
calibre User Manual, Release 2.56.0
fast_field_for(field_obj, book_id,default_value=None)
Same as field_for, except that it avoids the extra lookup to get the field object
field_for(name,book_id, default_value=None)
Return the value of the field name for the book identified by book_id. If no such book exists or it has
no definedvalue for the field name or no such field exists, then default_value is returned.
default_value is not used for title, title_sort, authors, author_sort and series_index. This is because
these always have values in the db. default_value is used for all custom columns.
The returnedvalue foris_multiple fields are always tuples, evenwhennovalues are found(in otherwords,
default_value is ignored). The exception is identifiers for which the returned value is always a dict. The
returned tuples are always in link order,that is, the order in which they were created.
field_ids_for(name,book_id)
Return the ids (as a tuple) for the values that the field name has on the book identified by book_id. If
there are no values, or no such book, or no such field,an empty tuple is returned.
find_identical_books(mi, search_restriction=u’‘, book_ids=None)
Finds books that have a superset of the authors in mi and the same title (title is fuzzy matched). See also
data_for_find_identical_books()(page280).
format(book_id,fmt, as_file=False, as_path=False, preserve_filename=False)
Return the ebook format as a bytestring or None if the format doesn’t exist, or we don’t have permission
to write to the ebook file.
Parameters
• as_file – If True the ebook format is returned as a file object. Note that the file object
is a SpooledTemporaryFile, so if what you want to do is copy the format to another file,
usecopy_format_to() (page 280) instead forperformance.
• as_path – Copies the format file to a temp file and returns the path to the temp file
• preserve_filename – If True and returning a path the filename is the same as that
used in the library. Note that using this means that repeated calls yield the same temp file
(which is re-created each time)
format_abspath(book_id,fmt)
Return absolute path to the ebook file of format format. You should almost never use this,as it breaks the
threadsafe promise of this API.Instead use,copy_format_to() (page 280).
Currently used only in calibredb list, the viewer, edit book,compare_format to original format, open with
and the catalogs (via get_data_as_dict()).
Apart from the viewer, open with and edit book, Idon’tbelieve anyof the others do any file write I/Owith
the results ofthis call.
format_hash(book_id,fmt)
Return the hash of the specified format forthe specified book. The kind ofhash is backend dependent,but
is usually SHA-256.
format_metadata(book_id,fmt, allow_cache=True, update_db=False)
Return the path, size and mtime for the specified format for the specified book. You should not use path
unless you absolutely have to, since accessing it directly breaks the threadsafe guarantees of this API.
Instead use thecopy_format_to() (page 280) method.
Parameters
• allow_cache – If True cached values are used, otherwise a slow filesystem access is
done. The cache values could be out of date if access was performed to the filesystem
outside of this API.
1.12. Setting up a calibre development environment
281
47
calibre User Manual, Release 2.56.0
• update_db – IfTrue The max_size field ofthe database is updates for this book.
formats(book_id,verify_formats=True)
Return tuple of all formats for the specified book. If verify_formats is True, verifies that the files exist on
disk.
get_categories(sort=u’name’,book_ids=None, already_fixed=None,first_letter_sort=False)
Used internally to implement the Tag Browser
get_custom_book_data(name, book_ids=(),default=None)
Get data forname. By defaultreturns dataforallbook_ids,pass ina list of bookids if you onlywant some
data. Returns a map ofbook_id to values. If a particular value could not be decoded,uses default forit.
get_id_map(field)
Return a mapping of id numbers to values for the specified field. The field must be a many-one or many-
many field,otherwise a ValueError is raised.
get_ids_for_custom_book_data(name)
Return the set of book ids forwhich name has data.
get_item_id(field,item_name)
Return the itemid for item_name (case-insensitive)
get_item_ids(field,item_names)
Return the itemid for item_name (case-insensitive)
get_item_name(field,item_id)
Return the item name for the item specified by item_id in the specified field. See alsoget_id_map()
(page 282).
get_metadata(book_id,get_cover=False, get_user_categories=True, cover_as_data=False)
Returnmetadata forthebookidentifiedbybook_idas acalibre.ebooks.metadata.book.base.Metadata
(page 153) object. Note that the list of formats is not verified. If get_cover is True, the cover is returned,
either a path to temp file as mi.coveror if cover_as_data is True then as mi.cover_data.
get_next_series_num_for(series, field=u’series’, current_indices=False)
Returnthenext series indexfor the specified series,takinginto account the various preferences thatcontrol
next series number generation.
Parameters
• field – The series-like field (defaults to the builtin series column)
• current_indices – If True, returns a mapping of book_id to current series_index
value instead.
get_proxy_metadata(book_id)
Likeget_metadata() (page 282) except that it returns a ProxyMetadata object that only reads values
from the database on demand. This is much faster than get_metadata when only a small number of fields
need tobe accessed fromthe returned metadata object.
get_usage_count_by_id(field)
Return a mapping of id to usage count for all values of the specified field, which must be a many-one or
many-many field.
has_book(mi)
Return True iff the database contains an entry with the same title as the passed in Metadata object. The
comparison is case-insensitive. See alsodata_for_has_book() (page 280).
has_format(book_id,fmt)
Return True iffthe format exists on disk
282
Chapter 1. Sections
47
calibre User Manual, Release 2.56.0
has_id(book_id)
Return True iffthe specifiedbook_id exists in the db
init()
Initialize this cache with data from the backend.
multisort(fields, ids_to_sort=None, virtual_fields=None)
Return a list of sorted book ids. If ids_to_sort is None, all book ids are returned.
fields must be a list of 2-tuples of the form (field_name, ascending=True or False). The most significant
field is the first 2-tuple.
pref(name,default=None)
Return the value for the specified preference or the value specified as default if the preference is not
set.
read_backup(book_id)
Return the OPF metadata backup for the book as a bytestring or None ifno such backup exists.
remove_books(book_ids,permanent=False)
Remove the books specified by the book_ids from the database and delete their format files. If
permanent is False,then the format files are not deleted.
remove_formats(formats_map, db_only=False)
Remove the specified formats from the specified books.
Parameters
• formats_map –A mappingofbook_idto alistofformats tobe removedfromthebook.
• db_only – If True,only remove the record for the format from the db,do not delete the
actual format file fromthe filesystem.
remove_items(field,item_ids, restrict_to_book_ids=None)
Delete all items in the specified field with the specified ids. Returns the set of affected book ids.
restrict_to_book_ids is an optional set of books ids. If specified the items will only be removed
from those books.
rename_items(field,item_id_to_new_name_map, change_index=True, restrict_to_book_ids=None)
Rename items from a many-one ormany-many field such as tags or series.
Parameters
• change_index – When renaming in a series-like field also change the series_index
values.
• restrict_to_book_ids – An optional set of book ids for which the rename is to be
performed, defaults to all books.
restore_book(book_id,mi,last_modified,path, formats)
Restore the book entry in the database fora book that already exists on the filesystem
restore_original_format(book_id, original_fmt)
Restore the specified format from the previously saved ORIGINAL_FORMAT, if any. Return True on
success. The ORIGINAL_FORMAT is deleted after a successful restore.
safe_read_lock
Asafe read lock is a lock that does nothing if the thread already has a write lock, otherwise it acquires
aread lock. This is necessary to prevent DowngradeLockErrors, which can happen when updating the
search cache in the presence of composite columns. Updating the search cache holds an exclusive lock,
but searching a composite column involves reading field values via ProxyMetadata which tries to get a
shared lock. There may be other scenarios that triggerthis as well.
1.12. Setting up a calibre development environment
283
52
calibre User Manual, Release 2.56.0
This property returns a new lockobject on every access. This lockobjectis not recursive (forperformance)
and must only be usedin a with statement as with cache.safe_read_lock: otherwise bad things
will happen.
save_original_format(book_id, fmt)
Save a copy of the specified format as ORIGINAL_FORMAT, overwriting any existing ORIGI-
NAL_FORMAT.
search(query, restriction=u’‘, virtual_fields=None, book_ids=None)
Search the database forthe specified query,returning a set of matchedbook ids.
Parameters
• restriction –Arestriction that is ANDedtothespecifiedquery. Notethatrestrictions
are cached,therefore the search for a AND b will be slower than a with restriction b.
• virtual_fields – Used internally (virtual fields such as on_device to search over).
• book_ids – If not None, a set of book ids for which books will be searched instead of
searching all books.
set_conversion_options(options,fmt=u’PIPE’)
options must be a map of the form{book_id:conversion_options}
set_cover(book_id_data_map)
Set the cover for this book. data can be either a QImage, QPixmap,file object or bytestring. It can also be
None, in which case any existing coveris removed.
set_field(name,book_id_to_val_map, allow_case_change=True, do_path_update=True)
Set the values of the field specified by name. Returns the set of all book ids that were affected by the
change.
Parameters
• book_id_to_val_map – Mapping of book_ids to values that should be applied.
• allow_case_change – If True, the case of many-one or many-many fields will be
changed. Forexample, ifa book has the tag tag1 and you set the tag for another book to
Tag1 then the bothbooks willhave the tagTag1 ifallow_case_change is True, otherwise
they will both have the tag tag1.
• do_path_update – Used internally,you should never change it.
set_metadata(book_id,
mi,
ignore_errors=False,
force_changes=False,
set_title=True,
set_authors=True, allow_case_change=False)
Set metadata for the book id fromthe Metadata object mi
Setting force_changes=True will force set_metadata to update fields even if mi contains empty values. In
this case, ‘None’ is distinguished from ‘empty’. If mi.XXX is None, the XXX is not replaced, otherwise
it is. The tags,identifiers, and coverattributes are special cases. Tags and identifiers cannot be set to None
so then will always be replaced if force_changes is true. You must ensure that mi contains the values you
want the book to have. Covers are always changed if a new cover is provided,but are never deleted. Also
note that force_changes has no effect on setting title orauthors.
set_pref(name,val)
Set the specified preference to the specified value. See alsopref() (page 283).
tags_older_than(tag,delta=None,must_have_tag=None,must_have_authors=None)
Return the ids of all books having the tag tag that are older than the specified time. tag comparison is
case insensitive.
Parameters
• delta – A timedelta object or None. IfNone, then all ids withthe tag are returned.
284
Chapter 1. Sections
48
calibre User Manual, Release 2.56.0
• must_have_tag – If not None the list of matches will be restricted to books that have
this tag
• must_have_authors – A list of authors. If not None the list of matches will be re-
stricted to books that have these authors (case insensitive).
user_categories_for_books(book_ids, proxy_metadata_map=None)
Return the user categories for the specified books. proxy_metadata_map is optional and is useful for a
performance boost, in contexts where a ProxyMetadata object for the books already exists. It should be a
mapping of book_ids to their corresponding ProxyMetadata objects.
API Documentation for the ebook editing tools
The ebook editing tools consist of acalibre.ebooks.oeb.polish.container.Container (page 285)
object that represents a book as a collection of HTML + resource files, and various tools that can be used to
perform operations on the container. All the tools are in the form of module level functions in the various
calibre.ebooks.oeb.polish.
*
modules. You obtain a containerobject for a book at a path like this:
from calibre.ebooks.oeb.polish.container import get_container
container = get_container('Path to o book file', tweak_mode=True)
If you are writing a plugin for the ebook editor,you get the current containerfor the book being edited like this:
from calibre.gui2.tweak_book import current_container
container = current_container()
if container is None:
report_error # No o book has s been opened yet
The Container object
class calibre.ebooks.oeb.polish.container.Container(rootpath,
opfpath,
log,
clone_data=None)
Acontainer represents an Open EBook as a directory full of files and an opf file. There are two important
concepts:
•The root directory. This is the base of the ebook. All the ebooks files are inside this directory or in its
sub-directories.
•Names: These are paths to the books’ files relative to the root directory. They always contain POSIX
separators and are unquoted. They can be thought of as canonical identifiers for files in the book. Most
methods on the container object work with names. Names are always in the NFC unicode normal form.
•Clones: the container object supports efficient on-disk cloning, which is used to implement checkpoints
in the ebook editor. In order to make this work, you should never access files on the filesystem directly.
Instead,useraw_data() (page 287)oropen()(page 287)to read/writetocomponentfiles inthe book.
When converting between hrefs and names use the methods provided by this class, they assume all hrefs are
quoted.
abspath_to_name(fullpath, root=None)
Convert an absolute pathto a canonical name relative to root
Parameters root – The base directory. By default the root for this containerobject is used.
add_file(name,data, media_type=None,spine_index=None)
Add a file to this container. Entries for the file are automatically created in the OPFmanifest and spine (if
the file is a text document)
1.12. Setting up a calibre development environment
285
48
calibre User Manual, Release 2.56.0
add_name_to_manifest(name)
Add anentry to the manifest for a file with the specified name. Returns the manifest id.
book_type = u’oeb’
The type of book (epub forEPUB files andazw3 for AZW3 files)
commit(outpath=None,keep_parsed=False)
Commit all dirtied parsed objects to the filesystem and write out the ebook file at outpath. :paramoutput:
The path to write the saved ebook file to. If None, the path of the original book file is used. :param
keep_parsed: If True the parsed representations ofcommitted items are kept in the cache.
commit_item(name,keep_parsed=False)
Commit a parsed object to disk (it is serialized and written to the underlying file). If keep_parsed is
True the parsed representationis retained in the cache. See also:parsed() (page 287)
dirty(name)
Mark the parsed object corresponding to name as dirty. See also:parsed() (page 287).
exists(name)
True iff a file corresponding to the canonical name exists. Note that this function suffers from the limita-
tions of the underlying OS filesystem,in particular case (in)sensitivity. So on a case insensitive filesystem
this will return True even if the case of name is different from the case of the underlying filesystem file.
See alsohas_name() (page 286)
filesize(name)
Return the size in bytes of the file represented by the specified canonical name. Automatically handles
dirtied parsed objects. See also:parsed() (page 287)
generate_item(name,id_prefix=None, media_type=None,unique_href=True)
Add an item to the manifest with href derived from the given name. Ensures uniqueness of href and id
automatically. Returns generated item.
get_file_path_for_processing(name, allow_modification=True)
Similar to open() except that it returns a file path, instead of an open file object.
guide_type_map
Mapping of guide type to canonical name
has_name(name)
Return True iff a file with the same canonical name as thatspecified exists. Unlikeexists() (page 286)
this method is always case-sensitive.
href_to_name(href,base=None)
Convert an href(relative to base) to a name. base must be a name orNone, in which case self.root is used.
insert_into_xml(parent, item, index=None)
Insert iteminto parent (orappend if index is None),fixingindentation. Only works withself closing items.
is_dir = False
If this container represents an unzipped book (a directory)
iterlinks(name,get_line_numbers=True)
Iterate overall links in name. If get_line_numbers is True the yields results of the form (link,line_number,
offset). Where line_number is the line_number at which the link occurs and offset is the number of
characters from the start of the line. Note that offset could actually encompass several lines ifnot zero.
manifest_has_name(name)
Return True ifthe manifest has an entry corresponding to name
manifest_id_map
Mapping of manifest id tocanonical names
286
Chapter 1. Sections
Documents you may be interested
Documents you may be interested
