mangalib-python-sdk 0.1.0__tar.gz → 0.2.1__tar.gz

{mangalib_python_sdk-0.1.0 → mangalib_python_sdk-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mangalib-python-sdk
-Version: 0.1.0
+Version: 0.2.1
 Summary: Async Python SDK for mangalib.me: title metadata, chapters, translations, catalog and page images
 Keywords: mangalib,manga,manhwa,comics,lib.social,sdk
 Author: LLIJIYAPNIK
@@ -18,22 +18,24 @@ Classifier: Typing :: Typed
 Requires-Dist: httpx>=0.27
 Requires-Dist: libsocial-core>=1.0,<2
 Requires-Dist: pydantic>=2.7
+Requires-Dist: img2pdf>=0.5 ; extra == 'pdf'
 Requires-Python: >=3.11
-Project-URL: Homepage, https://github.com/LLIJIYAPNIK/ranobelib-python-sdk
-Project-URL: Repository, https://github.com/LLIJIYAPNIK/ranobelib-python-sdk
-Project-URL: Issues, https://github.com/LLIJIYAPNIK/ranobelib-python-sdk/issues
-Project-URL: Changelog, https://github.com/LLIJIYAPNIK/ranobelib-python-sdk/blob/main/packages/mangalib/CHANGELOG.md
+Project-URL: Homepage, https://github.com/LLIJIYAPNIK/libsocial-sdk
+Project-URL: Repository, https://github.com/LLIJIYAPNIK/libsocial-sdk
+Project-URL: Issues, https://github.com/LLIJIYAPNIK/libsocial-sdk/issues
+Project-URL: Changelog, https://github.com/LLIJIYAPNIK/libsocial-sdk/blob/main/packages/mangalib/CHANGELOG.md
+Provides-Extra: pdf
 Description-Content-Type: text/markdown
 
 # mangalib-python-sdk
 
 [![PyPI](https://img.shields.io/pypi/v/mangalib-python-sdk)](https://pypi.org/project/mangalib-python-sdk/)
-[![License: MIT](https://img.shields.io/github/license/LLIJIYAPNIK/ranobelib-python-sdk)](../../LICENSE)
+[![License: MIT](https://img.shields.io/github/license/LLIJIYAPNIK/libsocial-sdk)](../../LICENSE)
 [![Python versions](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](pyproject.toml)
-[![CI](https://github.com/LLIJIYAPNIK/ranobelib-python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/LLIJIYAPNIK/ranobelib-python-sdk/actions/workflows/ci.yml)
+[![CI](https://github.com/LLIJIYAPNIK/libsocial-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/LLIJIYAPNIK/libsocial-sdk/actions/workflows/ci.yml)
 
 Async Python SDK for [mangalib.me](https://mangalib.me): title metadata, table of contents,
-translations, catalog search, and chapter pages as images.
+translations, catalog search, chapter pages as images, and export to CBZ or PDF.
 
 Like [`ranobelib-python-sdk`](https://pypi.org/project/ranobelib-python-sdk/), it talks to
 the undocumented but open JSON API behind the site (`api.cdnlibs.org`, shared by the whole
@@ -41,9 +43,8 @@ lib.social network) instead of scraping HTML. The shared part (API client, reque
 cache, titles, chapters, catalog) comes from `libsocial-core`, installed with it, so a
 process using both SDKs paces its requests to the API together.
 
-> **Status:** early. Titles, chapters, translations, the catalog and page downloads work;
-> export to CBZ/PDF is planned. There is no login, so paid and early-access chapters can't
-> be read: fetching one raises `AuthRequiredError`.
+> **Status:** early. There is no login, so paid and early-access chapters can't be read:
+> fetching one raises `AuthRequiredError`, and a whole-title download leaves them out.
 
 ## Installation
 
@@ -57,7 +58,9 @@ or
 pip install mangalib-python-sdk
 ```
 
-Requires Python 3.11+.
+PDF export needs the `pdf` extra (img2pdf): `uv add "mangalib-python-sdk[pdf]"` /
+`pip install "mangalib-python-sdk[pdf]"`. Without it, `"pdf"` just isn't one of the export
+formats. Requires Python 3.11+.
 
 ## Quickstart
 
@@ -76,6 +79,13 @@ async with MangaLib("https://mangalib.me/ru/manga/7965--chainsaw-man") as lib:
         print(page.number, page.width, page.height)
     images = await lib.download_pages(chapter)  # list[bytes], in reading order
 
+    # One chapter, several, a volume, or the whole title, into one file.
+    await lib.export([chapter], fmt="cbz", path="chainsaw-man-1.cbz")
+    volumes = await lib.download_title(translation_index=0, on_chapter=print)
+    await lib.export(volumes, fmt="pdf", path="chainsaw-man.pdf", on_chapter=print)
+
+    size = await lib.estimate_title_size()  # bytes of page images, from a sample
+
 async with Catalog() as catalog:
     page = await catalog.list_titles(query="chainsaw")
 ```
@@ -86,11 +96,26 @@ async with Catalog() as catalog:
 - `ChapterBranch.is_open` (from `get_table_of_contents()` / `get_translations()`) says
   whether a translation can be read without an account.
 - `download_page()` / `download_pages()` fall back from one image server to the next; see
-  `list_image_servers()` and the API notes for why `compress` is tried first.
+  `list_image_servers()` and the API notes for why `compress` is tried first. Requests to
+  an image host are paced across the process and retried on 429/5xx; `concurrency=` sets
+  how many pages are fetched at once.
+- `export()` writes `"cbz"` (pages in order + `ComicInfo.xml`) or `"pdf"` (a page per image,
+  an outline entry per chapter); `mangalib.exporters.EXPORTERS` lists what's available.
+- `chapter_size()` / `volume_size()` give the exact size of the page images, from `HEAD`
+  requests; `estimate_title_size()` extrapolates from a sample of chapters.
+
+## Examples
+
+Complete, runnable scripts for every feature above — title metadata, table of contents,
+chapters and volumes, translations and closed chapters, whole-title download, page images
+and image servers, export to CBZ/PDF and to a format of your own, sizes, the catalog, disk
+caching and error handling — live in
+**[`examples/mangalib/`](https://github.com/LLIJIYAPNIK/libsocial-sdk/tree/main/examples/mangalib)**,
+one heavily commented file per feature.
 
 ## Documentation
 
-Full API reference: **<https://LLIJIYAPNIK.github.io/ranobelib-python-sdk/>**. What the API
+Full API reference: **<https://LLIJIYAPNIK.github.io/libsocial-sdk/>**. What the API
 returns for MangaLib, and what was checked: the "MangaLib" section of
 [`docs/api-notes.md`](../../docs/api-notes.md). [`CHANGELOG.md`](CHANGELOG.md) lists what
 changed in each release.

{mangalib_python_sdk-0.1.0 → mangalib_python_sdk-0.2.1}/README.md

@@ -1,12 +1,12 @@
 # mangalib-python-sdk
 
 [![PyPI](https://img.shields.io/pypi/v/mangalib-python-sdk)](https://pypi.org/project/mangalib-python-sdk/)
-[![License: MIT](https://img.shields.io/github/license/LLIJIYAPNIK/ranobelib-python-sdk)](../../LICENSE)
+[![License: MIT](https://img.shields.io/github/license/LLIJIYAPNIK/libsocial-sdk)](../../LICENSE)
 [![Python versions](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)](pyproject.toml)
-[![CI](https://github.com/LLIJIYAPNIK/ranobelib-python-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/LLIJIYAPNIK/ranobelib-python-sdk/actions/workflows/ci.yml)
+[![CI](https://github.com/LLIJIYAPNIK/libsocial-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/LLIJIYAPNIK/libsocial-sdk/actions/workflows/ci.yml)
 
 Async Python SDK for [mangalib.me](https://mangalib.me): title metadata, table of contents,
-translations, catalog search, and chapter pages as images.
+translations, catalog search, chapter pages as images, and export to CBZ or PDF.
 
 Like [`ranobelib-python-sdk`](https://pypi.org/project/ranobelib-python-sdk/), it talks to
 the undocumented but open JSON API behind the site (`api.cdnlibs.org`, shared by the whole
@@ -14,9 +14,8 @@ lib.social network) instead of scraping HTML. The shared part (API client, reque
 cache, titles, chapters, catalog) comes from `libsocial-core`, installed with it, so a
 process using both SDKs paces its requests to the API together.
 
-> **Status:** early. Titles, chapters, translations, the catalog and page downloads work;
-> export to CBZ/PDF is planned. There is no login, so paid and early-access chapters can't
-> be read: fetching one raises `AuthRequiredError`.
+> **Status:** early. There is no login, so paid and early-access chapters can't be read:
+> fetching one raises `AuthRequiredError`, and a whole-title download leaves them out.
 
 ## Installation
 
@@ -30,7 +29,9 @@ or
 pip install mangalib-python-sdk
 ```
 
-Requires Python 3.11+.
+PDF export needs the `pdf` extra (img2pdf): `uv add "mangalib-python-sdk[pdf]"` /
+`pip install "mangalib-python-sdk[pdf]"`. Without it, `"pdf"` just isn't one of the export
+formats. Requires Python 3.11+.
 
 ## Quickstart
 
@@ -49,6 +50,13 @@ async with MangaLib("https://mangalib.me/ru/manga/7965--chainsaw-man") as lib:
         print(page.number, page.width, page.height)
     images = await lib.download_pages(chapter)  # list[bytes], in reading order
 
+    # One chapter, several, a volume, or the whole title, into one file.
+    await lib.export([chapter], fmt="cbz", path="chainsaw-man-1.cbz")
+    volumes = await lib.download_title(translation_index=0, on_chapter=print)
+    await lib.export(volumes, fmt="pdf", path="chainsaw-man.pdf", on_chapter=print)
+
+    size = await lib.estimate_title_size()  # bytes of page images, from a sample
+
 async with Catalog() as catalog:
     page = await catalog.list_titles(query="chainsaw")
 ```
@@ -59,11 +67,26 @@ async with Catalog() as catalog:
 - `ChapterBranch.is_open` (from `get_table_of_contents()` / `get_translations()`) says
   whether a translation can be read without an account.
 - `download_page()` / `download_pages()` fall back from one image server to the next; see
-  `list_image_servers()` and the API notes for why `compress` is tried first.
+  `list_image_servers()` and the API notes for why `compress` is tried first. Requests to
+  an image host are paced across the process and retried on 429/5xx; `concurrency=` sets
+  how many pages are fetched at once.
+- `export()` writes `"cbz"` (pages in order + `ComicInfo.xml`) or `"pdf"` (a page per image,
+  an outline entry per chapter); `mangalib.exporters.EXPORTERS` lists what's available.
+- `chapter_size()` / `volume_size()` give the exact size of the page images, from `HEAD`
+  requests; `estimate_title_size()` extrapolates from a sample of chapters.
+
+## Examples
+
+Complete, runnable scripts for every feature above — title metadata, table of contents,
+chapters and volumes, translations and closed chapters, whole-title download, page images
+and image servers, export to CBZ/PDF and to a format of your own, sizes, the catalog, disk
+caching and error handling — live in
+**[`examples/mangalib/`](https://github.com/LLIJIYAPNIK/libsocial-sdk/tree/main/examples/mangalib)**,
+one heavily commented file per feature.
 
 ## Documentation
 
-Full API reference: **<https://LLIJIYAPNIK.github.io/ranobelib-python-sdk/>**. What the API
+Full API reference: **<https://LLIJIYAPNIK.github.io/libsocial-sdk/>**. What the API
 returns for MangaLib, and what was checked: the "MangaLib" section of
 [`docs/api-notes.md`](../../docs/api-notes.md). [`CHANGELOG.md`](CHANGELOG.md) lists what
 changed in each release.

{mangalib_python_sdk-0.1.0 → mangalib_python_sdk-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mangalib-python-sdk"
-version = "0.1.0"
+version = "0.2.1"
 description = "Async Python SDK for mangalib.me: title metadata, chapters, translations, catalog and page images"
 readme = "README.md"
 license = "MIT"
@@ -34,11 +34,14 @@ dependencies = [
 name = "LLIJIYAPNIK"
 email = "kas4wot@yandex.ru"
 
+[project.optional-dependencies]
+pdf = ["img2pdf>=0.5"]
+
 [project.urls]
-Homepage = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk"
-Repository = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk"
-Issues = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk/issues"
-Changelog = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk/blob/main/packages/mangalib/CHANGELOG.md"
+Homepage = "https://github.com/LLIJIYAPNIK/libsocial-sdk"
+Repository = "https://github.com/LLIJIYAPNIK/libsocial-sdk"
+Issues = "https://github.com/LLIJIYAPNIK/libsocial-sdk/issues"
+Changelog = "https://github.com/LLIJIYAPNIK/libsocial-sdk/blob/main/packages/mangalib/CHANGELOG.md"
 
 [build-system]
 requires = ["uv_build>=0.11.26,<0.12.0"]
@@ -52,6 +55,8 @@ workspace = true
 
 [dependency-groups]
 dev = [
+    "img2pdf>=0.5",
+    "pypdf>=6.14.2",
     "pytest>=8.0",
     "pytest-asyncio>=0.24",
     "pytest-cov>=5.0",

{mangalib_python_sdk-0.1.0 → mangalib_python_sdk-0.2.1}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "mangalib-python-sdk"
-version = "0.1.0"
+version = "0.2.1"
 description = "Async Python SDK for mangalib.me: title metadata, chapters, translations, catalog and page images"
 readme = "README.md"
 license = "MIT"
@@ -26,11 +26,15 @@ dependencies = [
     "pydantic>=2.7",
 ]
 
+[project.optional-dependencies]
+# PDF export. Without it, "pdf" just isn't one of the export formats.
+pdf = ["img2pdf>=0.5"]
+
 [project.urls]
-Homepage = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk"
-Repository = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk"
-Issues = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk/issues"
-Changelog = "https://github.com/LLIJIYAPNIK/ranobelib-python-sdk/blob/main/packages/mangalib/CHANGELOG.md"
+Homepage = "https://github.com/LLIJIYAPNIK/libsocial-sdk"
+Repository = "https://github.com/LLIJIYAPNIK/libsocial-sdk"
+Issues = "https://github.com/LLIJIYAPNIK/libsocial-sdk/issues"
+Changelog = "https://github.com/LLIJIYAPNIK/libsocial-sdk/blob/main/packages/mangalib/CHANGELOG.md"
 
 [build-system]
 requires = ["uv_build>=0.11.26,<0.12.0"]
@@ -47,6 +51,8 @@ libsocial-core = { workspace = true }
 # mangalib-python-sdk` installs the package's own groups, not the root's.
 [dependency-groups]
 dev = [
+    "img2pdf>=0.5",
+    "pypdf>=6.14.2",
     "pytest>=8.0",
     "pytest-asyncio>=0.24",
     "pytest-cov>=5.0",

mangalib_python_sdk-0.2.1/src/mangalib/exporters/__init__.py

@@ -0,0 +1,73 @@
+"""Exporter protocol and format registry — the same contract as ``ranobelib.exporters``.
+
+A new export format is a new module in this package: define a class implementing
+``Exporter`` and decorate it with ``@register`` — no changes needed here or in ``sdk.py``.
+Every module in this package is auto-imported below so its ``@register`` runs on its own.
+A format whose optional dependency isn't installed (``pdf`` needs ``img2pdf``) skips its
+``@register``, so it's simply not in ``EXPORTERS``.
+"""
+
+from __future__ import annotations
+
+import importlib
+import pkgutil
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+from typing import ClassVar, Protocol, TypeVar, runtime_checkable
+
+from mangalib.models import Chapter, Title
+
+__all__ = ["EXPORTERS", "Exporter", "FetchPages", "register"]
+
+FetchPages = Callable[[Chapter], Awaitable[list[bytes]]]
+"""Downloads a chapter's page images, in reading order — ``MangaLib.download_pages()``."""
+
+
+@runtime_checkable
+class Exporter(Protocol):
+    """Renders a title's chapters, as page images, to a single file in some format."""
+
+    format: ClassVar[str]
+    """The registry key this exporter is selected by, e.g. ``"cbz"``."""
+
+    async def export(
+        self,
+        title: Title,
+        chapters: list[Chapter],
+        output_path: Path,
+        *,
+        fetch_pages: FetchPages,
+        on_chapter: Callable[[], None] | None = None,
+    ) -> Path:
+        """Write ``chapters`` (in the given order) to ``output_path``.
+
+        Args:
+            title: The chapters' parent title, for metadata (name, authors, ...).
+            chapters: The chapters to include, in the order they should appear — fetched
+                ones, with ``pages``.
+            output_path: Where to write the exported file.
+            fetch_pages: Downloads one chapter's page images. The exporter calls it once per
+                chapter, in order, so it never holds more than it has to in memory.
+            on_chapter: Called once per chapter written, if given — drives
+                ``MangaLib.export()``'s progress reporting.
+
+        Returns:
+            ``output_path``, once the file has been written.
+        """
+        ...
+
+
+ExporterT = TypeVar("ExporterT", bound=type[Exporter])
+
+EXPORTERS: dict[str, type[Exporter]] = {}
+"""Registered exporters, keyed by ``Exporter.format``."""
+
+
+def register(exporter: ExporterT) -> ExporterT:
+    """Class decorator: register ``exporter`` under its ``format`` key."""
+    EXPORTERS[exporter.format] = exporter
+    return exporter
+
+
+for _module_info in pkgutil.iter_modules(__path__, f"{__name__}."):
+    importlib.import_module(_module_info.name)

mangalib_python_sdk-0.2.1/src/mangalib/exporters/_shared.py

@@ -0,0 +1,33 @@
+"""Helpers shared by the exporters (not public API)."""
+
+from __future__ import annotations
+
+from mangalib.models import Chapter
+
+_SIGNATURES = (
+    (b"\xff\xd8\xff", "jpg"),
+    (b"\x89PNG\r\n\x1a\n", "png"),
+    (b"GIF87a", "gif"),
+    (b"GIF89a", "gif"),
+)
+
+
+def image_extension(data: bytes) -> str:
+    """The file extension for an image, from its bytes rather than its name.
+
+    A page's file name isn't a reliable guide: the ``compress`` server sends JPEG for
+    ``.png`` names (see docs/api-notes.md). Unrecognized data gets ``"jpg"``, what the
+    servers send nearly always.
+    """
+    if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "webp"
+    for signature, extension in _SIGNATURES:
+        if data.startswith(signature):
+            return extension
+    return "jpg"
+
+
+def chapter_label(chapter: Chapter) -> str:
+    """``"Том 1 Глава 5"`` plus the chapter's name, as the site shows a chapter."""
+    label = f"Том {chapter.volume} Глава {chapter.number}"
+    return f"{label} — {chapter.name}" if chapter.name else label

mangalib_python_sdk-0.2.1/src/mangalib/exporters/_writing.py

@@ -0,0 +1,27 @@
+"""Writing an export file atomically (not public API)."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import tempfile
+from collections.abc import Iterator
+from pathlib import Path
+
+
+@contextlib.contextmanager
+def atomic_output(path: Path) -> Iterator[Path]:
+    """A temporary file next to ``path`` that replaces it only if the block succeeds.
+
+    An export downloads every page as it goes, so it can fail halfway (a page no server
+    serves, a closed chapter); without this, that would leave a truncated file behind, or
+    clobber a good one from an earlier run.
+    """
+    descriptor, name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".part")
+    os.close(descriptor)
+    temporary = Path(name)
+    try:
+        yield temporary
+        os.replace(temporary, path)
+    finally:
+        temporary.unlink(missing_ok=True)

mangalib_python_sdk-0.2.1/src/mangalib/exporters/cbz.py

@@ -0,0 +1,143 @@
+"""CBZ exporter: a zip of the page images in reading order, with ``ComicInfo.xml``."""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+import zipfile
+from collections.abc import Callable
+from pathlib import Path
+from typing import ClassVar
+
+from mangalib._http import SITE_ORIGIN
+from mangalib.exporters import FetchPages, register
+from mangalib.exporters._shared import chapter_label, image_extension
+from mangalib.exporters._writing import atomic_output
+from mangalib.models import Chapter, Title
+
+_RIGHT_TO_LEFT_TYPES = frozenset({"Манга"})
+"""Title types (``Title.country``) read right to left — ``ComicInfo``'s
+``Manga=YesAndRightToLeft``. Manhwa, manhua and the rest are read left to right, and the
+field is left out for them rather than guessed further."""
+
+
+@register
+class CbzExporter:
+    """Writes chapters as one CBZ: every page image in reading order, plus ``ComicInfo.xml``.
+
+    Pages are stored without recompression (they're JPEGs already), named by their position
+    in the book with zero padding (``0001.jpg``, ``0002.jpg``, ...) so every reader sorts
+    them right, with the extension taken from the image's bytes. Where each chapter starts is
+    recorded as a ``Bookmark`` on its first page in ``ComicInfo.xml`` (schema 2.1, as read by
+    Komga, Kavita, ComicRack and others), which also carries the title's metadata.
+    """
+
+    format: ClassVar[str] = "cbz"
+
+    async def export(
+        self,
+        title: Title,
+        chapters: list[Chapter],
+        output_path: Path,
+        *,
+        fetch_pages: FetchPages,
+        on_chapter: Callable[[], None] | None = None,
+    ) -> Path:
+        """Write ``chapters`` to ``output_path`` as a CBZ — see ``Exporter.export()``."""
+        total_pages = sum(len(chapter.pages) for chapter in chapters)
+        width = max(4, len(str(total_pages)))
+        entries: list[_PageEntry] = []
+        with (
+            atomic_output(output_path) as temporary,
+            zipfile.ZipFile(temporary, "w", zipfile.ZIP_STORED) as archive,
+        ):
+            for chapter in chapters:
+                images = await fetch_pages(chapter)
+                for position, (page, data) in enumerate(zip(chapter.pages, images, strict=True)):
+                    index = len(entries)
+                    archive.writestr(f"{index + 1:0{width}}.{image_extension(data)}", data)
+                    entries.append(
+                        _PageEntry(
+                            size=len(data),
+                            width=page.width,
+                            height=page.height,
+                            bookmark=chapter_label(chapter) if position == 0 else None,
+                        )
+                    )
+                if on_chapter is not None:
+                    on_chapter()
+            archive.writestr("ComicInfo.xml", comic_info(title, chapters, entries))
+        return output_path
+
+
+class _PageEntry:
+    """What ``ComicInfo.xml`` says about one page of the book."""
+
+    def __init__(
+        self, *, size: int, width: int | None, height: int | None, bookmark: str | None
+    ) -> None:
+        self.size = size
+        self.width = width
+        self.height = height
+        self.bookmark = bookmark
+
+
+def comic_info(title: Title, chapters: list[Chapter], pages: list[_PageEntry]) -> bytes:
+    """``ComicInfo.xml`` for a book of ``chapters`` (not public API).
+
+    Elements are written in the schema's order, only when there's a value. ``Number`` (and
+    a chapter's name as ``Title``) is set for a single chapter, ``Volume`` when every chapter
+    is in the same numbered volume — a book spanning several has neither.
+    """
+    root = ET.Element(
+        "ComicInfo",
+        {
+            "xmlns:xsi": "http://www.w3.org/2001/XMLSchema-instance",
+            "xmlns:xsd": "http://www.w3.org/2001/XMLSchema",
+        },
+    )
+
+    def add(tag: str, value: object) -> None:
+        if value not in (None, "", []):
+            ET.SubElement(root, tag).text = str(value)
+
+    volumes = {chapter.volume for chapter in chapters}
+    single = chapters[0] if len(chapters) == 1 else None
+    volume = next(iter(volumes)) if len(volumes) == 1 else None
+    if single is not None:
+        book_title = single.name
+    elif volume is not None:
+        book_title = f"Том {volume}"
+    else:
+        book_title = None
+    teams = dict.fromkeys(team.name for chapter in chapters for team in chapter.teams)
+
+    add("Title", book_title)
+    add("Series", title.rus_name or title.name)
+    add("Number", single.number if single is not None else None)
+    add("Volume", volume if volume is not None and volume.isdigit() else None)
+    add("Summary", title.summary)
+    add("Year", title.release_date if (title.release_date or "").isdigit() else None)
+    add("Writer", ", ".join(person.name for person in title.authors))
+    add("Penciller", ", ".join(person.name for person in title.artists))
+    add("Translator", ", ".join(teams))
+    add("Genre", ", ".join(genre.name for genre in title.genres))
+    add("Tags", ", ".join(tag.name for tag in title.tags))
+    add("Web", f"{SITE_ORIGIN}/ru/manga/{title.slug_url}")
+    add("PageCount", len(pages))
+    add("LanguageISO", "ru")
+    if title.country is not None and title.country.name in _RIGHT_TO_LEFT_TYPES:
+        add("Manga", "YesAndRightToLeft")
+
+    pages_element = ET.SubElement(root, "Pages")
+    for index, page in enumerate(pages):
+        attributes = {"Image": str(index), "ImageSize": str(page.size)}
+        if page.width is not None and page.height is not None:
+            attributes["ImageWidth"] = str(page.width)
+            attributes["ImageHeight"] = str(page.height)
+        if page.bookmark is not None:
+            attributes["Bookmark"] = page.bookmark
+        ET.SubElement(pages_element, "Page", attributes)
+
+    ET.indent(root)
+    data: bytes = ET.tostring(root, encoding="utf-8", xml_declaration=True)
+    return data

mangalib_python_sdk-0.2.1/src/mangalib/exporters/pdf.py

@@ -0,0 +1,83 @@
+"""PDF exporter: one PDF page per page image, via img2pdf (``mangalib-python-sdk[pdf]``)."""
+
+from __future__ import annotations
+
+import asyncio
+import tempfile
+from collections.abc import Callable
+from pathlib import Path
+from typing import ClassVar
+
+from mangalib.exporters import FetchPages, register
+from mangalib.exporters._shared import chapter_label, image_extension
+from mangalib.exporters._writing import atomic_output
+from mangalib.models import Chapter, Title
+
+try:
+    import img2pdf
+    import pikepdf
+except ImportError:
+    img2pdf = None
+    pikepdf = None  # type: ignore[assignment]
+    # The "pdf" extra isn't installed: "pdf" just isn't registered below, and
+    # MangaLib.export(fmt="pdf") raises the same ValueError as for any unknown format.
+
+
+class PdfExporter:
+    """Writes chapters as one PDF: a page per page image, an outline entry per chapter.
+
+    JPEGs are embedded as they are, without recompression (img2pdf), so the file is about
+    the size of the images. Each PDF page is the image's own size; a tall webtoon strip
+    beyond the PDF page-size limit is scaled with ``/UserUnit`` rather than cut. The PDF is
+    assembled in memory, so for a whole long title CBZ is the lighter choice.
+    """
+
+    format: ClassVar[str] = "pdf"
+
+    async def export(
+        self,
+        title: Title,
+        chapters: list[Chapter],
+        output_path: Path,
+        *,
+        fetch_pages: FetchPages,
+        on_chapter: Callable[[], None] | None = None,
+    ) -> Path:
+        """Write ``chapters`` to ``output_path`` as a PDF — see ``Exporter.export()``."""
+        with tempfile.TemporaryDirectory(prefix="mangalib-pdf-") as directory:
+            files: list[Path] = []
+            outline: list[tuple[str, int]] = []
+            for chapter in chapters:
+                images = await fetch_pages(chapter)
+                if images:
+                    outline.append((chapter_label(chapter), len(files)))
+                for data in images:
+                    path = Path(directory) / f"{len(files):06}.{image_extension(data)}"
+                    path.write_bytes(data)
+                    files.append(path)
+                if on_chapter is not None:
+                    on_chapter()
+            with atomic_output(output_path) as temporary:
+                await asyncio.to_thread(_write_pdf, title, files, outline, temporary)
+        return output_path
+
+
+def _write_pdf(title: Title, files: list[Path], outline: list[tuple[str, int]], path: Path) -> None:
+    """Assemble the PDF (CPU-bound and synchronous, so it runs off the event loop)."""
+    with path.open("wb") as stream:
+        img2pdf.convert(
+            [str(file) for file in files],
+            outputstream=stream,
+            title=title.rus_name or title.name,
+            author=", ".join(person.name for person in title.authors) or None,
+            nodate=True,
+        )
+    with pikepdf.open(path, allow_overwriting_input=True) as pdf:
+        with pdf.open_outline() as document_outline:
+            for label, page_index in outline:
+                document_outline.root.append(pikepdf.OutlineItem(label, page_index))
+        pdf.save(path)
+
+
+if img2pdf is not None:
+    register(PdfExporter)