الورّاق — the golden-age book craftsman, reborn as a library.
Ancient craft | Digital knowledge | Libraries | Books | Manuscripts
Lightweight EPUB inspection library — version detection, TOC discovery, and content extraction.
| Feature | Description |
|---|---|
| Version Detection | EPUB 2.0 and 3.0 support |
| TOC Discovery | Automatic NAV (EPUB 3) and NCX (EPUB 2) detection |
| TOC Parsing | Parse navigation points with full tree structure |
| Classification | Classify entries as chapter, part, front/back matter, section |
| Content Extraction | Extract content as HTML, plaintext, or markdown |
| Security | Zip bomb detection and zip slip prevention |
| Full-Text Search | BM25 search over a persisted SQLite index |
| CLI | 6 commands for EPUB inspection from the terminal |
- Python 3.10+
- Dependencies:
markdownify,typer
pip install al-warraqNote: the install name is
al-warraq, the import name isal_warraq(Python does not allow hyphens in imports).
Or with uv:
uv add al-warraqOptional extras:
pip install "al-warraq[tui]" # interactive terminal app (al-warraq book.epub)
pip install "al-warraq[minio]" # MinIO-backed extraction cachefrom al_warraq import inspect_epub
info = inspect_epub("book.epub")
print(f"Title: {info.title}")
print(f"Version: EPUB {info.version}")
print(f"TOC: {info.toc.toc_type}")
al-warraq inspect book.epub
al-warraq --help
| Command | Description |
|---|---|
inspect |
Display EPUB version, TOC type, and title |
extract |
Extract EPUB contents to a directory |
validate |
Validate ZIP structure, OPF, and TOC |
toc |
Display table of contents as a classified tree |
content |
Extract content for a specific section |
search |
BM25 full-text search across sections |
With the tui extra installed, a bare path opens a full terminal app on the
book — header, scrollable results, and a bottom input with / slash commands
(/toc, /search, /content, /info, /open, /help, /quit); bare text
runs a BM25 search:
al-warraq book.epub # one book
al-warraq ~/books/ # library view: browse + search across all booksPath only → open the book; a folder → the library view (cross-book BM25 search, unzipped EPUB package folders included); verb + path → one-shot answer. Without a TTY (or without the extra) it falls back to plain output, so scripts never block.
al-warraq --install-completionSupported shells: Bash, Zsh, Fish, PowerShell
| Function | Description |
|---|---|
inspect_epub() |
One-step inspection: hash, extract, parse OPF, detect TOC |
hash_epub() |
SHA-256 hash of EPUB file |
extract_epub() |
Extract EPUB ZIP to directory |
find_opf() |
Find the .opf file in extracted EPUB |
parse_opf() |
Parse OPF for version and TOC info |
parse_ncx() |
Parse NCX file for navigation map |
parse_nav() |
Parse EPUB 3 NAV document |
classify_navpoint() |
Classify a NavPoint by label |
classify_children() |
Classify children by nesting depth |
extract_content() |
Extract content as HTML, plaintext, or markdown |
| Type | Description |
|---|---|
EpubInfo |
Inspection result: version, TOC, OPF path, title |
TocInfo |
TOC detection: type, paths |
NavPoint |
Navigation point: label, file, anchor, children, type |
NcxData |
Parsed NCX: doc title, nav points |
al_warraq/
├── __init__.py # Public API: inspect_epub + re-exports
├── classify.py # classify_navpoint, classify_children
├── cli.py # CLI: inspect, extract, validate, toc, content
├── content.py # extract_content (HTML, plaintext, markdown)
├── epub.py # hash_epub, extract_epub, find_opf
├── exceptions.py # AlWarraqError, InvalidEpubError
├── nav.py # parse_nav (EPUB 3 NAV)
├── ncx.py # parse_ncx, NavPoint, NcxData
└── opf.py # parse_opf, EpubInfo, TocInfo
git clone https://github.com/Abdullah-Wex/Al-Warraq.git
cd Al-Warraq
uv syncmake lint # ruff
make typecheck # mypy
make security # bandit
make test # pytest
make quality # all checks| Document | Description |
|---|---|
| API Reference | Complete Python API documentation |
| CLI Reference | All CLI commands and options |
| Examples | Practical usage examples |
| Changelog | Version history |
MIT License. See LICENSE for details.
Contributions welcome! See CONTRIBUTING.md for guidelines.