ranobelib-python-sdk 0.11.0__tar.gz → 0.12.0__tar.gz

{ranobelib_python_sdk-0.11.0 → ranobelib_python_sdk-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ranobelib-python-sdk
-Version: 0.11.0
+Version: 0.12.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.11.0 → ranobelib_python_sdk-0.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ranobelib-python-sdk"
-version = "0.11.0"
+version = "0.12.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.11.0 → ranobelib_python_sdk-0.12.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "ranobelib-python-sdk"
-version = "0.11.0"
+version = "0.12.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.11.0 → ranobelib_python_sdk-0.12.0}/src/ranobelib/__init__.py

@@ -21,6 +21,7 @@ from ranobelib.models import (
     Country,
     Footnote,
     Genre,
+    Label,
     Title,
     Volume,
 )
@@ -40,6 +41,7 @@ __all__ = [
     "DownloadTitleInterruptedError",
     "Footnote",
     "Genre",
+    "Label",
     "MultipleTitleTranslationsError",
     "MultipleTranslationsError",
     "RanobeLib",

{ranobelib_python_sdk-0.11.0 → ranobelib_python_sdk-0.12.0}/src/ranobelib/catalog.py

@@ -14,7 +14,7 @@ from typing import Any, Self
 
 from ranobelib.cache import DEFAULT_CACHE_DIR, DiskCache
 from ranobelib.client import RANOBELIB_SITE_ID, ApiClient
-from ranobelib.models import CatalogPage, Country, Genre, Title
+from ranobelib.models import CatalogPage, Country, Genre, Label, Title
 
 DEFAULT_SORT = "last_chapter_at"
 """Default sort order: title's last-chapter timestamp — the closest real equivalent to
@@ -30,7 +30,7 @@ class Catalog:
     Example:
         ```python
         async with Catalog() as catalog:
-            page = await catalog.list_titles(query="dxd", genres=[34], status=1)
+            page = await catalog.list_titles(query="dxd", genres=[34], statuses=[1])
             for title in page.items:
                 print(title.name)
         ```
@@ -84,8 +84,10 @@ class Catalog:
         query: str | None = None,
         genres: list[int] | None = None,
         tags: list[int] | None = None,
-        status: 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:
@@ -107,7 +109,10 @@ class Catalog:
                 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``.
-            status: A single ``Title.status.id`` to filter by (e.g. ongoing vs. completed).
+            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,
@@ -116,6 +121,11 @@ class Catalog:
                 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"``,
@@ -130,8 +140,9 @@ class Catalog:
             page exists.
 
         Raises:
-            ValueError: If ``page`` is less than 1, or ``per_page`` is outside
-                ``MIN_PER_PAGE..MAX_PER_PAGE``.
+            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}.")
@@ -139,6 +150,16 @@ class Catalog:
             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(
             page=page,
@@ -146,8 +167,10 @@ class Catalog:
             query=query,
             genres=genres,
             tags=tags,
-            status=status,
+            statuses=statuses,
             countries=countries,
+            min_chapters=min_chapters,
+            max_chapters=max_chapters,
             sort=sort,
         )
         if not refresh:
@@ -161,8 +184,10 @@ class Catalog:
             query=query,
             genres=genres,
             tags=tags,
-            status=status,
+            statuses=statuses,
             countries=countries,
+            min_chapters=min_chapters,
+            max_chapters=max_chapters,
             sort=sort,
         )
         self._cache.set(key, data)
@@ -223,6 +248,33 @@ class Catalog:
         self._cache.set(key, data)
         return _build_countries(data)
 
+    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
+        ranobelib.me 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 ranobelib.me.
+        """
+        key = "catalog:statuses"
+        if not refresh:
+            cached = self._cache.get(key)
+            if cached is not None:
+                return _build_statuses(cached)
+
+        data = await self._client.list_statuses()
+        self._cache.set(key, data)
+        return _build_statuses(data)
+
 
 def _cache_key(
     *,
@@ -231,16 +283,19 @@ def _cache_key(
     query: str | None,
     genres: list[int] | None,
     tags: list[int] | None,
-    status: int | None,
+    statuses: list[int] | None,
     countries: list[int] | None,
+    min_chapters: int | None,
+    max_chapters: int | None,
     sort: str,
 ) -> str:
     genres_part = ",".join(str(genre_id) for genre_id in genres or [])
     tags_part = ",".join(str(tag_id) for tag_id in tags or [])
+    statuses_part = ",".join(str(status_id) for status_id in statuses or [])
     countries_part = ",".join(str(country_id) for country_id in countries or [])
     return (
         f"catalog:{page}:{per_page}:{query or ''}:{genres_part}:{tags_part}:"
-        f"{status}:{countries_part}:{sort}"
+        f"{statuses_part}:{countries_part}:{min_chapters}:{max_chapters}:{sort}"
     )
 
 
@@ -258,3 +313,8 @@ def _build_genres(data: list[dict[str, Any]]) -> list[Genre]:
 def _build_countries(data: list[dict[str, Any]]) -> list[Country]:
     site_id = int(RANOBELIB_SITE_ID)
     return [Country.model_validate(item) for item in data if site_id in item.get("site_ids", [])]
+
+
+def _build_statuses(data: list[dict[str, Any]]) -> list[Label]:
+    site_id = int(RANOBELIB_SITE_ID)
+    return [Label.model_validate(item) for item in data if site_id in item.get("site_ids", [])]

{ranobelib_python_sdk-0.11.0 → ranobelib_python_sdk-0.12.0}/src/ranobelib/client.py

@@ -189,8 +189,10 @@ class ApiClient:
         query: str | None,
         genres: list[int] | None,
         tags: list[int] | None,
-        status: int | None,
+        statuses: list[int] | None,
         countries: list[int] | None,
+        min_chapters: int | None,
+        max_chapters: int | None,
         sort: str,
     ) -> dict[str, Any]:
         """Fetch one page of the catalog listing/search results.
@@ -209,12 +211,16 @@ class ApiClient:
                 see docs/api-notes.md), not just any one.
             tags: Tag ids to filter by. Same AND semantics as ``genres`` — a title must have
                 *all* of them, not just any one (see docs/api-notes.md).
-            status: A single ``Title.status.id`` to filter by.
+            statuses: ``Title.status.id``s to filter by. A title matches if its own status
+                is *any* of these (OR, like ``countries`` — a title only has one status, see
+                docs/api-notes.md). Sent on the wire as repeated ``status[]`` parameters.
             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, confirmed against the live API, see docs/api-notes.md). Sent on the
                 wire as repeated ``types[]`` parameters — the API's own name for this concept
                 is "type", not "country" (see docs/api-notes.md).
+            min_chapters: Minimum chapter count, inclusive. Sent as ``chap_count_min``.
+            max_chapters: Maximum chapter count, inclusive. Sent as ``chap_count_max``.
             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
@@ -235,10 +241,14 @@ class ApiClient:
             params.append(("genres[]", str(genre_id)))
         for tag_id in tags or []:
             params.append(("tags[]", str(tag_id)))
-        if status is not None:
-            params.append(("status[]", str(status)))
+        for status_id in statuses or []:
+            params.append(("status[]", str(status_id)))
         for country_id in countries or []:
             params.append(("types[]", str(country_id)))
+        if min_chapters is not None:
+            params.append(("chap_count_min", str(min_chapters)))
+        if max_chapters is not None:
+            params.append(("chap_count_max", str(max_chapters)))
 
         response = await self._get("/manga", params=httpx.QueryParams(params))
         self._raise_for_status(
@@ -283,6 +293,23 @@ class ApiClient:
         data: list[dict[str, Any]] = response.json()["data"]["types"]
         return data
 
+    async def list_statuses(self) -> list[dict[str, Any]]:
+        """Fetch the raw title status list shared across the whole lib.social network.
+
+        Same shape and caveats as ``list_genres``: not site-scoped by any request parameter,
+        returns every status known to the network at once, each tagged with the site ids it
+        applies to via ``site_ids``.
+
+        Returns:
+            The raw ``data.status`` array from the API response, unfiltered by site.
+        """
+        response = await self._get("/constants", params=httpx.QueryParams([("fields[]", "status")]))
+        self._raise_for_status(
+            response, not_found=RanobeLibError("Unexpected 404 from status list")
+        )
+        data: list[dict[str, Any]] = response.json()["data"]["status"]
+        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.11.0 → ranobelib_python_sdk-0.12.0}/src/ranobelib/models.py

@@ -463,6 +463,11 @@ class Title(BaseModel):
     artists: list[Person] = Field(default_factory=list)
     teams: list[Team] = Field(default_factory=list)
     chapter_count: int | None = None
+    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 ``RanobeLib.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."""
 
     @model_validator(mode="before")
     @classmethod
@@ -581,8 +586,9 @@ 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).
+    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).
     """
 
     items: list[Title]

{ranobelib_python_sdk-0.11.0 → ranobelib_python_sdk-0.12.0}/src/ranobelib/sdk.py

@@ -48,6 +48,7 @@ _INFO_FIELDS = [
     "authors",
     "artists",
     "chap_count",
+    "last_item_at",
 ]