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

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

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

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

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

@@ -2,6 +2,7 @@
 
 from ranobelib.catalog import Catalog
 from ranobelib.exceptions import (
+    AccessBlockedError,
     AmbiguousChapter,
     AuthRequiredError,
     ChapterNotFoundError,
@@ -27,6 +28,7 @@ from ranobelib.sdk import RanobeLib
 from ranobelib.sizing import chapter_size, volume_size
 
 __all__ = [
+    "AccessBlockedError",
     "AmbiguousChapter",
     "AuthRequiredError",
     "Catalog",

ranobelib_python_sdk-0.11.0/src/ranobelib/_http.py

@@ -0,0 +1,45 @@
+"""HTTP settings shared by every client the SDK opens (not public API).
+
+Lives in its own module rather than in ``client.py`` because it isn't specific to the
+api.cdnlibs.org JSON API: the exporters' image-downloading clients (cover.cdnlibs.org,
+ranobelib.me uploads) need the same headers, and importing them from here keeps the
+exporters from depending on ``ApiClient``'s module just for a constant.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import httpx
+
+SITE_ORIGIN = "https://ranobelib.me"
+"""Origin of the ranobelib.me website, as its own pages send it."""
+
+BROWSER_HEADERS: dict[str, str] = {
+    "Origin": SITE_ORIGIN,
+    "Referer": f"{SITE_ORIGIN}/",
+    "User-Agent": (
+        "Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 "
+        "(KHTML, like Gecko) Version/18.5 Mobile/15E148 Safari/604.1"
+    ),
+}
+"""Headers a browser on ranobelib.me sends, so requests look like they come from the site.
+
+The DDoS-Guard edge in front of api.cdnlibs.org and cover.cdnlibs.org rejects requests
+without a non-empty ``Referer`` with an HTML 403 page (see docs/api-notes.md, section
+"WAF 403"). Any ``Referer`` value was enough when checked; the site's own one is sent,
+together with ``Origin`` and a real browser ``User-Agent``, so the request as a whole matches
+what the site itself sends rather than advertising ``python-httpx``.
+"""
+
+
+def browser_headers(overrides: Mapping[str, str] | None = None) -> httpx.Headers:
+    """``BROWSER_HEADERS`` with ``overrides`` merged over them.
+
+    A key in ``overrides`` replaces the default one, matched case-insensitively (``httpx``
+    headers semantics) — the same merge ``ApiClient(headers=...)`` does for API requests.
+    """
+    headers = httpx.Headers(BROWSER_HEADERS)
+    if overrides:
+        headers.update(overrides)
+    return headers

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

@@ -7,6 +7,7 @@ its own ``ApiClient``/``DiskCache`` rather than a method on ``RanobeLib``.
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from pathlib import Path
 from types import TracebackType
 from typing import Any, Self
@@ -40,6 +41,7 @@ class Catalog:
         *,
         cache_dir: str | Path | None = None,
         cache_ttl: float | None = None,
+        headers: Mapping[str, str] | None = None,
     ) -> None:
         """Initialize the catalog client.
 
@@ -51,8 +53,10 @@ class Catalog:
             cache_ttl: Seconds after which a cached page is treated as stale and re-fetched.
                 ``None`` (the default) means cached pages never expire on their own — see
                 ``refresh=True`` on ``list_titles()`` to force one anyway.
+            headers: Extra HTTP headers merged over the SDK's defaults, same as
+                ``RanobeLib(headers=...)`` — see there.
         """
-        self._client = ApiClient()
+        self._client = ApiClient(headers=headers)
         self._cache = DiskCache(
             cache_dir if cache_dir is not None else DEFAULT_CACHE_DIR, ttl=cache_ttl
         )

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

@@ -4,13 +4,15 @@ from __future__ import annotations
 
 import asyncio
 import time
-from collections.abc import Awaitable, Callable
+from collections.abc import Awaitable, Callable, Mapping
 from types import TracebackType
 from typing import Any, Self
 
 import httpx
 
+from ranobelib._http import BROWSER_HEADERS
 from ranobelib.exceptions import (
+    AccessBlockedError,
     AuthRequiredError,
     ChapterNotFoundError,
     RanobeLibError,
@@ -36,6 +38,11 @@ class ApiClient:
     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.
+
+    Every request carries browser-like ``Origin``/``Referer``/``User-Agent`` headers on top
+    of the API-specific ``Site-Id``/``Accept``: without a non-empty ``Referer``, the
+    DDoS-Guard edge in front of the API answers every request with an HTML 403 page (see
+    docs/api-notes.md, section "WAF 403").
     """
 
     def __init__(
@@ -44,6 +51,7 @@ class ApiClient:
         base_url: str = API_BASE_URL,
         timeout: float = 15.0,
         transport: httpx.AsyncBaseTransport | None = None,
+        headers: Mapping[str, str] | None = None,
         max_concurrency: int = 5,
         request_delay: float | None = None,
         max_retries: int = 3,
@@ -57,6 +65,13 @@ class ApiClient:
             base_url: API base URL.
             timeout: Per-request timeout, in seconds.
             transport: Custom ``httpx`` transport, e.g. a mock transport for tests.
+            headers: Extra headers merged over the defaults (browser-like ``Origin``/
+                ``Referer``/``User-Agent`` plus the API's ``Site-Id``/``Accept``); a key
+                given here replaces the default one, matched case-insensitively. Meant for
+                swapping in a different ``User-Agent`` if the site's edge protection changes
+                its rules, without waiting for an SDK release. Overriding ``Site-Id`` or
+                ``Accept`` is possible but breaks the API's contract (see
+                docs/api-notes.md) — only do it knowingly.
             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
@@ -74,10 +89,13 @@ class ApiClient:
             timeout=timeout,
             transport=transport,
             headers={
+                **BROWSER_HEADERS,
                 "Site-Id": RANOBELIB_SITE_ID,
                 "Accept": "application/json",
             },
         )
+        if headers is not None:
+            self._http.headers.update(headers)
         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
@@ -302,6 +320,12 @@ class ApiClient:
         if response.status_code == 404:
             raise not_found
         if response.status_code == 403:
+            # The API's own 403 is JSON; the DDoS-Guard edge in front of it answers with an
+            # HTML page instead. Told apart by Content-Type, not by the page's wording, which
+            # can change (see docs/api-notes.md, section "WAF 403").
+            media_type = response.headers.get("Content-Type", "").split(";")[0].strip().lower()
+            if media_type != "application/json":
+                raise AccessBlockedError(str(response.request.url))
             raise AuthRequiredError(str(response.request.url))
         if response.status_code == 429:
             retry_after = response.headers.get("Retry-After")

{ranobelib_python_sdk-0.10.0 → ranobelib_python_sdk-0.11.0}/src/ranobelib/exceptions.py

@@ -153,6 +153,34 @@ class AuthRequiredError(RanobeLibError):
         super().__init__(f"Authorization required to access: {url}")
 
 
+class AccessBlockedError(RanobeLibError):
+    """Raised when the site's edge protection rejects a request before it reaches the API.
+
+    Not an authorization problem, unlike ``AuthRequiredError``: the DDoS-Guard edge in front
+    of api.cdnlibs.org answers with an HTML 403 page (the API's own 403 is JSON) when it
+    doesn't like the request — so far, a missing or empty ``Referer`` (see
+    docs/api-notes.md, section "WAF 403"). The SDK already sends browser-like headers, so
+    seeing this means either the edge changed its rules — check for an SDK update, or send
+    what it now expects via ``headers=`` on ``RanobeLib``/``Catalog`` (or ``ApiClient``, if
+    using it directly) — or the edge is blocking the network/IP itself, which no header
+    fixes. Not retried: resending the same request gets
+    the same answer.
+
+    Attributes:
+        url: The request URL that returned 403.
+    """
+
+    def __init__(self, url: str) -> None:
+        self.url = url
+        super().__init__(
+            f"Request blocked by the site's protection (not an authorization issue): {url}. "
+            "The site may have changed which requests it accepts: check for an SDK update, "
+            "or send different headers via RanobeLib(..., headers=...) / "
+            "Catalog(headers=...). If the same URL doesn't open in a browser on this network "
+            "either, the IP itself is blocked and no header change will help."
+        )
+
+
 class RateLimitError(RanobeLibError):
     """Raised when the API responds with 429 Too Many Requests.
 

{ranobelib_python_sdk-0.10.0 → ranobelib_python_sdk-0.11.0}/src/ranobelib/exporters/__init__.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 
 import importlib
 import pkgutil
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from pathlib import Path
 from typing import ClassVar, Protocol, TypeVar, runtime_checkable
 
@@ -30,6 +30,7 @@ class Exporter(Protocol):
         output_path: Path,
         *,
         on_chapter: Callable[[], None] | None = None,
+        headers: Mapping[str, str] | None = None,
     ) -> Path:
         """Write ``chapters`` (in the given order) to ``output_path``.
 
@@ -45,6 +46,10 @@ class Exporter(Protocol):
                 ``RanobeLib.export()``'s progress bar (see CLAUDE.md's roadmap step 23).
                 For epub/pdf this covers the per-chapter embedding step, not the earlier
                 illustration-download step, which isn't itself progress-reported.
+            headers: Extra HTTP headers for any downloads the exporter makes (epub/pdf
+                illustrations), merged over the SDK's browser-like defaults —
+                ``RanobeLib.export()`` passes its own ``headers=`` through here. Exporters
+                that make no requests (txt, fb2) accept and ignore it.
 
         Returns:
             ``output_path``, once the file has been written.

{ranobelib_python_sdk-0.10.0 → ranobelib_python_sdk-0.11.0}/src/ranobelib/exporters/epub.py

@@ -3,13 +3,14 @@
 from __future__ import annotations
 
 import html
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from pathlib import Path
 from typing import ClassVar
 
 import httpx
 from ebooklib import epub
 
+from ranobelib._http import browser_headers
 from ranobelib.exporters import register
 from ranobelib.exporters._illustrations import (
     download_images,
@@ -47,6 +48,7 @@ class EpubExporter:
         output_path: Path,
         *,
         on_chapter: Callable[[], None] | None = None,
+        headers: Mapping[str, str] | None = None,
     ) -> Path:
         """Write ``chapters`` to ``output_path`` as an EPUB file.
 
@@ -60,6 +62,8 @@ class EpubExporter:
             output_path: Where to write the ``.epub`` file.
             on_chapter: Called once per chapter embedded, if given — after illustrations
                 have already been downloaded, see the ``Exporter`` protocol's docstring.
+            headers: Extra HTTP headers for illustration downloads, merged over the
+                SDK's browser-like defaults (a given key replaces the default one).
 
         Returns:
             ``output_path``.
@@ -71,8 +75,13 @@ class EpubExporter:
         for author in title.authors:
             book.add_author(author.name)
 
+        # Browser headers: cover.cdnlibs.org's edge answers requests without a (non-empty)
+        # Referer with a 403, same as the API (see docs/api-notes.md, section "WAF 403").
         async with httpx.AsyncClient(
-            timeout=15.0, follow_redirects=True, transport=self._transport
+            timeout=15.0,
+            follow_redirects=True,
+            transport=self._transport,
+            headers=browser_headers(headers),
         ) as client:
             cover_url = pick_cover_url(title.cover)
             if cover_url is not None:

{ranobelib_python_sdk-0.10.0 → ranobelib_python_sdk-0.11.0}/src/ranobelib/exporters/fb2.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import datetime
 import xml.etree.ElementTree as ET
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from html.parser import HTMLParser
 from pathlib import Path
 from typing import ClassVar
@@ -153,6 +153,7 @@ class Fb2Exporter:
         output_path: Path,
         *,
         on_chapter: Callable[[], None] | None = None,
+        headers: Mapping[str, str] | None = None,
     ) -> Path:
         """Write ``chapters`` to ``output_path`` as FB2 XML.
 
@@ -161,6 +162,8 @@ class Fb2Exporter:
             chapters: The chapters to include, in the order they should appear.
             output_path: Where to write the ``.fb2`` file.
             on_chapter: Called once per chapter written, if given.
+            headers: Accepted for the ``Exporter`` protocol and ignored — this format
+                downloads nothing (no illustrations in fb2, see CLAUDE.md).
 
         Returns:
             ``output_path``.

{ranobelib_python_sdk-0.10.0 → ranobelib_python_sdk-0.11.0}/src/ranobelib/exporters/pdf.py

@@ -5,12 +5,13 @@ from __future__ import annotations
 import asyncio
 import base64
 import html
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from pathlib import Path
 from typing import ClassVar
 
 import httpx
 
+from ranobelib._http import browser_headers
 from ranobelib.exporters import register
 from ranobelib.exporters._illustrations import (
     download_images,
@@ -106,6 +107,7 @@ if weasyprint is not None:
             output_path: Path,
             *,
             on_chapter: Callable[[], None] | None = None,
+            headers: Mapping[str, str] | None = None,
         ) -> Path:
             """Write ``chapters`` to ``output_path`` as a PDF file.
 
@@ -116,12 +118,18 @@ if weasyprint is not None:
                 on_chapter: Called once per chapter rendered to HTML, if given — after
                     illustrations have already been downloaded, see the ``Exporter``
                     protocol's docstring.
+                headers: Extra HTTP headers for illustration downloads, merged over the
+                    SDK's browser-like defaults (a given key replaces the default one).
 
             Returns:
                 ``output_path``.
             """
+            # Browser headers for the cover CDN's edge — see the same comment in epub.py.
             async with httpx.AsyncClient(
-                timeout=15.0, follow_redirects=True, transport=self._transport
+                timeout=15.0,
+                follow_redirects=True,
+                transport=self._transport,
+                headers=browser_headers(headers),
             ) as client:
                 cover_url = pick_cover_url(title.cover)
                 cover_data_uri = None

{ranobelib_python_sdk-0.10.0 → ranobelib_python_sdk-0.11.0}/src/ranobelib/exporters/txt.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from html.parser import HTMLParser
 from pathlib import Path
 from typing import ClassVar
@@ -77,6 +77,7 @@ class TxtExporter:
         output_path: Path,
         *,
         on_chapter: Callable[[], None] | None = None,
+        headers: Mapping[str, str] | None = None,
     ) -> Path:
         """Write ``chapters`` to ``output_path`` as plain text.
 
@@ -85,6 +86,8 @@ class TxtExporter:
             chapters: The chapters to include, in the order they should appear.
             output_path: Where to write the ``.txt`` file.
             on_chapter: Called once per chapter written, if given.
+            headers: Accepted for the ``Exporter`` protocol and ignored — this format
+                downloads nothing (no illustrations in txt, see CLAUDE.md).
 
         Returns:
             ``output_path``.

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

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from pathlib import Path
 from types import TracebackType
 from typing import Any, Self
@@ -68,6 +68,7 @@ class RanobeLib:
         cache_dir: str | Path | None = None,
         cache_ttl: float | None = None,
         verbosity: Verbosity = False,
+        headers: Mapping[str, str] | None = None,
     ) -> None:
         """Initialize the SDK for a title.
 
