Metadata-Version: 2.4
Name: django-bookkeeper
Version: 0.3.0
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
Requires-Dist: rarfile>=4.2
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 / Requirement |
|---------|---------|
| Social login | `django-social-auth-app-django` |
| Cloud storage | `django-storages` |
| CBR comic support | system `unrar` or `unar` binary (`rarfile` is included automatically) |

## 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

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

## License

MIT
