Metadata-Version: 2.4
Name: fictionreaper
Version: 0.1.0
Summary: Download Royal Road fiction chapters as Markdown and EPUB (CLI + API)
Keywords: royal-road,web-fiction,scraper,markdown,epub,cli,fastapi
Author: Fluder-Paradyne
Author-email: Fluder-Paradyne <121793617+Fluder-Paradyne@users.noreply.github.com>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Text Processing
Classifier: Typing :: Typed
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: ebooklib>=0.20
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: lxml>=5.0
Requires-Dist: markdown>=3.10.2
Requires-Dist: pydantic>=2
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn[standard]>=0.30
Requires-Python: >=3.12
Project-URL: Changelog, https://github.com/Fluder-Paradyne/FictionReaper/releases
Project-URL: Homepage, https://github.com/Fluder-Paradyne/FictionReaper
Project-URL: Issues, https://github.com/Fluder-Paradyne/FictionReaper/issues
Project-URL: Repository, https://github.com/Fluder-Paradyne/FictionReaper
Description-Content-Type: text/markdown

# FictionReaper

Download [Royal Road](https://www.royalroad.com/) fiction as **Markdown** and/or **EPUB**.

Works on **macOS** and **Linux** (Python 3.12+). Ships a CLI and a small HTTP API.

## Install (end users)

Pick one. All put a `fictionreaper` command on your `PATH`.

### Option A — uv tool (recommended)

Install [uv](https://docs.astral.sh/uv/), then:

```bash
uv tool install git+https://github.com/Fluder-Paradyne/FictionReaper.git
fictionreaper --version
```

Upgrade later:

```bash
uv tool upgrade fictionreaper
# or reinstall from git tip:
uv tool install --force git+https://github.com/Fluder-Paradyne/FictionReaper.git
```

### Option B — pipx

```bash
pipx install git+https://github.com/Fluder-Paradyne/FictionReaper.git
fictionreaper --version
```

### Option C — pip (venv)

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install "git+https://github.com/Fluder-Paradyne/FictionReaper.git"
fictionreaper --version
```

### Option D — PyPI (after first publish)

```bash
pip install fictionreaper
# or:  uv tool install fictionreaper
# or:  pipx install fictionreaper
```

Publishing notes for maintainers: [docs/PUBLISHING.md](docs/PUBLISHING.md).

### Requirements

| | |
|--|--|
| OS | macOS or Linux |
| Python | **3.12+** (3.13 supported) |
| Network | outbound HTTPS to `royalroad.com` / CDN |

Native wheels for dependencies (`lxml`, etc.) are published for common Mac/Linux platforms; a normal install does not need a compiler in most cases.

## Quick start

```bash
# One chapter → Markdown + EPUB (default)
fictionreaper download \
  "https://www.royalroad.com/fiction/21220/mother-of-learning/chapter/301778/1-good-morning-brother"

# Whole fiction (many chapters — be polite with --delay)
fictionreaper download \
  "https://www.royalroad.com/fiction/21220/mother-of-learning" \
  --delay 1.0

# Formats
fictionreaper download "<url>" --format markdown
fictionreaper download "<url>" --format epub
fictionreaper download "<url>" --format markdown,epub
fictionreaper download "<url>" -f markdown -f epub

# Output directory
fictionreaper download "<url>" --output-dir ~/Books/rr
```

Output layout:

```text
downloads/<fiction-slug>/
  0001-chapter-slug.md
  0002-chapter-slug.md
  ...
  <fiction-slug>.epub
```

## HTTP API

```bash
fictionreaper serve --host 127.0.0.1 --port 8000
# docs: http://127.0.0.1:8000/docs
```

```bash
curl -sS -X POST 'http://127.0.0.1:8000/download' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://www.royalroad.com/fiction/21220/mother-of-learning/chapter/301778/1-good-morning-brother",
    "output_dir": "downloads",
    "delay_seconds": 1.0,
    "formats": ["markdown", "epub"]
  }'
```

## Development

```bash
git clone https://github.com/Fluder-Paradyne/FictionReaper.git
cd FictionReaper
uv sync --all-groups
uv run pytest
uv run mypy src
uv run ruff check src tests
uv build
```

## Ethics & legal

- For **personal archival / offline reading** of content you are allowed to access.
- Be polite: keep a non-zero `--delay`, don’t hammer the site.
- Respect [Royal Road’s Terms of Service](https://www.royalroad.com/) and copyright.
- Default User-Agent: `FictionReaper/0.1 (+https://github.com/Fluder-Paradyne/FictionReaper)`.

## License

MIT — see [LICENSE](LICENSE).