@@ -85,9 +86,18 @@ class RanobeLib:
                 ``"full"``: the same progress bars, plus a line logged for every title/
                 chapter-list/chapter-content fetch, noting whether it was served from the
                 disk cache or the API.
+            headers: Extra HTTP headers merged over the SDK's defaults (browser-like
+                ``Origin``/``Referer``/``User-Agent``, see docs/api-notes.md, section "WAF
+                403") — a key given here replaces the default one, matched
+                case-insensitively. Applied to every API request and, through ``export()``,
+                to epub/pdf illustration downloads. Meant for when the site's edge protection
+                changes which requests it lets through (``AccessBlockedError``): send what it
+                now expects without waiting for an SDK release. ``None`` (the default) sends
+                the defaults as-is.
         """
         self._slug_url = parse_slug_url(url)
-        self._client = ApiClient()
+        self._headers = dict(headers) if headers is not None else None
+        self._client = ApiClient(headers=self._headers)
         self._cache = DiskCache(
             cache_dir if cache_dir is not None else DEFAULT_CACHE_DIR, ttl=cache_ttl
         )
@@ -457,7 +467,8 @@ class RanobeLib:
             chapters: The chapters to include, in the order they should appear.
             path: Where to write the exported file.
             fmt: Export format — a key of ``ranobelib.exporters.EXPORTERS``
-                (currently: ``"txt"``, ``"fb2"``, ``"epub"``).
+                (currently: ``"txt"``, ``"fb2"``, ``"epub"``, and ``"pdf"`` where
+                WeasyPrint's native libraries are available).
 
         Raises:
             ValueError: If ``fmt`` isn't a registered export format.
@@ -468,7 +479,9 @@ class RanobeLib:
             raise ValueError(f"Unknown export format {fmt!r}. Available: {available}")
         title = await self.get_info()
         with self._reporter.progress(f"Exporting to {fmt}", len(chapters)) as advance:
-            return await exporter_cls().export(title, chapters, Path(path), on_chapter=advance)
+            return await exporter_cls().export(
+                title, chapters, Path(path), on_chapter=advance, headers=self._headers
+            )
 
     async def _build_volume(self, volume: int, raw_chapters: list[dict[str, Any]]) -> Volume:
         volume_str = str(volume)