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

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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "ranobelib-python-sdk"
-version = "0.9.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.9.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,
@@ -13,11 +14,21 @@ from ranobelib.exceptions import (
     TitleNotFoundError,
     VolumeNotFoundError,
 )
-from ranobelib.models import CatalogPage, Chapter, ChapterBranch, Country, Genre, Title, Volume
+from ranobelib.models import (
+    CatalogPage,
+    Chapter,
+    ChapterBranch,
+    Country,
+    Footnote,
+    Genre,
+    Title,
+    Volume,
+)
 from ranobelib.sdk import RanobeLib
 from ranobelib.sizing import chapter_size, volume_size
 
 __all__ = [
+    "AccessBlockedError",
     "AmbiguousChapter",
     "AuthRequiredError",
     "Catalog",
@@ -27,6 +38,7 @@ __all__ = [
     "ChapterNotFoundError",
     "Country",
     "DownloadTitleInterruptedError",
+    "Footnote",
     "Genre",
     "MultipleTitleTranslationsError",
     "MultipleTranslationsError",

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.9.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.9.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.9.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.9.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.11.0/src/ranobelib/exporters/_shared.py

@@ -0,0 +1,29 @@
+"""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
+
+
+FOOTNOTES_HEADING = "Notes"
+
+
+def chapter_body_html(chapter: Chapter) -> str:
+    """``chapter.content`` with its footnotes appended as a trailing "Notes" block.
+
+    Footnotes aren't part of ``Chapter.content`` (see ``Chapter.footnotes``), so exporters
+    render a chapter's body through this rather than reading ``content`` directly — otherwise
+    an export would silently drop them. There's no in-text link to point them back to (see
+    ``Footnote``), so they're listed after the chapter, in source order.
+    """
+    body = chapter.content or ""
+    if not chapter.footnotes:
+        return body
+    notes = "".join(f"<p>{footnote.content}</p>" for footnote in chapter.footnotes)
+    return f"{body}<hr /><p><strong>{FOOTNOTES_HEADING}</strong></p>{notes}"

{ranobelib_python_sdk-0.9.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,
@@ -19,7 +20,7 @@ from ranobelib.exporters._illustrations import (
     pick_cover_url,
     rewrite_image_srcs,
 )
-from ranobelib.exporters._shared import chapter_heading
+from ranobelib.exporters._shared import chapter_body_html, chapter_heading
 from ranobelib.models import Chapter, Title
 
 
@@ -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:
@@ -83,7 +92,9 @@ class EpubExporter:
 
             image_urls = list(
                 dict.fromkeys(
-                    url for chapter in chapters for url in extract_image_urls(chapter.content or "")
+                    url
+                    for chapter in chapters
+                    for url in extract_image_urls(chapter_body_html(chapter))
                 )
             )
             images = await download_images(client, image_urls)
@@ -106,7 +117,7 @@ class EpubExporter:
         toc: list[object] = []
         for index, chapter in enumerate(chapters, start=1):
             heading = chapter_heading(chapter)
-            body = rewrite_image_srcs(chapter.content or "", url_to_local)
+            body = rewrite_image_srcs(chapter_body_html(chapter), url_to_local)
             doc = epub.EpubHtml(
                 uid=f"chapter_{index}",
                 file_name=f"chapter_{index}.xhtml",

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

@@ -4,13 +4,13 @@ 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
 
 from ranobelib.exporters import register
-from ranobelib.exporters._shared import chapter_heading
+from ranobelib.exporters._shared import chapter_body_html, chapter_heading
 from ranobelib.models import Chapter, Title
 
 FB2_NS = "http://www.gribuser.ru/xml/fictionbook/2.0"
@@ -133,7 +133,7 @@ def _build_body(chapters: list[Chapter], on_chapter: Callable[[], None] | None)
         section = ET.SubElement(body, _tag("section"))
         section_title = ET.SubElement(section, _tag("title"))
         ET.SubElement(section_title, _tag("p")).text = chapter_heading(chapter)
-        for paragraph in html_to_fb2_paragraphs(chapter.content or ""):
+        for paragraph in html_to_fb2_paragraphs(chapter_body_html(chapter)):
             section.append(paragraph)
         if on_chapter is not None:
             on_chapter()
@@ -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.9.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,
@@ -20,7 +21,7 @@ from ranobelib.exporters._illustrations import (
     pick_cover_url,
     rewrite_image_srcs,
 )
-from ranobelib.exporters._shared import chapter_heading
+from ranobelib.exporters._shared import chapter_body_html, chapter_heading
 from ranobelib.models import Chapter, Title
 
 try:
@@ -63,7 +64,7 @@ def _title_page_html(title: Title, cover_data_uri: str | None) -> str:
 
 def _chapter_html(chapter: Chapter, url_to_data_uri: dict[str, str]) -> str:
     heading = html.escape(chapter_heading(chapter))
-    body = rewrite_image_srcs(chapter.content or "", url_to_data_uri)
+    body = rewrite_image_srcs(chapter_body_html(chapter), url_to_data_uri)
     return f'<section class="chapter"><h1>{heading}</h1>{body}</section>'
 
 
@@ -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
@@ -136,7 +144,7 @@ if weasyprint is not None:
                     dict.fromkeys(
                         url
                         for chapter in chapters
-                        for url in extract_image_urls(chapter.content or "")
+                        for url in extract_image_urls(chapter_body_html(chapter))
                     )
                 )
                 images = await download_images(client, image_urls)

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

@@ -2,13 +2,13 @@
 
 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
 
 from ranobelib.exporters import register
-from ranobelib.exporters._shared import chapter_heading
+from ranobelib.exporters._shared import chapter_body_html, chapter_heading
 from ranobelib.models import Chapter, Title
 
 _BLOCK_TAGS = frozenset({"p", "div"})
@@ -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,13 +86,15 @@ 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``.
         """
         sections = [title.name]
         for chapter in chapters:
-            body = html_to_text(chapter.content or "")
+            body = html_to_text(chapter_body_html(chapter))
             sections.append(f"{chapter_heading(chapter)}\n\n{body}")
             if on_chapter is not None:
                 on_chapter()

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

@@ -67,31 +67,73 @@ def _render_prosemirror_inline(node: dict[str, Any], attachments: list[dict[str,
     return "".join(_render_prosemirror_inline(child, attachments) for child in _child_nodes(node))
 
 
-def _render_prosemirror_block(node: dict[str, Any], attachments: list[dict[str, Any]]) -> str:
+_FOOTNOTE_ARROW = "↑"
+"""The "↑" a translator footnote paragraph starts with — see ``Chapter.footnotes``."""
+
+
+def _strip_footnote_arrow(paragraph: dict[str, Any]) -> dict[str, Any] | None:
+    """Return ``paragraph`` without its leading ``_FOOTNOTE_ARROW``, or ``None`` if its first
+    non-blank text doesn't start with one (i.e. it's a regular paragraph, not a footnote).
+
+    Non-text children (an image, a hard break) before that text are kept and skipped over,
+    same as ``_ContentSanitizer`` does for the HTML-string format.
+    """
+    children = _child_nodes(paragraph)
+    for index, child in enumerate(children):
+        if child.get("type") != "text":
+            continue
+        text = str(child.get("text", "")).lstrip()
+        if not text:
+            continue
+        if not text.startswith(_FOOTNOTE_ARROW):
+            return None
+        stripped = {**child, "text": text[len(_FOOTNOTE_ARROW) :].lstrip()}
+        return {**paragraph, "content": [*children[:index], stripped, *children[index + 1 :]]}
+    return None
+
+
+def _render_prosemirror_block(
+    node: dict[str, Any], attachments: list[dict[str, Any]], footnotes: list[str]
+) -> str:
     node_type = node.get("type")
     if node_type == "paragraph":
+        footnote = _strip_footnote_arrow(node)
+        paragraph = footnote if footnote is not None else node
         inner = "".join(
-            _render_prosemirror_inline(child, attachments) for child in _child_nodes(node)
+            _render_prosemirror_inline(child, attachments) for child in _child_nodes(paragraph)
         )
-        return f"<p>{inner}</p>"
+        if footnote is None:
+            return f"<p>{inner}</p>"
+        if inner.strip():
+            footnotes.append(inner.strip())
+        return ""
     if node_type == "image":
         return _render_prosemirror_inline(node, attachments)
     if node_type == "horizontalRule":
         return "<hr />"
-    return "".join(_render_prosemirror_block(child, attachments) for child in _child_nodes(node))
+    return "".join(
+        _render_prosemirror_block(child, attachments, footnotes) for child in _child_nodes(node)
+    )
 
 
-def _prosemirror_to_html(doc: dict[str, Any], attachments: list[dict[str, Any]]) -> str:
-    """Render a prosemirror-doc JSON structure as an HTML fragment.
+def _prosemirror_to_html(
+    doc: dict[str, Any], attachments: list[dict[str, Any]]
+) -> tuple[str, list[str]]:
+    """Render a prosemirror-doc JSON structure as an HTML fragment, plus its footnotes.
 
     Chapter content comes from the API in one of two formats — an HTML string, or
     prosemirror-doc JSON (see docs/api-notes.md) — this makes the latter match the tag
     vocabulary (``p``/``img``/``strong``/``em``) the former already uses natively, so
     downstream consumers (exporters) only ever handle one shape. Image nodes reference
     attachments by an opaque id, resolved against the chapter response's ``attachments``
-    array.
+    array. Footnote paragraphs (see ``Chapter.footnotes``) are left out of the returned HTML
+    and returned separately instead, as inline HTML fragments without the leading arrow.
     """
-    return "".join(_render_prosemirror_block(block, attachments) for block in _child_nodes(doc))
+    footnotes: list[str] = []
+    rendered = "".join(
+        _render_prosemirror_block(block, attachments, footnotes) for block in _child_nodes(doc)
+    )
+    return rendered, footnotes
 
 
 _ALLOWED_CONTENT_TAGS = frozenset({"p", "img", "strong", "em", "br", "hr"})
@@ -101,6 +143,70 @@ _DROPPED_CONTENT_TEXT_TAGS = frozenset({"script", "style"})
 _SAFE_IMG_SCHEMES = frozenset({"http", "https"})
 
 
+_DROPPED_BLOCK_TAGS = frozenset(
+    {
+        "address",
+        "article",
+        "aside",
+        "blockquote",
+        "caption",
+        "center",
+        "dd",
+        "details",
+        "div",
+        "dl",
+        "dt",
+        "fieldset",
+        "figcaption",
+        "figure",
+        "footer",
+        "form",
+        "h1",
+        "h2",
+        "h3",
+        "h4",
+        "h5",
+        "h6",
+        "header",
+        "hgroup",
+        "li",
+        "main",
+        "nav",
+        "ol",
+        "pre",
+        "section",
+        "summary",
+        "table",
+        "tbody",
+        "td",
+        "tfoot",
+        "th",
+        "thead",
+        "tr",
+        "ul",
+    }
+)
+_BLOCK_TAGS = _DROPPED_BLOCK_TAGS | {"p"}
+
+
+class _Block:
+    """A ``p`` or dropped block-level tag still being parsed.
+
+    ``run`` is the inline content collected since the block opened or since its last child
+    block — for a ``p`` that's its whole content; for a dropped block it's flushed into its
+    own ``<p>`` in ``segments`` whenever a child block (or ``hr``) starts, and when the block
+    closes. Each such paragraph is checked for a footnote on its own, so buffering is needed:
+    whether it is one is only known once its first non-blank text arrives.
+    """
+
+    def __init__(self, tag: str) -> None:
+        self.tag = tag
+        self.segments: list[str] = []
+        self.run: list[str] = []
+        self.arrow_index: int | None = None
+        self.seen_text = False
+
+
 class _ContentSanitizer(HTMLParser):
     """Rebuilds an HTML-string-format chapter body using only the same restricted tag
     vocabulary ``_prosemirror_to_html`` already produces for the other content format
@@ -116,20 +222,87 @@ class _ContentSanitizer(HTMLParser):
     safety concern. Text inside a dropped ``script``/``style`` tag is discarded rather than
     kept as escaped text — anywhere else, a dropped tag's text content is kept (e.g. a
     stripped ``<a href="...">text</a>`` still leaves ``text`` behind).
+
+    A dropped *block-level* tag (``li``, ``div``, ``h3``, ...) keeps the paragraph boundary
+    it gave its text: its inline content is wrapped in ``<p>`` rather than inlined into the
+    parent, one ``<p>`` per run of inline content between nested blocks, so the output stays
+    a flat sequence of paragraphs whatever the nesting was. Opening a block inside an open
+    ``p`` closes that ``p`` first, as HTML itself does (a ``p`` can't contain blocks).
+
+    A paragraph — an explicit ``p`` or one made from a dropped block's text — whose first
+    non-blank text starts with ``_FOOTNOTE_ARROW`` is a translator footnote: it's collected
+    into ``footnotes`` (sanitized inner HTML, arrow stripped) instead of the output.
     """
 
     def __init__(self) -> None:
         super().__init__(convert_charrefs=True)
         self._output: list[str] = []
+        self._blocks: list[_Block] = []
         self._skip_text_depth = 0
+        self.footnotes: list[str] = []
+
+    def _out(self) -> list[str]:
+        return self._blocks[-1].run if self._blocks else self._output
 
     def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
-        self._emit(tag, attrs, self_closing=False)
+        if tag in _BLOCK_TAGS:
+            self._open_block(tag)
+        else:
+            self._emit(tag, attrs)
 
     def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
-        self._emit(tag, attrs, self_closing=True)
+        if tag in _BLOCK_TAGS:
+            self._open_block(tag)
+            self._close_block()
+        else:
+            self._emit(tag, attrs)
+
+    def _open_block(self, tag: str) -> None:
+        # Same implicit closes HTML itself does: any block ends an open <p>, and a new <li>
+        # ends an open <li>.
+        if self._blocks and (self._blocks[-1].tag == "p" or self._blocks[-1].tag == tag == "li"):
+            self._close_block()
+        self._blocks.append(_Block(tag))
+
+    def _close_block(self) -> None:
+        block = self._blocks.pop()
+        if block.tag == "p":
+            paragraph = self._take_paragraph(block, keep_empty=True)
+        else:
+            self._flush_run(block)
+            paragraph = "".join(block.segments)
+        if paragraph:
+            self._append_block_html(paragraph)
+
+    def _take_paragraph(self, block: _Block, *, keep_empty: bool) -> str:
+        """Turn ``block.run`` into a ``<p>`` (or a footnote, returning ``""``) and reset it."""
+        run, arrow_index = block.run, block.arrow_index
+        block.run, block.arrow_index, block.seen_text = [], None, False
+        if arrow_index is not None:
+            run[arrow_index] = run[arrow_index].lstrip()[len(_FOOTNOTE_ARROW) :].lstrip()
+            inner = "".join(run).strip()
+            if inner:
+                self.footnotes.append(inner)
+            return ""
+        inner = "".join(run)
+        if keep_empty:
+            return f"<p>{inner}</p>"
+        return f"<p>{inner.strip()}</p>" if inner.strip() else ""
+
+    def _flush_run(self, block: _Block) -> None:
+        paragraph = self._take_paragraph(block, keep_empty=False)
+        if paragraph:
+            block.segments.append(paragraph)
+
+    def _append_block_html(self, block_html: str) -> None:
+        if not self._blocks:
+            self._output.append(block_html)
+            return
+        parent = self._blocks[-1]
+        self._flush_run(parent)
+        parent.segments.append(block_html)
 
-    def _emit(self, tag: str, attrs: list[tuple[str, str | None]], *, self_closing: bool) -> None:
+    def _emit(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
         resolved = _CONTENT_TAG_ALIASES.get(tag, tag)
         if resolved not in _ALLOWED_CONTENT_TAGS:
             if tag in _DROPPED_CONTENT_TEXT_TAGS:
@@ -138,40 +311,61 @@ class _ContentSanitizer(HTMLParser):
         if resolved == "img":
             src = dict(attrs).get("src")
             if src and urlsplit(src).scheme in _SAFE_IMG_SCHEMES:
-                self._output.append(f'<img loading="lazy" src="{html.escape(src, quote=True)}" />')
+                self._out().append(f'<img loading="lazy" src="{html.escape(src, quote=True)}" />')
+            return
+        if resolved == "hr" and self._blocks and self._blocks[-1].tag != "p":
+            # Between a dropped block's paragraphs, not inside one.
+            self._append_block_html("<hr />")
             return
         if resolved in _VOID_CONTENT_TAGS:
-            self._output.append(f"<{resolved} />")
+            self._out().append(f"<{resolved} />")
         else:
-            self._output.append(f"<{resolved}>")
+            self._out().append(f"<{resolved}>")
 
     def handle_endtag(self, tag: str) -> None:
+        if tag in _BLOCK_TAGS:
+            # Close up to the matching open block; a stray end tag with none open is dropped.
+            if any(block.tag == tag for block in self._blocks):
+                while self._blocks[-1].tag != tag:
+                    self._close_block()
+                self._close_block()
+            return
         resolved = _CONTENT_TAG_ALIASES.get(tag, tag)
         if resolved not in _ALLOWED_CONTENT_TAGS:
             if tag in _DROPPED_CONTENT_TEXT_TAGS and self._skip_text_depth > 0:
                 self._skip_text_depth -= 1
             return
         if resolved not in _VOID_CONTENT_TAGS:
-            self._output.append(f"</{resolved}>")
+            self._out().append(f"</{resolved}>")
 
     def handle_data(self, data: str) -> None:
-        if self._skip_text_depth == 0:
-            self._output.append(html.escape(data))
+        if self._skip_text_depth > 0:
+            return
+        if self._blocks and not self._blocks[-1].seen_text and data.strip():
+            block = self._blocks[-1]
+            block.seen_text = True
+            if data.lstrip().startswith(_FOOTNOTE_ARROW):
+                block.arrow_index = len(block.run)
+        self._out().append(html.escape(data))
 
     def get_html(self) -> str:
+        while self._blocks:
+            self._close_block()
         return "".join(self._output)
 
 
-def _sanitize_content_html(content: str) -> str:
+def _sanitize_content_html(content: str) -> tuple[str, list[str]]:
     """Sanitize an HTML-string-format chapter body down to the restricted tag vocabulary.
 
     Counterpart to ``_prosemirror_to_html`` for the other content format the API returns
     (see docs/api-notes.md) — without this, ``Chapter.content`` would only actually be safe
     to render as raw HTML for prosemirror-sourced chapters, not HTML-string-sourced ones.
+    Returns the sanitized HTML and, separately, the footnotes taken out of it (see
+    ``Chapter.footnotes``).
     """
     sanitizer = _ContentSanitizer()
     sanitizer.feed(content)
-    return sanitizer.get_html()
+    return sanitizer.get_html(), sanitizer.footnotes
 
 
 class Cover(BaseModel):
@@ -310,6 +504,22 @@ class ChapterBranch(BaseModel):
     user: ChapterUser
 
 
+class Footnote(BaseModel):
+    """A translator footnote (term explanation, translation note) taken out of a chapter.
+
+    The API has no structured footnotes (see docs/api-notes.md): they're ordinary
+    paragraphs/list items whose text starts with ``↑``, so that arrow is what the SDK detects
+    them by — and strips from ``content``. There's no ``marker`` linking a footnote back to a
+    point in the text: translators mark the reference with an unnumbered ``*`` at best, which
+    the text also uses for scene breaks and censored words, so ``Chapter.footnotes``'s order
+    (the order they appear in the source) is the only link there is.
+    """
+
+    content: str
+    """Sanitized inline HTML (same tag vocabulary as ``Chapter.content``), without the arrow
+    and without a wrapping ``<p>``."""
+
+
 class Chapter(BaseModel):
     """A chapter: volume, number, name, available translations, and optionally its content.
 
@@ -318,6 +528,10 @@ class Chapter(BaseModel):
     ``Chapter`` instead comes from fetching a single chapter's content, which has a
     different response shape (see docs/api-notes.md). ``content`` is the reverse: only
     populated by the single-chapter endpoint.
+
+    ``footnotes`` holds the chapter's translator footnotes (see ``Footnote``), which are
+    removed from ``content`` rather than kept in both places — empty when the chapter has
+    none, or when ``content`` isn't fetched.
     """
 
     id: int
@@ -330,6 +544,7 @@ class Chapter(BaseModel):
     branches: list[ChapterBranch] = Field(default_factory=list)
     bundle_id: int | None = None
     content: str | None = None
+    footnotes: list[Footnote] = Field(default_factory=list)
 
     @model_validator(mode="before")
     @classmethod
@@ -338,9 +553,20 @@ class Chapter(BaseModel):
             content = data.get("content")
             if isinstance(content, dict):
                 attachments = data.get("attachments") or []
-                data = {**data, "content": _prosemirror_to_html(content, attachments)}
+                rendered, footnotes = _prosemirror_to_html(content, attachments)
             elif isinstance(content, str):
-                data = {**data, "content": _sanitize_content_html(content)}
+                rendered, footnotes = _sanitize_content_html(content)
+            else:
+                return data
+            # A Chapter being re-validated from its own dump (model_validate(model_dump()))
+            # already has its footnotes out of ``content`` — keep them rather than overwrite
+            # them with the now-empty re-extraction.
+            data = {
+                **data,
+                "content": rendered,
+                "footnotes": data.get("footnotes")
+                or [{"content": footnote} for footnote in footnotes],
+            }
         return data
 
 

{ranobelib_python_sdk-0.9.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)

{ranobelib_python_sdk-0.9.0 → ranobelib_python_sdk-0.11.0}/src/ranobelib/sizing.py

@@ -2,10 +2,10 @@
 
 The API exposes no content-length or image-size field anywhere (see docs/api-notes.md), so
 any size here is necessarily approximate for the image portion: chapter text is measured
-exactly (the UTF-8 byte length of ``Chapter.content``), but each embedded ``<img>`` is
-assumed to weigh ``average_image_size`` bytes rather than downloaded to measure precisely —
-doing that would cost the same network traffic this module exists to help avoid paying
-upfront. The result approximates the underlying content size, not a specific export
+exactly (the UTF-8 byte length of ``Chapter.content`` plus its footnotes), but each embedded
+``<img>`` is assumed to weigh ``average_image_size`` bytes rather than downloaded to measure
+precisely — doing that would cost the same network traffic this module exists to help avoid
+paying upfront. The result approximates the underlying content size, not a specific export
 format's file size (epub's zip compression, pdf's layout overhead, fb2's XML verbosity are
 not modeled) — enough to decide whether a title is worth downloading, not to predict an
 exported file's exact byte count.
@@ -40,8 +40,11 @@ def chapter_size(chapter: Chapter, *, average_image_size: int = DEFAULT_AVERAGE_
             f"Chapter {chapter.volume}/{chapter.number} has no content to size — "
             "fetch it first, e.g. via get_chapter()."
         )
-    text_bytes = len(chapter.content.encode("utf-8"))
-    image_count = len(extract_image_urls(chapter.content))
+    # Footnotes are split out of ``content`` (see ``Chapter.footnotes``) but are still part
+    # of what was downloaded — and of what every exporter writes out.
+    text = chapter.content + "".join(footnote.content for footnote in chapter.footnotes)
+    text_bytes = len(text.encode("utf-8"))
+    image_count = len(extract_image_urls(text))
     return text_bytes + image_count * average_image_size
 
 

ranobelib_python_sdk-0.9.0/src/ranobelib/exporters/_shared.py

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