django-bookkeeper 0.2.1__tar.gz

django_bookkeeper-0.2.1/.claude/launch.json

@@ -0,0 +1,23 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "bookkeeper-demo",
+      "runtimeExecutable": "uv",
+      "runtimeArgs": [
+        "run",
+        "--with",
+        "django-bookkeeper",
+        "python",
+        "demo/manage.py",
+        "runserver",
+        "8765"
+      ],
+      "port": 8765,
+      "env": {
+        "DJANGO_SETTINGS_MODULE": "demo_project.settings",
+        "PYTHONPATH": "src:demo:."
+      }
+    }
+  ]
+}

django_bookkeeper-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_call: {}
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Ruff check
+        run: uv run ruff check src/ tests/ demo/
+
+  test:
+    needs: lint
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+        django-version: ["4.2", "5.0", "5.1"]
+        exclude:
+          # Django 5.0 dropped support before Python 3.13 was released
+          - python-version: "3.13"
+            django-version: "5.0"
+          # Django 4.2 didn't officially support 3.13 until later point releases
+          - python-version: "3.13"
+            django-version: "4.2"
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev --python ${{ matrix.python-version }}
+
+      - name: Run tests against Django ${{ matrix.django-version }}
+        # `uv run` re-syncs the venv to uv.lock before executing, which would
+        # silently revert a `uv pip install` override done in a separate step.
+        # `--with` overrides the dependency for this invocation only, and
+        # survives the sync.
+        run: uv run --with "django~=${{ matrix.django-version }}.0" pytest --cov --cov-report=xml
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.12' && matrix.django-version == '5.1'
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false

django_bookkeeper-0.2.1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,63 @@
+name: Publish to PyPI
+
+# Production releases publish on GitHub Release "published", not on tag
+# push — tags get verified on TestPyPI first (see publish-testpypi.yml).
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.tag_name }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Verify release tag matches package version
+        if: github.event_name == 'release'
+        env:
+          TAG_NAME: ${{ github.event.release.tag_name }}
+        run: |
+          PKG_VERSION=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          TAG_VERSION="${TAG_NAME#v}"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "::error::Release tag $TAG_NAME does not match pyproject.toml version $PKG_VERSION"
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for PyPI trusted publishing (OIDC)
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

django_bookkeeper-0.2.1/.github/workflows/publish-testpypi.yml

@@ -0,0 +1,62 @@
+name: Publish to TestPyPI
+
+# Tag pushes (vX.Y.Z) publish to TestPyPI for pre-release verification.
+# Pushing to pypi.org happens separately, on GitHub Release "published".
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Verify tag matches package version
+        if: github.event_name == 'push'
+        run: |
+          PKG_VERSION=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "::error::Tag v$TAG_VERSION does not match pyproject.toml version $PKG_VERSION"
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write # required for PyPI trusted publishing (OIDC)
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

django_bookkeeper-0.2.1/.gitignore

@@ -0,0 +1,23 @@
+.DS_Store
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.env
+*.sqlite3
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+.ruff_cache/
+*.mo
+*.pot
+/media/
+/static-collected/
+node_modules/
+demo/media/
+demo/demo.sqlite3

django_bookkeeper-0.2.1/AGENTS.md

