Metadata-Version: 2.4
Name: epubchapterize
Version: 0.4.0
Summary: A Python package for parsing chapters from EPUBs.
Author-email: Matthew Grant <nzmattgrant@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/nzmattgrant/epubchapterize
Project-URL: Documentation, https://github.com/nzmattgrant/epubchapterize/wiki
Project-URL: Source, https://github.com/nzmattgrant/epubchapterize
Project-URL: Tracker, https://github.com/nzmattgrant/epubchapterize/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: annotated-types==0.7.0
Requires-Dist: beautifulsoup4==4.13.3
Requires-Dist: blis==1.3.0
Requires-Dist: bs4==0.0.2
Requires-Dist: build==1.3.0
Requires-Dist: catalogue==2.0.10
Requires-Dist: certifi==2025.1.31
Requires-Dist: charset-normalizer==3.4.1
Requires-Dist: click==8.1.8
Requires-Dist: cloudpathlib==0.21.0
Requires-Dist: confection==0.1.5
Requires-Dist: cymem==2.0.11
Requires-Dist: EbookLib==0.18
Requires-Dist: idna==3.10
Requires-Dist: importlib_metadata==8.7.0
Requires-Dist: Jinja2==3.1.6
Requires-Dist: joblib==1.4.2
Requires-Dist: langcodes==3.5.0
Requires-Dist: language_data==1.3.0
Requires-Dist: lxml==5.3.2
Requires-Dist: marisa-trie==1.2.1
Requires-Dist: markdown-it-py==3.0.0
Requires-Dist: MarkupSafe==3.0.2
Requires-Dist: mdurl==0.1.2
Requires-Dist: murmurhash==1.0.12
Requires-Dist: nltk==3.9.1
Requires-Dist: numpy==2.0.2
Requires-Dist: packaging==24.2
Requires-Dist: preshed==3.0.9
Requires-Dist: pydantic==2.11.3
Requires-Dist: pydantic_core==2.33.1
Requires-Dist: Pygments==2.19.1
Requires-Dist: pyproject_hooks==1.2.0
Requires-Dist: regex==2024.11.6
Requires-Dist: requests==2.32.3
Requires-Dist: rich==14.0.0
Requires-Dist: shellingham==1.5.4
Requires-Dist: six==1.17.0
Requires-Dist: smart-open==7.1.0
Requires-Dist: soupsieve==2.6
Requires-Dist: spacy==3.8.7
Requires-Dist: spacy-legacy==3.0.12
Requires-Dist: spacy-loggers==1.0.5
Requires-Dist: srsly==2.5.1
Requires-Dist: syntok==1.4.4
Requires-Dist: thinc==8.3.6
Requires-Dist: tomli==2.2.1
Requires-Dist: tqdm==4.67.1
Requires-Dist: typer==0.15.2
Requires-Dist: typing-inspection==0.4.0
Requires-Dist: typing_extensions==4.13.1
Requires-Dist: urllib3==2.4.0
Requires-Dist: wasabi==1.1.3
Requires-Dist: weasel==0.4.1
Requires-Dist: wrapt==1.17.2
Requires-Dist: zipp==3.23.0
Dynamic: license-file

# EpubChapterize

EpubChapterize is a Python package designed to split EPUB files into chapters programmatically. It provides a simple interface to process EPUB files and extract their chapters for further use. Currently optimized for Project Gutenberg EPUB3s — if it doesn't work for your use case please get in touch.

## Installation

```bash
pip install epubchapterize
```

## Usage

```python
from epub_chapterize import chapterize

chapters, language, title, author, cover_image = chapterize("dracula.epub")

print(title)    # "Dracula"
print(author)   # "Bram Stoker"
print(language) # "en"

for chapter in chapters:
    print(chapter["title"])
    for sentence in chapter["sentences"]:
        print(sentence)
```

### Return values

| Value | Type | Description |
|---|---|---|
| `chapters` | `list[dict]` | List of chapter dicts, each with `"title"`, `"sentences"`, `"start_file"`, `"start_id"` and `"sentence_files"` keys |
| `language` | `str` | BCP 47 language code detected from the EPUB metadata (e.g. `"en"`, `"fr"`) |
| `title` | `str` | Book title from EPUB metadata |
| `author` | `str` | Author name from EPUB metadata |
| `cover_image` | `bytes \| None` | Raw bytes of the cover image, or `None` if not found |

A chapter starts in the file `"start_file"`, at the element whose id is `"start_id"`, which is where the table of contents links to (`None` when it links to the file itself). When headings in the same file with no text of their own lead into a chapter, like a part heading just before its first chapter, the chapter's title starts with theirs and the chapter starts where the first of them does. `"sentence_files"` lists the files its sentences are in, in order, each with the index in `"sentences"` of the first sentence there; the sentences up to the next entry's are in that file. Files are paths from the root of the EPUB written as URLs, which is how readers such as Readium name them.

### Example output

For the Standard Ebooks `dracula.epub` the returned `chapters` list looks like:

```python
[
    {"title": "Imprint", ...},
    {
        "title": "I",
        "sentences": [
            "Jonathan Harker’s Journal.",
            "(Kept in shorthand.)",
            "3 May.",
            ...
        ],
        "start_file": "epub/text/chapter-1.xhtml",
        "start_id": None,
        "sentence_files": [{"file": "epub/text/chapter-1.xhtml", "first_sentence": 0}]
    },
    {
        "title": "II",
        "sentences": [
            "Jonathan Harker’s Journal—continued",
            "5 May.—I must have been asleep, for certainly if I had been fully awake I must have noticed the approach of such a remarkable place.",
            ...
        ],
        "start_file": "epub/text/chapter-2.xhtml",
        "start_id": None,
        "sentence_files": [{"file": "epub/text/chapter-2.xhtml", "first_sentence": 0}]
    },
    ...
]
```

The `cover_image` bytes can be written straight to a file:

```python
if cover_image:
    with open("cover.jpg", "wb") as f:
        f.write(cover_image)
```

## Supported languages

Sentence segmentation is supported for English, French, German, Spanish, Italian, Dutch, and Portuguese via NLTK's Punkt tokenizer (installed automatically). No extra downloads are required unless you switch to the spaCy backend.

## Requirements

- Python 3.13 or higher

## License

MIT — see the LICENSE file for details.

## Contributing

Contributions are welcome! Feel free to submit issues or pull requests at [github.com/nzmattgrant/epubchapterize](https://github.com/nzmattgrant/epubchapterize).

## Author

Matthew Grant
