pypublib.epub module

pypublib.epub.create_book(contents)[source]

Create a Book object from extracted EPUB contents.

Populates a new Book instance with metadata, chapters, and resources from the extracted EPUB content dictionary.

Parameters:

contents (dict) – Dictionary containing extracted EPUB data with keys: ‘metadata’, ‘chapters’, ‘styles’, ‘images’, ‘fonts’, ‘spine’, ‘guide’, ‘cover’.

Returns:

A new Book instance populated with the extracted content.

Return type:

Book

pypublib.epub.extract_epub_content(file_path)[source]

Extract all relevant content from an EPUB file.

Reads all chapters, stylesheets, images, fonts, and metadata from the EPUB archive. Parses the OPF file to extract manifest, spine, and guide information.

Parameters:

file_path (str) – Path to the EPUB file.

Returns:

Dictionary containing:

  • ’metadata’: Parsed metadata from OPF

  • ’chapters’: Dict mapping hrefs to XHTML content

  • ’styles’: Dict mapping filenames to CSS content

  • ’images’: Dict mapping filenames to binary image data

  • ’fonts’: Dict mapping filenames to binary font data

  • ’manifest’: List of manifest items

  • ’spine’: Reading order list

  • ’guide’: Guide references

  • ’cover’: Cover image filename or None

Return type:

dict

pypublib.epub.pretty_print_xml(xml)[source]

Formats an XML string into a nice format. At the moment unimplemented.

Parameters:

xml (str) – XML string to format.

Returns:

Formatted XML string.

Return type:

str

pypublib.epub.publish_book(book, file_path)[source]

Save the book in EPUB format to the specified file path.

Convenience wrapper around save_book function.

Parameters:

  • book (Book) – The Book instance to publish.

  • file_path (str) – Output file path for the EPUB file.

See also

save_book() for the actual implementation.

pypublib.epub.read_book(file_path)[source]

Read an EPUB file and return a Book instance.

Validates the file path and EPUB structure before parsing. Returns None if the file cannot be read or parsed.

Parameters:

file_path (str) – Path to the EPUB file to read.

Returns:

A Book instance if successful, None if an error occurs.

Return type:

Book | None

Raises:

Catches and logs the following exceptions –

  • FileNotFoundError: File does not exist - zipfile.BadZipFile: Invalid EPUB container - UnicodeDecodeError: Encoding errors in EPUB content - KeyError: Missing required EPUB data - PermissionError: File permission issues

Example

>>> book = read_book("my_book.epub")
>>> if book:
...     print(f"Loaded: {book.title}")
pypublib.epub.save_book(book, file_path)[source]

Write the Book object to an EPUB file.

Creates a complete EPUB archive with all book components including chapters, navigation files, styles, images, fonts, and OPF metadata. The EPUB file is properly structured according to EPUB3 standards.

The process:

  1. Creates temporary directory structure

  2. Writes mimetype file (uncompressed)

  3. Creates META-INF/container.xml

  4. Saves all chapters as XHTML files

  5. Generates and saves navigation files (nav.xhtml and toc.ncx)

  6. Saves stylesheets, images, and fonts

  7. Generates and saves content.opf

  8. Archives everything as a ZIP file

Parameters:

  • book (Book) – The Book instance to save.

  • file_path (str) – Output file path for the EPUB file.

Note

The mimetype file is stored uncompressed as per EPUB specification.

pypublib.epub.validate_book(book)[source]

Validate the book structure and resources.

Performs comprehensive validation including:

  • Checks for empty books

  • Detects duplicate chapter hrefs

  • Validates chapter titles and hrefs

  • Validates metadata completeness

  • Checks resource references

Parameters:

book (Book) – The Book instance to validate.

Returns:

List of issue strings found. Empty list if book is valid.

Return type:

list

Example

>>> book_issues = validate_book(book)
>>> if issues:
...     for issue in book_issues:
...         print(f'Warning: {issue}')
pypublib.epub.validate_book_resources(book)[source]

Validate that all resources referenced in chapters are available in the book.

Checks for missing images and stylesheets referenced by chapters.

Parameters:

book (Book) – The Book instance to validate.

Returns:

List of dictionaries, each containing:

  • ’chapter’: Chapter title

  • ’missing_images’: List of missing image filenames

  • ’missing_styles’: List of missing stylesheet filenames

Return type:

list

pypublib.epub.validate_chapters(book)[source]

Validate that all chapters have required title and content.

Parameters:

book (Book) – The Book instance to validate.

Raises:

ValueError – If any chapter is missing a title or HTML content.

Return type:

None

pypublib.epub.validate_metadata(book)[source]

Validate that a book has required and optional metadata fields.

Checks for mandatory fields (title, creator) and optional fields (language, subject).

Parameters:

book (Book) – The Book instance to validate.

Returns:

A tuple of (missing_mandatory, missing_optional) where each is

a list of field names.

Return type:

tuple

Example

>>> mandatory, optional = validate_metadata(book)
>>> if mandatory:
...     print(f'Missing mandatory fields: {mandatory}')