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

ranobelib/models.py

@@ -0,0 +1,245 @@
+"""Pydantic models: Title, Chapter, Volume, Team, Branch, and related types."""
+
+from __future__ import annotations
+
+import html
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+SITE_BASE_URL = "https://ranobelib.me"
+"""Base URL used to resolve relative asset paths (e.g. in-chapter image attachments)."""
+
+
+def _prosemirror_to_text(doc: dict[str, Any]) -> str:
+    """Flatten a prosemirror-doc JSON structure into plain text paragraphs.
+
+    This is a minimal parser (text leaves only, joined paragraph by paragraph) sufficient
+    for a title's summary. Chapter content will need a richer version that preserves
+    formatting (bold/italic/headings/lists) once that feature is implemented.
+    """
+
+    def extract(node: dict[str, Any]) -> str:
+        if node.get("type") == "text":
+            return str(node.get("text", ""))
+        return "".join(extract(child) for child in node.get("content", []))
+
+    paragraphs = [extract(block) for block in doc.get("content", [])]
+    return "\n\n".join(paragraph for paragraph in paragraphs if paragraph)
+
+
+def _child_nodes(node: dict[str, Any]) -> list[dict[str, Any]]:
+    content: list[dict[str, Any]] = node.get("content") or []
+    return content
+
+
+def _resolve_attachment_url(image_id: str, attachments: list[dict[str, Any]]) -> str | None:
+    for attachment in attachments:
+        if attachment.get("name") == image_id:
+            url = attachment.get("url")
+            return f"{SITE_BASE_URL}{url}" if url else None
+    return None
+
+
+def _render_prosemirror_marks(text: str, marks: list[dict[str, Any]]) -> str:
+    for mark in marks:
+        if mark.get("type") == "bold":
+            text = f"<strong>{text}</strong>"
+        elif mark.get("type") == "italic":
+            text = f"<em>{text}</em>"
+    return text
+
+
+def _render_prosemirror_inline(node: dict[str, Any], attachments: list[dict[str, Any]]) -> str:
+    node_type = node.get("type")
+    if node_type == "text":
+        text = html.escape(str(node.get("text", "")))
+        return _render_prosemirror_marks(text, node.get("marks") or [])
+    if node_type == "hardBreak":
+        return "<br />"
+    if node_type == "image":
+        images = node.get("attrs", {}).get("images") or []
+        urls = (_resolve_attachment_url(image.get("image", ""), attachments) for image in images)
+        return "".join(f'<img loading="lazy" src="{url}" />' for url in urls if url)
+    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:
+    node_type = node.get("type")
+    if node_type == "paragraph":
+        inner = "".join(
+            _render_prosemirror_inline(child, attachments) for child in _child_nodes(node)
+        )
+        return f"<p>{inner}</p>"
+    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))
+
+
+def _prosemirror_to_html(doc: dict[str, Any], attachments: list[dict[str, Any]]) -> str:
+    """Render a prosemirror-doc JSON structure as an HTML fragment.
+
+    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.
+    """
+    return "".join(_render_prosemirror_block(block, attachments) for block in _child_nodes(doc))
+
+
+class Cover(BaseModel):
+    """A set of cover image URLs at different sizes."""
+
+    filename: str | None = None
+    thumbnail: str | None = None
+    default: str | None = None
+    md: str | None = None
+
+
+class Label(BaseModel):
+    """A small ``{id, label}`` enum value used throughout the API (status, age rating, ...)."""
+
+    id: int
+    label: str
+
+
+class Genre(BaseModel):
+    """A genre tag (e.g. Fantasy, Romance)."""
+
+    id: int
+    name: str
+    adult: bool = False
+
+
+class Tag(BaseModel):
+    """A free-form content tag."""
+
+    id: int
+    name: str
+    adult: bool = False
+
+
+class Person(BaseModel):
+    """An author or artist credited on a title."""
+
+    id: int
+    slug: str
+    slug_url: str
+    name: str
+    rus_name: str | None = None
+
+
+class Team(BaseModel):
+    """A translation team."""
+
+    id: int
+    slug: str
+    slug_url: str
+    name: str
+
+
+class Title(BaseModel):
+    """Metadata for a single title (novel)."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: int
+    name: str
+    rus_name: str | None = None
+    eng_name: str | None = None
+    other_names: list[str] = Field(default_factory=list, alias="otherNames")
+    slug: str
+    slug_url: str
+    cover: Cover
+    age_restriction: Label = Field(alias="ageRestriction")
+    status: Label
+    summary: str | None = None
+    release_date: str | None = Field(default=None, alias="releaseDate")
+    is_licensed: bool = False
+    genres: list[Genre] = Field(default_factory=list)
+    tags: list[Tag] = Field(default_factory=list)
+    authors: list[Person] = Field(default_factory=list)
+    artists: list[Person] = Field(default_factory=list)
+    teams: list[Team] = Field(default_factory=list)
+    chapter_count: int | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _flatten_chapter_count(cls, data: Any) -> Any:
+        if isinstance(data, dict) and "chapter_count" not in data:
+            items_count = data.get("items_count")
+            if isinstance(items_count, dict):
+                data = {**data, "chapter_count": items_count.get("uploaded")}
+        return data
+
+    @field_validator("summary", mode="before")
+    @classmethod
+    def _parse_summary(cls, value: Any) -> str | None:
+        if value is None:
+            return None
+        if isinstance(value, dict):
+            return _prosemirror_to_text(value)
+        return str(value)
+
+
+class ChapterUser(BaseModel):
+    """The uploader of a chapter branch."""
+
+    id: int
+    username: str
+
+
+class ChapterBranch(BaseModel):
+    """A single team's (or solo uploader's) translation of a chapter.
+
+    A chapter has more than one branch when several teams have translated it
+    independently; see ``Chapter.branches_count``.
+    """
+
+    id: int
+    branch_id: int | None = None
+    created_at: datetime
+    teams: list[Team] = Field(default_factory=list)
+    user: ChapterUser
+
+
+class Chapter(BaseModel):
+    """A chapter: volume, number, name, available translations, and optionally its content.
+
+    ``index``/``item_number``/``branches_count``/``branches`` come from the chapter-list
+    endpoint (see ``RanobeLib.get_table_of_contents()``) and are ``None``/empty when a
+    ``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.
+    """
+
+    id: int
+    volume: str
+    number: str
+    name: str | None = None
+    index: int | None = None
+    item_number: int | None = None
+    branches_count: int = 1
+    branches: list[ChapterBranch] = Field(default_factory=list)
+    bundle_id: int | None = None
+    content: str | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_content(cls, data: Any) -> Any:
+        if isinstance(data, dict) and isinstance(data.get("content"), dict):
+            attachments = data.get("attachments") or []
+            data = {**data, "content": _prosemirror_to_html(data["content"], attachments)}
+        return data
+
+
+class Volume(BaseModel):
+    """A volume: its number and the chapters it contains, in title order."""
+
+    number: str
+    chapters: list[Chapter] = Field(default_factory=list)

ranobelib/numbering.py

@@ -0,0 +1,34 @@
+"""Chapter numbering helpers (``number`` / ``number_secondary``) and title URL parsing."""
+
+from __future__ import annotations
+
+import re
+from urllib.parse import urlsplit
+
+_SLUG_URL_RE = re.compile(r"^\d+--[^/?#]+$")
+
+
+def parse_slug_url(source: str) -> str:
+    """Extract a title's ``slug_url`` (``{id}--{slug}``) from a URL or pass it through.
+
+    Args:
+        source: Either a full title URL (e.g.
+            ``https://ranobelib.me/ru/book/6712--high-school-dxd-novel``) or an already
+            bare ``slug_url`` (``6712--high-school-dxd-novel``).
+
+    Returns:
+        The bare ``slug_url``, as used by the ``/api/manga/{slug_url}`` endpoint.
+
+    Raises:
+        ValueError: If no ``{id}--{slug}`` segment could be found in ``source``.
+    """
+    candidate = source
+    if "://" in source:
+        path = urlsplit(source).path
+        segments = [segment for segment in path.split("/") if segment]
+        candidate = segments[-1] if segments else ""
+
+    if not _SLUG_URL_RE.match(candidate):
+        raise ValueError(f"Could not extract a title slug from: {source!r}")
+
+    return candidate

ranobelib/sdk.py

@@ -0,0 +1,321 @@
+"""Public facade of the SDK: the ``RanobeLib`` class."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from types import TracebackType
+from typing import Any, Self
+
+from ranobelib.cache import DEFAULT_CACHE_DIR, DiskCache
+from ranobelib.client import ApiClient
+from ranobelib.exceptions import (
+    ChapterNotFoundError,
+    MultipleTranslationsError,
+    VolumeNotFoundError,
+)
+from ranobelib.exporters import EXPORTERS
+from ranobelib.models import Chapter, ChapterBranch, Title, Volume
+from ranobelib.numbering import parse_slug_url
+
+_INFO_FIELDS = [
+    "background",
+    "eng_name",
+    "otherNames",
+    "summary",
+    "releaseDate",
+    "genres",
+    "tags",
+    "teams",
+    "authors",
+    "artists",
+    "chap_count",
+]
+
+
+class RanobeLib:
+    """Entry point for interacting with a single ranobelib.me title.
+
+    Example:
+        ```python
+        async with RanobeLib("https://ranobelib.me/ru/book/6712--high-school-dxd-novel") as lib:
+            info = await lib.get_info()
+        ```
+    """
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        cache_dir: str | Path | None = None,
+        cache_ttl: float | None = None,
+    ) -> None:
+        """Initialize the SDK for a title.
+
+        Args:
+            url: A ranobelib.me title URL, or a bare ``{id}--{slug}`` identifier.
+            cache_dir: Where to cache raw API responses (title metadata, chapter list,
+                chapter content) on disk, so a repeated export or downloading newly added
+                chapters doesn't re-fetch data already on hand. Defaults to
+                ``.ranobelib_cache`` in the current working directory.
+            cache_ttl: Seconds after which a cached response is treated as stale and
+                re-fetched. ``None`` (the default) means cached responses never expire on
+                their own — see ``refresh=True`` on individual methods to force one anyway.
+        """
+        self._slug_url = parse_slug_url(url)
+        self._client = ApiClient()
+        self._cache = DiskCache(
+            cache_dir if cache_dir is not None else DEFAULT_CACHE_DIR, ttl=cache_ttl
+        )
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    async def get_info(self, *, refresh: bool = False) -> Title:
+        """Fetch title metadata: names, cover, summary, genres, tags, authors, teams.
+
+        Args:
+            refresh: Bypass the disk cache and re-fetch from the API even if a cached
+                response is on hand.
+        """
+        data = await self._get_title(refresh=refresh)
+        return Title.model_validate(data)
+
+    async def get_table_of_contents(self, *, refresh: bool = False) -> list[Volume]:
+        """Fetch the title's volumes and chapter names/numbers, without chapter content.
+
+        Args:
+            refresh: Bypass the disk cache and re-fetch from the API even if a cached
+                response is on hand — needed to pick up newly published chapters, since
+                otherwise the cached chapter list would keep being reused.
+        """
+        raw_chapters = await self._get_chapters(refresh=refresh)
+        chapters = [Chapter.model_validate(item) for item in raw_chapters]
+        return _group_into_volumes(chapters)
+
+    async def get_chapter(
+        self,
+        volume: int,
+        number: str,
+        *,
+        branch_id: int | None = None,
+        refresh: bool = False,
+    ) -> Chapter:
+        """Fetch a single chapter, including its content.
+
+        When a chapter has more than one team's translation and ``branch_id`` isn't given,
+        this raises ``MultipleTranslationsError`` rather than guessing — see
+        ``get_translations()`` and docs/api-notes.md for why the API's own default (when
+        ``branch_id`` is omitted) isn't relied on. Doing this check costs an extra request
+        to fetch the chapter list, only when ``branch_id`` isn't already given.
+
+        Args:
+            volume: The chapter's volume number.
+            number: The chapter number, as returned by the API — may contain a decimal
+                (e.g. ``"51.6"``).
+            branch_id: Which translation to fetch, as returned by ``get_translations()``.
+                Only required when the chapter has more than one.
+            refresh: Bypass the disk cache and re-fetch from the API even if a cached
+                response is on hand.
+
+        Raises:
+            MultipleTranslationsError: If the chapter has more than one translation and
+                ``branch_id`` wasn't given.
+        """
+        volume_str = str(volume)
+        if branch_id is None:
+            raw_chapters = await self._get_chapters(refresh=refresh)
+            branch_id = self._resolve_branch_id(volume_str, number, raw_chapters)
+        return await self._fetch_chapter(volume_str, number, branch_id, refresh=refresh)
+
+    async def get_chapters(self, chapters: list[tuple[int, str]]) -> list[Chapter]:
+        """Fetch several chapters, including their content.
+
+        Fetches the chapter list once, shared across all requested chapters (also used to
+        detect chapters with more than one translation — see ``get_chapter``), then each
+        chapter individually and sequentially, in the order given.
+
+        Args:
+            chapters: A list of ``(volume, number)`` pairs identifying each chapter.
+
+        Raises:
+            ChapterNotFoundError: If any requested chapter doesn't exist.
+            MultipleTranslationsError: If any requested chapter has more than one
+                translation.
+        """
+        raw_chapters = await self._get_chapters()
+        result = []
+        for volume, number in chapters:
+            volume_str = str(volume)
+            branch_id = self._resolve_branch_id(volume_str, number, raw_chapters)
+            result.append(await self._fetch_chapter(volume_str, number, branch_id))
+        return result
+
+    async def get_translations(self, volume: int, number: str) -> list[ChapterBranch]:
+        """Fetch the available translations (branches) for a chapter.
+
+        Args:
+            volume: The chapter's volume number.
+            number: The chapter number.
+
+        Raises:
+            ChapterNotFoundError: If no chapter exists for this volume/number.
+        """
+        volume_str = str(volume)
+        raw_chapters = await self._get_chapters()
+        item = _find_raw_chapter(raw_chapters, volume_str, number)
+        if item is None:
+            raise ChapterNotFoundError(self._slug_url, volume=volume_str, number=number)
+        return [ChapterBranch.model_validate(branch) for branch in item.get("branches") or []]
+
+    async def get_volume(self, volume: int) -> Volume:
+        """Fetch a whole volume: all its chapters, each including content.
+
+        The API has no bulk "volume content" endpoint (see docs/api-notes.md), so this
+        fetches the chapter list once to find which numbers belong to the volume, then
+        fetches each of those chapters individually and sequentially.
+
+        Args:
+            volume: The volume number.
+
+        Raises:
+            VolumeNotFoundError: If the title has no chapters for this volume.
+            MultipleTranslationsError: If any of the volume's chapters has more than one
+                translation.
+        """
+        raw_chapters = await self._get_chapters()
+        return await self._build_volume(volume, raw_chapters)
+
+    async def get_volumes(self, volumes: list[int]) -> list[Volume]:
+        """Fetch several whole volumes, each including chapter content.
+
+        Fetches the chapter list once, shared across all requested volumes, then each
+        chapter individually and sequentially — same approach as ``get_volume``, applied
+        to more than one volume without re-fetching the chapter list per volume.
+
+        Args:
+            volumes: The volume numbers to fetch.
+
+        Raises:
+            VolumeNotFoundError: If the title has no chapters for one of the volumes.
+            MultipleTranslationsError: If any of the volumes' chapters has more than one
+                translation.
+        """
+        raw_chapters = await self._get_chapters()
+        return [await self._build_volume(volume, raw_chapters) for volume in volumes]
+
+    async def export(self, chapters: list[Chapter], *, fmt: str, path: str | Path) -> Path:
+        """Export chapters to a file.
+
+        Args:
+            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"``).
+
+        Raises:
+            ValueError: If ``fmt`` isn't a registered export format.
+        """
+        exporter_cls = EXPORTERS.get(fmt)
+        if exporter_cls is None:
+            available = ", ".join(sorted(EXPORTERS)) or "(none registered)"
+            raise ValueError(f"Unknown export format {fmt!r}. Available: {available}")
+        title = await self.get_info()
+        return await exporter_cls().export(title, chapters, Path(path))
+
+    async def _build_volume(self, volume: int, raw_chapters: list[dict[str, Any]]) -> Volume:
+        volume_str = str(volume)
+        numbers = [item["number"] for item in raw_chapters if item.get("volume") == volume_str]
+        if not numbers:
+            raise VolumeNotFoundError(self._slug_url, volume=volume_str)
+
+        chapters = []
+        for number in numbers:
+            branch_id = self._resolve_branch_id(volume_str, number, raw_chapters)
+            chapters.append(await self._fetch_chapter(volume_str, number, branch_id))
+        return Volume(number=volume_str, chapters=chapters)
+
+    async def _get_title(self, *, refresh: bool = False) -> dict[str, Any]:
+        key = f"title:{self._slug_url}:{','.join(sorted(_INFO_FIELDS))}"
+        if not refresh:
+            cached = self._cache.get(key)
+            if cached is not None:
+                return cached  # type: ignore[no-any-return]
+        data = await self._client.get_title(self._slug_url, fields=_INFO_FIELDS)
+        self._cache.set(key, data)
+        return data
+
+    async def _get_chapters(self, *, refresh: bool = False) -> list[dict[str, Any]]:
+        key = f"chapters:{self._slug_url}"
+        if not refresh:
+            cached = self._cache.get(key)
+            if cached is not None:
+                return cached  # type: ignore[no-any-return]
+        data = await self._client.get_chapters(self._slug_url)
+        self._cache.set(key, data)
+        return data
+
+    async def _fetch_chapter(
+        self, volume_str: str, number: str, branch_id: int | None, *, refresh: bool = False
+    ) -> Chapter:
+        key = f"chapter:{self._slug_url}:{volume_str}:{number}:{branch_id}"
+        if not refresh:
+            cached = self._cache.get(key)
+            if cached is not None:
+                return Chapter.model_validate(cached)
+        data = await self._client.get_chapter(
+            self._slug_url, number=number, volume=volume_str, branch_id=branch_id
+        )
+        self._cache.set(key, data)
+        return Chapter.model_validate(data)
+
+    def _resolve_branch_id(
+        self, volume_str: str, number: str, raw_chapters: list[dict[str, Any]]
+    ) -> int | None:
+        item = _find_raw_chapter(raw_chapters, volume_str, number)
+        if item is None:
+            return None  # Let the chapter fetch itself raise ChapterNotFoundError.
+
+        branches = item.get("branches") or []
+        if len(branches) <= 1:
+            return None
+
+        raise MultipleTranslationsError(
+            self._slug_url,
+            volume=volume_str,
+            number=number,
+            branches=[ChapterBranch.model_validate(branch) for branch in branches],
+        )
+
+
+def _group_into_volumes(chapters: list[Chapter]) -> list[Volume]:
+    """Group a flat, API-ordered chapter list into volumes, preserving that order."""
+    grouped: dict[str, list[Chapter]] = {}
+    for chapter in chapters:
+        grouped.setdefault(chapter.volume, []).append(chapter)
+    return [Volume(number=number, chapters=items) for number, items in grouped.items()]
+
+
+def _find_raw_chapter(
+    raw_chapters: list[dict[str, Any]], volume_str: str, number: str
+) -> dict[str, Any] | None:
+    """Find a chapter-list entry by volume/number, or ``None`` if there isn't one."""
+    return next(
+        (
+            item
+            for item in raw_chapters
+            if item.get("volume") == volume_str and item.get("number") == number
+        ),
+        None,
+    )