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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ranobelib-python-sdk
-Version: 0.11.0
+Version: 0.13.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.13.0}/pyproject.toml

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

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

@@ -1,5 +1,6 @@
 """Async Python SDK for ranobelib.me."""
 
+from ranobelib.cache import CacheStats, cache_stats, clear_cache
 from ranobelib.catalog import Catalog
 from ranobelib.exceptions import (
     AccessBlockedError,
@@ -14,6 +15,7 @@ from ranobelib.exceptions import (
     TitleNotFoundError,
     VolumeNotFoundError,
 )
+from ranobelib.images import chapter_image_urls, rewrite_image_urls
 from ranobelib.models import (
     CatalogPage,
     Chapter,
@@ -21,9 +23,11 @@ from ranobelib.models import (
     Country,
     Footnote,
     Genre,
+    Label,
     Title,
     Volume,
 )
+from ranobelib.paragraphs import chapter_paragraphs
 from ranobelib.sdk import RanobeLib
 from ranobelib.sizing import chapter_size, volume_size
 
@@ -31,6 +35,7 @@ __all__ = [
     "AccessBlockedError",
     "AmbiguousChapter",
     "AuthRequiredError",
+    "CacheStats",
     "Catalog",
     "CatalogPage",
     "Chapter",
@@ -40,6 +45,7 @@ __all__ = [
     "DownloadTitleInterruptedError",
     "Footnote",
     "Genre",
+    "Label",
     "MultipleTitleTranslationsError",
     "MultipleTranslationsError",
     "RanobeLib",
@@ -49,6 +55,11 @@ __all__ = [
     "TitleNotFoundError",
     "Volume",
     "VolumeNotFoundError",
+    "cache_stats",
+    "chapter_image_urls",
+    "chapter_paragraphs",
     "chapter_size",
+    "clear_cache",
+    "rewrite_image_urls",
     "volume_size",
 ]

ranobelib_python_sdk-0.13.0/src/ranobelib/cache.py

@@ -0,0 +1,179 @@
+"""Disk cache for raw JSON API responses, keyed by request identity.
+
+Also the public cache-maintenance helpers, ``cache_stats()`` and ``clear_cache()`` — the
+on-disk layout is an SDK internal, so code outside the SDK should go through these rather
+than measure or delete the cache's files itself.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import time
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+DEFAULT_CACHE_DIR = Path(".ranobelib_cache")
+"""Default cache directory, relative to the current working directory."""
+
+_ENTRY_NAME = re.compile(r"[0-9a-f]{64}\.json")
+"""Name of a file ``DiskCache`` writes (``_path_for``) — anything else in the directory
+isn't the cache's and is never counted or removed."""
+
+
+@dataclass(frozen=True)
+class CacheStats:
+    """How many cache entries there are (or were removed), and their total size on disk."""
+
+    entries: int
+    bytes: int
+
+
+class DiskCache:
+    """Caches JSON-serializable values to disk, keyed by an arbitrary string.
+
+    One file per key, named by the key's hash (so keys built from slugs, chapter numbers,
+    etc. are always safe filenames), holding the cached value plus the time it was written
+    so ``ttl`` can be checked on read without touching any other entry. Corrupted or
+    unreadable entries are treated as a cache miss rather than raised as an error, since a
+    stale/broken cache file shouldn't stop the SDK from just re-fetching the data.
+    """
+
+    def __init__(
+        self,
+        cache_dir: str | Path,
+        *,
+        ttl: float | None = None,
+        clock: Callable[[], float] = time.time,
+    ) -> None:
+        """Initialize the cache.
+
+        Args:
+            cache_dir: Directory to store cache files in. Created lazily on first write.
+            ttl: Seconds after which a cache entry is treated as a miss. ``None`` (the
+                default) means entries never expire.
+            clock: Time source used to stamp and check entries. Overridable for tests.
+        """
+        self._dir = Path(cache_dir)
+        self._ttl = ttl
+        self._clock = clock
+
+    def get(self, key: str) -> Any | None:
+        """Return the cached value for ``key``, or ``None`` on a miss or expiry."""
+        try:
+            payload = json.loads(self._path_for(key).read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError, KeyError):
+            return None
+        if self._ttl is not None and self._clock() - payload["cached_at"] > self._ttl:
+            return None
+        return payload["data"]
+
+    def set(self, key: str, data: Any) -> None:
+        """Write ``data`` to disk under ``key``, creating the cache directory if needed."""
+        path = self._path_for(key)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {"cached_at": self._clock(), "data": data}
+        path.write_text(json.dumps(payload), encoding="utf-8")
+
+    def stats(self) -> CacheStats:
+        """Count the cache's entries and their total size. See ``cache_stats()``."""
+        entries = size = 0
+        for path in self._entry_paths():
+            try:
+                size += path.stat().st_size
+            except OSError:  # Removed since it was listed.
+                continue
+            entries += 1
+        return CacheStats(entries=entries, bytes=size)
+
+    def clear(self, *, older_than: float | None = None) -> CacheStats:
+        """Remove the cache's entries, or only those older than ``older_than`` seconds.
+
+        See ``clear_cache()``.
+        """
+        if older_than is not None and older_than < 0:
+            raise ValueError(f"older_than must be >= 0, got {older_than}")
+        now = self._clock()
+        entries = size = 0
+        for path in self._entry_paths():
+            if older_than is not None and not self._is_older_than(path, now - older_than):
+                continue
+            try:
+                entry_size = path.stat().st_size
+                path.unlink()
+            except OSError:
+                # Already removed by someone else, or (on Windows) open in another process
+                # right now — either way, not ours to count as removed.
+                continue
+            entries += 1
+            size += entry_size
+        return CacheStats(entries=entries, bytes=size)
+
+    def _is_older_than(self, path: Path, cutoff: float) -> bool:
+        try:
+            cached_at = float(json.loads(path.read_text(encoding="utf-8"))["cached_at"])
+        except FileNotFoundError:
+            return False
+        except (OSError, ValueError, KeyError, TypeError):
+            # Unreadable/corrupted: get() can never serve it, so it's as good as expired.
+            return True
+        return cached_at < cutoff
+
+    def _entry_paths(self) -> Iterator[Path]:
+        try:
+            children = list(self._dir.iterdir())
+        except (FileNotFoundError, NotADirectoryError):
+            return
+        for path in children:
+            if _ENTRY_NAME.fullmatch(path.name) and path.is_file() and not path.is_symlink():
+                yield path
+
+    def _path_for(self, key: str) -> Path:
+        digest = hashlib.sha256(key.encode("utf-8")).hexdigest()
+        return self._dir / f"{digest}.json"
+
+
+def cache_stats(cache_dir: str | Path = DEFAULT_CACHE_DIR) -> CacheStats:
+    """Count the entries in an SDK disk cache and their total size on disk.
+
+    Only files the cache itself writes are counted, not anything else that happens to be in
+    the directory.
+
+    Args:
+        cache_dir: The cache directory — the same ``cache_dir`` passed to ``RanobeLib`` /
+            ``Catalog`` (default: theirs, ``.ranobelib_cache`` in the current directory).
+
+    Returns:
+        The number of entries and their total size in bytes. A missing directory is an empty
+        cache, ``CacheStats(entries=0, bytes=0)``, not an error.
+    """
+    return DiskCache(cache_dir).stats()
+
+
+def clear_cache(
+    cache_dir: str | Path = DEFAULT_CACHE_DIR, *, older_than: float | None = None
+) -> CacheStats:
+    """Remove entries from an SDK disk cache.
+
+    Only files the cache itself writes are removed — anything else in the directory, and the
+    directory itself, is left alone. Safe to call while clients are using the same cache: an
+    entry being read as it's removed is just a cache miss, and one written after it's
+    removed is simply recreated.
+
+    Args:
+        cache_dir: The cache directory — see ``cache_stats()``.
+        older_than: If given, only remove entries written more than this many seconds ago
+            (the same age check ``cache_ttl`` uses), plus any corrupted entry, which the
+            cache can't serve anyway. ``None`` (the default) removes every entry.
+
+    Returns:
+        The number of entries removed and the bytes they took. A missing directory removes
+        nothing, ``CacheStats(entries=0, bytes=0)``, rather than raising.
+
+    Raises:
+        ValueError: If ``older_than`` is negative.
+    """
+    return DiskCache(cache_dir).clear(older_than=older_than)

{ranobelib_python_sdk-0.11.0 → ranobelib_python_sdk-0.13.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.13.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.13.0}/src/ranobelib/exporters/_illustrations.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import asyncio
 import html
+from collections.abc import Callable
 from html.parser import HTMLParser
 from pathlib import Path
 from urllib.parse import urlsplit
@@ -62,7 +63,7 @@ def extract_image_urls(html_fragment: str) -> list[str]:
 
 
 class _ImageSrcRewriter(HTMLParser):
-    """Re-emits chapter-content HTML with ``<img src="...">`` URLs replaced per a mapping.
+    """Re-emits chapter-content HTML with each ``<img src="...">`` passed through a function.
 
     Rebuilds the markup tag-by-tag (rather than a targeted regex substitution) for the same
     reason the txt/fb2 exporters use ``HTMLParser`` over regex: HTML-string-format chapters
@@ -71,15 +72,13 @@ class _ImageSrcRewriter(HTMLParser):
     for epub, WeasyPrint's own HTML parser for pdf) are lenient enough not to need strict
     XHTML here.
 
-    An ``<img>`` whose URL isn't in ``url_to_local`` (download failed or was never
-    attempted) is dropped entirely rather than kept pointing at the original external URL —
-    a dangling absolute-URL reference isn't a self-contained embed, just a broken-looking
-    image in most consumers, so "not embedded" reads as "not present" instead.
+    ``replace`` gets each ``<img>``'s ``src`` (``""`` if it has none) and returns the new
+    value, or ``None`` to drop that ``<img>`` entirely.
     """
 
-    def __init__(self, url_to_local: dict[str, str]) -> None:
+    def __init__(self, replace: Callable[[str], str | None]) -> None:
         super().__init__(convert_charrefs=True)
-        self._url_to_local = url_to_local
+        self._replace = replace
         self._output: list[str] = []
 
     def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
@@ -90,10 +89,10 @@ class _ImageSrcRewriter(HTMLParser):
 
     def _emit(self, tag: str, attrs: list[tuple[str, str | None]], *, self_closing: bool) -> None:
         if tag == "img":
-            local_src = self._url_to_local.get(dict(attrs).get("src") or "")
-            if local_src is None:
+            new_src = self._replace(dict(attrs).get("src") or "")
+            if new_src is None:
                 return
-            attrs = [(name, local_src if name == "src" else value) for name, value in attrs]
+            attrs = [(name, new_src if name == "src" else value) for name, value in attrs]
 
         parts = [f"<{tag}"]
         for name, value in attrs:
@@ -115,13 +114,27 @@ class _ImageSrcRewriter(HTMLParser):
         return "".join(self._output)
 
 
-def rewrite_image_srcs(html_fragment: str, url_to_local: dict[str, str]) -> str:
-    """Rewrite ``<img src="...">`` URLs in ``html_fragment`` per ``url_to_local``."""
-    rewriter = _ImageSrcRewriter(url_to_local)
+def replace_image_srcs(html_fragment: str, replace: Callable[[str], str | None]) -> str:
+    """Pass every ``<img src="...">`` in ``html_fragment`` through ``replace``.
+
+    ``replace`` returns the new ``src``, or ``None`` to drop that ``<img>``.
+    """
+    rewriter = _ImageSrcRewriter(replace)
     rewriter.feed(html_fragment)
     return rewriter.get_html()
 
 
+def rewrite_image_srcs(html_fragment: str, url_to_local: dict[str, str]) -> str:
+    """Rewrite ``<img src="...">`` URLs in ``html_fragment`` per ``url_to_local``.
+
+    An ``<img>`` whose URL isn't in ``url_to_local`` (download failed or was never
+    attempted) is dropped entirely rather than kept pointing at the original external URL —
+    a dangling absolute-URL reference isn't a self-contained embed, just a broken-looking
+    image in most consumers, so "not embedded" reads as "not present" instead.
+    """
+    return replace_image_srcs(html_fragment, url_to_local.get)
+
+
 def pick_cover_url(cover: Cover) -> str | None:
     """The best available cover URL, preferring the largest: default, then md, then thumbnail."""
     return cover.default or cover.md or cover.thumbnail

ranobelib_python_sdk-0.13.0/src/ranobelib/images.py

@@ -0,0 +1,73 @@
+"""Listing and rewriting the images a fetched chapter references.
+
+Chapter illustrations are ``<img>`` tags with absolute URLs on ranobelib.me /
+``*.cdnlibs.org`` (see docs/api-notes.md), inside ``Chapter.content`` and, occasionally,
+``Chapter.footnotes``. These helpers expose the same ``<img>`` parsing the epub/pdf
+exporters and ``sizing.chapter_size()`` use internally, so a caller that serves chapters
+itself (e.g. through its own same-origin image proxy, for offline caching) doesn't need a
+second HTML parser of its own.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from ranobelib.exporters._illustrations import extract_image_urls, replace_image_srcs
+from ranobelib.models import Chapter, Footnote
+
+
+def _require_content(chapter: Chapter) -> str:
+    if chapter.content is None:
+        raise ValueError(
+            f"Chapter {chapter.volume}/{chapter.number} has no content — "
+            "fetch it first, e.g. via get_chapter()."
+        )
+    return chapter.content
+
+
+def chapter_image_urls(chapter: Chapter) -> list[str]:
+    """List the image URLs a fetched chapter references.
+
+    Args:
+        chapter: A chapter with content already fetched (e.g. via ``get_chapter()``).
+
+    Returns:
+        Every ``<img src>`` in ``chapter.content`` and then ``chapter.footnotes``, in
+        document order, each URL listed once (its first occurrence).
+
+    Raises:
+        ValueError: If ``chapter.content`` is ``None`` (not yet fetched — see ``Chapter``'s
+            docstring for when that happens).
+    """
+    fragments = [_require_content(chapter), *(footnote.content for footnote in chapter.footnotes)]
+    urls = (url for fragment in fragments for url in extract_image_urls(fragment))
+    return list(dict.fromkeys(urls))
+
+
+def rewrite_image_urls(chapter: Chapter, replace: Callable[[str], str]) -> Chapter:
+    """Return a copy of a fetched chapter with every ``<img src>`` passed through ``replace``.
+
+    Args:
+        chapter: A chapter with content already fetched (e.g. via ``get_chapter()``).
+        replace: Called with each image URL (once per ``<img>``, so possibly more than once
+            for the same URL); its result becomes the new ``src``, HTML-escaped as an
+            attribute value. An ``<img>`` without a ``src`` is left as it is.
+
+    Returns:
+        A new ``Chapter`` whose ``content`` and ``footnotes`` have their ``<img src>``
+        rewritten; every other field is unchanged, and ``chapter`` itself is not modified.
+
+    Raises:
+        ValueError: If ``chapter.content`` is ``None`` — see ``chapter_image_urls()``.
+    """
+    content = _require_content(chapter)
+
+    def rewrite(fragment: str) -> str:
+        return replace_image_srcs(fragment, lambda src: replace(src) if src else src)
+
+    return chapter.model_copy(
+        update={
+            "content": rewrite(content),
+            "footnotes": [Footnote(content=rewrite(f.content)) for f in chapter.footnotes],
+        }
+    )

{ranobelib_python_sdk-0.11.0 → ranobelib_python_sdk-0.13.0}/src/ranobelib/models.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import html
+import re
 from datetime import datetime
 from html.parser import HTMLParser
 from typing import Any
@@ -438,6 +439,28 @@ class Team(BaseModel):
     name: str
 
 
+_FORMAT_WORD = (
+    r"(?:(?:light|lite|web|лайт|веб|вэб)\s*-?\s*)?(?:novel(?:la|l|a)?|новелл?а)"
+    r"|web\s*-?\s*serial|ranobe|ранобэ|ln|wn|лн|quest|квест"
+)
+_FORMAT_SUFFIX = re.compile(
+    rf"[\s,:/]*(?:\(\s*(?:{_FORMAT_WORD})\s*\)|\[\s*(?:{_FORMAT_WORD})\s*\])\s*$",
+    re.IGNORECASE,
+)
+"""A publication-format marker at the end of a title name — ``(Новелла)``, ``(Novel)``,
+``(LN)``, ``[квест]``, ... — plus the separator (``,``/``:``/``/``) sometimes left before it.
+The word list comes from every name in the live catalog (see docs/api-notes.md, "Title
+names without the format suffix"); other bracketed tails (a year, ``(18+)``, ``(Фанфик)``,
+``[LitRPG]``, a franchise) tell titles apart, so they're not on it."""
+
+
+def _strip_format_suffix(name: str) -> str:
+    """``name`` without its trailing format marker(s) — they can stack: ``(LN) (Novel)``."""
+    while (match := _FORMAT_SUFFIX.search(name)) is not None:
+        name = name[: match.start()]
+    return name.strip()
+
+
 class Title(BaseModel):
     """Metadata for a single title (novel)."""
 
@@ -463,6 +486,34 @@ class Title(BaseModel):
     artists: list[Person] = Field(default_factory=list)
     teams: list[Team] = Field(default_factory=list)
     chapter_count: int | None = None
+    """Number of uploaded chapters. 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."""
+    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."""
+
+    @property
+    def base_names(self) -> list[str]:
+        """The title's names without the format suffix ranobelib.me appends to them.
+
+        ``rus_name``, ``eng_name``, ``name`` and ``other_names``, in that order, each with
+        trailing publication-format markers removed — ``"Старшая школа D×D (Новелла)"`` →
+        ``"Старшая школа D×D"``, likewise ``(Novel)``, ``(LN)``, ``(WN)``, ``(Light Novel)``,
+        ``(Ранобэ)``, ``[квест]``, ... (stacked ones too, ``(LN) (Novel)``). Other bracketed
+        tails — a year, ``(18+)``, ``(Фанфик)``, ``[LitRPG]``, a franchise name — distinguish
+        one title from another and are kept. Whitespace is trimmed; empty names and
+        duplicates (keeping the first) are dropped. Nothing else is normalized (case,
+        punctuation, ``×``): that's up to whatever compares the names.
+
+        The original fields are left as they are. On ``Catalog.list_titles()`` items
+        ``other_names`` is empty (the listing doesn't return it), so it contributes nothing.
+        """
+        names = [self.rus_name, self.eng_name, self.name, *self.other_names]
+        stripped = (_strip_format_suffix(name) for name in names if name)
+        return list(dict.fromkeys(name for name in stripped if name))
 
     @model_validator(mode="before")
     @classmethod
@@ -581,8 +632,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.13.0/src/ranobelib/paragraphs.py

@@ -0,0 +1,85 @@
+"""A fetched chapter's top-level blocks as plain text, indexed like the DOM.
+
+``Chapter.content`` is a flat, sanitized sequence of block-level elements (``<p>``,
+``<hr />``, ``<img>`` — see ``Chapter``), so a client rendering it as HTML sees one child
+element per block. ``chapter_paragraphs()`` gives each of those blocks' text at the same
+index, so e.g. a comment keyed by a paragraph's position in the reader's DOM
+(``content.children[i]``) can be shown next to that paragraph's text without a second HTML
+parser on the caller's side.
+"""
+
+from __future__ import annotations
+
+from html.parser import HTMLParser
+
+from ranobelib.models import Chapter
+
+_VOID_TAGS = frozenset({"br", "hr", "img"})
+
+
+class _TopLevelTextCollector(HTMLParser):
+    """Collects the text of each top-level element of an HTML fragment, in order.
+
+    Every start tag at depth 0 begins a new entry, void ones (``br``/``hr``/``img``)
+    included, since each is an element child in the DOM too. Text outside any element at the
+    top level isn't an entry (it's a text node, not an element child) and is ignored. A
+    ``<br />`` inside an entry separates words, like a space.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self._depth = 0
+        self.entries: list[list[str]] = []
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if self._depth == 0:
+            self.entries.append([])
+        if tag in _VOID_TAGS:
+            if self._depth > 0:
+                self.entries[-1].append(" ")
+        else:
+            self._depth += 1
+
+    def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        self.handle_starttag(tag, attrs)
+        if tag not in _VOID_TAGS:
+            self.handle_endtag(tag)
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag not in _VOID_TAGS and self._depth > 0:
+            self._depth -= 1
+
+    def handle_data(self, data: str) -> None:
+        if self._depth > 0:
+            self.entries[-1].append(data)
+
+
+def chapter_paragraphs(chapter: Chapter) -> list[str]:
+    """A fetched chapter's top-level blocks as plain text, in document order.
+
+    Entry ``i`` is the text of the ``i``-th top-level element of ``chapter.content`` — the
+    same position a browser gives it among the rendered content's element children — so a
+    paragraph index counted in the DOM can be used to look it up directly.
+
+    Args:
+        chapter: A chapter with content already fetched (e.g. via ``get_chapter()``).
+
+    Returns:
+        One string per top-level element: its text with entities decoded and whitespace
+        collapsed to single spaces (``""`` for a block without text, such as ``<hr />`` or
+        an image-only paragraph). ``chapter.footnotes`` aren't included — they're not part
+        of ``content`` (see ``Chapter.footnotes``).
+
+    Raises:
+        ValueError: If ``chapter.content`` is ``None`` (not yet fetched — see ``Chapter``'s
+            docstring for when that happens).
+    """
+    if chapter.content is None:
+        raise ValueError(
+            f"Chapter {chapter.volume}/{chapter.number} has no content — "
+            "fetch it first, e.g. via get_chapter()."
+        )
+    collector = _TopLevelTextCollector()
+    collector.feed(chapter.content)
+    collector.close()
+    return [" ".join("".join(parts).split()) for parts in collector.entries]

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

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

ranobelib_python_sdk-0.11.0/src/ranobelib/cache.py

@@ -1,64 +0,0 @@
-"""Disk cache for raw JSON API responses, keyed by request identity."""
-
-from __future__ import annotations
-
-import hashlib
-import json
-import time
-from collections.abc import Callable
-from pathlib import Path
-from typing import Any
-
-DEFAULT_CACHE_DIR = Path(".ranobelib_cache")
-"""Default cache directory, relative to the current working directory."""
-
-
-class DiskCache:
-    """Caches JSON-serializable values to disk, keyed by an arbitrary string.
-
-    One file per key, named by the key's hash (so keys built from slugs, chapter numbers,
-    etc. are always safe filenames), holding the cached value plus the time it was written
-    so ``ttl`` can be checked on read without touching any other entry. Corrupted or
-    unreadable entries are treated as a cache miss rather than raised as an error, since a
-    stale/broken cache file shouldn't stop the SDK from just re-fetching the data.
-    """
-
-    def __init__(
-        self,
-        cache_dir: str | Path,
-        *,
-        ttl: float | None = None,
-        clock: Callable[[], float] = time.time,
-    ) -> None:
-        """Initialize the cache.
-
-        Args:
-            cache_dir: Directory to store cache files in. Created lazily on first write.
-            ttl: Seconds after which a cache entry is treated as a miss. ``None`` (the
-                default) means entries never expire.
-            clock: Time source used to stamp and check entries. Overridable for tests.
-        """
-        self._dir = Path(cache_dir)
-        self._ttl = ttl
-        self._clock = clock
-
-    def get(self, key: str) -> Any | None:
-        """Return the cached value for ``key``, or ``None`` on a miss or expiry."""
-        try:
-            payload = json.loads(self._path_for(key).read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError, KeyError):
-            return None
-        if self._ttl is not None and self._clock() - payload["cached_at"] > self._ttl:
-            return None
-        return payload["data"]
-
-    def set(self, key: str, data: Any) -> None:
-        """Write ``data`` to disk under ``key``, creating the cache directory if needed."""
-        path = self._path_for(key)
-        path.parent.mkdir(parents=True, exist_ok=True)
-        payload = {"cached_at": self._clock(), "data": data}
-        path.write_text(json.dumps(payload), encoding="utf-8")
-
-    def _path_for(self, key: str) -> Path:
-        digest = hashlib.sha256(key.encode("utf-8")).hexdigest()
-        return self._dir / f"{digest}.json"