# Nyora Python

> The official Python SDK, CLI and terminal reader for Nyora — build a manga, manhwa or manhua reader with ~390 working sources (of ~960 in the catalog) across 40 languages through one typed API. As of v2.1 it is self-contained: `pip install nyora` bundles the open-source Kotatsu parser engine (and auto-downloads a JRE if there's no Java), and `Nyora()` auto-launches it locally on demand — no server required, or point it at any Nyora helper via `base_url` / `nyora config set-url`. No JavaScript bridge, no OTA bundle. A programmatic Tachiyomi / Mihon / Kotatsu alternative. Adds NyoraSync cloud sync (sync.nyora.xyz) for one account shared across the whole ecosystem. Package: `nyora` (PyPI), latest 2.1.0, Apache-2.0, Python 3.10+.

Docs base: https://nyora.xyz/docs/python/

## Documentation
- [Overview](https://nyora.xyz/docs/python/index.html): What Nyora Python is and how the pieces fit.
- [Quickstart](https://nyora.xyz/docs/python/quickstart.html): Install and make your first calls (find a source, search, details, pages).
- [Library guide](https://nyora.xyz/docs/python/guide/library.html): The `nyora.Nyora` client — `sources.list()/catalog()/find()` and `manga.popular()/latest()/search()/global_search()/details()/pages()`, the typed dataclasses (Source, Manga, MangaChapter, MangaPage, MangaDetails, SearchPage), and error handling. Sync (`Nyora`) and async (`AsyncNyora`) have identical APIs.
- [Command line (nyora-cli)](https://nyora.xyz/docs/python/guide/cli.html): Full CLI manual — `sources | popular | latest | search | details | pages | download | version`; a bare `nyora` launches the TUI (`nyora-cli` alone prints help). Download chapters as `.cbz`. Add `--json` to any command.
- [Terminal UI (TUI)](https://nyora.xyz/docs/python/guide/tui.html): The interactive reader — browse, search, read, with order-independent next/previous-chapter navigation; `sync` for the account menu, `lib` for the synced library.
- [Cloud sync (NyoraSync)](https://nyora.xyz/docs/python/guide/sync.html): `nyora.sync.NyoraSync` — email + password (OAuth2 password grant + JWT) against https://sync.nyora.xyz, then last-write-wins upsert/select over per-user tables (nyora_manga, nyora_favourite, nyora_history, nyora_bookmark). Methods: `register`, `sign_in`, `sign_out`, `upsert(table, rows)`, `select(table, since)`. Tokens persist to `~/.config/nyora/sync.json`. ONE account shared across the iOS app, the TUIs and both SDKs.
- [AI agent guide](https://nyora.xyz/docs/python/guide/agents.html): Driving Nyora programmatically from an LLM agent.
- [API reference](https://nyora.xyz/docs/python/reference/api.html): Full autodoc API for every public class and function.

## Chapter ordering (order-independent navigation)
Sources list chapters oldest-first (0→N) or newest-first (N→0); these helpers make "next"/"previous" always correct regardless. Top-level functions and convenience methods on `MangaDetails`:
- `nyora.next_chapter(chapters, current)` → MangaChapter | None
- `nyora.previous_chapter(chapters, current)` → MangaChapter | None
- `nyora.reading_order(chapters)` → list, earliest first
- `nyora.chapter_reading_delta(chapters)` → +1 (ascending) or -1 (descending)
- `details.next_chapter(chapter)` / `details.previous_chapter(chapter)` / `details.reading_order()`

## Install
- `pip3 install nyora`  ·  with the TUI: `pip3 install "nyora[tui]"`

## Quickstart — a working reader
```python
import nyora
with nyora.Nyora() as client:
    source = client.sources.find("mangadex")
    hits = client.manga.search(source.id, "frieren")
    details = client.manga.details(source.id, hits.entries[0].url, title=hits.entries[0].title)
    first = details.reading_order()[0]                      # earliest chapter, order-safe
    for page in client.manga.pages(source.id, first.url, branch=first.branch):
        print(page.url)                                     # image URLs, ready to render
```

## Related
- JavaScript twin: https://nyora.xyz/docs/js/  (`npm i nyora-sdk`)
- Website & downloads: https://nyora.xyz
- Repository: https://github.com/Nyora-Manga/nyora-python
