epub-blocks

epub-blocks is a small, dependency-free Python library for recipe-driven extraction of ordered text blocks from EPUB 2 and EPUB 3 containers. It also exposes locator-bearing source blocks so that consuming projects can prepare and review recipes reproducibly.

It requires Python 3.13 or later.

This project is at an early 0.x stage. Its public API and recipe format may evolve before 1.0.

Installation

Install the 0.1.0 release directly from GitHub:

python -m pip install "git+https://github.com/jtauber/epub-blocks.git@v0.1.0"

For development, install from a local checkout:

python -m pip install .

The runtime package has no third-party dependencies.

Scope

The package handles the reusable EPUB layer:

locating and parsing the EPUB package document;
reading identifiers and the XHTML spine;
excluding auxiliary linear="no" spine items by default;
selecting spine documents with case-insensitive glob patterns;
extracting paragraph, heading, quotation, list-item, and preformatted text blocks with stable source locators;
excluding document paths, element locators, CSS classes, page-breaks, and note references; and
selecting, omitting, slicing, joining, and normalizing XHTML fragments;
applying explicit extraction recipes to produce id, type, and text records; and
writing those records as headerless TSV files.

It deliberately leaves the interpretation and downstream use of extracted records to consuming projects.

Example

from pathlib import Path

from epub_blocks import extract_blocks

blocks = extract_blocks(
    Path("book.epub"),
    include_documents=["*chapter*.xhtml"],
    exclude_classes=["image-caption"],
)

for block in blocks:
    print(block.source_locator, block.tag, block.text)

source_locator has the form s008:text/chapter-01.xhtml#1.3.2. Element-path components are one-based child positions within the XHTML body.

Extraction recipes

An extraction recipe pins the EPUB identity and explicitly maps output blocks to XHTML fragments:

{
  "recipe_version": "1",
  "epub": {
    "identifier": "9780000000000",
    "sha256": "f4f9c2d902a41b80732b2dce7ad01a57f615859c21417a5019e3cd8e4d271282"
  },
  "normalization": {
    "collapse_whitespace": true,
    "strip": true,
    "unicode_normalization": "NFC"
  },
  "omit_epub_types": ["noteref", "pagebreak"],
  "blocks": [
    {
      "id": "01.001",
      "type": "{p}",
      "parts": [
        {
          "document": "text/chapter-01.xhtml",
          "element_path": "1.3.2"
        }
      ]
    }
  ]
}

The command-line interface writes a three-column, headerless TSV containing the identifier, type, and text of each extracted record:

epub-blocks book.epub recipe.json records.tsv

Identifiers and types are opaque strings chosen by the recipe. See the complete recipe format for the full field reference, locator and slicing semantics, normalization order, validation rules, and worked examples. A strict JSON Schema is also available for editor and pipeline integration.

Safety and trust model

EPUB files are untrusted ZIP and XML input. The default extraction APIs bound archive membership, individual and cumulative reads, compression ratios, XML document size, element count, and nesting depth. Duplicate or unsafe archive paths, encrypted members, external or internal DTDs, and entity declarations are rejected. The declaration-only HTML5 <!DOCTYPE html> is permitted. Custom positive limits can be supplied with SafetyLimits when a legitimate book is larger than a default.

These checks reduce resource-exhaustion and ambiguity risks; they are not a sandbox for arbitrary code. The package does not execute EPUB scripts or fetch network resources.

Public API

The supported import surface is the names exported by epub_blocks: the result and option data classes, SafetyLimits, inspect_epub, extract_blocks, the recipe-loading and extraction functions, write_tsv, and EpubBlocksError. Helpers in submodules are implementation details and may change during the pre-1.0 period.

Development

uv sync
uv run coverage run -m unittest discover -s tests
uv run coverage report
uv run ruff check .
uv run pyright
uv run python -m build
uv run twine check dist/*
uv run pyright --verifytypes epub_blocks --ignoreexternal

Coverage includes branch measurement and enforces a 90% minimum. Run uv run coverage html after the test command for a browsable report in htmlcov/.

No EPUB files are committed to this repository. Tests construct small synthetic EPUB containers in temporary directories.

See CONTRIBUTING.md for the complete check sequence and change policy, and CHANGELOG.md for release notes. Bugs and proposals are tracked in the issue tracker.

License

epub-blocks is available under the MIT License.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

epub_blocks-0.1.0.tar.gz (34.8 kB view details)

Uploaded Sep 3, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

epub_blocks-0.1.0-py3-none-any.whl (19.9 kB view details)

Uploaded Sep 3, 2026 Python 3

File details

Details for the file epub_blocks-0.1.0.tar.gz.

File metadata

Download URL: epub_blocks-0.1.0.tar.gz
Upload date: Sep 3, 2026
Size: 34.8 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for epub_blocks-0.1.0.tar.gz
Algorithm	Hash digest
SHA256	`cb7dd0b5cf43abaf444fcf3906c959f425a84726df187767b2b27cf40ccafa03`
MD5	`cb526a37235692bad1ba4a0cc8bda0ce`
BLAKE2b-256	`b1cd2c3b1ee7e384307a3cb7fd39f4799d535475539ded798e8f95fc2eff69b3`

See more details on using hashes here.

Provenance

The following attestation bundles were made for epub_blocks-0.1.0.tar.gz:

Publisher: release.yml on jtauber/epub-blocks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: epub_blocks-0.1.0.tar.gz
- Subject digest: cb7dd0b5cf43abaf444fcf3906c959f425a84726df187767b2b27cf40ccafa03
- Sigstore transparency entry: 2704985995
- Sigstore integration time: Sep 3, 2026
Source repository:
- Permalink: jtauber/epub-blocks@53a6065fc96232cc3c06d7e02dbe8222ce08f265
- Branch / Tag: refs/tags/v0.1.0
- Owner: https://github.com/jtauber
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@53a6065fc96232cc3c06d7e02dbe8222ce08f265
- Trigger Event: release

File details

Details for the file epub_blocks-0.1.0-py3-none-any.whl.

File metadata

Download URL: epub_blocks-0.1.0-py3-none-any.whl
Upload date: Sep 3, 2026
Size: 19.9 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for epub_blocks-0.1.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`79709901dc310b2da7d7ea4129936c2f08034e303f5ca3f0526fe6be691a6ca2`
MD5	`c7e7b68ef73d7ff0b756aebf9fb389a1`
BLAKE2b-256	`0d28aae01485330e4da9c35c32aadaf369b74ef615acbdc6cb1fd03d157f6b08`

See more details on using hashes here.

Provenance

The following attestation bundles were made for epub_blocks-0.1.0-py3-none-any.whl:

Publisher: release.yml on jtauber/epub-blocks

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: epub_blocks-0.1.0-py3-none-any.whl
- Subject digest: 79709901dc310b2da7d7ea4129936c2f08034e303f5ca3f0526fe6be691a6ca2
- Sigstore transparency entry: 2704986026
- Sigstore integration time: Sep 3, 2026
Source repository:
- Permalink: jtauber/epub-blocks@53a6065fc96232cc3c06d7e02dbe8222ce08f265
- Branch / Tag: refs/tags/v0.1.0
- Owner: https://github.com/jtauber
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@53a6065fc96232cc3c06d7e02dbe8222ce08f265
- Trigger Event: release

Release history Release notifications | RSS feed

0.4.0

Sep 5, 2026 2 files

0.3.0

Sep 4, 2026 2 files

0.2.0

Sep 4, 2026 2 files

This release

0.1.0 This release

Sep 3, 2026 2 files

epub-blocks 0.1.0

epub-blocks

Installation

Scope

Example

Extraction recipes

Safety and trust model

Public API

Development

License

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License expression

Requires

Tags

Classifiers

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed