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

> Discover the EPUB parsing libraries book-to-skill uses, featuring a dual-layer strategy with ebooklib and beautifulsoup4, or falling back to Python's standard library for zero-dependency operation.

- Repository: [Virgilio Junior/book-to-skill](https://github.com/virgiliojr94/book-to-skill)
- Tags: internals
- Published: 2026-08-26

---

**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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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.

```python
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`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/html.py). Because it uses only standard library components, this method is always available regardless of the installation environment.

```python
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`](https://github.com/virgiliojr94/book-to-skill/blob/main/pyproject.toml):

```bash
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`](https://github.com/virgiliojr94/book-to-skill/blob/main/epub.py) module provides dependency-free utility functions for analyzing EPUB structure without external libraries:

```python
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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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.