Metadata-Version: 2.4
Name: ndl-storykit
Version: 0.2.0
Summary: NOVELDOWNLOADER: rule-driven Chinese novel downloader and format converter
Project-URL: Homepage, https://github.com/makunxiang-cmd/project_noveldownloader
Project-URL: Repository, https://github.com/makunxiang-cmd/project_noveldownloader
Project-URL: Issues, https://github.com/makunxiang-cmd/project_noveldownloader/issues
Project-URL: Changelog, https://github.com/makunxiang-cmd/project_noveldownloader/blob/main/CHANGELOG.md
Author: makunxiang-cmd
License: MIT
License-File: LICENSE
Keywords: chinese,crawler,downloader,epub,novel
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.10
Requires-Dist: apscheduler>=3.10
Requires-Dist: ebooklib>=0.20
Requires-Dist: fastapi>=0.110
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: pydantic>=2.13.3
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=13.7
Requires-Dist: selectolax>=0.4.7
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: sse-starlette>=2.0
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn[standard]>=0.27
Provides-Extra: browser
Requires-Dist: playwright>=1.40; extra == 'browser'
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pre-commit>=3.6; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12.20260408; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.5; extra == 'docs'
Description-Content-Type: text/markdown

# NDL - NOVELDOWNLOADER

> Rule-driven Chinese novel downloader and format converter

[![CI](https://github.com/makunxiang-cmd/project_noveldownloader/actions/workflows/ci.yml/badge.svg)](https://github.com/makunxiang-cmd/project_noveldownloader/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)

[简体中文](README.zh-CN.md)

## Status

v0.1.0 is published on PyPI as `ndl-storykit`. The current source tree is back
on the next development version, `0.2.0.dev0`, after shipping the first public
release. Implemented surfaces include download, TXT/EPUB convert, library
management, search, rule updates, optional browser rendering for supported
rules, local Web UI, and auditable packaging checks. See
`docs/superpowers/SESSION-STATE.md` for the current handoff snapshot.

## What Works Now

- Validate YAML source rules with `ndl rules validate`
- Download a rule-matched static HTML site to TXT or EPUB after installing a YAML rule
- Convert local TXT files to TXT or styled EPUB
- Manage the local SQLite library with `ndl library list/show/remove`
- Refresh saved ongoing novels with `ndl update --all`
- Search rule-defined source indexes with `ndl search`
- Install validated remote YAML rules with `ndl rules update`
- Use optional Playwright-backed rendering when a rule declares `fetcher.type: browser`, including rule-defined wait/viewport controls
- Verify release wheel/sdist contents with `scripts/verify_distribution.py`
- Search, download, and trigger manual/recurring library updates from the local Web UI
- Enforce robots.txt, per-host rate limits, retries, and a first-run lawful-use disclaimer for downloads

## What It Does (Roadmap)

- Download Chinese web novels from static HTML sites, with Playwright for JS-heavy sites as an optional extra
- Convert between TXT and EPUB formats, standalone or after download
- Manage a local SQLite library and track ongoing novels for updates
- Search across multiple sites via rule-defined search endpoints
- Add new sites by writing YAML rules, not Python code
- Use either CLI or a local Web UI, both sharing the same state

## Non-Goals

NDL does not and will not:

- Support commercial platforms such as Qidian, Fanqie, Jinjiang, or Qimao
- Bypass paywalls, Cloudflare, CAPTCHAs, or DRM
- Include login/account features or proxy pools

See [`DISCLAIMER.md`](DISCLAIMER.md) for the full ethics and legal stance.

## Development Install

```bash
uv sync
uv run ndl --version
```

Optional browser-backed rules require the browser extra and a Playwright browser install:

```bash
uv sync --extra browser
uv run playwright install chromium
uv run ndl doctor browser
```

The package is published on PyPI as `ndl-storykit`. The import path inside the
package is still `ndl`, and the CLI entry point is still `ndl`:

```bash
pip install ndl-storykit
pip install 'ndl-storykit[browser]'   # with optional Playwright fetcher
```

## Usage

```bash
ndl download <url> -o book.epub --accept-disclaimer
ndl convert book.txt -o book.epub
ndl library list
ndl update --all --accept-disclaimer
ndl search "keyword"
ndl rules update --manifest-url <manifest-url>
ndl doctor browser
ndl serve --accept-disclaimer
ndl rules validate my-rule.yaml
```

## Contributing

See [`CONTRIBUTING.md`](CONTRIBUTING.md). Rule contributions are especially welcome and do not require Python.

## License

[MIT](LICENSE)
