ranobelib-python-sdk 0.6.1__tar.gz → 0.8.0__tar.gz

{ranobelib_python_sdk-0.6.1 → ranobelib_python_sdk-0.8.0}/PKG-INFO

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

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

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

@@ -13,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, Country, Genre, Title, Volume
 from ranobelib.sdk import RanobeLib
 from ranobelib.sizing import chapter_size, volume_size
 
@@ -25,7 +25,9 @@ __all__ = [
     "Chapter",
     "ChapterBranch",
     "ChapterNotFoundError",
+    "Country",
     "DownloadTitleInterruptedError",
+    "Genre",
     "MultipleTitleTranslationsError",
     "MultipleTranslationsError",
     "RanobeLib",

{ranobelib_python_sdk-0.6.1 → ranobelib_python_sdk-0.8.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, Country, Genre, Title
 
 DEFAULT_SORT = "last_chapter_at"
 """Default sort order: title's last-chapter timestamp — the closest real equivalent to
@@ -79,7 +79,9 @@ class Catalog:
         per_page: int = 30,
         query: str | None = None,
         genres: list[int] | None = None,
+        tags: list[int] | None = None,
         status: int | None = None,
+        country: int | None = None,
         sort: str = DEFAULT_SORT,
         refresh: bool = False,
     ) -> CatalogPage:
@@ -94,10 +96,19 @@ 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.
+            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``.
             status: A single ``Title.status.id`` to filter by (e.g. ongoing vs. completed).
+            country: A single ``Country.id`` to filter by — a title only has one country of
+                origin, unlike ``genres``. 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).
             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"``,
@@ -123,7 +134,14 @@ class Catalog:
             )
 
         key = _cache_key(
-            page=page, per_page=per_page, query=query, genres=genres, status=status, sort=sort
+            page=page,
+            per_page=per_page,
+            query=query,
+            genres=genres,
+            tags=tags,
+            status=status,
+            country=country,
+            sort=sort,
         )
         if not refresh:
             cached = self._cache.get(key)
@@ -131,11 +149,73 @@ class Catalog:
                 return _build_page(cached)
 
         data = await self._client.list_titles(
-            page=page, per_page=per_page, query=query, genres=genres, status=status, sort=sort
+            page=page,
+            per_page=per_page,
+            query=query,
+            genres=genres,
+            tags=tags,
+            status=status,
+            country=country,
+            sort=sort,
         )
         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)
+
+    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(country=...)``.
+
+        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 ranobelib.me
+        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 ranobelib.me.
+        """
+        key = "catalog:countries"
+        if not refresh:
+            cached = self._cache.get(key)
+            if cached is not None:
+                return _build_countries(cached)
+
+        data = await self._client.list_countries()
+        self._cache.set(key, data)
+        return _build_countries(data)
+
 
 def _cache_key(
     *,
@@ -143,14 +223,30 @@ def _cache_key(
     per_page: int,
     query: str | None,
     genres: list[int] | None,
+    tags: list[int] | None,
     status: int | None,
+    country: 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}"
+    tags_part = ",".join(str(tag_id) for tag_id in tags or [])
+    return (
+        f"catalog:{page}:{per_page}:{query or ''}:{genres_part}:{tags_part}:"
+        f"{status}:{country}:{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"])
+
+
+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", [])]
+
+
+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", [])]

{ranobelib_python_sdk-0.6.1 → ranobelib_python_sdk-0.8.0}/src/ranobelib/client.py

@@ -170,7 +170,9 @@ class ApiClient:
         per_page: int,
         query: str | None,
         genres: list[int] | None,
+        tags: list[int] | None,
         status: int | None,
+        country: int | None,
         sort: str,
     ) -> dict[str, Any]:
         """Fetch one page of the catalog listing/search results.
@@ -187,7 +189,12 @@ class ApiClient:
                 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.
+            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.
+            country: A single ``Country.id`` to filter by. Sent on the wire as ``types[]``
+                (repeatable array parameter, but only ever given one value here) — the API's
+                own name for this concept is "type", not "country" (see docs/api-notes.md).
             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
@@ -206,8 +213,12 @@ class ApiClient:
             params.append(("q", query))
         for genre_id in genres or []:
             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)))
+        if country is not None:
+            params.append(("types[]", str(country)))
 
         response = await self._get("/manga", params=httpx.QueryParams(params))
         self._raise_for_status(
@@ -217,6 +228,41 @@ 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 list_countries(self) -> list[dict[str, Any]]:
+        """Fetch the raw country/type list shared across the whole lib.social network.
+
+        Same shape and caveats as ``list_genres``: not site-scoped by any request parameter,
+        returns every "type" known to the network at once, each tagged with the site ids it
+        applies to via ``site_ids``. Named ``list_countries``/``fields[]=types`` mismatch is
+        deliberate — see ``Catalog.list_countries`` and docs/api-notes.md for why this reuses
+        the API's own "type" concept rather than the unrelated ``fields[]=countries`` field.
+
+        Returns:
+            The raw ``data.types`` array from the API response, unfiltered by site.
+        """
+        response = await self._get("/constants", params=httpx.QueryParams([("fields[]", "types")]))
+        self._raise_for_status(response, not_found=RanobeLibError("Unexpected 404 from type list"))
+        data: list[dict[str, Any]] = response.json()["data"]["types"]
+        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.1 → ranobelib_python_sdk-0.8.0}/src/ranobelib/models.py

@@ -206,6 +206,25 @@ class Tag(BaseModel):
     adult: bool = False
 
 
+class Country(BaseModel):
+    """A title's country/region of origin.
+
+    Despite the name (matching issue #48's requested public shape), this 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). For ranobelib.me specifically, the values are three literal
+    countries (Japan, Korea, China) plus three additional non-national origin categories the
+    site groups the same way: original English-language work, original (non-translated) web
+    novel, and fanfiction — surfaced as-is, not filtered down to "real" countries only.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: int
+    name: str = Field(alias="label")
+
+
 class Person(BaseModel):
     """An author or artist credited on a title."""
 
@@ -243,6 +262,7 @@ class Title(BaseModel):
     summary: str | None = None
     release_date: str | None = Field(default=None, alias="releaseDate")
     is_licensed: bool = False
+    country: Country | None = Field(default=None, alias="type")
     genres: list[Genre] = Field(default_factory=list)
     tags: list[Tag] = Field(default_factory=list)
     authors: list[Person] = Field(default_factory=list)