ranobelib-python-sdk 0.1.0__py3-none-any.whl

ranobelib/__init__.py

@@ -0,0 +1,28 @@
+"""Async Python SDK for ranobelib.me."""
+
+from ranobelib.exceptions import (
+    AuthRequiredError,
+    ChapterNotFoundError,
+    MultipleTranslationsError,
+    RanobeLibError,
+    RateLimitError,
+    TitleNotFoundError,
+    VolumeNotFoundError,
+)
+from ranobelib.models import Chapter, ChapterBranch, Title, Volume
+from ranobelib.sdk import RanobeLib
+
+__all__ = [
+    "AuthRequiredError",
+    "Chapter",
+    "ChapterBranch",
+    "ChapterNotFoundError",
+    "MultipleTranslationsError",
+    "RanobeLib",
+    "RanobeLibError",
+    "RateLimitError",
+    "Title",
+    "TitleNotFoundError",
+    "Volume",
+    "VolumeNotFoundError",
+]

ranobelib/cache.py

@@ -0,0 +1,64 @@
+"""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"

ranobelib/client.py

@@ -0,0 +1,210 @@
+"""Low-level HTTP client for the api.cdnlibs.org JSON API."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Awaitable, Callable
+from types import TracebackType
+from typing import Any, Self
+
+import httpx
+
+from ranobelib.exceptions import (
+    AuthRequiredError,
+    ChapterNotFoundError,
+    RanobeLibError,
+    RateLimitError,
+    TitleNotFoundError,
+)
+
+API_BASE_URL = "https://api.cdnlibs.org/api"
+"""Base URL of the lib.social JSON API shared across the network's sites."""
+
+RANOBELIB_SITE_ID = "3"
+"""``Site-Id`` header value that scopes requests to ranobelib.me. See docs/api-notes.md."""
+
+_RETRYABLE_STATUSES = frozenset({429, *range(500, 600)})
+
+DEFAULT_REQUEST_DELAY = 0.2
+"""Default minimum time, in seconds, between the start of one request and the next."""
+
+
+class ApiClient:
+    """Thin async wrapper around the undocumented api.cdnlibs.org JSON API.
+
+    Bounds concurrency with a semaphore, paces request starts with a small fixed delay, and
+    retries 429/5xx responses with exponential backoff — see docs/api-notes.md for why a
+    manual implementation was chosen over a dependency like ``tenacity`` for this.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str = API_BASE_URL,
+        timeout: float = 15.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+        max_concurrency: int = 5,
+        request_delay: float | None = None,
+        max_retries: int = 3,
+        retry_base_delay: float = 1.0,
+        sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        """Initialize the client.
+
+        Args:
+            base_url: API base URL.
+            timeout: Per-request timeout, in seconds.
+            transport: Custom ``httpx`` transport, e.g. a mock transport for tests.
+            max_concurrency: Maximum number of requests in flight at once.
+            request_delay: Minimum time, in seconds, between the start of one request and
+                the next, even under ``max_concurrency``. ``None`` (the default) uses
+                ``DEFAULT_REQUEST_DELAY``.
+            max_retries: How many times to retry a 429 or 5xx response before giving up and
+                raising.
+            retry_base_delay: Base delay, in seconds, for exponential backoff between
+                retries (doubled per attempt) — used unless a 429 response's
+                ``Retry-After`` header says otherwise.
+            sleep: Sleep function used for pacing and backoff. Overridable for tests.
+            clock: Time source used for pacing. Overridable for tests.
+        """
+        self._http = httpx.AsyncClient(
+            base_url=base_url,
+            timeout=timeout,
+            transport=transport,
+            headers={
+                "Site-Id": RANOBELIB_SITE_ID,
+                "Accept": "application/json",
+            },
+        )
+        self._semaphore = asyncio.Semaphore(max_concurrency)
+        self._request_delay = DEFAULT_REQUEST_DELAY if request_delay is None else request_delay
+        self._max_retries = max_retries
+        self._retry_base_delay = retry_base_delay
+        self._sleep = sleep
+        self._clock = clock
+        self._pacing_lock = asyncio.Lock()
+        self._last_request_at: float | None = None
+
+    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 connection pool."""
+        await self._http.aclose()
+
+    async def get_title(self, slug_url: str, *, fields: list[str] | None = None) -> dict[str, Any]:
+        """Fetch raw title metadata for ``slug_url``.
+
+        Args:
+            slug_url: The title's ``{id}--{slug}`` identifier.
+            fields: Extra ``fields[]`` values to request from the API.
+
+        Returns:
+            The ``data`` object from the API response.
+        """
+        params = httpx.QueryParams([("fields[]", field) for field in fields or []])
+        response = await self._get(f"/manga/{slug_url}", params=params)
+        self._raise_for_status(response, not_found=TitleNotFoundError(slug_url))
+        data: dict[str, Any] = response.json()["data"]
+        return data
+
+    async def get_chapters(self, slug_url: str) -> list[dict[str, Any]]:
+        """Fetch the raw chapter list for ``slug_url`` (single request, no pagination).
+
+        Args:
+            slug_url: The title's ``{id}--{slug}`` identifier.
+
+        Returns:
+            The ``data`` array from the API response.
+        """
+        response = await self._get(f"/manga/{slug_url}/chapters")
+        self._raise_for_status(response, not_found=TitleNotFoundError(slug_url))
+        data: list[dict[str, Any]] = response.json()["data"]
+        return data
+
+    async def get_chapter(
+        self,
+        slug_url: str,
+        *,
+        number: str,
+        volume: str,
+        branch_id: int | None = None,
+    ) -> dict[str, Any]:
+        """Fetch a single chapter's metadata and content.
+
+        Args:
+            slug_url: The title's ``{id}--{slug}`` identifier.
+            number: The chapter number, as returned by the API (may contain a decimal).
+            volume: The volume number.
+            branch_id: Which translation team's branch to fetch, for chapters with more
+                than one. Defaults to whichever branch the API picks (see
+                docs/api-notes.md — this is not simply the first branch listed).
+
+        Returns:
+            The ``data`` object from the API response.
+        """
+        params = {"number": number, "volume": volume}
+        if branch_id is not None:
+            params["branch_id"] = str(branch_id)
+        response = await self._get(f"/manga/{slug_url}/chapter", params=params)
+        self._raise_for_status(
+            response, not_found=ChapterNotFoundError(slug_url, volume=volume, number=number)
+        )
+        data: dict[str, Any] = response.json()["data"]
+        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
+        while True:
+            async with self._semaphore:
+                await self._pace()
+                response = await self._http.get(url, params=params)
+            if response.status_code not in _RETRYABLE_STATUSES or attempt >= self._max_retries:
+                return response
+            await self._sleep(self._backoff_delay(attempt, response))
+            attempt += 1
+
+    async def _pace(self) -> None:
+        """Wait, if needed, so this request starts at least ``request_delay`` after the last."""
+        async with self._pacing_lock:
+            now = self._clock()
+            if self._last_request_at is not None:
+                wait = self._last_request_at + self._request_delay - now
+                if wait > 0:
+                    await self._sleep(wait)
+            self._last_request_at = self._clock()
+
+    def _backoff_delay(self, attempt: int, response: httpx.Response) -> float:
+        if response.status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            if retry_after is not None:
+                try:
+                    return float(retry_after)
+                except ValueError:
+                    pass
+        delay: float = self._retry_base_delay * (2**attempt)
+        return delay
+
+    def _raise_for_status(self, response: httpx.Response, *, not_found: RanobeLibError) -> None:
+        if response.status_code == 404:
+            raise not_found
+        if response.status_code == 403:
+            raise AuthRequiredError(str(response.request.url))
+        if response.status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            raise RateLimitError(float(retry_after) if retry_after else None)
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            raise RanobeLibError(f"Unexpected API response: {exc}") from exc

