ranobelib-python-sdk 0.1.0__tar.gz → 0.3.0__tar.gz

{ranobelib_python_sdk-0.1.0 → ranobelib_python_sdk-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ranobelib-python-sdk
-Version: 0.1.0
+Version: 0.3.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
@@ -23,6 +23,7 @@ Requires-Python: >=3.11
 Project-URL: Homepage, https://github.com/LLIJIYAPNIK/ranobelib-python-sdk
 Project-URL: Repository, https://github.com/LLIJIYAPNIK/ranobelib-python-sdk
 Project-URL: Issues, https://github.com/LLIJIYAPNIK/ranobelib-python-sdk/issues
+Project-URL: Changelog, https://github.com/LLIJIYAPNIK/ranobelib-python-sdk/blob/main/CHANGELOG.md
 Description-Content-Type: text/markdown
 
 # ranobelib-python-sdk
@@ -41,7 +42,8 @@ The SDK talks to the undocumented but open JSON API behind the site (`api.cdnlib
 part of the lib.social network) instead of scraping HTML.
 
 > **Status:** all the calls in the quickstart below are implemented — metadata, table of
-> contents, single/bulk chapter and volume downloads, translation selection, and export to
+> contents, single/bulk chapter and volume downloads, whole-title bulk download, translation
+> selection, and export to
 > `"txt"`, `"fb2"`, `"epub"`, or `"pdf"` (cover + in-chapter illustrations embedded in
 > epub/pdf). Raw API responses are cached to disk, and the underlying client bounds
 > concurrency, paces requests, and retries 429/5xx with backoff. `fmt="pdf"` needs
@@ -83,17 +85,27 @@ async with RanobeLib("https://ranobelib.me/ru/book/6712--high-school-dxd-novel")
     translations = await lib.get_translations(volume=6, number="51.6")
     chapter = await lib.get_chapter(volume=6, number="51.6", branch_id=...)
 
+    all_volumes = await lib.download_title(translation_index=0, chapter_delay=0.5)
+
     await lib.export(chapters, fmt="epub", path="output.epub")
 ```
 
 This is the full current public API — everything above is implemented and works today.
 
+## Examples
+
+Complete, runnable scripts for every feature above — title metadata, table of contents,
+single/bulk chapter and volume downloads, translation selection, whole-title bulk download,
+disk caching, export to all four formats, and error handling — live in
+**[`examples/`](examples/)**, one heavily commented file per feature. Start there for
+copy-pasteable code.
+
 ## Documentation
 
 Full API reference and guides: **<https://LLIJIYAPNIK.github.io/ranobelib-python-sdk/>**
 (built with `mkdocs-material` + `mkdocstrings`, deployed on push to `main`). `CLAUDE.md`
 documents the full architecture, public API contract, and the reasoning behind the SDK's
-design decisions.
+design decisions. [`CHANGELOG.md`](CHANGELOG.md) lists what changed in each release.
 
 ## License
 

{ranobelib_python_sdk-0.1.0 → ranobelib_python_sdk-0.3.0}/README.md

@@ -14,7 +14,8 @@ The SDK talks to the undocumented but open JSON API behind the site (`api.cdnlib
 part of the lib.social network) instead of scraping HTML.
 
 > **Status:** all the calls in the quickstart below are implemented — metadata, table of
-> contents, single/bulk chapter and volume downloads, translation selection, and export to
+> contents, single/bulk chapter and volume downloads, whole-title bulk download, translation
+> selection, and export to
 > `"txt"`, `"fb2"`, `"epub"`, or `"pdf"` (cover + in-chapter illustrations embedded in
 > epub/pdf). Raw API responses are cached to disk, and the underlying client bounds
 > concurrency, paces requests, and retries 429/5xx with backoff. `fmt="pdf"` needs
@@ -56,17 +57,27 @@ async with RanobeLib("https://ranobelib.me/ru/book/6712--high-school-dxd-novel")
     translations = await lib.get_translations(volume=6, number="51.6")
     chapter = await lib.get_chapter(volume=6, number="51.6", branch_id=...)
 
+    all_volumes = await lib.download_title(translation_index=0, chapter_delay=0.5)
+
     await lib.export(chapters, fmt="epub", path="output.epub")
 ```
 
 This is the full current public API — everything above is implemented and works today.
 
+## Examples
+
+Complete, runnable scripts for every feature above — title metadata, table of contents,
+single/bulk chapter and volume downloads, translation selection, whole-title bulk download,
+disk caching, export to all four formats, and error handling — live in
+**[`examples/`](examples/)**, one heavily commented file per feature. Start there for
+copy-pasteable code.
+
 ## Documentation
 
 Full API reference and guides: **<https://LLIJIYAPNIK.github.io/ranobelib-python-sdk/>**
 (built with `mkdocs-material` + `mkdocstrings`, deployed on push to `main`). `CLAUDE.md`
 documents the full architecture, public API contract, and the reasoning behind the SDK's
-design decisions.
+design decisions. [`CHANGELOG.md`](CHANGELOG.md) lists what changed in each release.
 
 ## License
 

{ranobelib_python_sdk-0.1.0 → ranobelib_python_sdk-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ranobelib-python-sdk"
-version = "0.1.0"
+version = "0.3.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"
@@ -40,6 +40,7 @@ email = "kas4wot@yandex.ru"
 Homepage = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk"
 Repository = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk"
 Issues = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk/issues"
+Changelog = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk/blob/main/CHANGELOG.md"
 
 [build-system]
 requires = ["uv_build>=0.11.26,<0.12.0"]

{ranobelib_python_sdk-0.1.0 → ranobelib_python_sdk-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "ranobelib-python-sdk"
-version = "0.1.0"
+version = "0.3.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"
@@ -31,6 +31,7 @@ dependencies = [
 Homepage = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk"
 Repository = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk"
 Issues = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk/issues"
+Changelog = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk/blob/main/CHANGELOG.md"
 
 [build-system]
 requires = ["uv_build>=0.11.26,<0.12.0"]

{ranobelib_python_sdk-0.1.0 → ranobelib_python_sdk-0.3.0}/src/ranobelib/__init__.py

@@ -1,8 +1,10 @@
 """Async Python SDK for ranobelib.me."""
 
 from ranobelib.exceptions import (
+    AmbiguousChapter,
     AuthRequiredError,
     ChapterNotFoundError,
+    MultipleTitleTranslationsError,
     MultipleTranslationsError,
     RanobeLibError,
     RateLimitError,
@@ -13,10 +15,12 @@ from ranobelib.models import Chapter, ChapterBranch, Title, Volume
 from ranobelib.sdk import RanobeLib
 
 __all__ = [
+    "AmbiguousChapter",
     "AuthRequiredError",
     "Chapter",
     "ChapterBranch",
     "ChapterNotFoundError",
+    "MultipleTitleTranslationsError",
     "MultipleTranslationsError",
     "RanobeLib",
     "RanobeLibError",

{ranobelib_python_sdk-0.1.0 → ranobelib_python_sdk-0.3.0}/src/ranobelib/exceptions.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, NamedTuple
 
 if TYPE_CHECKING:
     from ranobelib.models import ChapterBranch
@@ -93,6 +93,54 @@ def _describe_branch(branch: ChapterBranch) -> str:
     return branch.user.username
 
 
+class AmbiguousChapter(NamedTuple):
+    """One chapter that ``RanobeLib.download_title()`` couldn't resolve a translation for.
+
+    Attributes:
+        volume: The chapter's volume number.
+        number: The chapter number.
+        branches: The chapter's available translations, as returned by
+            ``RanobeLib.get_translations()``.
+    """
+
+    volume: str
+    number: str
+    branches: list[ChapterBranch]
+
+
+class MultipleTitleTranslationsError(RanobeLibError):
+    """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:
+        slug_url: The title's ``{id}--{slug}`` identifier.
+        chapters: The ambiguous chapters and their available translations.
+    """
+
+    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)
+        )
+
+
 class AuthRequiredError(RanobeLibError):
     """Raised when the requested content requires authorization (paid or early access).
 

{ranobelib_python_sdk-0.1.0 → ranobelib_python_sdk-0.3.0}/src/ranobelib/sdk.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 from pathlib import Path
 from types import TracebackType
 from typing import Any, Self
@@ -9,7 +10,9 @@ from typing import Any, Self
 from ranobelib.cache import DEFAULT_CACHE_DIR, DiskCache
 from ranobelib.client import ApiClient
 from ranobelib.exceptions import (
+    AmbiguousChapter,
     ChapterNotFoundError,
+    MultipleTitleTranslationsError,
     MultipleTranslationsError,
     VolumeNotFoundError,
 )
@@ -215,6 +218,82 @@ class RanobeLib:
         raw_chapters = await self._get_chapters()
         return [await self._build_volume(volume, raw_chapters) for volume in volumes]
 
+    async def download_title(
+        self,
+        *,
+        branch_id: int | None = None,
+        translation_index: int | None = None,
+        chapter_delay: float = 0.0,
+    ) -> list[Volume]:
+        """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.
+
+        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.
+
+        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.
+        """
+        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.")
+
+        raw_chapters = await self._get_chapters()
+
+        planned: list[tuple[str, str, int | None]] = []
+        unresolved: list[AmbiguousChapter] = []
+        for item in raw_chapters:
+            volume_str: str = item["volume"]
+            number: str = item["number"]
+            branches = item.get("branches") or []
+            if len(branches) <= 1:
+                planned.append((volume_str, number, None))
+                continue
+
+            resolved, selected = _resolve_bulk_branch_id(
+                branches, branch_id=branch_id, translation_index=translation_index
+            )
+            if resolved:
+                planned.append((volume_str, number, selected))
+            else:
+                unresolved.append(
+                    AmbiguousChapter(
+                        volume=volume_str,
+                        number=number,
+                        branches=[ChapterBranch.model_validate(branch) for branch in branches],
+                    )
+                )
+
+        if unresolved:
+            raise MultipleTitleTranslationsError(self._slug_url, chapters=unresolved)
+
+        chapters = []
+        for index, (volume_str, number, selected_branch_id) in enumerate(planned):
+            chapters.append(await self._fetch_chapter(volume_str, number, selected_branch_id))
+            if chapter_delay and index < len(planned) - 1:
+                await asyncio.sleep(chapter_delay)
+        return _group_into_volumes(chapters)
+
     async def export(self, chapters: list[Chapter], *, fmt: str, path: str | Path) -> Path:
         """Export chapters to a file.
 
@@ -307,6 +386,24 @@ def _group_into_volumes(chapters: list[Chapter]) -> list[Volume]:
     return [Volume(number=number, chapters=items) for number, items in grouped.items()]
 
 
+def _resolve_bulk_branch_id(
+    branches: list[dict[str, Any]], *, branch_id: int | None, translation_index: int | None
+) -> tuple[bool, int | None]:
+    """Resolve which branch_id to request for one ambiguous chapter in ``download_title()``.
+
+    Returns ``(True, branch_id)`` if resolved, ``(False, None)`` if ``branch_id``/
+    ``translation_index`` doesn't identify one of this chapter's branches.
+    """
+    if branch_id is not None:
+        for branch in branches:
+            if branch.get("branch_id") == branch_id:
+                return True, branch_id
+        return False, None
+    if translation_index is not None and 0 <= translation_index < len(branches):
+        return True, branches[translation_index].get("branch_id")
+    return False, None
+
+
 def _find_raw_chapter(
     raw_chapters: list[dict[str, Any]], volume_str: str, number: str
 ) -> dict[str, Any] | None: