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

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

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

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

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

@@ -13,7 +13,16 @@ 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
 
@@ -27,6 +36,7 @@ __all__ = [
     "ChapterNotFoundError",
     "Country",
     "DownloadTitleInterruptedError",
+    "Footnote",
     "Genre",
     "MultipleTitleTranslationsError",
     "MultipleTranslationsError",

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

@@ -81,7 +81,7 @@ class Catalog:
         genres: list[int] | None = None,
         tags: list[int] | None = None,
         status: int | None = None,
-        country: int | None = None,
+        countries: list[int] | None = None,
         sort: str = DEFAULT_SORT,
         refresh: bool = False,
     ) -> CatalogPage:
@@ -104,11 +104,14 @@ class Catalog:
                 from tags being more numerous/specific than genres). Also not validated
                 before sending, same as ``genres``.
             status: A single ``Title.status.id`` to filter by (e.g. ongoing vs. completed).
-            country: A single ``Country.id`` to filter by — a title only has one country of
-                origin, unlike ``genres``. Ids come from ``list_countries()``. Sent on the
-                wire as the API's ``types[]`` parameter, not a ``country``/``countries[]``
-                one — see docs/api-notes.md for why (``Country`` mirrors the API's own
-                "type" concept, which isn't strictly limited to literal countries).
+            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,
+                see docs/api-notes.md). ``None`` or an empty list applies no country filter.
+                Ids come from ``list_countries()``. Sent on the wire as the API's ``types[]``
+                parameter, not a ``country``/``countries[]`` one — see docs/api-notes.md for
+                why (``Country`` mirrors the API's own "type" concept, which isn't strictly
+                limited to literal countries).
             sort: Sort order. Despite the name, this is sent as the API's ``sort_by``
                 parameter — an actual ``sort`` parameter exists but is silently ignored by
                 the API (see docs/api-notes.md). Known accepted values: ``"name"``,
@@ -140,7 +143,7 @@ class Catalog:
             genres=genres,
             tags=tags,
             status=status,
-            country=country,
+            countries=countries,
             sort=sort,
         )
         if not refresh:
@@ -155,7 +158,7 @@ class Catalog:
             genres=genres,
             tags=tags,
             status=status,
-            country=country,
+            countries=countries,
             sort=sort,
         )
         self._cache.set(key, data)
@@ -191,7 +194,7 @@ class Catalog:
 
     async def list_countries(self, *, refresh: bool = False) -> list[Country]:
         """Fetch the full list of catalog countries (id → name), for use as filter options
-        with ``list_titles(country=...)``.
+        with ``list_titles(countries=...)``.
 
         Mirrors ``list_genres()`` exactly, down to the network-wide, not-site-scoped shape
         of the underlying endpoint (``GET /api/constants?fields[]=types`` — the API's own
@@ -225,14 +228,15 @@ def _cache_key(
     genres: list[int] | None,
     tags: list[int] | None,
     status: int | None,
-    country: int | None,
+    countries: list[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 [])
+    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}:{country}:{sort}"
+        f"{status}:{countries_part}:{sort}"
     )
 
 

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

@@ -172,7 +172,7 @@ class ApiClient:
         genres: list[int] | None,
         tags: list[int] | None,
         status: int | None,
-        country: int | None,
+        countries: list[int] | None,
         sort: str,
     ) -> dict[str, Any]:
         """Fetch one page of the catalog listing/search results.
@@ -192,9 +192,11 @@ class ApiClient:
             tags: Tag ids to filter by. Same AND semantics as ``genres`` — a title must have
                 *all* of them, not just any one (see docs/api-notes.md).
             status: A single ``Title.status.id`` to filter by.
-            country: A single ``Country.id`` to filter by. Sent on the wire as ``types[]``
-                (repeatable array parameter, but only ever given one value here) — the API's
-                own name for this concept is "type", not "country" (see docs/api-notes.md).
+            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).
             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
@@ -217,8 +219,8 @@ class ApiClient:
             params.append(("tags[]", str(tag_id)))
         if status is not None:
             params.append(("status[]", str(status)))
-        if country is not None:
-            params.append(("types[]", str(country)))
+        for country_id in countries or []:
+            params.append(("types[]", str(country_id)))
 
         response = await self._get("/manga", params=httpx.QueryParams(params))
         self._raise_for_status(

ranobelib_python_sdk-0.10.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.8.0 → ranobelib_python_sdk-0.10.0}/src/ranobelib/exporters/epub.py

@@ -19,7 +19,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
 
 
@@ -83,7 +83,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 +108,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.8.0 → ranobelib_python_sdk-0.10.0}/src/ranobelib/exporters/fb2.py

@@ -10,7 +10,7 @@ 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()

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

@@ -20,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
 
 try:
@@ -63,7 +63,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>'
 
 
@@ -136,7 +136,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.8.0 → ranobelib_python_sdk-0.10.0}/src/ranobelib/exporters/txt.py

@@ -8,7 +8,7 @@ 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"})
@@ -91,7 +91,7 @@ class TxtExporter:
         """
         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.8.0 → ranobelib_python_sdk-0.10.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.8.0 → ranobelib_python_sdk-0.10.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.8.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