@@ -0,0 +1,140 @@
+# Agent instructions for django-bookkeeper
+
+This file documents how to work in this repo so AI coding agents follow the
+same process humans do. Read this before making changes.
+
+## What this project is
+
+A reusable Django app (`src/bookkeeper/`) for storing, cataloguing, and
+reading e-books (PDF, EPUB, CBZ), installable via pip/uv. `demo/` is a
+throwaway Django project that exercises the app end-to-end — it is not
+part of the published package.
+
+## Branching (GitFlow) — never push directly to main
+
+- `main` — stable releases only. Never commit or push directly here.
+- `develop` — integration branch. Feature/fix branches merge here via PR.
+- `feature/*` — new features, branched from `develop`.
+- `fix/*` — bug fixes, branched from `develop`.
+- `release/*` — release prep branches.
+
+Always create a branch and open a PR. Do not push to `develop` or `main`
+directly unless explicitly told to.
+
+## Before every push
+
+Run lint and tests. Both must pass:
+
+```bash
+uv run ruff check src/ tests/ demo/
+uv run pytest --cov
+```
+
+CI runs the same `ruff check` command and a pytest matrix across Python
+3.11–3.13 and Django 4.2/5.0/5.1 — catch failures locally first.
+
+Note: `ruff format` is not currently enforced (the existing codebase
+hasn't been run through the formatter). Don't add a `ruff format --check`
+CI gate without first reformatting the codebase as a deliberate, separate
+change — otherwise it fails on ~11 pre-existing files immediately.
+
+## Working with the demo project
+
+The demo lives in `demo/` but imports `bookkeeper` from `../src`. Because of
+this, commands run from inside `demo/` need an explicit `PYTHONPATH`:
+
+```bash
+cd demo
+PYTHONPATH=../src:.. uv run python manage.py migrate
+PYTHONPATH=../src:.. uv run python manage.py seed_demo
+PYTHONPATH=../src:.. uv run python manage.py runserver
+```
+
+(`make demo` from the repo root wraps this correctly — prefer it when you
+just want to run the demo, use the explicit `PYTHONPATH` form when you need
+a one-off management command.)
+
+### Re-seeding after model or extraction changes
+
+`seed_demo --fast` skips books that already exist (matched by file hash),
+so changing extraction logic (e.g. `EpubReader.extract_chapters()`) has
+**no effect on already-seeded books** — they were extracted once at
+upload time and the result is stored in the DB. To pick up extraction
+changes:
+
+```bash
+PYTHONPATH=../src:.. uv run python manage.py flush --no-input
+PYTHONPATH=../src:.. uv run python manage.py seed_demo
+```
+
+This applies to any manually-uploaded book too — re-upload it after
+pulling a fix to extraction code.
+
+## Architecture notes
+
+- `src/bookkeeper/readers/` — one module per format (`epub.py`, `pdf.py`,
+  `cbz.py`), each implementing `BaseReader` (metadata/cover extraction).
+  `EpubReader` additionally extracts chapter HTML at upload time (see
+  below) — this is EPUB-specific, not part of the shared interface.
+- **EPUB chapters are extracted once, at upload time**, not re-parsed on
+  every read. `EpubReader.extract_chapters()` walks the spine, sanitizes
+  each XHTML item with BeautifulSoup, and stores the result in `Chapter`
+  rows. The reader serves `Chapter.html` directly — no epub.js, no
+  runtime EPUB parsing. epub.js remains only as a fallback for
+  fixed-layout (pre-paginated) EPUBs, which aren't extracted.
+- `src/bookkeeper/hooks.py` — Django signals (`book_opened`,
+  `progress_updated`, `book_finished`, `book_rated`, `book_uploaded`,
+  `highlight_created`, `bookmark_created`) are the extension points for
+  consuming projects. Don't add new functionality that should be
+  observable externally without firing a signal.
+- URLs are namespaced (`bookkeeper:`) and never hardcode a mount prefix
+  in templates — always use `{% url %}`. The demo mounts the app at `/`,
+  but consuming projects can mount it anywhere (e.g. `/books/`).
+  **JavaScript must follow the same rule**: never hardcode an API path
+  like `/books/api/...` — read it from a `data-url-*` attribute injected
+  via `{% url %}` in the template. (See `reader.html`/`reader.js` for the
+  pattern. A hardcoded path in `bookkeeper.js`'s star-rating widget is a
+  known bug — see issue #4.)
+
+## Known gotchas worth knowing before touching the reader
+
+- **EPUB self-closing tags**: BeautifulSoup's `lxml-xml` parser (needed to
+  read well-formed XHTML) serializes empty elements as `<tag/>`, which is
+  valid XML but meaningless to a browser's HTML5 parser for non-void
+  elements like `<a>` — the tag stays open and swallows everything after
+  it. `EpubReader.extract_chapters()` works around this by forcing an
+  explicit empty text node on empty non-void, non-SVG elements before
+  serializing. Don't "simplify" this by reparsing the whole fragment
+  through an HTML parser — that lowercases SVG's case-sensitive
+  attributes (e.g. `viewBox` → `viewbox`), breaking SVG cover rendering.
+- **Flexbox scroll containers need `min-height: 0`**: flex children
+  default to `min-height: auto`, meaning they won't shrink below their
+  content size. Any new scrollable panel inside the reader's flex layout
+  needs `min-height: 0` alongside `overflow-y: auto`, or it will grow to
+  fit all content instead of scrolling.
+- **`[hidden]` can be overridden by author CSS**: if you give an element
+  with the `hidden` attribute its own `display: flex`/`block` rule, that
+  rule wins over the browser's `[hidden] { display: none }` UA rule. Any
+  element toggled via the `hidden` attribute needs an explicit
+  `#id[hidden] { display: none; }` rule alongside its own display rules
+  (see the four reader viewer divs in `reader.css` for the pattern).
+
+## Release process
+
+Versioning is currently manual (static `version` in `pyproject.toml`,
+not git-tag-derived).
+
+1. Bump `version` in `pyproject.toml`.
+2. Commit, merge to `main` via the normal release-branch flow.
+3. Tag and push `vX.Y.Z` — this triggers `publish-testpypi.yml`, which
+   verifies the tag matches the `pyproject.toml` version and publishes to
+   **test.pypi.org** via OIDC trusted publishing.
+4. Verify the TestPyPI release installs and works correctly.
+5. Cut a GitHub Release from that tag — this triggers `publish-pypi.yml`,
+   which publishes to **pypi.org**.
+
+Both publish workflows gate on the CI workflow (lint + test matrix)
+passing first, via `workflow_call`. Trusted publisher config (on both
+PyPI and TestPyPI) must reference the exact workflow filename and
+environment name — see `.github/workflows/publish-*.yml` for the
+environment names (`testpypi` / `pypi`).

django_bookkeeper-0.2.1/CLAUDE.md

@@ -0,0 +1,3 @@
+See [AGENTS.md](AGENTS.md) for project conventions, branching workflow,
+demo setup, and release process. That file is the source of truth for
+all coding agents working in this repo, not just Claude.

django_bookkeeper-0.2.1/Dockerfile.demo

@@ -0,0 +1,16 @@
+FROM python:3.12-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libmagic1 \
+    libmupdf-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY pyproject.toml uv.lock ./
+RUN pip install uv && uv sync --no-dev
+
+COPY src/ ./src/
+COPY demo/ ./demo/
+
+EXPOSE 8000

django_bookkeeper-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric Williams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_bookkeeper-0.2.1/Makefile

@@ -0,0 +1,35 @@
+.PHONY: demo demo-reset test lint
+
+# ── Demo ─────────────────────────────────────────────────────────────────────
+
+demo:
+	@echo "Setting up demo…"
+	cd demo && DJANGO_SETTINGS_MODULE=demo_project.settings PYTHONPATH=../src:.. \
+	  uv run python manage.py migrate --run-syncdb
+	@echo "Seeding demo data (downloads ~5 public-domain EPUBs)…"
+	cd demo && DJANGO_SETTINGS_MODULE=demo_project.settings PYTHONPATH=../src:.. \
+	  uv run python manage.py seed_demo
+	@echo ""
+	@echo "Starting server at http://127.0.0.1:8000/"
+	cd demo && DJANGO_SETTINGS_MODULE=demo_project.settings PYTHONPATH=../src:.. \
+	  uv run python manage.py runserver
+
+demo-reset:
+	rm -f demo/demo.sqlite3
+	rm -rf demo/media/bookkeeper
+	$(MAKE) demo
+
+demo-run:
+	cd demo && DJANGO_SETTINGS_MODULE=demo_project.settings PYTHONPATH=../src:.. \
+	  uv run python manage.py runserver
+
+# ── Dev ──────────────────────────────────────────────────────────────────────
+
+test:
+	uv run pytest tests/ -v
+
+lint:
+	uv run ruff check src/ tests/ demo/
+
+lint-fix:
+	uv run ruff check --fix src/ tests/ demo/

django_bookkeeper-0.2.1/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: django-bookkeeper
+Version: 0.2.1
+Summary: A Django app for storing, cataloguing, and reading e-Books (PDF, EPUB, CBZ)
+Project-URL: Homepage, https://github.com/ehwio/django-bookkeeper
+Project-URL: Repository, https://github.com/ehwio/django-bookkeeper
+Project-URL: Issues, https://github.com/ehwio/django-bookkeeper/issues
+Author-email: Eric Williams <eric@subcritical.org>
+License: MIT License
+        
+        Copyright (c) 2026 Eric Williams
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cbz,django,ebook,epub,library,pdf,reader
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: django-storages>=1.14
+Requires-Dist: django>=4.2
+Requires-Dist: ebooklib>=0.18
+Requires-Dist: lxml>=5.0
+Requires-Dist: pillow>=10.0
+Requires-Dist: pymupdf>=1.24
+Requires-Dist: python-magic>=0.4.27
+Provides-Extra: dev
+Requires-Dist: django-debug-toolbar>=4.3; extra == 'dev'
+Requires-Dist: factory-boy>=3.3; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-django>=4.8; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: social
+Requires-Dist: social-auth-app-django>=5.4; extra == 'social'
+Description-Content-Type: text/markdown
+
+# 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](https://github.com/futurepress/epub.js/)
+  - PDF rendering via [PDF.js](https://mozilla.github.io/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.
+- Django best-practices: `django-storages` compatible, `AUTH_USER_MODEL` aware, namespaced URLs
+
+## 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:
+
+```bash
+git clone https://github.com/ehwio/django-bookkeeper
+cd django-bookkeeper
+uv sync
+make demo
+```
+
+Then open **http://127.0.0.1:8000/** and sign in as `demo` / `demo`.
+
+**Or with Docker:**
+
+```bash
+docker compose up
+```
+
+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](https://www.gutenberg.org/) on first run.
+> They are public domain and freely distributable.
+
+---
+
+## Installation
+
+```bash
+pip install django-bookkeeper
+# or
+uv add django-bookkeeper
+```
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    ...
+    "bookkeeper",
+]
+```
+
+Include URLs:
+
+```python
+# urls.py
+from django.urls import include, path
+
+urlpatterns = [
+    path("books/", include("bookkeeper.urls", namespace="bookkeeper")),
+]
+```
+
+Run migrations:
+
+```bash
+python manage.py migrate
+```
+
+## Optional dependencies
+
+| Feature | Package |
+|---------|---------|
+| Social login | `django-social-auth-app-django` |
+| Cloud storage | `django-storages` |
+
+## Hooks
+
+Connect to Bookkeeper signals to extend behaviour:
+
+```python
+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
+
+```bash
+git clone https://github.com/ehwio/django-bookkeeper
+cd django-bookkeeper
+uv sync --extra dev
+uv run pytest
+uv run ruff check src/ tests/
+```
+
+### GitFlow
+
+- `main` — stable releases
+- `develop` — integration branch
+- `feature/*` — new features
+- `fix/*` — bug fixes
+- `release/*` — release prep
+
+## License
+
+MIT