电子书编辑工具的API文档¶
电子书编辑工具包括一个:class:`calibre.ebooks.oeb.polish.container.Container`对象,该对象将一本书表示为一组HTML+资源文件,以及可用于在容器上执行操作的各种工具。所有工具都是各种``Calibre.ebooks.oeb.polish.*``模块中模块级函数的形式。
您可以在如下路径获取图书的容器对象:
from calibre.ebooks.oeb.polish.container import get_container
container = get_container('Path to book file', tweak_mode=True)
如果您正在为电子书编辑器编写插件,您将获得正在编辑的图书的当前容器,如下所示:
from calibre.gui2.tweak_book import current_container
container = current_container()
if container is None:
report_error # No book has been opened yet
容器对象¶
- class calibre.ebooks.oeb.polish.container.Container(rootpath, opfpath, log, clone_data=None)[原始碼]¶
A container represents an open e-book as a folder full of files and an OPF file. There are two important concepts:
The root folder. This is the base of the e-book. All the e-books files are inside this folder or in its sub-folders.
Names: These are paths to the books' files relative to the root folder. 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.
克隆:容器对象支持高效的磁盘克隆,用于在电子书编辑器中实现检查点。为了实现这一点,您不应该直接访问文件系统上的文件。相反,可以使用:meth:`raw_data`或:meth:`open`来读/写书中的组件文件。
当使用此类提供的方法在href和名称之间进行转换时,它们假定所有href都被引用。
- abspath_to_name(fullpath, root=None)[原始碼]¶
将绝对路径转换为相对于:attr:root的规范名称
- 參數:
root -- The base folder. By default the root for this container object is used.
- add_file(name, data=b'', media_type=None, spine_index=None, modify_name_if_needed=False, process_manifest_item=None, suggested_id='')[原始碼]¶
将文件添加到此容器。文件条目自动在OPF清单和书脊中创建(如果文件是文本文档)
- add_name_to_manifest(name, process_manifest_item=None, suggested_id='')[原始碼]¶
向具有指定名称的文件的清单中添加条目。返回清单ID。
- book_type = 'oeb'¶
图书类型(epub用于EPUB文件,azw3用于AZW3文件)
- commit(outpath=None, keep_parsed=False)[原始碼]¶
将所有有害的解析对象提交到文件系统,并在outpath写出电子书文件。
- 參數:
output -- 要将保存的电子书文件写入的路径。如果没有,则使用原始书籍文件的路径。
keep_parsed -- 如果为True,则已提交项的解析表示形式保留在缓存中。
- 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 representation is retained in the cache. See also:parsed()
- exists(name)[原始碼]¶
True iff a file/folder corresponding to the canonical name exists. Note that this function suffers from the limitations 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 also
has_name()
- filesize(name)[原始碼]¶
Return the size in bytes of the file represented by the specified canonical name. Automatically handles dirtied parsed objects. See also:
parsed()
- generate_item(name, id_prefix=None, media_type=None, unique_href=True)[原始碼]¶
使用从给定名称派生的HREF将项目添加到清单中。自动保证href和id的唯一性。返回生成的项。
- get_file_path_for_processing(name, allow_modification=True)[原始碼]¶
与open()类似,不同之处在于它返回文件路径,而不是打开的文件对象。
- property guide_type_map¶
指南类型到规范名称的映射
- has_name(name)[原始碼]¶
Return True iff a file with the same canonical name as that specified exists. Unlike
exists()
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 or None, in which case self.root is used.
- is_dir = False¶
如果此容器表示解压缩的图书(目录)
- iterlinks(name, get_line_numbers=True)[原始碼]¶
遍历名称中的所有链接。如果get_line_numbers为“真”,则生成表单结果(链接、行号、偏移量)。其中line_number是发生链接的line_number,偏移量是从行开始算起的字符数。请注意,偏移量实际上可以包含多行(如果不是零的话)。
- make_name_unique(name)[原始碼]¶
Ensure that name does not already exist in this book. If it does, return a modified version that does not exist.
- property manifest_id_map¶
清单ID到规范名称的映射
- manifest_items_of_type(predicate)[原始碼]¶
The names of all manifest items whose media-type matches predicate. predicate can be a set, a list, a string or a function taking a single argument, which will be called with the media-type.
- manifest_items_with_property(property_name)[原始碼]¶
All manifest items that have the specified property
- property manifest_type_map¶
Mapping of manifest media-type to list of canonical names of that media-type
- property mi¶
The metadata of this book as a Metadata object. Note that this object is constructed on the fly every time this property is requested, so use it sparingly.
- name_to_href(name, base=None)[原始碼]¶
Convert a name to a href relative to base, which must be a name or None in which case self.root is used as the base
- property names_that_must_not_be_changed¶
Set of names that must never be renamed. Depends on the e-book file format.
- property names_that_must_not_be_removed¶
Set of names that must never be deleted from the container. Depends on the e-book file format.
- property names_that_need_not_be_manifested¶
Set of names that are allowed to be missing from the manifest. Depends on the e-book file format.
- open(name, mode='rb')[原始碼]¶
Open the file pointed to by name for direct read/write. Note that this will commit the file if it is dirtied and remove it from the parse cache. You must finish with this file before accessing the parsed version of it again, or bad things will happen.
- property opf¶
The parsed OPF file
- opf_get_or_create(name)[原始碼]¶
Convenience method to either return the first XML element with the specified name or create it under the opf:package element and then return it, if it does not already exist.
- property opf_version¶
The version set on the OPF's <package> element
- property opf_version_parsed¶
The version set on the OPF's <package> element as a tuple of integers
- opf_xpath(expr)[原始碼]¶
Convenience method to evaluate an XPath expression on the OPF file, has the opf: and dc: namespace prefixes pre-defined.
- parsed(name)[原始碼]¶
Return a parsed representation of the file specified by name. For HTML and XML files an lxml tree is returned. For CSS files a css_parser stylesheet is returned. Note that parsed objects are cached for performance. If you make any changes to the parsed object, you must call
dirty()
so that the container knows to update the cache. See alsoreplace()
.
- raw_data(name, decode=True, normalize_to_nfc=True)[原始碼]¶
Return the raw data corresponding to the file specified by name
- 參數:
decode -- If True and the file has a text based MIME type, decode it and return a unicode object instead of raw bytes.
normalize_to_nfc -- If True the returned unicode object is normalized to the NFC normal form as is required for the EPUB and AZW3 file formats.
- relpath(path, base=None)[原始碼]¶
Convert an absolute path (with os separators) to a path relative to base (defaults to self.root). The relative path is not a name. Use
abspath_to_name()
for that.
- remove_from_spine(spine_items, remove_if_no_longer_in_spine=True)[原始碼]¶
Remove the specified items (by canonical name) from the spine. If
remove_if_no_longer_in_spine
is True, the items are also deleted from the book, not just from the spine.
- remove_from_xml(item)[原始碼]¶
Removes item from parent, fixing indentation (works only with self closing items)
- remove_item(name, remove_from_guide=True)[原始碼]¶
Remove the item identified by name from this container. This removes all references to the item in the OPF manifest, guide and spine as well as from any internal caches.
- rename(current_name, new_name)[原始碼]¶
Renames a file from current_name to new_name. It automatically rebases all links inside the file if the folder the file is in changes. Note however, that links are not updated in the other files that could reference this file. This is for performance, such updates should be done once, in bulk.
- replace(name, obj)[原始碼]¶
Replace the parsed object corresponding to name with obj, which must be a similar object, i.e. an lxml tree for HTML/XML or a css_parser stylesheet for a CSS file.
- replace_links(name, replace_func)[原始碼]¶
Replace all links in name using replace_func, which must be a callable that accepts a URL and returns the replaced URL. It must also have a 'replaced' attribute that is set to True if any actual replacement is done. Convenient ways of creating such callables are using the
LinkReplacer
andLinkRebaser
classes.
- serialize_item(name)[原始碼]¶
Convert a parsed object (identified by canonical name) into a bytestring. See
parsed()
.
- set_spine(spine_items)[原始碼]¶
Set the spine to be spine_items where spine_items is an iterable of the form (name, linear). Will raise an error if one of the names is not present in the manifest.
- property spine_items¶
An iterator yielding the path for every item in the books' spine. See also:
spine_iter
andspine_items
.
- property spine_iter¶
An iterator that yields item, name is_linear for every item in the books' spine. item is the lxml element, name is the canonical file name and is_linear is True if the item is linear. See also:
spine_names
andspine_items
.
- property spine_names¶
An iterator yielding name and is_linear for every item in the books' spine. See also:
spine_iter
andspine_items
.
Managing component files in a container¶
- calibre.ebooks.oeb.polish.replace.replace_links(container, link_map, frag_map=<function <lambda>>, replace_in_opf=False)[原始碼]¶
Replace links to files in the container. Will iterate over all files in the container and change the specified links in them.
- 參數:
link_map -- A mapping of old canonical name to new canonical name. For example:
{'images/old.png': 'images/new.png'}
frag_map -- A callable that takes two arguments
(name, anchor)
and returns a new anchor. This is useful if you need to change the anchors in HTML files. By default, it does nothing.replace_in_opf -- If False, links are not replaced in the OPF file.
- calibre.ebooks.oeb.polish.replace.rename_files(container, file_map)[原始碼]¶
Rename files in the container, automatically updating all links to them.
- 參數:
file_map -- A mapping of old canonical name to new canonical name, for example:
{'text/chapter1.html': 'chapter1.html'}
.
- calibre.ebooks.oeb.polish.replace.get_recommended_folders(container, names)[原始碼]¶
Return the folders that are recommended for the given filenames. The recommendation is based on where the majority of files of the same type are located in the container. If no files of a particular type are present, the recommended folder is assumed to be the folder containing the OPF file.
Pretty printing and auto fixing parse errors¶
- calibre.ebooks.oeb.polish.pretty.fix_html(container, raw)[原始碼]¶
Fix any parsing errors in the HTML represented as a string in raw. Fixing is done using the HTML5 parsing algorithm.
- calibre.ebooks.oeb.polish.pretty.fix_all_html(container)[原始碼]¶
Fix any parsing errors in all HTML files in the container. Fixing is done using the HTML5 parsing algorithm.
- calibre.ebooks.oeb.polish.pretty.pretty_html(container, name, raw)[原始碼]¶
Pretty print the HTML represented as a string in raw
- calibre.ebooks.oeb.polish.pretty.pretty_css(container, name, raw)[原始碼]¶
Pretty print the CSS represented as a string in raw
Managing book jackets¶
Splitting and merging of files¶
- calibre.ebooks.oeb.polish.split.split(container, name, loc_or_xpath, before=True, totals=None)[原始碼]¶
Split the file specified by name at the position specified by loc_or_xpath. Splitting automatically migrates all links and references to the affected files.
- 參數:
loc_or_xpath -- Should be an XPath expression such as //h:div[@id="split_here"]. Can also be a loc which is used internally to implement splitting in the preview panel.
before -- If True the split occurs before the identified element otherwise after it.
totals -- Used internally
- calibre.ebooks.oeb.polish.split.multisplit(container, name, xpath, before=True)[原始碼]¶
Split the specified file at multiple locations (all tags that match the specified XPath expression). See also:
split()
. Splitting automatically migrates all links and references to the affected files.- 參數:
before -- If True the splits occur before the identified element otherwise after it.
- calibre.ebooks.oeb.polish.split.merge(container, category, names, master)[原始碼]¶
Merge the specified files into a single file, automatically migrating all links and references to the affected files. The file must all either be HTML or CSS files.
- 參數:
category -- Must be either
'text'
for HTML files or'styles'
for CSS filesnames -- The list of files to be merged
master -- Which of the merged files is the master file, that is, the file that will remain after merging.
Managing covers¶
- calibre.ebooks.oeb.polish.cover.set_cover(container, cover_path, report=None, options=None)[原始碼]¶
Set the cover of the book to the image pointed to by cover_path.
- 參數:
cover_path -- Either the absolute path to an image file or the canonical name of an image in the book. When using an image in the book, you must also set options, see below.
report -- An optional callable that takes a single argument. It will be called with information about the tasks being processed.
options -- None or a dictionary that controls how the cover is set. The dictionary can have entries: keep_aspect: True or False (Preserve aspect ratio of covers in EPUB) no_svg: True or False (Use an SVG cover wrapper in the EPUB titlepage) existing: True or False (
cover_path
refers to an existing image in the book)
Working with CSS¶
- calibre.ebooks.oeb.polish.fonts.change_font(container, old_name, new_name=None)[原始碼]¶
Change a font family from old_name to new_name. Changes all occurrences of the font family in stylesheets, style tags and style attributes. If the old_name refers to an embedded font, it is removed. You can set new_name to None to remove the font family instead of changing it.
- calibre.ebooks.oeb.polish.css.remove_unused_css(container, report=None, remove_unused_classes=False, merge_rules=False, merge_rules_with_identical_properties=False, remove_unreferenced_sheets=False)[原始碼]¶
Remove all unused CSS rules from the book. An unused CSS rule is one that does not match any actual content.
- 參數:
report -- An optional callable that takes a single argument. It is called with information about the operations being performed.
remove_unused_classes -- If True, class attributes in the HTML that do not match any CSS rules are also removed.
merge_rules -- If True, rules with identical selectors are merged.
merge_rules_with_identical_properties -- If True, rules with identical properties are merged.
remove_unreferenced_sheets -- If True, stylesheets that are not referenced by any content are removed
- calibre.ebooks.oeb.polish.css.filter_css(container, properties, names=())[原始碼]¶
Remove the specified CSS properties from all CSS rules in the book.
- 參數:
properties -- Set of properties to remove. For example:
{'font-family', 'color'}
.names -- The files from which to remove the properties. Defaults to all HTML and CSS files in the book.
Working with the Table of Contents¶
- calibre.ebooks.oeb.polish.toc.from_xpaths(container, xpaths, prefer_title=False)[原始碼]¶
Generate a Table of Contents from a list of XPath expressions. Each expression in the list corresponds to a level of the generate ToC. For example:
['//h:h1', '//h:h2', '//h:h3']
will generate a three level Table of Contents from the<h1>
,<h2>
and<h3>
tags.
- calibre.ebooks.oeb.polish.toc.from_links(container)[原始碼]¶
Generate a Table of Contents from links in the book.
書籍編輯工具¶
- class calibre.gui2.tweak_book.plugin.Tool[原始碼]¶
基礎類別:
object
The base class for individual tools in an Edit Book plugin. Useful members include:
self.plugin
: A reference to thecalibre.customize.Plugin
object to which this tool belongs.self.
boss
self.
gui
Methods that must be overridden in sub classes:
- name = None¶
Set this to a unique name it will be used as a key
- allowed_in_toolbar = True¶
If True the user can choose to place this tool in the plugins toolbar
If True the user can choose to place this tool in the plugins menu
- toolbar_button_popup_mode = 'delayed'¶
The popup mode for the menu (if any) of the toolbar button. Possible values are 'delayed', 'instant', 'button'
- property boss¶
The
calibre.gui2.tweak_book.boss.Boss
object. Used to control the user interface.
- property gui¶
The main window of the user interface
- property current_container¶
Return the current
calibre.ebooks.oeb.polish.container.Container
object that represents the book being edited.
- register_shortcut(qaction, unique_name, default_keys=(), short_text=None, description=None, **extra_data)[原始碼]¶
Register a keyboard shortcut that will trigger the specified
qaction
. This keyboard shortcut will become automatically customizable by the user in the Keyboard shortcuts section of the editor preferences.- 參數:
qaction -- A QAction object, it will be triggered when the configured key combination is pressed by the user.
unique_name -- A unique name for this shortcut/action. It will be used internally, it must not be shared by any other actions in this plugin.
default_keys -- A list of the default keyboard shortcuts. If not specified no default shortcuts will be set. If the shortcuts specified here conflict with either builtin shortcuts or shortcuts from user configuration/other plugins, they will be ignored. In that case, users will have to configure the shortcuts manually via Preferences. For example:
default_keys=('Ctrl+J', 'F9')
.short_text -- An optional short description of this action. If not specified the text from the QAction will be used.
description -- An optional longer description of this action, it will be used in the preferences entry for this shortcut.
- create_action(for_toolbar=True)[原始碼]¶
Create a QAction that will be added to either the plugins toolbar or the plugins menu depending on
for_toolbar
. For example:def create_action(self, for_toolbar=True): ac = QAction(get_icons('myicon.png'), 'Do something') if for_toolbar: # We want the toolbar button to have a popup menu menu = QMenu() ac.setMenu(menu) menu.addAction('Do something else') subaction = menu.addAction('And another') # Register a keyboard shortcut for this toolbar action be # careful to do this for only one of the toolbar action or # the menu action, not both. self.register_shortcut(ac, 'some-unique-name', default_keys=('Ctrl+K',)) return ac
也參考
Method
register_shortcut()
.
Controlling the editor's user interface¶
The e-book editor's user interface is controlled by a single global Boss object. This has many useful methods that can be used in plugin code to perform common tasks.
- class calibre.gui2.tweak_book.boss.Boss(parent, notify=None)[原始碼]¶
-
- apply_container_update_to_gui(mark_as_modified=True)[原始碼]¶
Update all the components of the user interface to reflect the latest data in the current book container.
- 參數:
mark_as_modified -- If True, the book will be marked as modified, so the user will be prompted to save it when quitting.
- commit_all_editors_to_container()[原始碼]¶
Commit any changes that the user has made to files open in editors to the container. You should call this method before performing any actions on the current container
- property currently_editing¶
Return the name of the file being edited currently or None if no file is being edited
- edit_file(name, syntax=None, use_template=None)[原始碼]¶
Open the file specified by name in an editor
- 參數:
syntax -- The media type of the file, for example,
'text/html'
. If not specified it is guessed from the file extension.use_template -- A template to initialize the opened editor with
- open_book(path=None, edit_file=None, clear_notify_data=True, open_folder=False, search_text=None)[原始碼]¶
Open the e-book at
path
for editing. Will show an error if the e-book is not in a supported format or the current book has unsaved changes.- 參數:
edit_file -- The name of a file inside the newly opened book to start editing. Can also be a list of names.
- rewind_savepoint()[原始碼]¶
Undo the previous creation of a restore checkpoint, useful if you create a checkpoint, then abort the operation with no changes
- show_current_diff(allow_revert=True, to_container=None)[原始碼]¶
Show the changes to the book from its last checkpointed state
- 參數:
allow_revert -- If True the diff dialog will have a button to allow the user to revert all changes
to_container -- A container object to compare the current container to. If None, the previously checkpointed container is used