PyAppleBooks

PyAppleBooks is a Python API library to access your Apple Books data.

Installation

pip install py_apple_books

Requires Python 3.10+ on macOS.

Available Functions

Collections

Collection writes (v1.9.0+)

Apple exposes no automation API for collections, so these write directly to the library's SQLite store — behind guard rails: every call refuses while Books.app is running, takes a WAL-inclusive timestamped backup (kept under ~/.py_apple_books/backups/, restorable via write_safety.restore_library), validates the schema and aborts on drift, and runs in a single transaction that maintains Core Data's bookkeeping. Only user-created collections can be renamed or deleted; membership edits also work on "Want to Read". Writes also refuse when Books.app's state can't be verified — off macOS (e.g. in Docker), or if pgrep fails — raising WriteError.

⚠️ With iCloud "Collections, bookmarks and highlights" sync enabled, direct writes may not propagate to other devices and can be reverted by a cloud re-sync. Verify a small edit cross-device before relying on it.

Books

Reading Progress

Annotations

Book Content (v1.7.0+)

Read the full text of your non-DRM EPUBs. Powered by ebooklib and beautifulsoup4.

BookContent methods:

BookContent properties:

Exceptions

Content-access methods may raise:

Examples

Creating a client

from py_apple_books import PyAppleBooks

api = PyAppleBooks()

List books

for book in api.list_books():
    print(f"{book.title} — {book.author or 'Unknown Author'}")

Get annotations

for a in api.list_annotations(limit=5):
    print(f"[{a.color}] {a.selected_text}")

Search highlights

for a in api.search_annotation_by_highlighted_text('genome'):
    print(a.selected_text)

Filter by color

for a in api.get_annotations_by_color('yellow'):
    print(a.selected_text)

Reading progress

for book in api.get_books_in_progress(limit=5):
    print(f"{book.title}: {book.reading_progress:.1f}%")

Read chapter content

from py_apple_books.exceptions import BookNotDownloadedError, DRMProtectedError

book = api.get_book_by_id(42)
try:
    content = api.get_book_content(book.id)
except BookNotDownloadedError:
    print("Open the book in Apple Books first to download it.")
except DRMProtectedError:
    print("DRM-protected Store purchase — text content isn't readable.")
else:
    for ch in content.list_chapters():
        print(f"{'  ' * ch.depth}[{ch.order}] {ch.title}")

    # Read the first substantive chapter
    text = content.get_chapter_content(content.list_chapters()[0].id)
    print(text[:500])

See what the user is currently reading

# The book they most recently opened
for book in api.get_recently_read_books(limit=1):
    ch = api.get_current_reading_chapter(book.id)
    if ch is None:
        continue
    content = api.get_book_content(book.id)
    text = content.get_chapter_content(ch.id)
    print(f"Currently reading: {book.title}")
    print(f"Progress: {book.reading_progress:.1f}%")
    print(f"Chapter {ch.order}: {ch.title}")
    print(text[:500])

Get all collections and books

for collection in api.list_collections():
    print(f"{collection.title}: {len(collection.books)} books")
    for book in collection.books:
        print(f"  - {book.title}")

How content access handles Apple Books' quirks

• iCloud placeholders — books you've imported but haven't opened lately can live only in iCloud. is_downloaded detects this via os.stat (for files) or du -sk (for bundle directories) without triggering a download. get_book_content raises BookNotDownloadedError so you can prompt the user to open the book in Apple Books.
• DRM'd Store purchases — FairPlay-encrypted EPUBs carry META-INF/sinf.xml / an encryption.xml covering their content, and their chapter bodies are opaque ciphertext. Detected up-front from that evidence; callers get a clear DRMProtectedError. EPUBs whose encryption.xml only obfuscates fonts are readable.
• Untrusted book files — imported EPUBs are stored as unzipped bundles, so every entry is read through a contained reader: anything resolving outside the bundle, non-regular files and oversized entries raise UnsafeEpubEntryError instead of exposing unrelated local files.
• Missing metadata — Apple's unknown-author placeholder is returned as author=None, and the ZPAGECOUNT placeholder (0 or 1) as page_count=None.
• Non-standard EPUB layouts — OPFs at unusual paths, NCX files not declared in <spine toc=…> (e.g. The 4-Hour Workweek), EPUB3 books with nav docs only (e.g. On Numbers and Games), URL-encoded href characters (%21 → !), duplicate navPoint ids — all handled, with a stdlib NCX override for the ebooklib blind spots.
• Fragment-scoped chapters — Project Gutenberg EPUBs often put multiple sections in one XHTML file, separated by anchors. get_chapter_content returns only the requested section, not the whole file.

Running the tests

pip install -e '.[dev]'
pytest

The test suite covers placeholder/DRM detection, NCX parsing, XHTML text extraction, fragment scoping, and end-to-end BookContent behavior against generated EPUB fixtures. No real Apple Books library required.

Upcoming Features

• Adding a book to collection
• Removing a book from collection
• Updating annotations

Contribution

Thank you for considering contributing to this project! Your help is greatly appreciated.

Opening Issues

If you encounter a bug, have a feature request, or want to discuss something related to the project, please open an issue on the GitHub repository. When opening an issue, please provide:

Bug Reports: Describe the issue in detail. Include steps to reproduce the bug if possible, along with any error messages or screenshots.

Feature Requests: Clearly explain the new feature you'd like to see added to the project. Provide context on why this feature would be beneficial.

General Discussions: Feel free to start discussions on broader topics related to the project.

Contributing

1️⃣ Fork the GitHub repository https://github.com/vgnshiyer/py-apple-books
2️⃣ Create a new branch for your changes (git checkout -b feature/my-new-feature).
3️⃣ Make your changes and test them thoroughly.
4️⃣ Push your changes and open a Pull Request to main.

Please provide a clear title and description of your changes.

License

PyAppleBooks is licensed under the MIT license. See the LICENSE file for details.