ranobelib-python-sdk 0.6.0__tar.gz → 0.7.0__tar.gz

{ranobelib_python_sdk-0.6.0 → ranobelib_python_sdk-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ranobelib-python-sdk
-Version: 0.6.0
+Version: 0.7.0
 Summary: Async Python SDK for ranobelib.me: title metadata, chapter/volume downloads, and export to epub/fb2/txt/pdf
 Keywords: ranobelib,ranobe,novel,webnovel,epub,fb2,sdk
 Author: LLIJIYAPNIK

{ranobelib_python_sdk-0.6.0 → ranobelib_python_sdk-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ranobelib-python-sdk"
-version = "0.6.0"
+version = "0.7.0"
 description = "Async Python SDK for ranobelib.me: title metadata, chapter/volume downloads, and export to epub/fb2/txt/pdf"
 readme = "README.md"
 license = "MIT"

{ranobelib_python_sdk-0.6.0 → ranobelib_python_sdk-0.7.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "ranobelib-python-sdk"
-version = "0.6.0"
+version = "0.7.0"
 description = "Async Python SDK for ranobelib.me: title metadata, chapter/volume downloads, and export to epub/fb2/txt/pdf"
 readme = "README.md"
 license = "MIT"

{ranobelib_python_sdk-0.6.0 → ranobelib_python_sdk-0.7.0}/src/ranobelib/__init__.py

@@ -5,6 +5,7 @@ from ranobelib.exceptions import (
     AmbiguousChapter,
     AuthRequiredError,
     ChapterNotFoundError,
+    DownloadTitleInterruptedError,
     MultipleTitleTranslationsError,
     MultipleTranslationsError,
     RanobeLibError,
@@ -12,7 +13,7 @@ from ranobelib.exceptions import (
     TitleNotFoundError,
     VolumeNotFoundError,
 )
-from ranobelib.models import CatalogPage, Chapter, ChapterBranch, Title, Volume
+from ranobelib.models import CatalogPage, Chapter, ChapterBranch, Genre, Title, Volume
 from ranobelib.sdk import RanobeLib
 from ranobelib.sizing import chapter_size, volume_size
 
@@ -24,6 +25,8 @@ __all__ = [
     "Chapter",
     "ChapterBranch",
     "ChapterNotFoundError",
+    "DownloadTitleInterruptedError",
+    "Genre",
     "MultipleTitleTranslationsError",
     "MultipleTranslationsError",
     "RanobeLib",

{ranobelib_python_sdk-0.6.0 → ranobelib_python_sdk-0.7.0}/src/ranobelib/catalog.py

@@ -12,8 +12,8 @@ from types import TracebackType
 from typing import Any, Self
 
 from ranobelib.cache import DEFAULT_CACHE_DIR, DiskCache
-from ranobelib.client import ApiClient
-from ranobelib.models import CatalogPage, Title
+from ranobelib.client import RANOBELIB_SITE_ID, ApiClient
+from ranobelib.models import CatalogPage, Genre, Title
 
 DEFAULT_SORT = "last_chapter_at"
 """Default sort order: title's last-chapter timestamp — the closest real equivalent to
@@ -94,9 +94,8 @@ class Catalog:
             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). The SDK doesn't validate these against
-                a known genre list — there's no public, unauthenticated way to fetch one (see
-                docs/api-notes.md) — an unrecognized id just matches nothing.
+                (AND, not OR — see docs/api-notes.md). Not validated against ``list_genres()``
+                before sending — an unrecognized id just matches nothing rather than erroring.
             status: A single ``Title.status.id`` to filter by (e.g. ongoing vs. completed).
             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
@@ -136,6 +135,34 @@ class Catalog:
         self._cache.set(key, data)
         return _build_page(data)
 
+    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 ranobelib.me before
+        returning, so callers don't get filter options (e.g. "Детское") that could never
+        match any ranobelib title.
+
+        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 ranobelib.me.
+        """
+        key = "catalog:genres"
+        if not refresh:
+            cached = self._cache.get(key)
+            if cached is not None:
+                return _build_genres(cached)
+
+        data = await self._client.list_genres()
+        self._cache.set(key, data)
+        return _build_genres(data)
+
 
 def _cache_key(
     *,
@@ -154,3 +181,8 @@ def _build_page(data: dict[str, Any]) -> CatalogPage:
     items = [Title.model_validate(item) for item in data["data"]]
     meta = data["meta"]
     return CatalogPage(items=items, page=meta["current_page"], has_next_page=meta["has_next_page"])
+
+
+def _build_genres(data: list[dict[str, Any]]) -> list[Genre]:
+    site_id = int(RANOBELIB_SITE_ID)
+    return [Genre.model_validate(item) for item in data if site_id in item.get("site_ids", [])]

{ranobelib_python_sdk-0.6.0 → ranobelib_python_sdk-0.7.0}/src/ranobelib/client.py

@@ -217,6 +217,24 @@ class ApiClient:
         result: dict[str, Any] = response.json()
         return result
 
+    async def list_genres(self) -> list[dict[str, Any]]:
+        """Fetch the raw genre list shared across the whole lib.social network.
+
+        Unlike ``list_titles``, this endpoint isn't site-scoped by any request parameter
+        (confirmed: a ``Site-Id`` header changes nothing about the response) — it returns
+        every genre known to the network at once, each tagged with the site ids it applies
+        to via a ``site_ids`` field. Callers must filter to ``RANOBELIB_SITE_ID`` themselves
+        (see ``Catalog.list_genres``, which drops e.g. site-5-only genres like "Детское"
+        before returning).
+
+        Returns:
+            The raw ``data.genres`` array from the API response, unfiltered by site.
+        """
+        response = await self._get("/constants", params=httpx.QueryParams([("fields[]", "genres")]))
+        self._raise_for_status(response, not_found=RanobeLibError("Unexpected 404 from genre list"))
+        data: list[dict[str, Any]] = response.json()["data"]["genres"]
+        return data
+
     async def _get(self, url: str, *, params: Any = None) -> httpx.Response:
         """Issue a GET request, bounded by concurrency/pacing and retried on 429/5xx."""
         attempt = 0

{ranobelib_python_sdk-0.6.0 → ranobelib_python_sdk-0.7.0}/src/ranobelib/exceptions.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, NamedTuple
 
 if TYPE_CHECKING:
-    from ranobelib.models import ChapterBranch
+    from ranobelib.models import ChapterBranch, Volume
 
 
 class RanobeLibError(Exception):
@@ -164,3 +164,36 @@ class RateLimitError(RanobeLibError):
         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}")
+
+
+class DownloadTitleInterruptedError(RanobeLibError):
+    """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:
+        slug_url: The title's ``{id}--{slug}`` identifier.
+        volumes: 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.
+    """
+
+    def __init__(self, slug_url: str, *, volumes: list[Volume], completed: int, total: int) -> None:
+        self.slug_url = slug_url
+        self.volumes = 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."
+        )

{ranobelib_python_sdk-0.6.0 → ranobelib_python_sdk-0.7.0}/src/ranobelib/sdk.py

@@ -14,8 +14,11 @@ from ranobelib.console import Reporter, Verbosity
 from ranobelib.exceptions import (
     AmbiguousChapter,
     ChapterNotFoundError,
+    DownloadTitleInterruptedError,
     MultipleTitleTranslationsError,
     MultipleTranslationsError,
+    RanobeLibError,
+    RateLimitError,
     VolumeNotFoundError,
 )
 from ranobelib.exporters import EXPORTERS
@@ -23,6 +26,16 @@ from ranobelib.models import Chapter, ChapterBranch, Title, Volume
 from ranobelib.numbering import parse_slug_url
 from ranobelib.sizing import DEFAULT_AVERAGE_IMAGE_SIZE, DEFAULT_SAMPLE_SIZE, chapter_size
 
+DEFAULT_RATE_LIMIT_RETRIES = 6
+"""Default ``download_title(max_rate_limit_retries=...)`` — see docs/api-notes.md."""
+
+_RATE_LIMIT_RETRY_BASE_DELAY = 5.0
+"""Base delay, in seconds, for download_title()'s bulk rate-limit backoff (doubled per
+attempt, capped at _RATE_LIMIT_RETRY_MAX_DELAY) — used when the API's 429 doesn't send a
+Retry-After header."""
+
+_RATE_LIMIT_RETRY_MAX_DELAY = 60.0
+
 _INFO_FIELDS = [
     "background",
     "eng_name",
@@ -235,6 +248,7 @@ class RanobeLib:
         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[Volume]:
         """Download every chapter of the title, across all its volumes.
 
@@ -248,6 +262,14 @@ class RanobeLib:
         ``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
@@ -266,11 +288,20 @@ class RanobeLib:
                 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.
         """
         if branch_id is not None and translation_index is not None:
             raise ValueError("Pass at most one of branch_id or translation_index, not both.")
@@ -304,16 +335,31 @@ class RanobeLib:
         if unresolved:
             raise MultipleTitleTranslationsError(self._slug_url, chapters=unresolved)
 
-        chapters = []
+        chapters: list[Chapter] = []
         total = len(planned)
-        with self._reporter.progress(f"Downloading {self._slug_url}", total) as advance:
-            for index, (volume_str, number, selected_branch_id) in enumerate(planned):
-                chapters.append(await self._fetch_chapter(volume_str, number, selected_branch_id))
-                advance()
-                if on_chapter is not None:
-                    on_chapter(index + 1, total)
-                if chapter_delay and index < total - 1:
-                    await asyncio.sleep(chapter_delay)
+        try:
+            with self._reporter.progress(f"Downloading {self._slug_url}", total) as advance:
+                for index, (volume_str, number, selected_branch_id) in enumerate(planned):
+                    chapters.append(
+                        await self._fetch_chapter_riding_out_rate_limits(
+                            volume_str,
+                            number,
+                            selected_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 RanobeLibError as exc:
+            raise DownloadTitleInterruptedError(
+                self._slug_url,
+                volumes=_group_into_volumes(chapters),
+                completed=len(chapters),
+                total=total,
+            ) from exc
         return _group_into_volumes(chapters)
 
     async def estimate_title_size(
@@ -476,6 +522,44 @@ class RanobeLib:
         self._cache.set(key, data)
         return Chapter.model_validate(data)
 
+    async def _fetch_chapter_riding_out_rate_limits(
+        self,
+        volume_str: str,
+        number: str,
+        branch_id: int | None,
+        *,
+        max_rate_limit_retries: int,
+    ) -> Chapter:
+        """Fetch one chapter for a bulk download, retrying past ``ApiClient``'s own budget.
+
+        ``ApiClient._get()`` already retries a 429 a few times with its own backoff, tuned
+        for a single request (see docs/api-notes.md) — not enough to ride out sustained rate
+        limiting partway through a long sequential download. This adds a second, coarser
+        retry layer on top: on a ``RateLimitError`` that already survived ``ApiClient``'s own
+        retries, wait (honoring ``Retry-After`` if given, otherwise capped exponential
+        backoff) and try again, up to ``max_rate_limit_retries`` times, before finally letting
+        the error propagate to the caller (``download_title()``, which turns it into
+        ``DownloadTitleInterruptedError`` carrying whatever was already downloaded).
+        """
+        attempt = 0
+        while True:
+            try:
+                return await self._fetch_chapter(volume_str, number, branch_id)
+            except RateLimitError as exc:
+                if attempt >= max_rate_limit_retries:
+                    raise
+                delay = exc.retry_after
+                if delay is None:
+                    delay = min(
+                        _RATE_LIMIT_RETRY_BASE_DELAY * (2**attempt), _RATE_LIMIT_RETRY_MAX_DELAY
+                    )
+                self._reporter.log(
+                    f"[rate-limit] chapter {volume_str}/{number}: retrying in {delay:g}s "
+                    f"(attempt {attempt + 1}/{max_rate_limit_retries})"
+                )
+                await asyncio.sleep(delay)
+                attempt += 1
+
     def _resolve_branch_id(
         self, volume_str: str, number: str, raw_chapters: list[dict[str, Any]]
     ) -> int | None: