pypublib.book module

class pypublib.book.Book(metadata=None)[source]

Bases: object

Represents an EPUB book container holding:

A Book instance manages all data needed for an EPUB publication:

metadata: Dublin Core and custom metadata
chapters: mapping of chapter href to Chapter instances
styles: global CSS stylesheets
images: image assets
fonts: embedded font files
guide: optional navigation aids
cover: filename of the cover image

Notes

A generated UUID is added as identifier if none is provided.
Convenience properties expose common metadata as attributes.
All data are stored in memory. This includes chapters, style sheets, images, and font data as binaries.
Use publish_book() from the epub module to store all data in an EPUB file. The necessary OPF file is then created on the fly from the data in the Book structure.

Parameters:: metadata (Dict | None)

metadata

Dublin Core and custom metadata key-value pairs.

Type:: dict

chapters

Mapping of href to Chapter instances.

Type:: dict

styles

Mapping of filename to CSS content.

Type:: dict

images

Mapping of filename to binary image data.

Type:: dict

fonts

Mapping of filename to binary font data.

Type:: dict

guide

List of guide reference items.

Type:: list

cover

Filename of the cover image.

Type:: str

__repr__()[source]

Return a compact debug string representation of the book.

Returns:: Compact representation including title, author, and asset counts.
Return type:: str

add_chapter(chapter, href=None)[source]

Add a new chapter, or replace a chapter using its href as the key.

Parameters:

chapter (Chapter) – The chapter to add.
href (str, optional) – Custom href to use as key. If None, uses chapter.href. Defaults to None.

Return type:

None

add_chapters(*chapters)[source]

Add multiple chapters in order.

Parameters:: *chapters (Chapter) – Variable length argument list of Chapter instances to add.
Return type:: None

add_cover(cover, image)[source]

Add a cover image and set it as the book cover.

Also prepends a synthetic ‘Cover.xhtml’ chapter.

Parameters:

cover (str) – Filename of the cover image.
image (bytes | bytearray) – Binary image data.

Return type:

None

add_font(name, font)[source]

Add an embedded font file.

Parameters:

name (str) – Target filename inside the EPUB.
font (bytes | bytearray) – Binary font data.

add_image(name, image)[source]

Add an image asset.

Parameters:

name (str) – Target filename inside the EPUB.
image (bytes | bytearray) – Binary image data.

Return type:

None

add_image_from_file(file)[source]

Add an image asset from a file.

Reads the file as binary and uses the filename as the key.

Parameters:: file (str) – Path to an image file.
Return type:: None

add_images(images)[source]

Add multiple images from a dict of {name: image}.

Parameters:: images (dict) – Dictionary mapping image names to binary image data.
Return type:: None

add_metadata(key, value)[source]

Add or replace an arbitrary metadata key/value pair.

Parameters:

key (str) – The metadata key.
value – The metadata value.

add_style(name, sheet)[source]

Add a global stylesheet.

Parameters:

name (str) – Target filename inside the EPUB.
sheet (str | bytes) – CSS content as string or bytes.

Return type:

None

add_style_from_file(file)[source]

Add a global stylesheet from a CSS file.

Reads the file content and uses the filename as the key.

Parameters:: file (str) – Path to a CSS file.
Return type:: None

add_styles(styles)[source]

Add multiple styles from a dict of {name: sheet}.

Parameters:: styles (dict) – Dictionary mapping stylesheet names to CSS content.
Return type:: None

property author: str

Get the primary creator/author (alias for creator).

Returns:: The creator name.
Return type:: str

property cover_image: bytes | bytearray | None

Return the raw cover image content.

Returns:: The binary cover image data, or None if no cover is set.
Return type:: bytes | bytearray | None

property creator: str

Get the primary creator/author.

Returns:: The creator name.
Return type:: str

property date: str

Get the publication date.

Returns:: Publication date as string (ISO-8601 recommended).
Return type:: str

property description: str

Get the book description.

Returns:: Short description or abstract.
Return type:: str

from_contents(contents)[source]

Populate the Book from a contents dictionary, typically extracted from an existing EPUB.

Parameters:: contents (dict) – Dictionary with book components. Should have keys: ‘metadata’, ‘chapters’, ‘styles’, ‘images’, ‘fonts’, ‘guide’, ‘cover’.
Return type:: None

get_chapter(href)[source]

Return the chapter by href or None if not found.

Parameters:: href (str) – The href of the chapter to retrieve.
Returns:: The chapter with the specified href, or None if not found.
Return type:: Chapter | None

property identifier: str

Get the unique identifier.

Returns:: Unique identifier (e.g., UUID, ISBN).
Return type:: str

property language: str

Get the language code.

Returns:: Language code (e.g., ‘en’, ‘de’).
Return type:: str

property manifest: List[Dict[str, str]]

Generate the manifest entries for the OPF file.

Creates a list of manifest item dictionaries for all chapters, styles, images, and fonts in the book.

