EPUB Files

class bkgen.epub.EPUB(fn=None, mode=’r’, compression=8, **args)

Bases: bl.zip.ZIP, bkgen.source.Source

MEDIATYPES = {‘.epub’: ‘application/epub+zip’, ‘.ncx’: ‘application/x-dtbncx+xml’, ‘.opf’: ‘application/oebps-package+xml’, ‘.xhtml’: ‘application/xhtml+xml’}

NS = {‘container’: ‘urn:oasis:names:tc:opendocument:xmlns:container’, ‘cp’: ‘http://schemas.openxmlformats.org/package/2006/metadata/core-properties’, ‘dc’: ‘http://purl.org/dc/elements/1.1/’, ‘dcmitype’: ‘http://purl.org/dc/dcmitype/’, ‘dcterms’: ‘http://purl.org/dc/terms/’, ‘epub’: ‘http://www.idpf.org/2007/ops’, ‘html’: ‘http://www.w3.org/1999/xhtml’, ‘m’: ‘http://www.w3.org/1998/Math/MathML’, ‘ncx’: ‘http://www.daisy.org/z3986/2005/ncx/’, ‘opf’: ‘http://www.idpf.org/2007/opf’, ‘pub’: ‘http://publishingxml.org/ns’, ‘xml’: ‘http://www.w3.org/XML/1998/namespace’, ‘xsi’: ‘http://www.w3.org/2001/XMLSchema-instance’}

OPF

Our ElementMaker unpacks lists when it is called, enabling it to work with nested-list-returning XT transformations.

classmethod append_toc_to_spine(opffn, nav_href)

nav html needs to be in spine in order for Kindle to display a TOC

classmethod build(output_path, metadata, epub_name=None, manifest=None, spine_items=None, cover_src=None, cover_html=True, nav_toc=None, nav_landmarks=None, nav_page_list=None, nav_href=’nav.xhtml’, nav_title=’Navigation’, show_nav=False, before_compile=None, zip=True, check=True)

build EPUB file output; returns EPUB object

REQUIRED parameters:

output_path = where the build files are to be located metadata = a metadata element to be used in building the EPUB

OPTIONAL parameters:

epub_name = the base filename for the build; or = output_path basename manifest = the opf:manifest to use; or built from crawling the output_path spine_items = a list of dicts that have the following attributes:

‘href’ : REQUIRED relative file path from output_path ‘idref’ : opf:itemref/@idref (default generated from href) ‘linear’ : opf:itemref/@linear (=”yes”|”no”, default “yes”) ‘properties’: opf:itemref/@properties ‘title’ : can be used to populate nav items ‘landmark’ : if given, included in landmarks nav with this landmark epub:type

cover_src = the cover image src; or no cover included cover_html = whether to include the cover in the first html document (default True). nav_toc = a toc nav element for the nav; or built from opf:spine_items nav_landmarks = a landmarks nav element for the nav; or built nav_page_list = a page-list nav element for the nav; or built nav_href = the relative path to use for the nav file (also ncx) nav_title = the title to display on the nav page zip_epub = if True, zip the EPUB after building

check()

use epubcheck to validate the epub

documents(path=None, opf=None)

return a list of pub:document containing the content in the EPUB path = the output path for the documents.

classmethod epub_fn(output_path, epub_name=None, ext=’.epub’)

classmethod epub_name_from_path(output_path)

classmethod get_nav_fn(output_path)

get_opf()

return the opf as an XML document

classmethod get_opf_fn(output_path)

from a given output_path, return the first opf_fn from META-INF/container.xml

classmethod href_to_id(href)

images()

classmethod make_container_file(output_path, *opf_fns)

given an output_path and a list of opf_fns, create a META-INF/container.xml file

classmethod make_cover_html(output_path, cover_src)

classmethod make_mimetype_file(output_path, mimetype=None)

create a mimetype file in output_path

classmethod make_nav_file(output_path, *nav_elems, nav_href=’_nav.xhtml’, title=’Navigation’)

create a nav.xhtml file in output_path, return the filename to it

classmethod make_ncx_file(output_path, nav_fn, metadata)

use the nav file and metadata to create an ncx file

classmethod make_opf_file(output_path, opf_name=None, metadata=None, manifest=None, spine=None, guide=None)

create an opf file in output_path, return the filename to it output_path = the filesystem path in which the epub is being built (required) opf_name = the relative path to the opf file in output_path; default output_path basename metadata = the opf:metadata element (required) manifest = an opf:manifest element spine = an opf:spine element; if None, use all (x)html files in output_path.

metadata(opf=None)

return an opf:metadata element with the metadata in the EPUB

classmethod nav_elem(*nav_items, epub_type=None, title=None, hidden=”)

create and return an html:nav element.

nav_items = a list of dict-type elements with the following attributes:

href : the href to the nav item (required) title : the text to display in the nav item (required) epub_type : if given, the epub:type for the nav item <a> element (for landmarks nav)

epub_type = the epub:type attribute of the nav element title = the optional title text to display on this nav hidden = whether or not the nav element should be hidden; default not specified (None)

classmethod nav_landmarks(*landmarks, title=’Landmarks’, hidden=”)

builds a landmarks nav element from the given landmarks parameters. Each parameter is a dict:

‘epub_type’ : the epub:type attribute, which is the landmark type ‘href’ : the href to the landmark ‘title’ : the text to display for this landmark

Common landmarks include: (see http://www.idpf.org/accessibility/guidelines/content/nav/landmarks.php)

cover, toc, title-page, frontmatter, bodymatter, backmatter, loi (list of illustrations), lot (list of tables), preface, bibliography, index, glossary, acknowledgments

classmethod nav_landmarks_from_spine_items(output_path, spine_items, title=’Landmarks’, hidden=”)

build nav landmarks from spine_items. Each spine_item can have an optional landmark attribute, which if given is the epub_type of that landmark.

classmethod nav_page_list_from_spine_items(output_path, spine_items, title=’Page List’, hidden=”)

builds a page-list nav element from the content listed in the manifest.

classmethod nav_toc_from_spine_items(output_path, spine_items, nav_title=’Table of Contents’, hidden=”)

classmethod opf_guide(output_path, **references)

classmethod opf_manifest(output_path, opf_name=None, nav_href=None, cover_src=None, exclude=[‘mimetype’, ‘*.xml’, ‘*.opf’, ‘.*’, ‘~*’, ‘#*#’])

build and return an opf:manifest element opf_name = the relative path to the opf file nav_href = the relative path (href) to the nav.xhtml file cover_src = the relative path (src) to the cover image file

classmethod opf_manifest_item(opf_path, href, mediatype=None)

classmethod opf_package_metadata(metadata, xml_lang=’en-US’, cover_src=None)

make adjustments to (a deep copy of) the metadata for the opf:package context

classmethod opf_spine(output_path, spine_items=None, manifest=None, ncx_href=None)

create and return an opf:spine element output_path = the filesystem path in which the epub is being built (required) spine_items = a list of dicts that has spine item attributes; or build from opf:manifest manifest = an opf:manifest to build the spine from (if spine_items not given) ncx_href = if given, used to add the toc attribute to the spine

classmethod opf_spine_itemref(spine_item)

create an opf:itemref for the opf:spine from the given spine_item, with the following attributes: href : if given, is converted to the idref using href_to_id() idref : if given (and no href), is used as the idref linear : if given, becomes the “linear” property (“yes|no”) properties : if given, space-separated list of spine itemref properties

resources(path=None, opf=None)

return a list of files containing project resources in the EPUB path = the output path for the resources

classmethod spine_items_from_manifest(output_path, manifest)

A list of spine_item dicts (see spec above under EPUB.build())

classmethod unhide_toc(navfn)

the toc in the nav_toc.xhtml file should NOT be hidden

write(fn=None)

classmethod zip_epub(output_path, epubfn=None, mimetype_fn=None, opf_fn=None, container_fn=None, other_fns=[], compression=8)

zip the epub and return its filename