ranobelib API reference

Entry point

ranobelib.RanobeLib

RanobeLib(
    url: str,
    *,
    cache_dir: str | Path | None = None,
    cache_ttl: float | None = None,
    verbosity: Verbosity = False,
    headers: Mapping[str, str] | None = None,
)

Bases: TitleClient[Title, Chapter, Volume]

Entry point for interacting with a single ranobelib.me title.

Example

async with RanobeLib("https://ranobelib.me/ru/book/6712--high-school-dxd-novel") as lib:
    info = await lib.get_info()

Initialize the SDK for a title.

Parameters:

Name	Type	Description	Default
url	str	A ranobelib.me title URL, or a bare {id}--{slug} identifier.	required
cache_dir	str | Path | None	Where to cache raw API responses (title metadata, chapter list, chapter content) on disk, so a repeated export or downloading newly added chapters doesn't re-fetch data already on hand. Defaults to .ranobelib_cache in the current working directory.	None
cache_ttl	float | None	Seconds after which a cached response is treated as stale and re-fetched. None (the default) means cached responses never expire on their own — see refresh=True on individual methods to force one anyway.	None
verbosity	Verbosity	Console output level. False (default): silent. "progress_only": progress bars during download_title()/export()/estimate_title_size(). "full": the same progress bars, plus a line logged for every title/ chapter-list/chapter-content fetch, noting whether it was served from the disk cache or the API.	False
headers	Mapping[str, str] | None	Extra HTTP headers merged over the SDK's defaults (browser-like Origin/Referer/User-Agent, see docs/api-notes.md, section "WAF 403") — a key given here replaces the default one, matched case-insensitively. Applied to every API request and, through export(), to epub/pdf illustration downloads. Meant for when the site's edge protection changes which requests it lets through (AccessBlockedError): send what it now expects without waiting for an SDK release. None (the default) sends the defaults as-is.	None

Source code in packages/ranobelib/src/ranobelib/sdk.py

def __init__(
    self,
    url: str,
    *,
    cache_dir: str | Path | None = None,
    cache_ttl: float | None = None,
    verbosity: Verbosity = False,
    headers: Mapping[str, str] | None = None,
) -> None:
    """Initialize the SDK for a title.

    Args:
        url: A ranobelib.me title URL, or a bare ``{id}--{slug}`` identifier.
        cache_dir: Where to cache raw API responses (title metadata, chapter list,
            chapter content) on disk, so a repeated export or downloading newly added
            chapters doesn't re-fetch data already on hand. Defaults to
            ``.ranobelib_cache`` in the current working directory.
        cache_ttl: Seconds after which a cached response is treated as stale and
            re-fetched. ``None`` (the default) means cached responses never expire on
            their own — see ``refresh=True`` on individual methods to force one anyway.
        verbosity: Console output level. ``False`` (default): silent. ``"progress_only"``:
            progress bars during ``download_title()``/``export()``/``estimate_title_size()``.
            ``"full"``: the same progress bars, plus a line logged for every title/
            chapter-list/chapter-content fetch, noting whether it was served from the
            disk cache or the API.
        headers: Extra HTTP headers merged over the SDK's defaults (browser-like
            ``Origin``/``Referer``/``User-Agent``, see docs/api-notes.md, section "WAF
            403") — a key given here replaces the default one, matched
            case-insensitively. Applied to every API request and, through ``export()``,
            to epub/pdf illustration downloads. Meant for when the site's edge protection
            changes which requests it lets through (``AccessBlockedError``): send what it
            now expects without waiting for an SDK release. ``None`` (the default) sends
            the defaults as-is.
    """
    super().__init__(
        url,
        cache_dir=cache_dir if cache_dir is not None else DEFAULT_CACHE_DIR,
        cache_ttl=cache_ttl,
        verbosity=verbosity,
        headers=headers,
    )

slug_url property

slug_url: str

The title's {id}--{slug} identifier.

aclose async

aclose() -> None

Close the underlying HTTP client.

Source code in packages/core/src/libsocial/title.py

async def aclose(self) -> None:
    """Close the underlying HTTP client."""
    await self._client.aclose()

download_title async

download_title(
    *,
    branch_id: int | None = None,
    translation_index: int | None = None,
    chapter_delay: float = 0.0,
    on_chapter: Callable[[int, int], None] | None = None,
    max_rate_limit_retries: int = DEFAULT_RATE_LIMIT_RETRIES,
) -> list[VolumeT]

Download every chapter of the title, across all its volumes.

Fetches the chapter list once, then every chapter's content, sequentially, in the API's own order — same pacing/retry/backoff as any other chapter fetch (see ApiClient), plus chapter_delay on top if given.

Resolving translations is checked for the whole title up front, not chapter by chapter: if any chapters have more than one translation, this fetches nothing and raises MultipleTitleTranslationsError listing all of them at once (unless branch_id or translation_index resolves every one of them), rather than failing partway through a long download on the first ambiguous chapter.

A long title's sequential download can outlast ApiClient's own retry budget for 429s (tuned for a single one-off request, not hundreds/thousands of sequential fetches — see docs/api-notes.md). On top of that, each chapter fetch that still comes back rate-limited is retried again here, up to max_rate_limit_retries times, with its own (coarser) backoff. If a chapter fetch still fails after that — from rate limiting or anything else — the chapters already downloaded are not discarded: they're attached to a raised DownloadTitleInterruptedError instead of being lost.

Parameters:

Name	Type	Description	Default
branch_id	int | None	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.	None
translation_index	int | None	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.	None
chapter_delay	float	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.	0.0
on_chapter	Callable[[int, int], None] | None	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.	None
max_rate_limit_retries	int	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).	DEFAULT_RATE_LIMIT_RETRIES

Raises:

Type	Description
ValueError	If both branch_id and translation_index are given.
MultipleTitleTranslationsError	If the title has one or more chapters with more than one translation that branch_id/translation_index didn't resolve.
DownloadTitleInterruptedError	If fetching a chapter fails unrecoverably partway through the download — carries every chapter already fetched.

Source code in packages/core/src/libsocial/title.py

async def download_title(
    self,
    *,
    branch_id: int | None = None,
    translation_index: int | None = None,
    chapter_delay: float = 0.0,
    on_chapter: Callable[[int, int], None] | None = None,
    max_rate_limit_retries: int = DEFAULT_RATE_LIMIT_RETRIES,
) -> list[VolumeT]:
    """Download every chapter of the title, across all its volumes.

    Fetches the chapter list once, then every chapter's content, sequentially, in the
    API's own order — same pacing/retry/backoff as any other chapter fetch (see
    ``ApiClient``), plus ``chapter_delay`` on top if given.

    Resolving translations is checked for the whole title up front, not chapter by
    chapter: if any chapters have more than one translation, this fetches nothing and
    raises ``MultipleTitleTranslationsError`` listing *all* of them at once (unless
    ``branch_id`` or ``translation_index`` resolves every one of them), rather than
    failing partway through a long download on the first ambiguous chapter.

    A long title's sequential download can outlast ``ApiClient``'s own retry budget for
    429s (tuned for a single one-off request, not hundreds/thousands of sequential
    fetches — see docs/api-notes.md). On top of that, each chapter fetch that still comes
    back rate-limited is retried again here, up to ``max_rate_limit_retries`` times, with
    its own (coarser) backoff. If a chapter fetch still fails after that — from rate
    limiting or anything else — the chapters already downloaded are not discarded: they're
    attached to a raised ``DownloadTitleInterruptedError`` instead of being lost.

    Args:
        branch_id: 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``.
        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``.
        chapter_delay: 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.
        on_chapter: 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.
        max_rate_limit_retries: 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).

    Raises:
        ValueError: If both ``branch_id`` and ``translation_index`` are given.
        MultipleTitleTranslationsError: If the title has one or more chapters with more
            than one translation that ``branch_id``/``translation_index`` didn't resolve.
        DownloadTitleInterruptedError: If fetching a chapter fails unrecoverably partway
            through the download — carries every chapter already fetched.
    """
    self._check_translation_selectors(branch_id, translation_index)
    raw_chapters = await self._get_chapters()
    planned, unresolved = self._plan_chapters(
        raw_chapters, branch_id=branch_id, translation_index=translation_index
    )
    if unresolved:
        raise MultipleTitleTranslationsError(
            self._slug_url,
            chapters=[
                AmbiguousChapter(
                    volume=item["volume"],
                    number=item["number"],
                    branches=[
                        ChapterBranch.model_validate(branch) for branch in item["branches"]
                    ],
                )
                for item in unresolved
            ],
        )

    chapters: list[ChapterT] = []
    total = len(planned)
    try:
        with self._reporter.progress(f"Downloading {self._slug_url}", total) as advance:
            for index, chapter in enumerate(planned):
                chapters.append(
                    await self._fetch_chapter_riding_out_rate_limits(
                        chapter.volume,
                        chapter.number,
                        chapter.branch_id,
                        max_rate_limit_retries=max_rate_limit_retries,
                    )
                )
                advance()
                if on_chapter is not None:
                    on_chapter(index + 1, total)
                if chapter_delay and index < total - 1:
                    await asyncio.sleep(chapter_delay)
    except LibSocialError as exc:
        raise DownloadTitleInterruptedError(
            self._slug_url,
            volumes=self._group_into_volumes(chapters),
            completed=len(chapters),
            total=total,
        ) from exc
    return self._group_into_volumes(chapters)