ranobelib/exceptions.py

@@ -0,0 +1,118 @@
+"""Custom exceptions raised by the SDK."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ranobelib.models import ChapterBranch
+
+
+class RanobeLibError(Exception):
+    """Base class for all errors raised by the SDK."""
+
+
+class TitleNotFoundError(RanobeLibError):
+    """Raised when a title cannot be found on ranobelib.me.
+
+    Attributes:
+        slug_url: The title's ``{id}--{slug}`` identifier that couldn't be found.
+    """
+
+    def __init__(self, slug_url: str) -> None:
+        self.slug_url = slug_url
+        super().__init__(f"Title not found: {slug_url!r}")
+
+
+class ChapterNotFoundError(RanobeLibError):
+    """Raised when a chapter cannot be found for a given volume/number.
+
+    Attributes:
+        slug_url: The title's ``{id}--{slug}`` identifier.
+        volume: The volume number that was requested.
+        number: The chapter number that was requested.
+    """
+
+    def __init__(self, slug_url: str, *, volume: str, number: str) -> None:
+        self.slug_url = slug_url
+        self.volume = volume
+        self.number = number
+        super().__init__(f"Chapter not found: {slug_url!r} volume={volume!r} number={number!r}")
+
+
+class VolumeNotFoundError(RanobeLibError):
+    """Raised when a title has no chapters for a given volume number.
+
+    Attributes:
+        slug_url: The title's ``{id}--{slug}`` identifier.
+        volume: The volume number that was requested.
+    """
+
+    def __init__(self, slug_url: str, *, volume: str) -> None:
+        self.slug_url = slug_url
+        self.volume = volume
+        super().__init__(f"Volume not found: {slug_url!r} volume={volume!r}")
+
+
+class MultipleTranslationsError(RanobeLibError):
+    """Raised when a chapter has more than one team's translation and none was selected.
+
+    The SDK does not guess a default: the API's own default when ``branch_id`` is omitted
+    is not simply the first branch listed, and the actual rule it uses isn't documented
+    (see docs/api-notes.md) — returning it silently would be unpredictable. Call
+    ``RanobeLib.get_translations()`` to list the available branches, then pass one's
+    ``branch_id`` explicitly.
+
+    Attributes:
+        slug_url: The title's ``{id}--{slug}`` identifier.
+        volume: The chapter's volume number.
+        number: The chapter number.
+        branches: The chapter's available translations, as returned by
+            ``RanobeLib.get_translations()``.
+    """
+
+    def __init__(
+        self, slug_url: str, *, volume: str, number: str, branches: list[ChapterBranch]
+    ) -> None:
+        self.slug_url = slug_url
+        self.volume = volume
+        self.number = number
+        self.branches = branches
+        options = ", ".join(
+            f"branch_id={branch.branch_id} ({_describe_branch(branch)})" for branch in branches
+        )
+        super().__init__(
+            f"Multiple translations for {slug_url!r} volume={volume!r} number={number!r}: "
+            f"{options}. Pass branch_id to select one (see RanobeLib.get_translations())."
+        )
+
+
+def _describe_branch(branch: ChapterBranch) -> str:
+    if branch.teams:
+        return ", ".join(team.name for team in branch.teams)
+    return branch.user.username
+
+
+class AuthRequiredError(RanobeLibError):
+    """Raised when the requested content requires authorization (paid or early access).
+
+    Attributes:
+        url: The request URL that returned 403.
+    """
+
+    def __init__(self, url: str) -> None:
+        self.url = url
+        super().__init__(f"Authorization required to access: {url}")
+
+
+class RateLimitError(RanobeLibError):
+    """Raised when the API responds with 429 Too Many Requests.
+
+    Attributes:
+        retry_after: The response's ``Retry-After`` value, in seconds, if it sent one.
+    """
+
+    def __init__(self, retry_after: float | None = None) -> None:
+        self.retry_after = retry_after
+        suffix = f" (retry after {retry_after}s)" if retry_after is not None else ""
+        super().__init__(f"Rate limited by the API{suffix}")

ranobelib/exporters/__init__.py

@@ -0,0 +1,56 @@
+"""Exporter protocol and format registry.
+
+A new export format is a new module in this package: define a class implementing
+``Exporter`` and decorate it with ``@register`` — no changes needed here or in ``sdk.py``.
+Every module in this package is auto-imported below so its ``@register`` runs on its own.
+"""
+
+from __future__ import annotations
+
+import importlib
+import pkgutil
+from pathlib import Path
+from typing import ClassVar, Protocol, TypeVar, runtime_checkable
+
+from ranobelib.models import Chapter, Title
+
+
+@runtime_checkable
+class Exporter(Protocol):
+    """Renders a title's chapters to a single file in some format."""
+
+    format: ClassVar[str]
+    """The registry key this exporter is selected by, e.g. ``"txt"``."""
+
+    async def export(self, title: Title, chapters: list[Chapter], output_path: Path) -> Path:
+        """Write ``chapters`` (in the given order) to ``output_path``.
+
+        ``async`` since embedding illustrations (epub, pdf) requires downloading them —
+        the SDK is async-only throughout (see CLAUDE.md), so this can't drop to a sync
+        HTTP call. txt/fb2 do no I/O and just don't ``await`` anything in their bodies.
+
+        Args:
+            title: The chapters' parent title, for metadata (name, authors, ...).
+            chapters: The chapters to include, in the order they should appear.
+            output_path: Where to write the exported file.
+
+        Returns:
+            ``output_path``, once the file has been written.
+        """
+        ...
+
+
+ExporterT = TypeVar("ExporterT", bound=type[Exporter])
+
+EXPORTERS: dict[str, type[Exporter]] = {}
+"""Registered exporters, keyed by ``Exporter.format``."""
+
+
+def register(exporter: ExporterT) -> ExporterT:
+    """Class decorator: register ``exporter`` under its ``format`` key."""
+    EXPORTERS[exporter.format] = exporter
+    return exporter
+
+
+for _module_info in pkgutil.iter_modules(__path__, f"{__name__}."):
+    importlib.import_module(_module_info.name)

