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

ranobelib/exporters/epub.py

@@ -0,0 +1,117 @@
+"""EPUB exporter (cover and in-chapter illustrations included)."""
+
+from __future__ import annotations
+
+import html
+from pathlib import Path
+from typing import ClassVar
+
+import httpx
+from ebooklib import epub
+
+from ranobelib.exporters import register
+from ranobelib.exporters._illustrations import (
+    download_images,
+    extract_image_urls,
+    guess_extension,
+    media_type_for,
+    pick_cover_url,
+    rewrite_image_srcs,
+)
+from ranobelib.exporters._shared import chapter_heading
+from ranobelib.models import Chapter, Title
+
+
+@register
+class EpubExporter:
+    """Exports chapters as a single EPUB file, with cover and in-chapter illustrations."""
+
+    format: ClassVar[str] = "epub"
+
+    def __init__(self, *, transport: httpx.AsyncBaseTransport | None = None) -> None:
+        """Initialize the exporter.
+
+        Args:
+            transport: Custom ``httpx`` transport for the image-downloading client, e.g. a
+                mock transport for tests. Not part of the ``Exporter`` protocol itself —
+                ``RanobeLib.export()`` always constructs exporters with no arguments, so
+                this is only reachable by instantiating ``EpubExporter`` directly.
+        """
+        self._transport = transport
+
+    async def export(self, title: Title, chapters: list[Chapter], output_path: Path) -> Path:
+        """Write ``chapters`` to ``output_path`` as an EPUB file.
+
+        Downloads the title's cover and every image referenced in the chapters' content and
+        embeds them; a download that fails is skipped rather than failing the whole export
+        (see docs/api-notes.md's "Illustrations" notes).
+
+        Args:
+            title: The chapters' parent title; supplies metadata, cover, and authors.
+            chapters: The chapters to include, in the order they should appear.
+            output_path: Where to write the ``.epub`` file.
+
+        Returns:
+            ``output_path``.
+        """
+        book = epub.EpubBook()
+        book.set_identifier(title.slug_url)
+        book.set_title(title.name)
+        book.set_language("ru")
+        for author in title.authors:
+            book.add_author(author.name)
+
+        async with httpx.AsyncClient(
+            timeout=15.0, follow_redirects=True, transport=self._transport
+        ) as client:
+            cover_url = pick_cover_url(title.cover)
+            if cover_url is not None:
+                cover_images = await download_images(client, [cover_url])
+                cover_bytes = cover_images.get(cover_url)
+                if cover_bytes is not None:
+                    book.set_cover(f"cover{guess_extension(cover_url)}", cover_bytes)
+
+            image_urls = list(
+                dict.fromkeys(
+                    url for chapter in chapters for url in extract_image_urls(chapter.content or "")
+                )
+            )
+            images = await download_images(client, image_urls)
+
+        url_to_local: dict[str, str] = {}
+        for index, (url, data) in enumerate(images.items(), start=1):
+            extension = guess_extension(url)
+            local_name = f"images/img{index:04d}{extension}"
+            url_to_local[url] = local_name
+            book.add_item(
+                epub.EpubItem(
+                    uid=local_name,
+                    file_name=local_name,
+                    media_type=media_type_for(extension),
+                    content=data,
+                )
+            )
+
+        spine: list[object] = ["nav"]
+        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)
+            doc = epub.EpubHtml(
+                uid=f"chapter_{index}",
+                file_name=f"chapter_{index}.xhtml",
+                title=heading,
+                lang="ru",
+            )
+            doc.content = f"<h1>{html.escape(heading)}</h1>{body}"
+            book.add_item(doc)
+            spine.append(doc)
+            toc.append(doc)
+
+        book.toc = toc
+        book.add_item(epub.EpubNcx())
+        book.add_item(epub.EpubNav())
+        book.spine = spine
+
+        epub.write_epub(str(output_path), book)
+        return output_path

ranobelib/exporters/fb2.py

