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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ranobelib-python-sdk
-Version: 0.4.1
+Version: 0.6.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.4.1 → ranobelib_python_sdk-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ranobelib-python-sdk"
-version = "0.4.1"
+version = "0.6.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.4.1 → ranobelib_python_sdk-0.6.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "ranobelib-python-sdk"
-version = "0.4.1"
+version = "0.6.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.4.1 → ranobelib_python_sdk-0.6.0}/src/ranobelib/__init__.py

@@ -1,5 +1,6 @@
 """Async Python SDK for ranobelib.me."""
 
+from ranobelib.catalog import Catalog
 from ranobelib.exceptions import (
     AmbiguousChapter,
     AuthRequiredError,
@@ -11,13 +12,15 @@ from ranobelib.exceptions import (
     TitleNotFoundError,
     VolumeNotFoundError,
 )
-from ranobelib.models import Chapter, ChapterBranch, Title, Volume
+from ranobelib.models import CatalogPage, Chapter, ChapterBranch, Title, Volume
 from ranobelib.sdk import RanobeLib
 from ranobelib.sizing import chapter_size, volume_size
 
 __all__ = [
     "AmbiguousChapter",
     "AuthRequiredError",
+    "Catalog",
+    "CatalogPage",
     "Chapter",
     "ChapterBranch",
     "ChapterNotFoundError",

ranobelib_python_sdk-0.6.0/src/ranobelib/catalog.py

@@ -0,0 +1,156 @@
+"""Catalog listing/search: the ``Catalog`` class.
+
+Unlike ``RanobeLib`` (scoped to one title via its URL/slug), catalog listing isn't scoped to
+any title at all — see CLAUDE.md's roadmap entry for why this is a separate entry point with
+its own ``ApiClient``/``DiskCache`` rather than a method on ``RanobeLib``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+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
+
+DEFAULT_SORT = "last_chapter_at"
+"""Default sort order: title's last-chapter timestamp — the closest real equivalent to
+"recently updated" (the API has no ``updated_at`` sort value, see docs/api-notes.md)."""
+
+MIN_PER_PAGE = 10
+MAX_PER_PAGE = 60
+
+
+class Catalog:
+    """Entry point for listing/searching the ranobelib.me catalog.
+
+    Example:
+        ```python
+        async with Catalog() as catalog:
+            page = await catalog.list_titles(query="dxd", genres=[34], status=1)
+            for title in page.items:
+                print(title.name)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        cache_dir: str | Path | None = None,
+        cache_ttl: float | 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 (``cache.py``), 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.
+        """
+        self._client = ApiClient()
+        self._cache = DiskCache(
+            cache_dir if cache_dir is not None else DEFAULT_CACHE_DIR, ttl=cache_ttl
+        )
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    async def list_titles(
+        self,
+        *,
+        page: int = 1,
+        per_page: int = 30,
+        query: str | None = None,
+        genres: list[int] | None = None,
+        status: int | None = None,
+        sort: str = DEFAULT_SORT,
+        refresh: bool = False,
+    ) -> CatalogPage:
+        """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). 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.
+            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
+                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 ``CatalogPage``: the matching titles (as ``Title`` models) plus whether a next
+            page exists.
+
+        Raises:
+            ValueError: If ``page`` is less than 1, or ``per_page`` is outside
+                ``MIN_PER_PAGE..MAX_PER_PAGE``.
+        """
+        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}."
+            )
+
+        key = _cache_key(
+            page=page, per_page=per_page, query=query, genres=genres, status=status, sort=sort
+        )
+        if not refresh:
+            cached = self._cache.get(key)
+            if cached is not None:
+                return _build_page(cached)
+
+        data = await self._client.list_titles(
+            page=page, per_page=per_page, query=query, genres=genres, status=status, sort=sort
+        )
+        self._cache.set(key, data)
+        return _build_page(data)
+
+
+def _cache_key(
+    *,
+    page: int,
+    per_page: int,
+    query: str | None,
+    genres: list[int] | None,
+    status: int | None,
+    sort: str,
+) -> str:
+    genres_part = ",".join(str(genre_id) for genre_id in genres or [])
+    return f"catalog:{page}:{per_page}:{query or ''}:{genres_part}:{status}:{sort}"
+
+
+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"])

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

@@ -163,6 +163,60 @@ class ApiClient:
         data: dict[str, Any] = response.json()["data"]
         return data
 
+    async def list_titles(
+        self,
+        *,
+        page: int,
+        per_page: int,
+        query: str | None,
+        genres: list[int] | None,
+        status: int | None,
+        sort: str,
+    ) -> dict[str, Any]:
+        """Fetch one page of the catalog listing/search results.
+
+        Unlike the other ``ApiClient`` methods, this returns the *whole* response body, not
+        just ``data`` — callers need ``meta.has_next_page`` too, and there's no total count
+        to derive it from otherwise (see docs/api-notes.md).
+
+        Args:
+            page: 1-based page number.
+            per_page: Page size. The API only accepts ``10..60`` (validated by the caller,
+                see ``Catalog.list_titles``); values outside that raise here via a 422.
+            query: Free-text search term, matched against name/rus_name/eng_name. ``None``
+                or empty omits the ``q`` parameter entirely.
+            genres: Genre ids to filter by. A title must have *all* of them (AND, not OR —
+                see docs/api-notes.md), not just any one.
+            status: A single ``Title.status.id`` to filter by.
+            sort: Forwarded as the API's ``sort_by`` parameter, not ``sort`` — the API
+                silently ignores an actual ``sort`` parameter (see docs/api-notes.md); this
+                mismatch between the SDK's public keyword and the wire parameter name is
+                deliberate, not a typo.
+
+        Returns:
+            The full JSON response: ``{"data": [...], "meta": {...}, "links": {...}}``.
+        """
+        params: list[tuple[str, str | int | float | bool | None]] = [
+            ("site_id[]", RANOBELIB_SITE_ID),
+            ("page", str(page)),
+            ("limit", str(per_page)),
+            ("sort_by", sort),
+        ]
+        if query:
+            params.append(("q", query))
+        for genre_id in genres or []:
+            params.append(("genres[]", str(genre_id)))
+        if status is not None:
+            params.append(("status[]", str(status)))
+
+        response = await self._get("/manga", params=httpx.QueryParams(params))
+        self._raise_for_status(
+            response,
+            not_found=RanobeLibError(f"Unexpected 404 from catalog listing (page={page})"),
+        )
+        result: dict[str, Any] = response.json()
+        return result
+
     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.4.1 → ranobelib_python_sdk-0.6.0}/src/ranobelib/models.py

@@ -329,3 +329,16 @@ class Volume(BaseModel):
 
     number: str
     chapters: list[Chapter] = Field(default_factory=list)
+
+
+class CatalogPage(BaseModel):
+    """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``, ...) just come back
+    at their defaults, same as any other partially-populated ``Title`` (see docs/api-notes.md).
+    """
+
+    items: list[Title]
+    page: int
+    has_next_page: bool

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

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+from collections.abc import Callable
 from pathlib import Path
 from types import TracebackType
 from typing import Any, Self
@@ -233,6 +234,7 @@ class RanobeLib:
         branch_id: int | None = None,
         translation_index: int | None = None,
         chapter_delay: float = 0.0,
+        on_chapter: Callable[[int, int], None] | None = None,
     ) -> list[Volume]:
         """Download every chapter of the title, across all its volumes.
 
@@ -258,6 +260,12 @@ class RanobeLib:
             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.
 
         Raises:
             ValueError: If both ``branch_id`` and ``translation_index`` are given.
@@ -297,11 +305,14 @@ class RanobeLib:
             raise MultipleTitleTranslationsError(self._slug_url, chapters=unresolved)
 
         chapters = []
-        with self._reporter.progress(f"Downloading {self._slug_url}", len(planned)) as advance:
+        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 chapter_delay and index < len(planned) - 1:
+                if on_chapter is not None:
+                    on_chapter(index + 1, total)
+                if chapter_delay and index < total - 1:
                     await asyncio.sleep(chapter_delay)
         return _group_into_volumes(chapters)