mangalib API reference

A chapter fetched with get_chapter() (or another fetching method).

The ImageServer.id to try first — see download_page().

How many pages to ask about at once.

If chapter has no pages (not fetched), server isn't one of list_image_servers(), or concurrency is less than 1.

If no server gave a page's size.

The page, from a fetched chapter's pages.

The ImageServer.id to try first (see list_image_servers()).

The image file's bytes, as the server sent them.

If server isn't one of list_image_servers().

If no server served the image.

A chapter fetched with get_chapter() (or get_chapters(), get_volume(), ...): one from get_table_of_contents() has no pages.

The ImageServer.id to try first — see download_page().

How many pages to download at once. The pacing per image host applies on top, so more than a few mostly adds waiting.

If server isn't one of list_image_servers(), or concurrency is less than 1.

If a page couldn't be downloaded from any server; the other downloads still in flight are cancelled.

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 how many there are.

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

Same as download_title(translation_index=...).

The ImageServer.id to try first — see download_page().

How many pages to ask about at once.

The estimated size in bytes, or 0 if the title has no chapter with an open

translation that branch_id/translation_index resolves.

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

Fetched chapters and/or volumes, in the order they should appear.

Export format — a key of mangalib.exporters.EXPORTERS: "cbz", and "pdf" when the pdf extra (img2pdf) is installed.

Where to write the exported file.

The ImageServer.id to try first — see download_page().

How many pages to download at once.

Called with (completed, total) after each chapter is written — the same progress hook as download_title(on_chapter=...), independent of verbosity.

If fmt isn't a registered format, there are no chapters, one of them has no pages (not fetched), server isn't one of list_image_servers(), or concurrency is less than 1 — all checked before anything is downloaded.

If a page couldn't be downloaded from any server. Nothing is written to path then.

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.

A volume fetched with get_volume()/get_volumes()/ download_title().

The ImageServer.id to try first — see download_page().

How many pages to ask about at once.

See chapter_size().

If no server gave a page's size.

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 — fetched ones, with pages.

Where to write the exported file.

Downloads one chapter's page images. The exporter calls it once per chapter, in order, so it never holds more than it has to in memory.

Called once per chapter written, if given — drives MangaLib.export()'s progress reporting.

output_path, once the file has been written.