@@ -0,0 +1,164 @@
+"""FB2 exporter."""
+
+from __future__ import annotations
+
+import datetime
+import xml.etree.ElementTree as ET
+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.models import Chapter, Title
+
+FB2_NS = "http://www.gribuser.ru/xml/fictionbook/2.0"
+ET.register_namespace("", FB2_NS)
+
+_BLOCK_TAGS = frozenset({"p", "div"})
+_STRONG_TAGS = frozenset({"strong", "b"})
+_EMPHASIS_TAGS = frozenset({"em", "i"})
+
+_FALLBACK_GENRE = "prose_contemporary"
+"""FB2's genre vocabulary is a fixed, controlled list with no reliable mapping from
+ranobelib's free-text genres — guessing wrong would be worse than a generic, always-valid
+fallback (title-info requires at least one genre), so genre mapping is out of scope for now.
+"""
+
+
+def _tag(name: str) -> str:
+    return f"{{{FB2_NS}}}{name}"
+
+
+class _HtmlToFb2Paragraphs(HTMLParser):
+    """Parses the SDK's normalized chapter-content HTML into FB2 ``<p>``/``<empty-line/>``
+    elements, preserving ``<strong>``/``<em>`` marks (mapped from ``b``/``i`` too — see
+    docs/api-notes.md's chapter-content notes on that tag variance).
+
+    Built on the stdlib parser rather than a regex, same reasoning as the txt exporter's
+    ``html_to_text``: HTML-string-format chapters pass the site's own markup through as-is.
+    Images carry no text and are dropped, matching CLAUDE.md's "no illustrations in fb2/txt"
+    decision.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self._paragraphs: list[ET.Element] = []
+        self._current: ET.Element | None = None
+        self._stack: list[ET.Element] = []
+
+    def _open_paragraph(self) -> None:
+        if self._current is None:
+            self._current = ET.Element(_tag("p"))
+            self._stack = [self._current]
+
+    def _close_paragraph(self) -> None:
+        if self._current is not None:
+            if (self._current.text and self._current.text.strip()) or len(self._current):
+                self._paragraphs.append(self._current)
+            self._current = None
+            self._stack = []
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag in _BLOCK_TAGS or tag == "br":
+            self._close_paragraph()
+            self._open_paragraph()
+        elif tag == "hr":
+            self._close_paragraph()
+            self._paragraphs.append(ET.Element(_tag("empty-line")))
+        elif tag in _STRONG_TAGS:
+            self._open_paragraph()
+            self._stack.append(ET.SubElement(self._stack[-1], _tag("strong")))
+        elif tag in _EMPHASIS_TAGS:
+            self._open_paragraph()
+            self._stack.append(ET.SubElement(self._stack[-1], _tag("emphasis")))
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in _BLOCK_TAGS:
+            self._close_paragraph()
+        elif (tag in _STRONG_TAGS or tag in _EMPHASIS_TAGS) and len(self._stack) > 1:
+            self._stack.pop()
+
+    def handle_data(self, data: str) -> None:
+        self._open_paragraph()
+        target = self._stack[-1]
+        if len(target) == 0:
+            target.text = (target.text or "") + data
+        else:
+            last = target[-1]
+            last.tail = (last.tail or "") + data
+
+    def get_paragraphs(self) -> list[ET.Element]:
+        self._close_paragraph()
+        return self._paragraphs
+
+
+def html_to_fb2_paragraphs(html_fragment: str) -> list[ET.Element]:
+    """Convert an HTML chapter-content fragment to a list of FB2 body elements."""
+    parser = _HtmlToFb2Paragraphs()
+    parser.feed(html_fragment)
+    return parser.get_paragraphs()
+
+
+def _build_description(title: Title) -> ET.Element:
+    description = ET.Element(_tag("description"))
+
+    title_info = ET.SubElement(description, _tag("title-info"))
+    ET.SubElement(title_info, _tag("genre")).text = _FALLBACK_GENRE
+    for author in title.authors:
+        author_el = ET.SubElement(title_info, _tag("author"))
+        ET.SubElement(author_el, _tag("nickname")).text = author.name
+    ET.SubElement(title_info, _tag("book-title")).text = title.name
+    if title.summary:
+        annotation = ET.SubElement(title_info, _tag("annotation"))
+        for paragraph in title.summary.split("\n\n"):
+            ET.SubElement(annotation, _tag("p")).text = paragraph
+    ET.SubElement(title_info, _tag("lang")).text = "ru"
+
+    document_info = ET.SubElement(description, _tag("document-info"))
+    document_author = ET.SubElement(document_info, _tag("author"))
+    ET.SubElement(document_author, _tag("nickname")).text = "ranobelib-python-sdk"
+    today = datetime.date.today().isoformat()
+    ET.SubElement(document_info, _tag("date"), value=today).text = today
+    ET.SubElement(document_info, _tag("id")).text = title.slug_url
+    ET.SubElement(document_info, _tag("version")).text = "1.0"
+
+    return description
+
+
+def _build_body(chapters: list[Chapter]) -> ET.Element:
+    body = ET.Element(_tag("body"))
+    for chapter in chapters:
+        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 ""):
+            section.append(paragraph)
+    return body
+
+
+@register
+class Fb2Exporter:
+    """Exports chapters as a single FB2 (FictionBook 2) file, one section per chapter."""
+
+    format: ClassVar[str] = "fb2"
+
+    async def export(self, title: Title, chapters: list[Chapter], output_path: Path) -> Path:
+        """Write ``chapters`` to ``output_path`` as FB2 XML.
+
+        Args:
+            title: The chapters' parent title; supplies ``description`` metadata.
+            chapters: The chapters to include, in the order they should appear.
+            output_path: Where to write the ``.fb2`` file.
+
+        Returns:
+            ``output_path``.
+        """
+        root = ET.Element(_tag("FictionBook"))
+        root.append(_build_description(title))
+        root.append(_build_body(chapters))
+
+        tree = ET.ElementTree(root)
+        ET.indent(tree, space="  ")
+        tree.write(output_path, encoding="utf-8", xml_declaration=True)
+        return output_path

ranobelib/exporters/pdf.py

@@ -0,0 +1,147 @@
+"""PDF exporter (WeasyPrint, reuses the HTML template from the epub exporter)."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import html
+from pathlib import Path
+from typing import ClassVar
+
+import httpx
+
+from ranobelib.exporters import register
+from ranobelib.exporters._illustrations import (
+    download_images,
+    extract_image_urls,
+    guess_extension,
+    media_type_for,
+    pick_cover_url,
+    rewrite_image_srcs,
+)
+from ranobelib.exporters._shared import chapter_heading
+from ranobelib.models import Chapter, Title
+
+try:
+    import weasyprint
+except (ImportError, OSError):
+    weasyprint = None
+    # WeasyPrint's native dependencies (Pango/cairo/gobject, normally provided by a GTK3
+    # runtime on Windows/macOS; readily apt-installable on Linux) aren't available on this
+    # system -- see docs/api-notes.md's "PDF export" notes. The pip package itself installs
+    # fine everywhere; only this native check at weasyprint's own import time can fail. When
+    # it does, "pdf" simply isn't registered as an export format below -- RanobeLib.export(
+    # fmt="pdf") then raises the same ValueError it would for any other unknown format,
+    # rather than crashing `import ranobelib` itself.
+
+_PAGE_CSS = """
+@page { margin: 2cm 1.5cm; }
+body { font-family: serif; line-height: 1.4; }
+.titlepage { text-align: center; break-after: page; }
+.titlepage img { max-width: 60%; max-height: 70vh; }
+.chapter { break-before: page; }
+.chapter:first-of-type { break-before: avoid; }
+img { max-width: 100%; }
+"""
+
+
+def _data_uri(media_type: str, data: bytes) -> str:
+    encoded = base64.b64encode(data).decode("ascii")
+    return f"data:{media_type};base64,{encoded}"
+
+
+def _title_page_html(title: Title, cover_data_uri: str | None) -> str:
+    cover_html = f'<img src="{cover_data_uri}" />' if cover_data_uri else ""
+    authors_html = ""
+    if title.authors:
+        names = ", ".join(html.escape(author.name) for author in title.authors)
+        authors_html = f"<p>{names}</p>"
+    heading = html.escape(title.name)
+    return f'<section class="titlepage">{cover_html}<h1>{heading}</h1>{authors_html}</section>'
+
+
+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)
+    return f'<section class="chapter"><h1>{heading}</h1>{body}</section>'
+
+
+if weasyprint is not None:
+
+    def _render_pdf(document: str, output_path: Path) -> None:
+        weasyprint.HTML(string=document).write_pdf(str(output_path))
+
+    @register
+    class PdfExporter:
+        """Exports chapters as a single PDF file, with cover and in-chapter illustrations.
+
+        Reuses the same illustration-downloading pipeline as ``EpubExporter``
+        (``exporters/_illustrations.py``) and the same chapter-heading/content shape — only
+        the final embedding step differs: images become base64 ``data:`` URIs directly in
+        the HTML string instead of separate files in a zip, since a PDF has no container to
+        put them in. WeasyPrint then renders that self-contained HTML/CSS to PDF; no network
+        access happens during rendering itself, only during the earlier httpx-based download
+        step, keeping all network I/O on the SDK's own async client (WeasyPrint has no async
+        API, so rendering runs in a thread via ``asyncio.to_thread`` rather than blocking the
+        event loop for however long a large book takes to lay out).
+        """
+
+        format: ClassVar[str] = "pdf"
+
+        def __init__(self, *, transport: httpx.AsyncBaseTransport | None = None) -> None:
+            """Initialize the exporter.
+
+            Args:
+                transport: Custom ``httpx`` transport for the image-downloading client, e.g.
+                    a mock transport for tests. Not part of the ``Exporter`` protocol itself
+                    — see ``EpubExporter.__init__`` for why.
+            """
+            self._transport = transport
+
+        async def export(self, title: Title, chapters: list[Chapter], output_path: Path) -> Path:
+            """Write ``chapters`` to ``output_path`` as a PDF file.
+
+            Args:
+                title: The chapters' parent title; supplies metadata, cover, and authors.
+                chapters: The chapters to include, in the order they should appear.
+                output_path: Where to write the ``.pdf`` file.
+
+            Returns:
+                ``output_path``.
+            """
+            async with httpx.AsyncClient(
+                timeout=15.0, follow_redirects=True, transport=self._transport
+            ) as client:
+                cover_url = pick_cover_url(title.cover)
+                cover_data_uri = None
+                if cover_url is not None:
+                    cover_images = await download_images(client, [cover_url])
+                    cover_bytes = cover_images.get(cover_url)
+                    if cover_bytes is not None:
+                        cover_media_type = media_type_for(guess_extension(cover_url))
+                        cover_data_uri = _data_uri(cover_media_type, cover_bytes)
+
+                image_urls = list(
+                    dict.fromkeys(
+                        url
+                        for chapter in chapters
+                        for url in extract_image_urls(chapter.content or "")
+                    )
+                )
+                images = await download_images(client, image_urls)
+
+            url_to_data_uri = {
+                url: _data_uri(media_type_for(guess_extension(url)), data)
+                for url, data in images.items()
+            }
+
+            body = _title_page_html(title, cover_data_uri) + "".join(
+                _chapter_html(chapter, url_to_data_uri) for chapter in chapters
+            )
+            document = (
+                f"<html><head><meta charset='utf-8'><style>{_PAGE_CSS}</style></head>"
+                f"<body>{body}</body></html>"
+            )
+
+            await asyncio.to_thread(_render_pdf, document, output_path)
+            return output_path

