dtourolle/dreader-application
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update docs
Python CI / test (3.12) (push) Successful in 8m40s
Details
Python CI / test (3.13) (push) Successful in 22m41s
Details

Browse Source
This commit is contained in:
dtourolle
2025-11-09 22:06:06 +01:00
parent 0f9e38eb7c
commit 8f6205dcfe
6 changed files with 1606 additions and 1503 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+167 -18
View File
@@ -8,11 +8,9 @@
| ![Documentation Coverage](https://gitea.tourolle.paris/dtourolle/dreader-application/raw/branch/badges/cov_info/coverage-docs.svg) | **Documentation Coverage** - Percentage of code with docstrings |
| ![License](https://img.shields.io/badge/license-MIT-blue.svg) | **License** - Project licensing information |
> 📋 **Note**: Badges show results from the commit referenced in the URLs. Red "error" badges indicate build failures for that specific step.
## Description
DReader Application is a complete, production-ready ebook reader built on [pyWebLayout](https://gitea.tourolle.paris/dtourolle/pyWebLayout). It demonstrates how to build a full-featured ebook reader with text highlighting, bookmarks, gesture support, and position persistence.
DReader Application is a complete, production-ready ebook reader built on [pyWebLayout](https://gitea.tourolle.paris/dtourolle/pyWebLayout). It demonstrates how to build a full-featured ebook reader with library browsing, text highlighting, bookmarks, gesture support, overlays, and position persistence.
This project serves as both a reference implementation and a ready-to-use ereader library for building desktop, web-based, or embedded reading applications.
@@ -20,11 +18,12 @@ This project serves as both a reference implementation and a ready-to-use ereade
### Core Reading Features
- 📖 **EPUB Support** - Load and render EPUB files with full text extraction
- 📚 **Library Management** - Browse and select books from your collection
- 📄 **Page Rendering** - Render pages as PIL Images optimized for any display
- ⬅️➡️ **Navigation** - Smooth forward and backward page navigation
- 🔖 **Bookmarks** - Save and restore reading positions with persistence
- 📑 **Chapter Navigation** - Jump to chapters by title or index via TOC
- 📋 **TOC Overlay** - Interactive table of contents overlay with gesture support
- 📋 **Unified Overlays** - Navigation (TOC + Bookmarks) and Settings overlays
- 📊 **Progress Tracking** - Real-time reading progress percentage
### Text Interaction
@@ -40,6 +39,7 @@ This project serves as both a reference implementation and a ready-to-use ereade
- 💾 **Position Persistence** - Stable positions across style changes
- ⚡ **Smart Reflow** - Automatic text reflow on font/spacing changes
- 🎨 **Custom Styling** - Full control over colors, fonts, and layout
- 💾 **Settings Persistence** - Save and restore preferences across sessions
## Installation
@@ -156,8 +156,8 @@ reader.get_chapters() # List all chapters
reader.get_current_chapter_info()
reader.get_reading_progress() # Returns 0.0 to 1.0
# TOC Overlay
overlay_image = reader.open_toc_overlay() # Returns composited image with TOC
# Navigation Overlay (unified TOC + Bookmarks)
overlay_image = reader.open_navigation_overlay() # Opens with tabs
reader.close_overlay()
reader.is_overlay_open()
```
@@ -236,34 +236,84 @@ elif response.action == ActionType.CHAPTER_SELECTED:
# - TAP: Select words, activate links, navigate TOC
# - LONG_PRESS: Show definitions or context menu
# - SWIPE_LEFT/RIGHT: Page navigation
# - SWIPE_UP: Open TOC overlay (from bottom 20% of screen)
# - SWIPE_DOWN: Close overlay
# - SWIPE_UP: Open navigation overlay (from bottom 20% of screen)
# - SWIPE_DOWN: Close overlay or open settings (from top 20%)
# - PINCH_IN/OUT: Font size adjustment
# - DRAG: Text selection
```
### File Operations
### Settings Persistence
```python
# Save current page to file
reader.render_to_file("current_page.png")
from dreader.state import StateManager
from pathlib import Path
# Context manager (auto-saves position on close)
with EbookReader(page_size=(800, 1000)) as reader:
reader.load_epub("book.epub")
# ... use reader ...
# Position automatically saved on exit
# Initialize state manager
state_file = Path.home() / ".config" / "dreader" / "state.json"
state_manager = StateManager(state_file=state_file)
# Load saved state
state = state_manager.load_state()
# Create reader and apply saved settings
reader = EbookReader(page_size=(800, 1000))
reader.load_epub("mybook.epub")
reader.apply_settings(state.settings.to_dict())
# Settings are automatically saved
reader.increase_font_size()
state_manager.update_settings(reader.get_current_settings())
state_manager.save_state()
```
### Library Management
```python
from dreader.library import LibraryManager
# Initialize library
library = LibraryManager(
library_path="/path/to/books",
page_size=(800, 1200)
)
# Scan for EPUB files
library.scan_library()
# Render library view
library_image = library.render_library()
# Handle book selection
book_path = library.handle_library_tap(x=400, y=300)
if book_path:
reader.load_epub(book_path)
```
## Examples
Check out the `examples/` directory for complete working examples:
Check out the [examples/](examples/) directory for complete working examples:
### Basic Examples
- **[simple_ereader_example.py](examples/simple_ereader_example.py)** - Basic ereader usage with EPUB loading and navigation
- **[ereader_demo.py](examples/ereader_demo.py)** - Comprehensive demo showcasing all features
- **[word_selection_highlighting.py](examples/word_selection_highlighting.py)** - Text selection and highlighting
- **[simple_word_highlight.py](examples/simple_word_highlight.py)** - Minimal highlighting example
### Text Highlighting
- **[word_selection_highlighting.py](examples/word_selection_highlighting.py)** - Text selection and highlighting
### Overlays
- **[demo_toc_overlay.py](examples/demo_toc_overlay.py)** - Interactive table of contents overlay
- **[navigation_overlay_example.py](examples/navigation_overlay_example.py)** - Unified navigation overlay (TOC + Bookmarks)
- **[demo_settings_overlay.py](examples/demo_settings_overlay.py)** - Settings panel with font/spacing controls
### Library & State
- **[library_reading_integration.py](examples/library_reading_integration.py)** - Complete library → reading → resume workflow
- **[persistent_settings_example.py](examples/persistent_settings_example.py)** - Save/restore settings across sessions
### Advanced
- **[demo_pagination.py](examples/demo_pagination.py)** - Pagination system demonstration
- **[generate_ereader_gifs.py](examples/generate_ereader_gifs.py)** - Generate animated GIF demonstrations
- **[generate_library_demo_gif.py](examples/generate_library_demo_gif.py)** - Generate library demo animations
## Architecture
@@ -279,6 +329,27 @@ dreader.application.EbookReader (High-Level API)
└── pyWebLayout.io.readers.epub_reader # EPUB parsing
```
### Component Structure
```
dreader/
├── application.py # Main EbookReader class (coordinator)
├── managers/ # Specialized management modules
│ ├── document.py # Document loading (EPUB/HTML)
│ ├── settings.py # Font and spacing controls
│ └── highlight_coordinator.py # Text highlighting
├── handlers/
│ └── gestures.py # Touch event routing
├── overlays/ # UI overlay system
│ ├── base.py # Base overlay functionality
│ ├── navigation.py # TOC and bookmarks overlay
│ └── settings.py # Settings overlay
├── library.py # Library browsing and book selection
├── state.py # Application state persistence
├── html_generator.py # HTML generation for overlays
└── gesture.py # Gesture definitions and responses
```
### Relationship to pyWebLayout
**pyWebLayout** is a layout engine library providing low-level primitives:
@@ -297,6 +368,30 @@ Think of it like this:
- **pyWebLayout** = React (library)
- **DReader Application** = Next.js (framework)
## State Management
### File Structure
```
~/.config/dreader/
├── state.json # Application state
├── covers/ # Cached book covers
├── bookmarks/ # Per-book bookmarks
├── highlights/ # Per-book highlights
└── xray/ # X-Ray data (future)
```
### State Persistence
- **Auto-save**: Every 60 seconds
- **Immediate save**: On mode change, settings change, shutdown
- **Boot behavior**: Resume last book at last position or show library
- **Error handling**: Fall back to library if book missing or state corrupt
### Position Stability
- Positions stored by abstract document structure (chapter/block/word indices)
- Stable across font size changes, spacing changes, page size changes
- Per-book storage using document IDs
- Special `__auto_resume__` bookmark for last reading position
## Use Cases
- 📱 **Desktop Ereader Applications** - Build native ereader apps with Python
@@ -340,6 +435,9 @@ python simple_ereader_example.py /path/to/book.epub
# Run comprehensive demo
python ereader_demo.py /path/to/book.epub
# Run library integration demo
python library_reading_integration.py /path/to/library/
# Generate animated GIFs
python generate_ereader_gifs.py /path/to/book.epub
```
@@ -351,6 +449,10 @@ The project includes comprehensive tests covering:
- **Application API** - All EbookReader methods and workflows
- **System Integration** - Layout manager, bookmarks, and state management
- **Highlighting** - Word and selection highlighting with persistence
- **Overlays** - Navigation and settings overlay interactions
- **Gestures** - Touch event handling and routing
- **Boot Recovery** - State persistence and position restoration
- **Library** - Book scanning, selection, and metadata
- **Edge Cases** - Error handling, boundary conditions, and recovery
```bash
@@ -367,6 +469,53 @@ pytest -v
pytest --cov=dreader --cov-report=term-missing
```
## Hardware Integration
DReader requires a Hardware Abstraction Layer (HAL) for display and input:
```python
from abc import ABC, abstractmethod
from PIL import Image
class DisplayHAL(ABC):
"""Abstract display interface for platform integration"""
@abstractmethod
def show_image(self, image: Image.Image):
"""Display a PIL Image on the screen"""
@abstractmethod
def get_touch_events(self) -> Iterator[TouchEvent]:
"""Get iterator of touch events from hardware"""
@abstractmethod
def set_brightness(self, level: int):
"""Set display brightness (0-10)"""
```
**Example HAL Implementations:**
- **E-ink Displays**: IT8951, Remarkable device SDK
- **Desktop**: pygame, tkinter, Qt
- **Web**: Flask + HTML canvas
- **Embedded**: Device-specific framebuffer
See [HAL_IMPLEMENTATION_SPEC.md](HAL_IMPLEMENTATION_SPEC.md) for detailed integration guidelines.
## Documentation
- [README.md](README.md) - This file, main project documentation
- [REQUIREMENTS.md](REQUIREMENTS.md) - Application requirements specification
- [ARCHITECTURE.md](ARCHITECTURE.md) - System architecture and design details
- [HAL_IMPLEMENTATION_SPEC.md](HAL_IMPLEMENTATION_SPEC.md) - Hardware integration guide
## Performance
- **Boot Time**: ~2-3 seconds to resume reading
- **Page Turn**: ~50-100ms (depends on page complexity)
- **Overlay Open**: ~200-250ms (includes HTML generation and rendering)
- **Memory Usage**: ~20-30MB base + 10-50MB per book
- **Cache**: Automatic cover image and metadata caching for fast library loading
## Contributing
Contributions welcome! This project demonstrates what's possible with pyWebLayout. If you build something cool or find ways to improve the reader, please share!