Metadata-Version: 2.4
Name: weaver-reader
Version: 0.2.5
Summary: A complete system for scraping novel chapters from FreeWebNovel, converting scraped data into standardized EPUB books, and reading them locally in a dedicated desktop application.
Author: kerem-ea
Project-URL: Homepage, https://github.com/kerem-ea/weaver-reader
Project-URL: Repository, https://github.com/kerem-ea/weaver-reader
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Flask>=2.0
Requires-Dist: selectolax
Requires-Dist: curl-cffi
Requires-Dist: camoufox
Requires-Dist: pywebview
Requires-Dist: ebooklib
Requires-Dist: pillow
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# Weaver Reader

A complete system for scraping novel chapters from FreeWebNovel, converting scraped data into standardized EPUB books, and reading them locally in a dedicated desktop application.

## Installation

### From PyPI

```powershell
pip install weaver-reader
```

This installs four command-line tools: `weaver`, `weaver-scraper`, `weaver-epub` and `weaver-app`.

`weaver` is the umbrella command. Run `weaver --help` to list the tools, or dispatch directly:

```powershell
weaver scraper ...   # same as weaver-scraper ...
weaver epub ...      # same as weaver-epub ...
weaver app ...       # same as weaver-app ...
```

### From source (for development)

```powershell
git clone https://github.com/kerem-ea/weaver-reader
cd weaver-reader
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e .[dev]
```

Then run the test suite:

```powershell
python -m pytest tests
```

## Workflow

### 1. Scrape novel chapters

```powershell
weaver-scraper
```

Follow the interactive prompts, or pass arguments directly:

```powershell
weaver-scraper <slug-or-url> <start-chapter> <end-chapter> <mode>
weaver-scraper shadow-slave 1 10 1
```

Other options:

```powershell
weaver-scraper --version   # print the version and exit
weaver-scraper --help      # print usage
```

Modes:
- `1` — fast HTTP, then browser retry for failures
- `2` — browser-only
- `3` — slow HTTP, then browser retry for failures

All commands (`weaver`, `weaver-scraper`, `weaver-epub`, `weaver-app`) support `--version` and `--help`.

Scraped raw JSON, cover images and progress are saved to the per-user data directory `%APPDATA%\weaver-reader\data\<novel-slug>\` on Windows.

> First time using the scraper? The Camoufox browser binaries may need to be fetched: `camoufox fetch`.

### 2. Convert scraped JSON to EPUB

```powershell
weaver-epub
```

An interactive menu lists all scraped novels in the data directory. You can also build a single novel or all of them directly:

```powershell
weaver-epub <novel-slug>
weaver-epub all
```

Volumes are resolved from three tiers of data (the site is never consulted):
1. The novel's stored `metadata.json` `volumes` (user-editable, highest priority)
2. Curated default volume specs
3. Auto-generated contiguous splits, persisted back into `metadata.json`

Override flags:

```powershell
weaver-epub <novel-slug> --volumes 4    # force split into 4 auto volumes
weaver-epub <novel-slug> --flat         # single flat EPUB
weaver-epub <novel-slug> --auto         # regenerate stored volumes
```

Generated `.epub` files are written next to the scraped data for each novel.

### 3. Run the Reader Application

```powershell
weaver-app
```

The desktop reader discovers `.epub` files under the data directory generated by `weaver-epub`. Reading progress is tracked per novel and stored in the per-user location `%APPDATA%\weaver-reader\last_read.json` (Windows) so your reading state never touches the repository.

## Project Structure

```
src/weaver/             Package source (installed under the `weaver` import name)
|-- cli.py              Top-level `weaver` command dispatcher (scraper/epub/app)
|-- _common.py          Shared data-root, version & progress-file resolution
|-- scraper/            Novel scraper component
|   |-- browser.py      Camoufox browser scraping engine
|   |-- catalog.py      Chapter index & title fetcher
|   |-- constants.py    Scraper timeouts & configuration presets
|   |-- cover.py        Landing page cover image fetcher
|   |-- fetch.py        Fast HTTP scraper engine
|   |-- parsing.py      HTML parsing and text extraction
|   |-- paths.py        Scraper output directory setup
|   |-- progress.py     Incremental JSONL state writer
|   |-- scrape.py       Main scraper entry point
|   |-- session.py      Browser session & CF challenge helpers
|   `-- site_config.py  Site configuration registry
|-- epub/               Modular EPUB generator engine
|   |-- builder.py      EPUB document construction routines
|   |-- chapters.py     Chapter & volume HTML/XHTML formatting
|   |-- cli.py          CLI entry point
|   |-- constants.py    Volume specs & CSS styles
|   |-- cover.py        Cover image preparation
|   |-- finder.py       Scraped data file locator
|   `-- volumes.py      Tiered volume resolution & persistence
`-- app/                Desktop reader application
    |-- api.py          pywebview JS bridge API
    |-- app.py          Application entry point and desktop launcher
    |-- epub_parser.py  EPUB metadata parser & content extractor
    |-- keep_awake.py   System display sleep prevention manager
    |-- multi_progress.py Multi-novel JSON progress storage manager
    |-- paths.py        Data root & progress directory finder
    |-- routes.py       Flask web application endpoints
    |-- window_manager.py Screen geometry & window positioning helpers
    |-- static/         Frontend assets (JS, CSS, icons)
    `-- templates/      HTML templates
tests/                  pytest test suite
assets/                 Static repository assets (default cover)
data/                   Sample scraped novel data (Shadow Slave)
build.bat               Windows wheel + reader.exe build script
pyproject.toml          Project metadata and dependencies
```

## Build the standalone app (Windows)

```powershell
build.bat
```

This builds the Python wheel/sdist into `dist/` and a standalone `reader.exe` via PyInstaller.

## License

MIT