ranobelib/exporters/txt.py

@@ -0,0 +1,89 @@
+"""Plain text exporter."""
+
+from __future__ import annotations
+
+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.models import Chapter, Title
+
+_BLOCK_TAGS = frozenset({"p", "div"})
+
+
+class _HtmlToText(HTMLParser):
+    """Extracts readable plain text from the SDK's normalized chapter-content HTML.
+
+    Built on the stdlib parser rather than a regex, since chapter content isn't limited to
+    the small tag vocabulary ``Chapter.content`` normalizes prosemirror-doc chapters to —
+    HTML-string-format chapters pass the site's own markup through as-is, which can include
+    tags/entities a regex would mishandle (see docs/api-notes.md's chapter-content notes).
+    Images carry no text and are dropped automatically, matching the "no illustrations in
+    txt/fb2" decision in CLAUDE.md.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self._paragraphs: list[str] = []
+        self._current: list[str] = []
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag in _BLOCK_TAGS:
+            self._flush()
+        elif tag == "br":
+            self._current.append("\n")
+        elif tag == "hr":
+            self._flush()
+            self._paragraphs.append("---")
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in _BLOCK_TAGS:
+            self._flush()
+
+    def handle_data(self, data: str) -> None:
+        self._current.append(data)
+
+    def _flush(self) -> None:
+        text = "".join(self._current).strip()
+        if text:
+            self._paragraphs.append(text)
+        self._current = []
+
+    def get_text(self) -> str:
+        self._flush()
+        return "\n\n".join(self._paragraphs)
+
+
+def html_to_text(html_fragment: str) -> str:
+    """Convert an HTML chapter-content fragment to plain text paragraphs."""
+    parser = _HtmlToText()
+    parser.feed(html_fragment)
+    return parser.get_text()
+
+
+@register
+class TxtExporter:
+    """Exports chapters as a single plain-text file, one heading per chapter."""
+
+    format: ClassVar[str] = "txt"
+
+    async def export(self, title: Title, chapters: list[Chapter], output_path: Path) -> Path:
+        """Write ``chapters`` to ``output_path`` as plain text.
+
+        Args:
+            title: The chapters' parent title; only its name is used.
+            chapters: The chapters to include, in the order they should appear.
+            output_path: Where to write the ``.txt`` file.
+
+        Returns:
+            ``output_path``.
+        """
+        sections = [title.name]
+        for chapter in chapters:
+            body = html_to_text(chapter.content or "")
+            sections.append(f"{chapter_heading(chapter)}\n\n{body}")
+
+        output_path.write_text("\n\n\n".join(sections) + "\n", encoding="utf-8")
+        return output_path