estimate_title_size async

estimate_title_size(
    *,
    sample_size: int = DEFAULT_SAMPLE_SIZE,
    average_image_size: int = DEFAULT_AVERAGE_IMAGE_SIZE,
    branch_id: int | None = None,
    translation_index: int | None = None,
) -> int

Estimate the whole title's download size in bytes, from a sample of its chapters.

Fetches the chapter list (cheap, cached), then the content of up to sample_size chapters spread evenly across the title — not just the first ones, since early and late chapters can differ in length — and extrapolates the sample's average sizing.chapter_size() across the title's total chapter count. This trades exactness for cost: an exact total requires fetching every chapter's content, the same cost as download_title() itself, which defeats the purpose of checking "is this worth downloading" before paying that cost.

Sampled chapters go through the same disk cache as any other chapter fetch, so a later download_title() call doesn't refetch them.

Parameters:

Name	Type	Description	Default
sample_size	int	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.	DEFAULT_SAMPLE_SIZE
average_image_size	int	Forwarded to sizing.chapter_size() for each sampled chapter.	DEFAULT_AVERAGE_IMAGE_SIZE
branch_id	int | None	Same meaning as download_title(branch_id=...) — which translation to sample for chapters that have more than one. Mutually exclusive with translation_index.	None
translation_index	int | None	Same meaning as download_title(translation_index=...). Mutually exclusive with branch_id.	None

Returns:

Type	Description
int	The estimated size in bytes, or 0 if the title has no chapters, or none of
int	its chapters have a translation branch_id/translation_index resolves.

Raises:

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

Note

Unlike download_title(), a chapter with more than one translation that branch_id/translation_index doesn't resolve is skipped when picking the sample rather than raising MultipleTitleTranslationsError — an estimate doesn't need a specific translation to be correct, only a chapter's worth of this title's content to measure.

Source code in packages/ranobelib/src/ranobelib/sdk.py

