Which Libraries Does book-to-skill Use for EPUB Parsing? A Dual-Layer Extraction Strategy

The book-to-skill library employs a resilient two-layer EPUB parsing architecture that prioritizes the optional ebooklib and beautifulsoup4 packages for rich text extraction, but automatically falls back to Python’s standard library modules—zipfile, posixpath, re, and an internal HTML parser—to ensure zero-dependency operation.

The open-source repository virgiliojr94/book-to-skill implements this dual-path strategy in its core parsing module, allowing users to extract text from EPUB files with or without installing external dependencies. Understanding which libraries power this process helps developers choose the optimal configuration for their environment, whether they prioritize minimal dependencies or maximum extraction fidelity.

The Dual-Layer EPUB Parsing Architecture

The book_to_skill/parsers/epub.py file implements two distinct extraction pathways. The library attempts the richer, external-library path first, but gracefully degrades to a pure standard-library implementation if those packages are absent.

Optional Rich Extraction with ebooklib and BeautifulSoup

When the environment includes ebooklib and beautifulsoup4 (specified as optional dependencies in pyproject.toml), the parser invokes the extract_with_ebooklib function (lines 24-36). This path loads the EPUB container using ebooklib.epub.read_epub, iterates over all document items, and employs BeautifulSoup to parse HTML/XML content and extract clean text.

The import block for these external libraries is guarded by a try/except ImportError block, ensuring the code degrades gracefully if the packages are missing.

from book_to_skill.parsers.epub import extract_with_ebooklib

text = extract_with_ebooklib("my_book.epub")
if text is not None:
    print(text[:500])   # preview the first 500 characters

else:
    print("Ebooklib not installed or extraction failed.")

Standard Library Fallback with zipfile and Internal HTML Parser

If the optional dependencies are unavailable, the parser automatically switches to the extract_with_zipfile function (lines 63-122). This implementation relies entirely on Python’s built-in modules: zipfile to open the EPUB archive, posixpath for path manipulation, and re for regular expression operations.

This path discovers the OPF package document, builds a reading order from the EPUB spine, and feeds each HTML/XHTML file through the _HTMLTextExtractor class defined in book_to_skill/parsers/html.py. Because it uses only standard library components, this method is always available regardless of the installation environment.

from book_to_skill.parsers.epub import extract_with_zipfile

text = extract_with_zipfile("my_book.epub")
if text:
    print(text[:500])
else:
    print("Failed to extract text from the EPUB.")

How the Extraction Logic Works

Both extraction paths follow the EPUB specification to locate content, but they differ in implementation depth.

The extract_with_zipfile function (lines 63-84 and 87-122) manually navigates the EPUB zip structure to find the container.xml file, parses the OPF manifest to identify the spine reading order, then extracts text from each content document. The _HTMLTextExtractor handles the actual HTML-to-text conversion without external parsing libraries.

In contrast, extract_with_ebooklib delegates container parsing and item iteration to the ebooklib package, using BeautifulSoup’s robust HTML parser to handle complex markup and edge cases that the internal extractor might simplify.

Installing Optional Dependencies

To enable the enhanced extraction mode, install the optional dependencies listed in the repository’s pyproject.toml:

pip install ebooklib beautifulsoup4

Without these packages, the library operates in standard-library-only mode, maintaining full functionality but potentially handling complex EPUB structures differently.

Additional EPUB Utilities

Beyond text extraction, the epub.py module provides dependency-free utility functions for analyzing EPUB structure without external libraries:

from book_to_skill.parsers.epub import count_epub_chapters, count_epub_images

chapters = count_epub_chapters("my_book.epub")
images   = count_epub_images("my_book.epub")
print(f"Chapters: {chapters}, Images: {images}")

These functions use the same zipfile-based approach as the core fallback extractor, ensuring they work in any Python environment.

Summary

• book-to-skill implements a dual-layer EPUB parsing strategy in book_to_skill/parsers/epub.py to balance features against dependencies.
• The optional layer uses ebooklib and beautifulsoup4 (lines 24-36) for robust, high-fidelity text extraction when available.
• The core fallback layer relies exclusively on Python’s zipfile, posixpath, and re modules, plus the internal _HTMLTextExtractor from book_to_skill/parsers/html.py (lines 63-122).
• The extract_with_ebooklib function requires external packages, while extract_with_zipfile works with zero dependencies.
• Both methods respect the EPUB spine reading order and OPF manifest structure.

Frequently Asked Questions

Does book-to-skill require external libraries to parse EPUB files?

No. While the library can utilize ebooklib and beautifulsoup4 for enhanced extraction, the extract_with_zipfile function in book_to_skill/parsers/epub.py provides complete EPUB parsing capabilities using only Python’s standard library. This ensures the library functions in restricted environments or minimal Docker containers without additional PyPI dependencies.

What is the difference between extract_with_ebooklib and extract_with_zipfile?

extract_with_ebooklib (lines 24-36) leverages the ebooklib package to handle EPUB container semantics and BeautifulSoup to parse HTML, offering better handling of complex markup. extract_with_zipfile (lines 63-122) manually implements EPUB container logic using zipfile and parses HTML with the internal _HTMLTextExtractor. The former requires additional installations but may extract cleaner text from complex documents; the latter guarantees operation in any standard Python environment.

How does book-to-skill handle EPUB spine reading order?

Both extraction methods parse the OPF (Open Packaging Format) document to identify the spine element, which defines the linear reading order of the EPUB content. The standard-library path manually constructs this sequence in extract_with_zipfile (lines 87-122), while extract_with_ebooklib relies on ebooklib’s abstraction of the spine. This ensures extracted text follows the author-intended document flow regardless of the extraction method used.

Where is the HTML text extraction logic implemented?

The core HTML-to-text conversion lives in book_to_skill/parsers/html.py within the _HTMLTextExtractor class. This class is used exclusively by the standard-library fallback path (extract_with_zipfile) when BeautifulSoup is unavailable. It handles tag stripping and text normalization without external parsing dependencies.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}