ranobelib API reference

Translation to use for every chapter that has more than one — same meaning as get_chapter(..., branch_id=...), applied title-wide. Chapters with only one translation are unaffected. Mutually exclusive with translation_index.

Alternative to branch_id: pick the translation at this position in each ambiguous chapter's branches list (0 for the first, and so on) — useful when ambiguous chapters don't share one branch_id across the title. Mutually exclusive with branch_id.

Extra delay, in seconds, after fetching each chapter, on top of ApiClient's own per-request pacing — to be gentler on the API during a large bulk download. Defaults to no extra delay.

Called with (completed, total) after each chapter is fetched, if given — a programmatic progress hook for callers that aren't printing to a console (e.g. a web app polling/streaming download progress to a browser), who would otherwise have no way to observe anything before this whole await returns. Independent of verbosity: both can be set at once, each drives its own output.

How many extra times to retry a single chapter fetch that comes back rate-limited, on top of ApiClient's own retries, before giving up on the whole download — see above. Each retry honors the API's Retry-After if it sent one, otherwise waits with its own capped exponential backoff. Set to 0 to disable this extra layer and let a persistent RateLimitError end the download immediately (still wrapped in DownloadTitleInterruptedError with whatever was already fetched).

If both branch_id and translation_index are given.

If the title has one or more chapters with more than one translation that branch_id/translation_index didn't resolve.

If fetching a chapter fails unrecoverably partway through the download — carries every chapter already fetched.

How many chapters to sample. Clamped to the number of chapters the title actually has (or that resolve to a usable translation, see below) if that's fewer.

Forwarded to sizing.chapter_size() for each sampled chapter.

Same meaning as download_title(branch_id=...) — which translation to sample for chapters that have more than one. Mutually exclusive with translation_index.

Same meaning as download_title(translation_index=...). Mutually exclusive with branch_id.

The estimated size in bytes, or 0 if the title has no chapters, or none of

its chapters have a translation branch_id/translation_index resolves.

If both branch_id and translation_index are given, or if sample_size is less than 1.

The chapters to include, in the order they should appear.

Where to write the exported file.

Export format — a key of ranobelib.exporters.EXPORTERS (currently: "txt", "fb2", "epub", and "pdf" where WeasyPrint's native libraries are available).

If fmt isn't a registered export format.

The chapter's volume number.

The chapter number, as returned by the API — may contain a decimal (e.g. "51.6").

Which translation to fetch, as returned by get_translations(). Only required when the chapter has more than one.

Bypass the disk cache and re-fetch from the API even if a cached response is on hand.

If the chapter has more than one translation and branch_id wasn't given.

A list of (volume, number) pairs identifying each chapter.

If any requested chapter doesn't exist.

If any requested chapter has more than one translation.

Bypass the disk cache and re-fetch from the API even if a cached response is on hand.

Bypass the disk cache and re-fetch from the API even if a cached response is on hand — needed to pick up newly published chapters, since otherwise the cached chapter list would keep being reused.

The chapter's volume number.

The chapter number.

If no chapter exists for this volume/number.

The volume number.

If the title has no chapters for this volume.

If any of the volume's chapters has more than one translation.

The volume numbers to fetch.

If the title has no chapters for one of the volumes.

If any of the volumes' chapters has more than one translation.

Bypass the disk cache and re-fetch from the API even if the country list was already cached.

Every Country (id, name) that applies to site.

Bypass the disk cache and re-fetch from the API even if the genre list was already cached.

Every Genre (id, name, adult flag) that applies to site.

Bypass the disk cache and re-fetch from the API even if the status list was already cached.

Every status (Label: id, label) that applies to site.

1-based page number.

How many titles per page. Must be between MIN_PER_PAGE (10) and MAX_PER_PAGE (60) — the API's own limits (see docs/api-notes.md); anything outside that range raises here instead of a confusing 422 from the API.

Free-text search term, matched against name/rus_name/eng_name. None (the default) or an empty string lists without searching.

Genre ids to filter by. A title must have all of them, not just one (AND, not OR — see docs/api-notes.md). Not validated against list_genres() before sending — an unrecognized id just matches nothing rather than erroring.

Tag.ids (from Title.tags) to filter by. Same AND semantics as genres — a title must have all of them, not just any one (confirmed against the live API, see docs/api-notes.md; not the OR some might expect from tags being more numerous/specific than genres). Also not validated before sending, same as genres.

Title.status.ids to filter by (e.g. ongoing, completed). A title matches if its own status is any of these (OR, same as countries — a title only has one status, see docs/api-notes.md). None or an empty list applies no status filter. Ids come from list_statuses().

Country.ids to filter by. A title matches if its own country is any of these (OR, not AND like genres/tags — a title only has one country of origin, so requiring all of them could never match past the first, see docs/api-notes.md). None or an empty list applies no country filter. Ids come from list_countries(). Sent on the wire as the API's types[] parameter, not a country/countries[] one — see docs/api-notes.md for why (Country mirrors the API's own "type" concept, which isn't strictly limited to literal countries).

Only titles with at least this many chapters (inclusive). Counts the same number as Title.chapter_count (uploaded chapters). None (the default) applies no lower bound.

Only titles with at most this many chapters (inclusive). None (the default) applies no upper bound.

Sort order. Despite the name, this is sent as the API's sort_by parameter — an actual sort parameter exists but is silently ignored by the API (see docs/api-notes.md). Known accepted values: "name", "created_at", "views", "chap_count", "last_chapter_at" (the default), "rate_avg", "random" — this list isn't guaranteed exhaustive.

Bypass the disk cache and re-fetch from the API even if this exact combination of parameters was already cached.

A page_model page: the matching titles plus whether a next page exists.

If page is less than 1, per_page is outside MIN_PER_PAGE..MAX_PER_PAGE, min_chapters/max_chapters is negative, or min_chapters is greater than max_chapters.

The chapters' parent title, for metadata (name, authors, ...).

The chapters to include, in the order they should appear.

Where to write the exported file.

Called once per chapter processed, if given — drives RanobeLib.export()'s progress bar (see CLAUDE.md's roadmap step 23). For epub/pdf this covers the per-chapter embedding step, not the earlier illustration-download step, which isn't itself progress-reported.

Extra HTTP headers for any downloads the exporter makes (epub/pdf illustrations), merged over the SDK's browser-like defaults — RanobeLib.export() passes its own headers= through here. Exporters that make no requests (txt, fb2) accept and ignore it.

output_path, once the file has been written.