async def estimate_title_size(
    self,
    *,
    sample_size: int = DEFAULT_SAMPLE_SIZE,
    average_image_size: int = DEFAULT_AVERAGE_IMAGE_SIZE,
    branch_id: int | None = None,
    translation_index: int | None = None,
) -> int:
    """Estimate the whole title's download size in bytes, from a sample of its chapters.

    Fetches the chapter list (cheap, cached), then the content of up to ``sample_size``
    chapters spread evenly across the title — not just the first ones, since early and
    late chapters can differ in length — and extrapolates the sample's average
    ``sizing.chapter_size()`` across the title's total chapter count. This trades
    exactness for cost: an exact total requires fetching every chapter's content, the
    same cost as ``download_title()`` itself, which defeats the purpose of checking
    "is this worth downloading" *before* paying that cost.

    Sampled chapters go through the same disk cache as any other chapter fetch, so a
    later ``download_title()`` call doesn't refetch them.

    Args:
        sample_size: 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.
        average_image_size: Forwarded to ``sizing.chapter_size()`` for each sampled
            chapter.
        branch_id: Same meaning as ``download_title(branch_id=...)`` — which translation
            to sample for chapters that have more than one. Mutually exclusive with
            ``translation_index``.
        translation_index: Same meaning as ``download_title(translation_index=...)``.
            Mutually exclusive with ``branch_id``.

    Returns:
        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.

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

    Note:
        Unlike ``download_title()``, a chapter with more than one translation that
        ``branch_id``/``translation_index`` doesn't resolve is skipped when picking the
        sample rather than raising ``MultipleTitleTranslationsError`` — an estimate
        doesn't need a specific translation to be correct, only *a* chapter's worth of
        this title's content to measure.
    """
    self._check_translation_selectors(branch_id, translation_index)
    if sample_size < 1:
        raise ValueError(f"sample_size must be at least 1, got {sample_size}.")

    raw_chapters = await self._get_chapters()
    if not raw_chapters:
        return 0

    resolvable, _ = self._plan_chapters(
        raw_chapters, branch_id=branch_id, translation_index=translation_index
    )
    if not resolvable:
        return 0

    size = min(sample_size, len(resolvable))
    step = max(1, len(resolvable) // size)
    sample = [resolvable[index] for index in range(0, len(resolvable), step)][:size]

    total_sample_bytes = 0
    with self._reporter.progress(f"Sampling {self._slug_url}", len(sample)) as advance:
        for volume_str, number, selected_branch_id in sample:
            chapter = await self._fetch_chapter(volume_str, number, selected_branch_id)
            total_sample_bytes += chapter_size(chapter, average_image_size=average_image_size)
            advance()

    average_bytes = total_sample_bytes / len(sample)
    return round(average_bytes * len(raw_chapters))

export async

export(
    chapters: list[Chapter], *, fmt: str, path: str | Path
) -> Path

Export chapters to a file.

Parameters:

Name	Type	Description	Default
chapters	list[Chapter]	The chapters to include, in the order they should appear.	required
path	str | Path	Where to write the exported file.	required
fmt	str	Export format — a key of ranobelib.exporters.EXPORTERS (currently: "txt", "fb2", "epub", and "pdf" where WeasyPrint's native libraries are available).	required

Raises:

Type	Description
ValueError	If fmt isn't a registered export format.

Source code in packages/ranobelib/src/ranobelib/sdk.py

async def export(self, chapters: list[Chapter], *, fmt: str, path: str | Path) -> Path:
    """Export chapters to a file.

    Args:
        chapters: The chapters to include, in the order they should appear.
        path: Where to write the exported file.
        fmt: Export format — a key of ``ranobelib.exporters.EXPORTERS``
            (currently: ``"txt"``, ``"fb2"``, ``"epub"``, and ``"pdf"`` where
            WeasyPrint's native libraries are available).

    Raises:
        ValueError: If ``fmt`` isn't a registered export format.
    """
    exporter_cls = EXPORTERS.get(fmt)
    if exporter_cls is None:
        available = ", ".join(sorted(EXPORTERS)) or "(none registered)"
        raise ValueError(f"Unknown export format {fmt!r}. Available: {available}")
    title = await self.get_info()
    with self._reporter.progress(f"Exporting to {fmt}", len(chapters)) as advance:
        return await exporter_cls().export(
            title, chapters, Path(path), on_chapter=advance, headers=self._headers
        )

get_chapter async

get_chapter(
    volume: int,
    number: str,
    *,
    branch_id: int | None = None,
    refresh: bool = False,
) -> ChapterT

Fetch a single chapter, including its content.

When a chapter has more than one team's translation and branch_id isn't given, this raises MultipleTranslationsError rather than guessing — see get_translations() and docs/api-notes.md for why the API's own default (when branch_id is omitted) isn't relied on. Doing this check costs an extra request to fetch the chapter list, only when branch_id isn't already given.

Parameters:

Name	Type	Description	Default
volume	int	The chapter's volume number.	required
number	str	The chapter number, as returned by the API — may contain a decimal (e.g. "51.6").	required
branch_id	int | None	Which translation to fetch, as returned by get_translations(). Only required when the chapter has more than one.	None
refresh	bool	Bypass the disk cache and re-fetch from the API even if a cached response is on hand.	False

Raises:

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

Source code in packages/core/src/libsocial/title.py

async def get_chapter(
    self,
    volume: int,
    number: str,
    *,
    branch_id: int | None = None,
    refresh: bool = False,
) -> ChapterT:
    """Fetch a single chapter, including its content.

    When a chapter has more than one team's translation and ``branch_id`` isn't given,
    this raises ``MultipleTranslationsError`` rather than guessing — see
    ``get_translations()`` and docs/api-notes.md for why the API's own default (when
    ``branch_id`` is omitted) isn't relied on. Doing this check costs an extra request
    to fetch the chapter list, only when ``branch_id`` isn't already given.

    Args:
        volume: The chapter's volume number.
        number: The chapter number, as returned by the API — may contain a decimal
            (e.g. ``"51.6"``).
        branch_id: Which translation to fetch, as returned by ``get_translations()``.
            Only required when the chapter has more than one.
        refresh: Bypass the disk cache and re-fetch from the API even if a cached
            response is on hand.

    Raises:
        MultipleTranslationsError: If the chapter has more than one translation and
            ``branch_id`` wasn't given.
    """
    volume_str = str(volume)
    if branch_id is None:
        raw_chapters = await self._get_chapters(refresh=refresh)
        branch_id = self._resolve_branch_id(volume_str, number, raw_chapters)
    return await self._fetch_chapter(volume_str, number, branch_id, refresh=refresh)

get_chapters async

get_chapters(
    chapters: list[tuple[int, str]],
) -> list[ChapterT]

Fetch several chapters, including their content.

Fetches the chapter list once, shared across all requested chapters (also used to detect chapters with more than one translation — see get_chapter), then each chapter individually and sequentially, in the order given.

Parameters:

Name	Type	Description	Default
chapters	list[tuple[int, str]]	A list of (volume, number) pairs identifying each chapter.	required

Raises:

Type	Description
ChapterNotFoundError	If any requested chapter doesn't exist.
MultipleTranslationsError	If any requested chapter has more than one translation.

Source code in packages/core/src/libsocial/title.py

async def get_chapters(self, chapters: list[tuple[int, str]]) -> list[ChapterT]:
    """Fetch several chapters, including their content.

    Fetches the chapter list once, shared across all requested chapters (also used to
    detect chapters with more than one translation — see ``get_chapter``), then each
    chapter individually and sequentially, in the order given.

    Args:
        chapters: A list of ``(volume, number)`` pairs identifying each chapter.

    Raises:
        ChapterNotFoundError: If any requested chapter doesn't exist.
        MultipleTranslationsError: If any requested chapter has more than one
            translation.
    """
    raw_chapters = await self._get_chapters()
    result = []
    for volume, number in chapters:
        volume_str = str(volume)
        branch_id = self._resolve_branch_id(volume_str, number, raw_chapters)
        result.append(await self._fetch_chapter(volume_str, number, branch_id))
    return result

get_info async

get_info(*, refresh: bool = False) -> TitleT

Fetch title metadata: names, cover, summary, genres, tags, authors, teams.

Parameters:

Name	Type	Description	Default
refresh	bool	Bypass the disk cache and re-fetch from the API even if a cached response is on hand.	False

Source code in packages/core/src/libsocial/title.py

async def get_info(self, *, refresh: bool = False) -> TitleT:
    """Fetch title metadata: names, cover, summary, genres, tags, authors, teams.

    Args:
        refresh: Bypass the disk cache and re-fetch from the API even if a cached
            response is on hand.
    """
    data = await self._get_title(refresh=refresh)
    return self.title_model.model_validate(data)

get_table_of_contents async

get_table_of_contents(
    *, refresh: bool = False
) -> list[VolumeT]

Fetch the title's volumes and chapter names/numbers, without chapter content.

Parameters:

Name	Type	Description	Default
refresh	bool	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.	False

Source code in packages/core/src/libsocial/title.py

async def get_table_of_contents(self, *, refresh: bool = False) -> list[VolumeT]:
    """Fetch the title's volumes and chapter names/numbers, without chapter content.

    Args:
        refresh: 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.
    """
    raw_chapters = await self._get_chapters(refresh=refresh)
    chapters = [self.chapter_model.model_validate(item) for item in raw_chapters]
    return self._group_into_volumes(chapters)

get_translations async

get_translations(
    volume: int, number: str
) -> list[ChapterBranch]

Fetch the available translations (branches) for a chapter.

Parameters:

Name	Type	Description	Default
volume	int	The chapter's volume number.	required
number	str	The chapter number.	required

Raises:

Type	Description
ChapterNotFoundError	If no chapter exists for this volume/number.

Source code in packages/core/src/libsocial/title.py

async def get_translations(self, volume: int, number: str) -> list[ChapterBranch]:
    """Fetch the available translations (branches) for a chapter.

    Args:
        volume: The chapter's volume number.
        number: The chapter number.

    Raises:
        ChapterNotFoundError: If no chapter exists for this volume/number.
    """
    volume_str = str(volume)
    raw_chapters = await self._get_chapters()
    item = _find_raw_chapter(raw_chapters, volume_str, number)
    if item is None:
        raise ChapterNotFoundError(self._slug_url, volume=volume_str, number=number)
    return [ChapterBranch.model_validate(branch) for branch in item.get("branches") or []]

get_volume async

get_volume(volume: int) -> VolumeT

Fetch a whole volume: all its chapters, each including content.

The API has no bulk "volume content" endpoint (see docs/api-notes.md), so this fetches the chapter list once to find which numbers belong to the volume, then fetches each of those chapters individually and sequentially.

Parameters:

Name	Type	Description	Default
volume	int	The volume number.	required

Raises:

Type	Description
VolumeNotFoundError	If the title has no chapters for this volume.
MultipleTranslationsError	If any of the volume's chapters has more than one translation.

Source code in packages/core/src/libsocial/title.py

async def get_volume(self, volume: int) -> VolumeT:
    """Fetch a whole volume: all its chapters, each including content.

    The API has no bulk "volume content" endpoint (see docs/api-notes.md), so this
    fetches the chapter list once to find which numbers belong to the volume, then
    fetches each of those chapters individually and sequentially.

    Args:
        volume: The volume number.

    Raises:
        VolumeNotFoundError: If the title has no chapters for this volume.
        MultipleTranslationsError: If any of the volume's chapters has more than one
            translation.
    """
    raw_chapters = await self._get_chapters()
    return await self._build_volume(volume, raw_chapters)

get_volumes async

get_volumes(volumes: list[int]) -> list[VolumeT]

Fetch several whole volumes, each including chapter content.

Fetches the chapter list once, shared across all requested volumes, then each chapter individually and sequentially — same approach as get_volume, applied to more than one volume without re-fetching the chapter list per volume.

Parameters:

Name	Type	Description	Default
volumes	list[int]	The volume numbers to fetch.	required

Raises:

Type	Description
VolumeNotFoundError	If the title has no chapters for one of the volumes.
MultipleTranslationsError	If any of the volumes' chapters has more than one translation.

Source code in packages/core/src/libsocial/title.py

async def get_volumes(self, volumes: list[int]) -> list[VolumeT]:
    """Fetch several whole volumes, each including chapter content.

    Fetches the chapter list once, shared across all requested volumes, then each
    chapter individually and sequentially — same approach as ``get_volume``, applied
    to more than one volume without re-fetching the chapter list per volume.

    Args:
        volumes: The volume numbers to fetch.

    Raises:
        VolumeNotFoundError: If the title has no chapters for one of the volumes.
        MultipleTranslationsError: If any of the volumes' chapters has more than one
            translation.
    """
    raw_chapters = await self._get_chapters()
    return [await self._build_volume(volume, raw_chapters) for volume in volumes]

ranobelib.Catalog

Catalog(
    *,
    cache_dir: str | Path | None = None,
    cache_ttl: float | None = None,
    headers: Mapping[str, str] | None = None,
)

Bases: Catalog[Title]

Entry point for listing/searching the ranobelib.me catalog.

Lists titles (list_titles()) and the filter options for them (list_genres(), list_countries(), list_statuses()), each filtered to ranobelib.me.

Example

async with Catalog() as catalog:
    page = await catalog.list_titles(query="dxd", genres=[34], statuses=[1])
    for title in page.items:
        print(title.name)

Initialize the catalog client.

Parameters:

Name	Type	Description	Default
cache_dir	str | Path | None	Where to cache raw API responses on disk, one entry per distinct set of listing parameters (page/filters/sort) — same disk cache as RanobeLib uses, just keyed by listing parameters instead of a title's slug. Defaults to .ranobelib_cache in the current working directory.	None
cache_ttl	float | None	Seconds after which a cached page is treated as stale and re-fetched. None (the default) means cached pages never expire on their own — see refresh=True on list_titles() to force one anyway.	None
headers	Mapping[str, str] | None	Extra HTTP headers merged over the SDK's defaults, same as RanobeLib(headers=...) — see there.	None

Source code in packages/ranobelib/src/ranobelib/catalog.py

def __init__(
    self,
    *,
    cache_dir: str | Path | None = None,
    cache_ttl: float | None = None,
    headers: Mapping[str, str] | None = None,
) -> None:
    """Initialize the catalog client.

    Args:
        cache_dir: Where to cache raw API responses on disk, one entry per distinct set
            of listing parameters (page/filters/sort) — same disk cache as ``RanobeLib``
            uses, just keyed by listing parameters instead of a title's slug. Defaults
            to ``.ranobelib_cache`` in the current working directory.
        cache_ttl: Seconds after which a cached page is treated as stale and re-fetched.
            ``None`` (the default) means cached pages never expire on their own — see
            ``refresh=True`` on ``list_titles()`` to force one anyway.
        headers: Extra HTTP headers merged over the SDK's defaults, same as
            ``RanobeLib(headers=...)`` — see there.
    """
    super().__init__(
        cache_dir=cache_dir if cache_dir is not None else DEFAULT_CACHE_DIR,
        cache_ttl=cache_ttl,
        headers=headers,
    )

aclose async

aclose() -> None

Close the underlying HTTP client.

Source code in packages/core/src/libsocial/catalog.py

async def aclose(self) -> None:
    """Close the underlying HTTP client."""
    await self._client.aclose()

list_countries async

list_countries(*, refresh: bool = False) -> list[Country]

Fetch the full list of catalog countries (id → name), for use as filter options with list_titles(countries=...).

Mirrors list_genres() exactly, down to the network-wide, not-site-scoped shape of the underlying endpoint (GET /api/constants?fields[]=types — the API's own name for what this SDK calls "country" is "type", see docs/api-notes.md and Country's docstring). This filters that down to entries tagged for site before returning, same as list_genres() does for genres.

Parameters:

Name	Type	Description	Default
refresh	bool	Bypass the disk cache and re-fetch from the API even if the country list was already cached.	False

Returns:

Type	Description
list[Country]	Every Country (id, name) that applies to site.

Source code in packages/core/src/libsocial/catalog.py

async def list_countries(self, *, refresh: bool = False) -> list[Country]:
    """Fetch the full list of catalog countries (id → name), for use as filter options
    with ``list_titles(countries=...)``.

    Mirrors ``list_genres()`` exactly, down to the network-wide, not-site-scoped shape
    of the underlying endpoint (``GET /api/constants?fields[]=types`` — the API's own
    name for what this SDK calls "country" is "type", see docs/api-notes.md and
    ``Country``'s docstring). This filters that down to entries tagged for ``site`` before
    returning, same as ``list_genres()`` does for genres.

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

    Returns:
        Every ``Country`` (id, name) that applies to ``site``.
    """
    key = "catalog:countries"
    if not refresh:
        cached = self._cache.get(key)
        if cached is not None:
            return _for_site(Country, cached, self.site)

    data = await self._client.list_countries()
    self._cache.set(key, data)
    return _for_site(Country, data, self.site)

list_genres async

list_genres(*, refresh: bool = False) -> list[Genre]

Fetch the full list of catalog genres (id → name), for use as filter options with list_titles(genres=[...]).

The underlying endpoint (GET /api/constants?fields[]=genres) has no site-scoping parameter — it returns the full genre list shared across the whole lib.social network in one shot, each tagged with the site ids it applies to (see docs/api-notes.md). This filters that down to genres tagged for site before returning, so callers don't get filter options that could never match any of the site's titles (e.g. "Детское", tagged only for site 5, on ranobelib.me).

Parameters:

Name	Type	Description	Default
refresh	bool	Bypass the disk cache and re-fetch from the API even if the genre list was already cached.	False

Returns:

Type	Description
list[Genre]	Every Genre (id, name, adult flag) that applies to site.

Source code in packages/core/src/libsocial/catalog.py

async def list_genres(self, *, refresh: bool = False) -> list[Genre]:
    """Fetch the full list of catalog genres (id → name), for use as filter options
    with ``list_titles(genres=[...])``.

    The underlying endpoint (``GET /api/constants?fields[]=genres``) has no site-scoping
    parameter — it returns the full genre list shared across the whole lib.social
    network in one shot, each tagged with the site ids it applies to (see
    docs/api-notes.md). This filters that down to genres tagged for ``site`` before
    returning, so callers don't get filter options that could never match any of the
    site's titles (e.g. "Детское", tagged only for site 5, on ranobelib.me).

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

    Returns:
        Every ``Genre`` (id, name, adult flag) that applies to ``site``.
    """
    # No site in the key, unlike list_titles(): the response is the whole network's
    # list, and _for_site() filters it on every read, cached or not.
    key = "catalog:genres"
    if not refresh:
        cached = self._cache.get(key)
        if cached is not None:
            return _for_site(Genre, cached, self.site)

    data = await self._client.list_genres()
    self._cache.set(key, data)
    return _for_site(Genre, data, self.site)

list_statuses async

list_statuses(*, refresh: bool = False) -> list[Label]

Fetch the full list of title statuses (id → label), for use as filter options with list_titles(statuses=...).

Mirrors list_genres()/list_countries(): the underlying endpoint (GET /api/constants?fields[]=status) isn't site-scoped, so entries not tagged for site are dropped before returning (see docs/api-notes.md). Returns the same Label model as Title.status, so a title's status can be compared against these directly.

Parameters:

Name	Type	Description	Default
refresh	bool	Bypass the disk cache and re-fetch from the API even if the status list was already cached.	False

Returns:

Type	Description
list[Label]	Every status (Label: id, label) that applies to site.

Source code in packages/core/src/libsocial/catalog.py

async def list_statuses(self, *, refresh: bool = False) -> list[Label]:
    """Fetch the full list of title statuses (id → label), for use as filter options
    with ``list_titles(statuses=...)``.

    Mirrors ``list_genres()``/``list_countries()``: the underlying endpoint
    (``GET /api/constants?fields[]=status``) isn't site-scoped, so entries not tagged for
    ``site`` are dropped before returning (see docs/api-notes.md). Returns the same
    ``Label`` model as ``Title.status``, so a title's status can be compared against
    these directly.

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

    Returns:
        Every status (``Label``: id, label) that applies to ``site``.
    """
    key = "catalog:statuses"
    if not refresh:
        cached = self._cache.get(key)
        if cached is not None:
            return _for_site(Label, cached, self.site)

    data = await self._client.list_statuses()
    self._cache.set(key, data)
    return _for_site(Label, data, self.site)

list_titles async

list_titles(
    *,
    page: int = 1,
    per_page: int = 30,
    query: str | None = None,
    genres: list[int] | None = None,
    tags: list[int] | None = None,
    statuses: list[int] | None = None,
    countries: list[int] | None = None,
    min_chapters: int | None = None,
    max_chapters: int | None = None,
    sort: str = DEFAULT_SORT,
    refresh: bool = False,
) -> CatalogPage[TitleT]

Fetch one page of catalog listing/search results.

Parameters:

Name	Type	Description	Default
page	int	1-based page number.	1
per_page	int	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.	30
query	str | None	Free-text search term, matched against name/rus_name/eng_name. None (the default) or an empty string lists without searching.	None
genres	list[int] | None	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.	None
tags	list[int] | None	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.	None
statuses	list[int] | None	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().	None
countries	list[int] | None	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).	None
min_chapters	int | None	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.	None
max_chapters	int | None	Only titles with at most this many chapters (inclusive). None (the default) applies no upper bound.	None
sort	str	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.	DEFAULT_SORT
refresh	bool	Bypass the disk cache and re-fetch from the API even if this exact combination of parameters was already cached.	False

Returns:

Type	Description
CatalogPage[TitleT]	A page_model page: the matching titles plus whether a next page exists.

Raises:

Type	Description
ValueError	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.

Source code in packages/core/src/libsocial/catalog.py

async def list_titles(
    self,
    *,
    page: int = 1,
    per_page: int = 30,
    query: str | None = None,
    genres: list[int] | None = None,
    tags: list[int] | None = None,
    statuses: list[int] | None = None,
    countries: list[int] | None = None,
    min_chapters: int | None = None,
    max_chapters: int | None = None,
    sort: str = DEFAULT_SORT,
    refresh: bool = False,
) -> CatalogPage[TitleT]:
    """Fetch one page of catalog listing/search results.

    Args:
        page: 1-based page number.
        per_page: 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.
        query: Free-text search term, matched against name/rus_name/eng_name. ``None``
            (the default) or an empty string lists without searching.
        genres: 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.
        tags: ``Tag.id``s (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``.
        statuses: ``Title.status.id``s 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()``.
        countries: ``Country.id``s 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).
        min_chapters: 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.
        max_chapters: Only titles with at most this many chapters (inclusive). ``None``
            (the default) applies no upper bound.
        sort: 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.
        refresh: Bypass the disk cache and re-fetch from the API even if this exact
            combination of parameters was already cached.

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

    Raises:
        ValueError: 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``.
    """
    if page < 1:
        raise ValueError(f"page must be at least 1, got {page}.")
    if not MIN_PER_PAGE <= per_page <= MAX_PER_PAGE:
        raise ValueError(
            f"per_page must be between {MIN_PER_PAGE} and {MAX_PER_PAGE}, got {per_page}."
        )
    for name, value in (("min_chapters", min_chapters), ("max_chapters", max_chapters)):
        if value is not None and value < 0:
            raise ValueError(f"{name} must be at least 0, got {value}.")
    if min_chapters is not None and max_chapters is not None and min_chapters > max_chapters:
        # The API itself silently swaps the bounds instead (see docs/api-notes.md) —
        # raising here rather than relying on that undocumented behavior.
        raise ValueError(
            f"min_chapters ({min_chapters}) must not be greater than "
            f"max_chapters ({max_chapters})."
        )

    key = _cache_key(
        site_id=self.site.id,
        page=page,
        per_page=per_page,
        query=query,
        genres=genres,
        tags=tags,
        statuses=statuses,
        countries=countries,
        min_chapters=min_chapters,
        max_chapters=max_chapters,
        sort=sort,
    )
    if not refresh:
        cached = self._cache.get(key)
        if cached is not None:
            return self._build_page(cached)

    data = await self._client.list_titles(
        page=page,
        per_page=per_page,
        query=query,
        genres=genres,
        tags=tags,
        statuses=statuses,
        countries=countries,
        min_chapters=min_chapters,
        max_chapters=max_chapters,
        sort=sort,
    )
    self._cache.set(key, data)
    return self._build_page(data)

Models

ranobelib.CatalogPage

Bases: CatalogPage[Title]

One page of catalog listing/search results, as returned by Catalog.list_titles().

items reuses Title as-is — a catalog list item has every field Title requires, the ones it doesn't send (genres, summary, chapter_count, last_chapter_at, ...) just come back at their defaults, same as any other partially-populated Title (see docs/api-notes.md).

ranobelib.Title

Bases: Title

Metadata for a single title (novel).

base_names property

base_names: list[str]

The title's names without the format suffix ranobelib.me appends to them.

rus_name, eng_name, name and other_names, in that order, each with trailing publication-format markers removed — "Старшая школа D×D (Новелла)" → "Старшая школа D×D", likewise (Novel), (LN), (WN), (Light Novel), (Ранобэ), [квест], ... (stacked ones too, (LN) (Novel)). Other bracketed tails — a year, (18+), (Фанфик), [LitRPG], a franchise name — distinguish one title from another and are kept. Whitespace is trimmed; empty names and duplicates (keeping the first) are dropped. Nothing else is normalized (case, punctuation, ×): that's up to whatever compares the names.

The original fields are left as they are. On Catalog.list_titles() items other_names is empty (the listing doesn't return it), so it contributes nothing.

chapter_count class-attribute instance-attribute

chapter_count: int | None = None

Number of uploaded chapters. Only TitleClient.get_info() fills it in: the catalog listing endpoint doesn't return it (see docs/api-notes.md), so it's None on Catalog.list_titles() items.

last_chapter_at class-attribute instance-attribute

last_chapter_at: datetime | None = Field(
    default=None, alias="last_item_at"
)

When the most recent chapter was published — the value the catalog's sort="last_chapter_at" orders by. Only TitleClient.get_info() fills it in: the catalog listing endpoint doesn't return it (see docs/api-notes.md), so it's None on Catalog.list_titles() items, and on a title with no chapters yet.

ranobelib.Chapter

Bases: Chapter

A chapter: volume, number, name, available translations, and optionally its content.

index/item_number/branches_count/branches come from the chapter-list endpoint (see RanobeLib.get_table_of_contents()) and are None/empty when a Chapter instead comes from fetching a single chapter's content, which has a different response shape (see docs/api-notes.md). content is the reverse: only populated by the single-chapter endpoint.

footnotes holds the chapter's translator footnotes (see Footnote), which are removed from content rather than kept in both places — empty when the chapter has none, or when content isn't fetched.

ranobelib.Footnote

Bases: BaseModel

A translator footnote (term explanation, translation note) taken out of a chapter.

The API has no structured footnotes (see docs/api-notes.md): they're ordinary paragraphs/list items whose text starts with ↑, so that arrow is what the SDK detects them by — and strips from content. There's no marker linking a footnote back to a point in the text: translators mark the reference with an unnumbered * at best, which the text also uses for scene breaks and censored words, so Chapter.footnotes's order (the order they appear in the source) is the only link there is.

content instance-attribute

content: str

Sanitized inline HTML (same tag vocabulary as Chapter.content), without the arrow and without a wrapping <p>.

ranobelib.Volume

Bases: Volume[Chapter]

A volume: its number and the chapters it contains, in title order.

ranobelib.ChapterBranch

Bases: BaseModel

A single team's (or solo uploader's) translation of a chapter.

A chapter has more than one branch when several teams have translated it independently; see Chapter.branches_count.

ranobelib.Genre

Bases: BaseModel

A genre tag (e.g. Fantasy, Romance).

ranobelib.Country

Bases: BaseModel

A title's country/region of origin.

Maps onto what the raw API itself calls "type" (Title's raw type field; the catalog filter's types[] parameter; GET /api/constants?fields[]=types) — not a country/countries[]/fields[]=countries concept, which turned out to be something unrelated (see docs/api-notes.md). The values aren't all literal countries: on ranobelib.me, Japan, Korea and China sit next to original English-language work, original web novel and fanfiction, all surfaced as-is.

ranobelib.Label

Bases: BaseModel

A small {id, label} enum value used throughout the API (status, age rating, ...).

Exceptions

ranobelib.RanobeLibError module-attribute

RanobeLibError = LibSocialError

Base class for all errors raised by the SDK (libsocial.LibSocialError).

ranobelib.TitleNotFoundError

TitleNotFoundError(slug_url: str)

Bases: LibSocialError

Raised when a title cannot be found on the site.

Attributes:

Name	Type	Description
slug_url		The title's {id}--{slug} identifier that couldn't be found.

Source code in packages/core/src/libsocial/exceptions.py

def __init__(self, slug_url: str) -> None:
    self.slug_url = slug_url
    super().__init__(f"Title not found: {slug_url!r}")

ranobelib.ChapterNotFoundError

ChapterNotFoundError(
    slug_url: str, *, volume: str, number: str
)

Bases: LibSocialError

Raised when a chapter cannot be found for a given volume/number.

Attributes:

Name	Type	Description
slug_url		The title's {id}--{slug} identifier.
volume		The volume number that was requested.
number		The chapter number that was requested.

Source code in packages/core/src/libsocial/exceptions.py

def __init__(self, slug_url: str, *, volume: str, number: str) -> None:
    self.slug_url = slug_url
    self.volume = volume
    self.number = number
    super().__init__(f"Chapter not found: {slug_url!r} volume={volume!r} number={number!r}")

ranobelib.VolumeNotFoundError

VolumeNotFoundError(slug_url: str, *, volume: str)

Bases: LibSocialError

Raised when a title has no chapters for a given volume number.

Attributes:

Name	Type	Description
slug_url		The title's {id}--{slug} identifier.
volume		The volume number that was requested.

Source code in packages/core/src/libsocial/exceptions.py

def __init__(self, slug_url: str, *, volume: str) -> None:
    self.slug_url = slug_url
    self.volume = volume
    super().__init__(f"Volume not found: {slug_url!r} volume={volume!r}")

ranobelib.MultipleTranslationsError

MultipleTranslationsError(
    slug_url: str,
    *,
    volume: str,
    number: str,
    branches: list[ChapterBranch],
)

Bases: LibSocialError

Raised when a chapter has more than one team's translation and none was selected.

The SDK does not guess a default: the API's own default when branch_id is omitted is not simply the first branch listed, and the actual rule it uses isn't documented (see docs/api-notes.md) — returning it silently would be unpredictable. Call TitleClient.get_translations() to list the available branches, then pass one's branch_id explicitly.

Attributes:

Name	Type	Description
slug_url		The title's {id}--{slug} identifier.
volume		The chapter's volume number.
number		The chapter number.
branches		The chapter's available translations, as returned by TitleClient.get_translations().

Source code in packages/core/src/libsocial/exceptions.py

def __init__(
    self, slug_url: str, *, volume: str, number: str, branches: list[ChapterBranch]
) -> None:
    self.slug_url = slug_url
    self.volume = volume
    self.number = number
    self.branches = branches
    options = ", ".join(
        f"branch_id={branch.branch_id} ({_describe_branch(branch)})" for branch in branches
    )
    super().__init__(
        f"Multiple translations for {slug_url!r} volume={volume!r} number={number!r}: "
        f"{options}. Pass branch_id to select one (see get_translations())."
    )

ranobelib.MultipleTitleTranslationsError

MultipleTitleTranslationsError(
    slug_url: str, *, chapters: list[AmbiguousChapter]
)

Bases: LibSocialError

Raised by download_title() when one or more chapters have an unresolved translation.

Unlike MultipleTranslationsError (one chapter), this can list several: a title-wide bulk download checks every chapter up front rather than stopping at the first ambiguous one, so a caller doesn't have to fix one chapter, rerun, hit the next, and rerun again. Pass branch_id or translation_index to download_title() to resolve them, or fetch the listed chapters individually with get_chapter(..., branch_id=...).

Attributes:

Name	Type	Description
slug_url		The title's {id}--{slug} identifier.
chapters		The ambiguous chapters and their available translations.

Source code in packages/core/src/libsocial/exceptions.py

def __init__(self, slug_url: str, *, chapters: list[AmbiguousChapter]) -> None:
    self.slug_url = slug_url
    self.chapters = chapters
    lines = [
        f"  volume={chapter.volume!r} number={chapter.number!r}: "
        + ", ".join(
            f"branch_id={branch.branch_id} ({_describe_branch(branch)})"
            for branch in chapter.branches
        )
        for chapter in chapters
    ]
    super().__init__(
        f"{len(chapters)} chapter(s) in {slug_url!r} have more than one translation "
        "unresolved by the given branch_id/translation_index. Pass branch_id or "
        "translation_index to download_title() to select one for every chapter listed, "
        "or fetch them individually with get_chapter(..., branch_id=...):\n" + "\n".join(lines)
    )

ranobelib.AuthRequiredError

AuthRequiredError(url: str)

Bases: LibSocialError

Raised when the requested content requires authorization (paid or early access).

Attributes:

Name	Type	Description
url		The request URL that returned 403.

Source code in packages/core/src/libsocial/exceptions.py

def __init__(self, url: str) -> None:
    self.url = url
    super().__init__(f"Authorization required to access: {url}")

ranobelib.AccessBlockedError

AccessBlockedError(
    url: str, *, headers_hint: str = DEFAULT_HEADERS_HINT
)

Bases: LibSocialError

Raised when the site's edge protection rejects a request before it reaches the API.

Not an authorization problem, unlike AuthRequiredError: the DDoS-Guard edge in front of api.cdnlibs.org answers with an HTML 403 page (the API's own 403 is JSON) when it doesn't like the request — so far, a missing or empty Referer (see docs/api-notes.md, section "WAF 403"). The SDK already sends browser-like headers, so seeing this means either the edge changed its rules — check for an SDK update, or send what it now expects via headers= on the title client/Catalog (or ApiClient, if using it directly) — or the edge is blocking the network/IP itself, which no header fixes. Not retried: resending the same request gets the same answer.

Attributes:

Name	Type	Description
url		The request URL that returned 403.

Initialize the error.

Parameters:

Name	Type	Description	Default
url	str	The request URL that returned 403.	required
headers_hint	str	Where to pass different headers, as the message suggests it — a site package names its own entry points (see ApiClient.headers_hint).	DEFAULT_HEADERS_HINT

Source code in packages/core/src/libsocial/exceptions.py

def __init__(self, url: str, *, headers_hint: str = DEFAULT_HEADERS_HINT) -> None:
    """Initialize the error.

    Args:
        url: The request URL that returned 403.
        headers_hint: Where to pass different headers, as the message suggests it — a
            site package names its own entry points (see ``ApiClient.headers_hint``).
    """
    self.url = url
    super().__init__(
        f"Request blocked by the site's protection (not an authorization issue): {url}. "
        "The site may have changed which requests it accepts: check for an SDK update, "
        f"or send different headers via {headers_hint}. "
        "If the same URL doesn't open in a browser on this network "
        "either, the IP itself is blocked and no header change will help."
    )

ranobelib.RateLimitError

RateLimitError(retry_after: float | None = None)

Bases: LibSocialError

Raised when the API responds with 429 Too Many Requests.

Attributes:

Name	Type	Description
retry_after		The response's Retry-After value, in seconds, if it sent one.

Source code in packages/core/src/libsocial/exceptions.py

def __init__(self, retry_after: float | None = None) -> None:
    self.retry_after = retry_after
    suffix = f" (retry after {retry_after}s)" if retry_after is not None else ""
    super().__init__(f"Rate limited by the API{suffix}")

ranobelib.DownloadTitleInterruptedError

DownloadTitleInterruptedError(
    slug_url: str,
    *,
    volumes: Sequence[Volume[Any]],
    completed: int,
    total: int,
)

Bases: LibSocialError

Raised by download_title() when a chapter fetch fails unrecoverably partway through.

download_title() fetches hundreds-to-thousands of chapters sequentially for a long title, which can outlast even the extra, bulk-specific rate-limit retry budget described in download_title()'s max_rate_limit_retries — or hit some other unrecoverable error (e.g. AuthRequiredError on a chapter that turns out to need a paywall/auth token). Rather than letting that error propagate on its own and silently discard every chapter already fetched, it's wrapped in this exception instead, carrying what was already downloaded — so a caller can keep that partial result, or simply call download_title() again: the SDK's disk cache means already-fetched chapters aren't re-requested, so a retry resumes close to where this one stopped rather than restarting the whole title. See docs/api-notes.md's "Rate limiting и retry" section and issue #41.

Attributes:

Name	Type	Description
slug_url		The title's {id}--{slug} identifier.
volumes	list[Volume[Any]]	Chapters fetched before the failure, grouped into volumes the same way a successful download_title() call would return them.
completed		How many chapters were fetched before the failure.
total		How many chapters download_title() had planned to fetch in total.

Source code in packages/core/src/libsocial/exceptions.py

def __init__(
    self, slug_url: str, *, volumes: Sequence[Volume[Any]], completed: int, total: int
) -> None:
    self.slug_url = slug_url
    self.volumes: list[Volume[Any]] = list(volumes)
    self.completed = completed
    self.total = total
    super().__init__(
        f"download_title() for {slug_url!r} was interrupted after {completed}/{total} "
        "chapter(s) fetched — see __cause__ for why, .volumes for what was already fetched."
    )

Cache maintenance

ranobelib.cache_stats

cache_stats(
    cache_dir: str | Path = DEFAULT_CACHE_DIR,
) -> CacheStats

Count the entries in an SDK disk cache and their total size on disk.

Only files the cache itself writes are counted, not anything else that happens to be in the directory.

Parameters:

Name	Type	Description	Default
cache_dir	str | Path	The cache directory — the same cache_dir passed to RanobeLib / Catalog (default: theirs, .ranobelib_cache in the current directory).	DEFAULT_CACHE_DIR

Returns:

Type	Description
CacheStats	The number of entries and their total size in bytes. A missing directory is an empty
CacheStats	cache, CacheStats(entries=0, bytes=0), not an error.

Source code in packages/ranobelib/src/ranobelib/cache.py

def cache_stats(cache_dir: str | Path = DEFAULT_CACHE_DIR) -> CacheStats:
    """Count the entries in an SDK disk cache and their total size on disk.

    Only files the cache itself writes are counted, not anything else that happens to be in
    the directory.

    Args:
        cache_dir: The cache directory — the same ``cache_dir`` passed to ``RanobeLib`` /
            ``Catalog`` (default: theirs, ``.ranobelib_cache`` in the current directory).

    Returns:
        The number of entries and their total size in bytes. A missing directory is an empty
        cache, ``CacheStats(entries=0, bytes=0)``, not an error.
    """
    return _core.cache_stats(cache_dir)

ranobelib.clear_cache

clear_cache(
    cache_dir: str | Path = DEFAULT_CACHE_DIR,
    *,
    older_than: float | None = None,
) -> CacheStats

Remove entries from an SDK disk cache.

Only files the cache itself writes are removed — anything else in the directory, and the directory itself, is left alone. Safe to call while clients are using the same cache: an entry being read as it's removed is just a cache miss, and one written after it's removed is simply recreated.

Parameters:

Name	Type	Description	Default
cache_dir	str | Path	The cache directory — see cache_stats().	DEFAULT_CACHE_DIR
older_than	float | None	If given, only remove entries written more than this many seconds ago (the same age check cache_ttl uses), plus any corrupted entry, which the cache can't serve anyway. None (the default) removes every entry.	None

Returns:

Type	Description
CacheStats	The number of entries removed and the bytes they took. A missing directory removes
CacheStats	nothing, CacheStats(entries=0, bytes=0), rather than raising.

Raises:

Type	Description
ValueError	If older_than is negative.

Source code in packages/ranobelib/src/ranobelib/cache.py

def clear_cache(
    cache_dir: str | Path = DEFAULT_CACHE_DIR, *, older_than: float | None = None
) -> CacheStats:
    """Remove entries from an SDK disk cache.

    Only files the cache itself writes are removed — anything else in the directory, and the
    directory itself, is left alone. Safe to call while clients are using the same cache: an
    entry being read as it's removed is just a cache miss, and one written after it's
    removed is simply recreated.

    Args:
        cache_dir: The cache directory — see ``cache_stats()``.
        older_than: If given, only remove entries written more than this many seconds ago
            (the same age check ``cache_ttl`` uses), plus any corrupted entry, which the
            cache can't serve anyway. ``None`` (the default) removes every entry.

    Returns:
        The number of entries removed and the bytes they took. A missing directory removes
        nothing, ``CacheStats(entries=0, bytes=0)``, rather than raising.

    Raises:
        ValueError: If ``older_than`` is negative.
    """
    return _core.clear_cache(cache_dir, older_than=older_than)

ranobelib.CacheStats dataclass

CacheStats(entries: int, bytes: int)

How many cache entries there are (or were removed), and their total size on disk.

Sizing

ranobelib.chapter_size

chapter_size(
    chapter: Chapter,
    *,
    average_image_size: int = DEFAULT_AVERAGE_IMAGE_SIZE,
) -> int

Estimate a fetched chapter's size in bytes: exact text plus assumed-average images.

Parameters:

Name	Type	Description	Default
chapter	Chapter	A chapter with content already fetched (e.g. via get_chapter()).	required
average_image_size	int	Assumed bytes per <img> referenced in the chapter's content.	DEFAULT_AVERAGE_IMAGE_SIZE

Raises:

Type	Description
ValueError	If chapter.content is None (not yet fetched — see Chapter's docstring for when that happens).

Source code in packages/ranobelib/src/ranobelib/sizing.py

def chapter_size(chapter: Chapter, *, average_image_size: int = DEFAULT_AVERAGE_IMAGE_SIZE) -> int:
    """Estimate a fetched chapter's size in bytes: exact text plus assumed-average images.

    Args:
        chapter: A chapter with content already fetched (e.g. via ``get_chapter()``).
        average_image_size: Assumed bytes per ``<img>`` referenced in the chapter's content.

    Raises:
        ValueError: If ``chapter.content`` is ``None`` (not yet fetched — see
            ``Chapter``'s docstring for when that happens).
    """
    if chapter.content is None:
        raise ValueError(
            f"Chapter {chapter.volume}/{chapter.number} has no content to size — "
            "fetch it first, e.g. via get_chapter()."
        )
    # Footnotes are split out of ``content`` (see ``Chapter.footnotes``) but are still part
    # of what was downloaded — and of what every exporter writes out.
    text = chapter.content + "".join(footnote.content for footnote in chapter.footnotes)
    text_bytes = len(text.encode("utf-8"))
    image_count = len(extract_image_urls(text))
    return text_bytes + image_count * average_image_size

ranobelib.volume_size

volume_size(
    volume: Volume,
    *,
    average_image_size: int = DEFAULT_AVERAGE_IMAGE_SIZE,
) -> int

Estimate a fetched volume's size in bytes: the sum of its chapters' chapter_size().

Parameters:

Name	Type	Description	Default
volume	Volume	A volume whose chapters have content already fetched (e.g. via get_volume()).	required
average_image_size	int	Forwarded to chapter_size() for each chapter.	DEFAULT_AVERAGE_IMAGE_SIZE

Raises:

Type	Description
ValueError	If any chapter in volume.chapters has no content — see chapter_size().

Source code in packages/ranobelib/src/ranobelib/sizing.py

def volume_size(volume: Volume, *, average_image_size: int = DEFAULT_AVERAGE_IMAGE_SIZE) -> int:
    """Estimate a fetched volume's size in bytes: the sum of its chapters' ``chapter_size()``.

    Args:
        volume: A volume whose chapters have content already fetched (e.g. via
            ``get_volume()``).
        average_image_size: Forwarded to ``chapter_size()`` for each chapter.

    Raises:
        ValueError: If any chapter in ``volume.chapters`` has no content — see
            ``chapter_size()``.
    """
    return sum(
        chapter_size(chapter, average_image_size=average_image_size) for chapter in volume.chapters
    )

Chapter content

ranobelib.chapter_image_urls

chapter_image_urls(chapter: Chapter) -> list[str]

List the image URLs a fetched chapter references.

Parameters:

Name	Type	Description	Default
chapter	Chapter	A chapter with content already fetched (e.g. via get_chapter()).	required

Returns:

Type	Description
list[str]	Every <img src> in chapter.content and then chapter.footnotes, in
list[str]	document order, each URL listed once (its first occurrence).

Raises:

Type	Description
ValueError	If chapter.content is None (not yet fetched — see Chapter's docstring for when that happens).

Source code in packages/ranobelib/src/ranobelib/images.py

def chapter_image_urls(chapter: Chapter) -> list[str]:
    """List the image URLs a fetched chapter references.

    Args:
        chapter: A chapter with content already fetched (e.g. via ``get_chapter()``).

    Returns:
        Every ``<img src>`` in ``chapter.content`` and then ``chapter.footnotes``, in
        document order, each URL listed once (its first occurrence).

    Raises:
        ValueError: If ``chapter.content`` is ``None`` (not yet fetched — see ``Chapter``'s
            docstring for when that happens).
    """
    fragments = [_require_content(chapter), *(footnote.content for footnote in chapter.footnotes)]
    urls = (url for fragment in fragments for url in extract_image_urls(fragment))
    return list(dict.fromkeys(urls))

ranobelib.rewrite_image_urls

rewrite_image_urls(
    chapter: Chapter, replace: Callable[[str], str]
) -> Chapter

Return a copy of a fetched chapter with every <img src> passed through replace.

Parameters:

Name	Type	Description	Default
chapter	Chapter	A chapter with content already fetched (e.g. via get_chapter()).	required
replace	Callable[[str], str]	Called with each image URL (once per <img>, so possibly more than once for the same URL); its result becomes the new src, HTML-escaped as an attribute value. An <img> without a src is left as it is.	required

Returns:

Type	Description
Chapter	A new Chapter whose content and footnotes have their <img src>
Chapter	rewritten; every other field is unchanged, and chapter itself is not modified.

Raises:

Type	Description
ValueError	If chapter.content is None — see chapter_image_urls().

Source code in packages/ranobelib/src/ranobelib/images.py

def rewrite_image_urls(chapter: Chapter, replace: Callable[[str], str]) -> Chapter:
    """Return a copy of a fetched chapter with every ``<img src>`` passed through ``replace``.

    Args:
        chapter: A chapter with content already fetched (e.g. via ``get_chapter()``).
        replace: Called with each image URL (once per ``<img>``, so possibly more than once
            for the same URL); its result becomes the new ``src``, HTML-escaped as an
            attribute value. An ``<img>`` without a ``src`` is left as it is.

    Returns:
        A new ``Chapter`` whose ``content`` and ``footnotes`` have their ``<img src>``
        rewritten; every other field is unchanged, and ``chapter`` itself is not modified.

    Raises:
        ValueError: If ``chapter.content`` is ``None`` — see ``chapter_image_urls()``.
    """
    content = _require_content(chapter)

    def rewrite(fragment: str) -> str:
        return replace_image_srcs(fragment, lambda src: replace(src) if src else src)

    return chapter.model_copy(
        update={
            "content": rewrite(content),
            "footnotes": [Footnote(content=rewrite(f.content)) for f in chapter.footnotes],
        }
    )

ranobelib.chapter_paragraphs

chapter_paragraphs(chapter: Chapter) -> list[str]

A fetched chapter's top-level blocks as plain text, in document order.

Entry i is the text of the i-th top-level element of chapter.content — the same position a browser gives it among the rendered content's element children — so a paragraph index counted in the DOM can be used to look it up directly.

Parameters:

Name	Type	Description	Default
chapter	Chapter	A chapter with content already fetched (e.g. via get_chapter()).	required

Returns:

Type	Description
list[str]	One string per top-level element: its text with entities decoded and whitespace
list[str]	collapsed to single spaces ("" for a block without text, such as <hr /> or
list[str]	an image-only paragraph). chapter.footnotes aren't included — they're not part
list[str]	of content (see Chapter.footnotes).

Raises:

Type	Description
ValueError	If chapter.content is None (not yet fetched — see Chapter's docstring for when that happens).

Source code in packages/ranobelib/src/ranobelib/paragraphs.py

def chapter_paragraphs(chapter: Chapter) -> list[str]:
    """A fetched chapter's top-level blocks as plain text, in document order.

    Entry ``i`` is the text of the ``i``-th top-level element of ``chapter.content`` — the
    same position a browser gives it among the rendered content's element children — so a
    paragraph index counted in the DOM can be used to look it up directly.

    Args:
        chapter: A chapter with content already fetched (e.g. via ``get_chapter()``).

    Returns:
        One string per top-level element: its text with entities decoded and whitespace
        collapsed to single spaces (``""`` for a block without text, such as ``<hr />`` or
        an image-only paragraph). ``chapter.footnotes`` aren't included — they're not part
        of ``content`` (see ``Chapter.footnotes``).

    Raises:
        ValueError: If ``chapter.content`` is ``None`` (not yet fetched — see ``Chapter``'s
            docstring for when that happens).
    """
    if chapter.content is None:
        raise ValueError(
            f"Chapter {chapter.volume}/{chapter.number} has no content — "
            "fetch it first, e.g. via get_chapter()."
        )
    collector = _TopLevelTextCollector()
    collector.feed(chapter.content)
    collector.close()
    return [" ".join("".join(parts).split()) for parts in collector.entries]

Exporters

Not re-exported from the top-level ranobelib package — import from ranobelib.exporters. Adding a new export format is a new module in ranobelib/exporters/ implementing Exporter and decorated with @register; no changes needed elsewhere.

ranobelib.exporters.Exporter

Bases: Protocol

Renders a title's chapters to a single file in some format.

format class-attribute

format: str

The registry key this exporter is selected by, e.g. "txt".

export async

export(
    title: Title,
    chapters: list[Chapter],
    output_path: Path,
    *,
    on_chapter: Callable[[], None] | None = None,
    headers: Mapping[str, str] | None = None,
) -> Path

Write chapters (in the given order) to output_path.

async since embedding illustrations (epub, pdf) requires downloading them — the SDK is async-only throughout (see CLAUDE.md), so this can't drop to a sync HTTP call. txt/fb2 do no I/O and just don't await anything in their bodies.

Parameters:

Name	Type	Description	Default
title	Title	The chapters' parent title, for metadata (name, authors, ...).	required
chapters	list[Chapter]	The chapters to include, in the order they should appear.	required
output_path	Path	Where to write the exported file.	required
on_chapter	Callable[[], None] | None	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.	None
headers	Mapping[str, str] | None	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.	None

Returns:

Type	Description
Path	output_path, once the file has been written.

Source code in packages/ranobelib/src/ranobelib/exporters/__init__.py

async def export(
    self,
    title: Title,
    chapters: list[Chapter],
    output_path: Path,
    *,
    on_chapter: Callable[[], None] | None = None,
    headers: Mapping[str, str] | None = None,
) -> Path:
    """Write ``chapters`` (in the given order) to ``output_path``.

    ``async`` since embedding illustrations (epub, pdf) requires downloading them —
    the SDK is async-only throughout (see CLAUDE.md), so this can't drop to a sync
    HTTP call. txt/fb2 do no I/O and just don't ``await`` anything in their bodies.

    Args:
        title: The chapters' parent title, for metadata (name, authors, ...).
        chapters: The chapters to include, in the order they should appear.
        output_path: Where to write the exported file.
        on_chapter: 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.
        headers: 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.

    Returns:
        ``output_path``, once the file has been written.
    """
    ...

ranobelib.exporters.register

register(exporter: ExporterT) -> ExporterT

Class decorator: register exporter under its format key.

Source code in packages/ranobelib/src/ranobelib/exporters/__init__.py

def register(exporter: ExporterT) -> ExporterT:
    """Class decorator: register ``exporter`` under its ``format`` key."""
    EXPORTERS[exporter.format] = exporter
    return exporter

Registered exporters, keyed by Exporter.format.