ranobelib/exporters/_illustrations.py

@@ -0,0 +1,170 @@
+"""Illustration handling shared between exporters that embed images (epub, pdf).
+
+Not part of the public Exporter protocol. Chapter content's ``<img>`` tags carry absolute
+URLs (see docs/api-notes.md); embedding them means downloading the bytes and rewriting each
+``src`` to wherever the target format keeps embedded resources (a local file inside an epub
+zip, a ``data:`` URI inline in an HTML string for pdf) — everything up to that last,
+format-specific rewrite step is identical between the two, hence living here once.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import html
+from html.parser import HTMLParser
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import httpx
+
+from ranobelib.models import Cover
+
+_VOID_TAGS = frozenset({"br", "hr", "img"})
+
+_MEDIA_TYPES = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+}
+_DEFAULT_EXTENSION = ".jpg"
+
+IMAGE_CONCURRENCY = 5
+"""Same conservative default as ApiClient's max_concurrency (see client.py) — these are a
+different host (site/CDN uploads, not api.cdnlibs.org) with unknown rate limits of their
+own, so this doesn't reuse ApiClient's own semaphore/retry machinery, just a plain cap.
+A failed download is skipped rather than retried: embedding is best-effort, one broken
+image shouldn't fail the whole export."""
+
+
+class _ImageUrlCollector(HTMLParser):
+    """Collects every ``<img src="...">`` URL referenced in a chapter-content HTML fragment."""
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.urls: list[str] = []
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag == "img":
+            src = dict(attrs).get("src")
+            if src:
+                self.urls.append(src)
+
+    handle_startendtag = handle_starttag
+
+
+def extract_image_urls(html_fragment: str) -> list[str]:
+    """List the ``<img src="...">`` URLs referenced in a chapter-content HTML fragment."""
+    collector = _ImageUrlCollector()
+    collector.feed(html_fragment)
+    return collector.urls
+
+
+class _ImageSrcRewriter(HTMLParser):
+    """Re-emits chapter-content HTML with ``<img src="...">`` URLs replaced per a mapping.
+
+    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
+    pass the site's own markup through as-is (see docs/api-notes.md). Everything other than
+    ``img`` passes through unchanged; both consumers (ebooklib's ``lxml.html``-based parser
+    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.
+    """
+
+    def __init__(self, url_to_local: dict[str, str]) -> None:
+        super().__init__(convert_charrefs=True)
+        self._url_to_local = url_to_local
+        self._output: list[str] = []
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        self._emit(tag, attrs, self_closing=tag in _VOID_TAGS)
+
+    def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        self._emit(tag, attrs, self_closing=True)
+
+    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:
+                return
+            attrs = [(name, local_src if name == "src" else value) for name, value in attrs]
+
+        parts = [f"<{tag}"]
+        for name, value in attrs:
+            if value is None:
+                parts.append(f" {name}")
+            else:
+                parts.append(f' {name}="{html.escape(value, quote=True)}"')
+        parts.append(" />" if self_closing else ">")
+        self._output.append("".join(parts))
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag not in _VOID_TAGS:
+            self._output.append(f"</{tag}>")
+
+    def handle_data(self, data: str) -> None:
+        self._output.append(html.escape(data))
+
+    def get_html(self) -> str:
+        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)
+    rewriter.feed(html_fragment)
+    return rewriter.get_html()
+
+
+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
+
+
+def guess_extension(url: str) -> str:
+    """A file extension for ``url``, from its path, falling back to a default."""
+    suffix = Path(urlsplit(url).path).suffix.lower()
+    return suffix if suffix in _MEDIA_TYPES else _DEFAULT_EXTENSION
+
+
+def media_type_for(extension: str) -> str:
+    """The MIME media type for a file extension from ``guess_extension``."""
+    return _MEDIA_TYPES.get(extension, _MEDIA_TYPES[_DEFAULT_EXTENSION])
+
+
+async def _try_download(
+    client: httpx.AsyncClient, semaphore: asyncio.Semaphore, url: str
+) -> bytes | None:
+    async with semaphore:
+        try:
+            response = await client.get(url)
+            response.raise_for_status()
+        except httpx.HTTPError:
+            return None
+    return response.content
+
+
+async def download_images(
+    client: httpx.AsyncClient, urls: list[str], *, concurrency: int = IMAGE_CONCURRENCY
+) -> dict[str, bytes]:
+    """Download each of ``urls`` concurrently, skipping (not retrying) any that fail.
+
+    Args:
+        client: The client to download with.
+        urls: URLs to fetch. Not deduplicated — that's the caller's job (chapters often
+            share images).
+        concurrency: Maximum simultaneous downloads.
+
+    Returns:
+        A mapping from URL to its downloaded bytes, containing only the URLs that
+        succeeded — failed URLs are simply absent, not mapped to ``None``.
+    """
+    semaphore = asyncio.Semaphore(concurrency)
+    results = await asyncio.gather(*(_try_download(client, semaphore, url) for url in urls))
+    return {url: data for url, data in zip(urls, results, strict=True) if data is not None}

ranobelib/exporters/_shared.py

@@ -0,0 +1,11 @@
+"""Helpers shared between exporter implementations (not part of the public Exporter protocol)."""
+
+from __future__ import annotations
+
+from ranobelib.models import Chapter
+
+
+def chapter_heading(chapter: Chapter) -> str:
+    """A human-readable "Volume X, Chapter Y[: Name]" heading for ``chapter``."""
+    heading = f"Volume {chapter.volume}, Chapter {chapter.number}"
+    return f"{heading}: {chapter.name}" if chapter.name else heading