django-bookkeeper 0.4.0

A Django app for storing, cataloguing, and reading e-Books (PDF, EPUB, CBZ)

django-bookkeeper

A Django app for storing, cataloguing, and reading e-Books (PDF, EPUB, CBZ).

Features

• Upload PDF, EPUB, and CBZ files (drag-and-drop or browse)
• Automatic metadata extraction — title, author, publisher, cover image
• Deduplication by SHA-256 hash
• Modern reader with:
  • EPUB rendering via epub.js (chapters are extracted to HTML at upload time for performance; epub.js is used as a fallback for fixed-layout EPUBs)
  • PDF rendering via PDF.js
  • CBZ page-by-page comic reader
  • Keyboard navigation (arrow keys)
• Reader settings: light/sepia/dark themes, font family & size, line height, column width
• Highlights in five colours with optional notes
• Bookmarks with titles and notes
• Reading progress — auto-saved position and percentage
• 5-star ratings per user
• Favourites and finished-book tracking
• Extensible hook signals for recent-books lists, activity feeds, etc.
• PWA-installable — add to your home screen on iOS and Android for a full-screen, standalone reading app
• Django best-practices: django-storages compatible, AUTH_USER_MODEL aware, namespaced URLs

Screenshots

Try the demo

The fastest way to see Bookkeeper in action — one command downloads five public-domain classics from Project Gutenberg and starts a local server:

git clone https://github.com/ehwio/django-bookkeeper
cd django-bookkeeper
make demo

Then open http://127.0.0.1:8000/ and sign in as demo / demo.

On subsequent runs, use make demo-run to start the server without re-seeding. Use make demo-reset to wipe the database and media and re-seed from scratch.

Admin interface: after seeding, create an admin account to access /admin/:

cd demo
PYTHONPATH=../src:.. uv run python manage.py create_admin

Then visit http://127.0.0.1:8000/admin/ and sign in with your admin credentials.

Or with Docker:

docker compose up

Uses Dockerfile.demo — builds the demo image from the demo/ directory.

The demo ships with:

• Pride and Prejudice — Jane Austen
• Twenty Thousand Leagues Under the Seas — Jules Verne
• The Time Machine — H.G. Wells
• Alice's Adventures in Wonderland — Lewis Carroll
• Frankenstein — Mary Wollstonecraft Shelley

Books are downloaded from Project Gutenberg on first run. They are public domain and freely distributable.

Progressive Web App (PWA)

Bookkeeper can be installed on your device's home screen for a full-screen, app-like experience with no browser chrome. On supported browsers, look for the Share → Add to Home Screen (iOS) or Install app option.

This requires no service worker — the manifest and meta tags enable the A2HS flow; offline reading is a future enhancement.

---

Installation

pip install django-bookkeeper
# or
uv add django-bookkeeper

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    "bookkeeper",
]

Include URLs:

# urls.py
from django.urls import include, path

urlpatterns = [
    path("books/", include("bookkeeper.urls", namespace="bookkeeper")),
]

Run migrations:

python manage.py migrate

Dependencies

django-bookkeeper requires Django 4.2 or later and uses these packages:

Package	Purpose
django-storages	Storage backend abstraction
Pillow	Image processing (covers)
ebooklib	EPUB metadata/structure extraction
PyMuPDF	PDF text/metadata extraction
python-magic	File type detection
beautifulsoup4	HTML/XML parsing
lxml	Fast XML/HTML processing
rarfile	CBR comic support

Optional dependencies

Feature	Package / Requirement
Social login	social-auth-app-django
CBR comic support	system unrar or unar binary
Cloud storage	Already included — django-storages is a required dependency

Hooks

Connect to Bookkeeper signals to extend behaviour:

from bookkeeper.hooks import book_opened, book_finished, progress_updated

@book_opened.connect
def track_recent(sender, user, book, **kwargs):
    RecentBook.objects.update_or_create(user=user, defaults={"book": book})

Available signals: book_opened, progress_updated, book_finished, book_rated, book_uploaded, highlight_created, bookmark_created.

Development

git clone https://github.com/ehwio/django-bookkeeper
cd django-bookkeeper
uv sync --extra dev
uv run pytest --cov
uv run ruff check src/ tests/ demo/

GitFlow

• main — stable releases
• develop — integration branch
• feature/* — new features
• fix/* — bug fixes
• release/* — release prep

See RELEASING.md for the step-by-step release process (TestPyPI → PyPI via GitHub Actions).

License

MIT