Returns:: List of manifest item dictionaries with keys ‘id’, ‘href’, and ‘media-type’.
Return type:: list

Note

Cover images are marked with the ‘cover-image’ property.

property nav: str

Generate the nav.xhtml content for EPUB3.

Creates the navigation document with table of contents and landmarks.

Returns:: XHTML content for nav.xhtml file.
Return type:: str

property ncx: str

Generate the toc.ncx content for EPUB2 compatibility.

Creates the Navigation Center eXtended (NCX) document used for navigation in EPUB2 and as a fallback in EPUB3.

Returns:: NCX XML content.
Return type:: str

property opf: str

Generate the complete OPF (Open Packaging Format) XML content.

Creates the content.opf file which defines the EPUB package structure, including metadata, manifest, spine, and guide sections.

Returns:: Complete OPF XML as a string.
Return type:: str

Note

The OPF file is the central descriptor of an EPUB archive structure.

property publisher: str

Get the publisher name.

Returns:: Publisher name.
Return type:: str

remove_chapter(chapter)[source]

Removes the chapter from the book.

Parameters:: chapter (str) – The chapter or the href of the chapter to remove.
Returns:: None.
Return type:: None

property series: str

Get the series name.

Returns:: The name of the series this book belongs to.
Return type:: str

set_cover(cover)[source]

Set the cover image filename and ensure a cover chapter is the first entry.

Parameters:: cover (str) – Filename of the cover image.
Return type:: None

set_metadata(creator=None, title=None, language='de', identifier=None, description=None, publisher=None, date=None)[source]

Bulk metadata setter for common Dublin Core metadata.

Only non-empty values are applied. Useful for setting multiple metadata fields at once during book initialization.

Parameters:

creator (str, optional) – Creator/author name. Defaults to None.
title (str, optional) – Book title. Defaults to None.
language (str, optional) – Language code. Defaults to “de”.
identifier (str, optional) – Unique identifier. Defaults to None.
description (str, optional) – Book description. Defaults to None.
publisher (str, optional) – Publisher name. Defaults to None.
date (str, optional) – Publication date. Defaults to None.

property subject: List[str]

Get the list of subjects/keywords.

Returns:: Subject keywords.
Return type:: set

property title: str

Get the human-readable title of the book.

Returns:: The book title.
Return type:: str

property toc: str

Generate the table of contents.

Alias for the ncx property.

Returns:: TOC NCX XML content.
Return type:: str

class pypublib.book.Opf(opf_xml)[source]

Bases: object

A parser for the OPF (Open Packaging Format) file of an EPUB (content.opf).

Parses the OPF XML and provides access to its components including metadata, manifest items, spine references, and guide entries.

xml

The root element of the OPF XML document.

Type:: etree.Element

manifest(): Reads all <item> elements from <manifest> and returns them as a list of dicts.

metadata(): Returns all metadata tags from <metadata> as a dict {name: text}.

spine(): Returns all idref values from <spine>/<itemref> as a list.

guide(): Reads all <reference> elements from <guide> and returns them as a list of dicts.

cover(): Returns the href of the cover image if marked with cover-image property.

__repr__()[source]

Return a compact debug representation of parsed OPF content.

Return type:: str

property cover: str | None

Get the href of the cover image.

Returns the href of the cover item from the <manifest> section if it has the ‘cover-image’ property, otherwise returns None.

Returns:: The cover image href, or None if no cover is marked.
Return type:: str | None

classmethod from_file(opf_file)[source]

Create an Opf instance by reading the contents of an OPF file.

Parameters:

opf_file (str) – Path to the OPF file.

Returns:

A new Opf instance parsed from the file.

Return type:

Opf

Raises:

FileNotFoundError – If the file does not exist.
etree.ParserError – If the XML cannot be parsed.

property guide: List[Dict[str, str]]

Get all guide reference items from the OPF.

Reads all <reference> elements from the <guide> section and returns them as a list of dictionaries with keys ‘type’, ‘title’, and ‘href’.

Returns:: List of guide reference items.
Return type:: list[dict[str, str]]

property manifest: Dict[str, Dict[str, str]]

Get all manifest items from the OPF.

Reads all <item> elements from the <manifest> section and returns them as a dictionary keyed by item id with values containing ‘href’ and ‘media-type’.

Returns:: Manifest item mapping keyed by id.
Return type:: dict[str, dict[str, str | None]]

property metadata: Dict[str, str | List[str]]

Get all metadata from the OPF.

Reads all metadata elements from the <metadata> section and returns them as a dictionary. Multiple <dc:subject> elements are collected into a set.

Returns:: Dictionary with metadata key-value pairs.
Return type:: dict[str, str | list[str]]

Note

Multiple subject tags are merged into a single ‘subject’ key containing a set.

property spine: List[str]

Get all spine item references from the OPF.

Returns all idref values from <spine>/<itemref> elements, which define the reading order of the document.

Returns:: List of item idrefs in spine order.
Return type:: list[str]