novel-downloader 1.4.5__py3-none-any.whl → 2.0.0__py3-none-any.whl

novel_downloader/utils/epub/documents.py

@@ -0,0 +1,297 @@
+#!/usr/bin/env python3
+"""
+novel_downloader.utils.epub.documents
+-------------------------------------
+
+Defines the classes that render EPUB navigation and packaging documents:
+- NavDocument: builds the XHTML nav.xhtml (EPUB 3)
+- NCXDocument: builds the NCX XML navigation map (EPUB 2)
+- OpfDocument: builds the content.opf package document
+"""
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from .constants import (
+    NAV_TEMPLATE,
+    NCX_TEMPLATE,
+    OPF_TEMPLATE,
+)
+from .models import (
+    ChapterEntry,
+    EpubResource,
+    ManifestEntry,
+    NavPoint,
+    SpineEntry,
+    VolumeEntry,
+)
+
+
+@dataclass
+class NavDocument(EpubResource):
+    title: str = "未命名"
+    language: str = "zh-CN"
+    id: str = "nav"
+    filename: str = "nav.xhtml"
+    media_type: str = field(init=False, default="application/xhtml+xml")
+    content_items: list[ChapterEntry | VolumeEntry] = field(default_factory=list)
+
+    def add_chapter(self, id: str, label: str, src: str) -> None:
+        """
+        Add a top-level chapter entry to the navigation.
+
+        :param id: The unique ID for the chapter.
+        :param label: The display title for the chapter.
+        :param src: The href target for the chapter's XHTML file.
+        """
+        self.content_items.append(ChapterEntry(id=id, label=label, src=src))
+
+    def add_volume(
+        self,
+        id: str,
+        label: str,
+        src: str,
+        chapters: list[ChapterEntry],
+    ) -> None:
+        """
+        Add a volume entry with nested chapters to the navigation.
+
+        :param id: The unique ID for the volume.
+        :param label: The display title for the volume.
+        :param src: The href target for the volume's intro XHTML file.
+        :param chapters: A list of chapter entries under this volume.
+        """
+        self.content_items.append(
+            VolumeEntry(id=id, label=label, src=src, chapters=chapters)
+        )
+
+    def to_xhtml(self) -> str:
+        """
+        Generate the XHTML content for nav.xhtml based on the NavDocument.
+
+        :return: A string containing the full XHTML for nav.xhtml.
+        """
+        items_str = self._render_items_str(self.content_items)
+        raw = NAV_TEMPLATE.format(
+            lang=self.language,
+            id=self.id,
+            title=self.title,
+            items=items_str,
+        )
+        return raw
+
+    @classmethod
+    def _render_items_str(cls, items: Sequence[ChapterEntry | VolumeEntry]) -> str:
+        lines: list[str] = []
+        for item in items:
+            if isinstance(item, VolumeEntry) and item.chapters:
+                lines.append(f'<li><a href="{item.src}">{item.label}</a>')
+                lines.append("  <ol>")
+                child = cls._render_items_str(item.chapters)
+                lines.extend(child.splitlines())
+                lines.append("  </ol>")
+                lines.append("</li>")
+            else:
+                lines.append(f'<li><a href="{item.src}">{item.label}</a></li>')
+        return "\n".join(lines)
+
+
+@dataclass
+class NCXDocument(EpubResource):
+    title: str = "未命名"
+    uid: str = ""
+    id: str = "ncx"
+    filename: str = "toc.ncx"
+    media_type: str = field(init=False, default="application/x-dtbncx+xml")
+    nav_points: list[NavPoint] = field(default_factory=list)
+
+    def add_chapter(
+        self,
+        id: str,
+        label: str,
+        src: str,
+    ) -> None:
+        """
+        Add a single flat chapter entry to the NCX nav map.
+        """
+        self.nav_points.append(NavPoint(id=id, label=label, src=src))
+
+    def add_volume(
+        self,
+        id: str,
+        label: str,
+        src: str,
+        chapters: list[ChapterEntry],
+    ) -> None:
+        """
+        Add a volume with nested chapters to the NCX nav map.
+        """
+        children = [NavPoint(id=c.id, label=c.label, src=c.src) for c in chapters]
+        self.nav_points.append(NavPoint(id=id, label=label, src=src, children=children))
+
+    def to_xml(self) -> str:
+        """
+        Generate the XML content for toc.ncx used in EPUB 2 navigation.
+
+        :return: A string containing the full NCX XML document.
+        """
+        order = 1
+        lines: list[str] = []
+        for pt in self.nav_points:
+            order, block = self._render_navpoint_str(pt, order)
+            lines.extend(block)
+        navpoints = "\n".join(lines)
+        raw = NCX_TEMPLATE.format(
+            uid=self.uid,
+            depth=self._depth(self.nav_points),
+            title=self.title,
+            navpoints=navpoints,
+        )
+        return raw
+
+    @classmethod
+    def _depth(cls, points: list[NavPoint]) -> int:
+        if not points:
+            return 0
+        return 1 + max(cls._depth(child.children) for child in points)
+
+    @classmethod
+    def _render_navpoint_str(cls, pt: NavPoint, order: int) -> tuple[int, list[str]]:
+        lines: list[str] = []
+        # open navPoint
+        lines.append(f'<navPoint id="{pt.id}" playOrder="{order}">')
+        order += 1
+        # label and content
+        lines.append(f"<navLabel><text>{pt.label}</text></navLabel>")
+        lines.append(f'<content src="{pt.src}"/>')
+        # children
+        for child in pt.children:
+            order, child_lines = cls._render_navpoint_str(child, order)
+            lines.extend(child_lines)
+        # close
+        lines.append("</navPoint>")
+        return order, lines
+
+
+@dataclass
+class OpfDocument(EpubResource):
+    # metadata fields
+    title: str = ""
+    author: str = ""
+    description: str = ""
+    uid: str = ""
+    subject: list[str] = field(default_factory=list)
+    language: str = "zh-CN"
+
+    # resource identity
+    id: str = "opf"
+    filename: str = "content.opf"
+    media_type: str = field(init=False, default="application/oebps-package+xml")
+
+    # internal state
+    include_cover: bool = False
+    manifest: list[ManifestEntry] = field(default_factory=list)
+    spine: list[SpineEntry] = field(default_factory=list)
+    _cover_item: ManifestEntry | None = field(init=False, default=None)
+    _toc_item: ManifestEntry | None = field(init=False, default=None)
+    _cover_doc: ManifestEntry | None = field(init=False, default=None)
+
+    def add_manifest_item(
+        self,
+        id: str,
+        href: str,
+        media_type: str,
+        properties: str | None = None,
+    ) -> None:
+        entry = ManifestEntry(
+            id=id,
+            href=href,
+            media_type=media_type,
+            properties=properties,
+        )
+        self.manifest.append(entry)
+
+        if properties == "cover-image":
+            self._cover_item = entry
+        if media_type == "application/x-dtbncx+xml":
+            self._toc_item = entry
+        if id == "cover":
+            self._cover_doc = entry
+
+    def add_spine_item(
+        self,
+        idref: str,
+        properties: str | None = None,
+    ) -> None:
+        self.spine.append(SpineEntry(idref=idref, properties=properties))
+
+    def set_subject(self, subject: list[str]) -> None:
+        self.subject = subject
+
+    def to_xml(self) -> str:
+        """
+        Generate the content.opf XML, which defines metadata, manifest, and spine.
+
+        This function outputs a complete OPF package document that includes:
+        - <metadata>: title, author, language, identifiers, etc.
+        - <manifest>: all resource entries
+        - <spine>: the reading order of the content
+        - <guide>: optional references like cover page
+
+        :return: A string containing the full OPF XML content.
+        """
+        now_iso = datetime.now(UTC).replace(microsecond=0).isoformat()
+
+        # metadata block
+        meta_lines: list[str] = []
+        meta_lines.append(f'<meta property="dcterms:modified">{now_iso}</meta>')
+        meta_lines.append(f'<dc:identifier id="id">{self.uid}</dc:identifier>')
+        meta_lines.append(f"<dc:title>{self.title}</dc:title>")
+        meta_lines.append(f"<dc:language>{self.language}</dc:language>")
+        if self.author:
+            meta_lines.append(f'<dc:creator id="creator">{self.author}</dc:creator>')
+        if self.description:
+            meta_lines.append(f"<dc:description>{self.description}</dc:description>")
+        if self.subject:
+            joined = ",".join(self.subject)
+            meta_lines.append(f"<dc:subject>{joined}</dc:subject>")
+        if self.include_cover and self._cover_item:
+            meta_lines.append(f'<meta name="cover" content="{self._cover_item.id}"/>')
+        metadata = "\n".join(meta_lines)
+
+        # manifest block
+        man_lines: list[str] = []
+        for item in self.manifest:
+            props = f' properties="{item.properties}"' if item.properties else ""
+            man_lines.append(
+                f'<item id="{item.id}" href="{item.href}" media-type="{item.media_type}"{props}/>'  # noqa: E501
+            )
+        manifest_items = "\n".join(man_lines)
+
+        # spine block
+        toc_attr = f' toc="{self._toc_item.id}"' if self._toc_item else ""
+        spine_lines: list[str] = []
+        for ref in self.spine:
+            props = f' properties="{ref.properties}"' if ref.properties else ""
+            spine_lines.append(f'    <itemref idref="{ref.idref}"{props}/>')
+        spine_items = "\n".join(spine_lines)
+
+        # guide block
+        if self.include_cover and self._cover_doc:
+            guide_section = (
+                "  <guide>\n"
+                f'    <reference type="cover" title="Cover" href="{self._cover_doc.href}"/>\n'  # noqa: E501
+                "  </guide>\n"
+            )
+        else:
+            guide_section = ""
+
+        raw = OPF_TEMPLATE.format(
+            metadata=metadata,
+            manifest_items=manifest_items,
+            spine_toc=toc_attr,
+            spine_items=spine_items,
+            guide_section=guide_section,
+        )
+        return raw

novel_downloader/utils/epub/models.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""
+novel_downloader.utils.epub.models
+----------------------------------
+
+Defines the core EPUB data models and resource classes used by the builder:
+- Typed entries for table of contents (ChapterEntry, VolumeEntry)
+- Manifest and spine record types (ManifestEntry, SpineEntry)
+- Hierarchical NavPoint for NCX navigation
+- Base resource class (EpubResource) and specializations:
+    - StyleSheet
+    - ImageResource
+    - Chapter (with XHTML serialization)
+- Volume container for grouping chapters with optional intro and cover
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .constants import (
+    CHAP_TMPLATE,
+    CSS_TMPLATE,
+)
+
+
+@dataclass(frozen=True)
+class ChapterEntry:
+    id: str
+    label: str
+    src: str
+
+
+@dataclass(frozen=True)
+class VolumeEntry:
+    id: str
+    label: str
+    src: str
+    chapters: list[ChapterEntry]
+
+
+@dataclass(frozen=True)
+class ManifestEntry:
+    id: str
+    href: str
+    media_type: str
+    properties: str | None = None
+
+
+@dataclass(frozen=True)
+class SpineEntry:
+    idref: str
+    properties: str | None = None
+
+
+@dataclass
+class NavPoint:
+    """
+    A table-of-contents entry, possibly with nested children.
+    """
+
+    id: str
+    label: str
+    src: str
+    children: list[NavPoint] = field(default_factory=list)
+
+
+@dataclass
+class EpubResource:
+    """
+    Base class for any EPUB-packaged resource.
+    """
+
+    id: str
+    filename: str
+    media_type: str
+
+
+@dataclass
+class StyleSheet(EpubResource):
+    content: str
+    media_type: str = field(init=False, default="text/css")
+
+
+@dataclass
+class ImageResource(EpubResource):
+    data: bytes
+
+
+@dataclass
+class Chapter(EpubResource):
+    title: str
+    content: str
+    css: list[StyleSheet] = field(default_factory=list)
+    media_type: str = field(init=False, default="application/xhtml+xml")
+
+    def to_xhtml(self, lang: str = "zh-CN") -> str:
+        """
+        Generate the XHTML for a chapter.
+        """
+        links = "\n".join(
+            CSS_TMPLATE.format(filename=css.filename, media_type=css.media_type)
+            for css in self.css
+        )
+        return CHAP_TMPLATE.format(
+            lang=lang,
+            title=self.title,
+            xlinks=links,
+            content=self.content,
+        )
+
+
+@dataclass
+class Volume:
+    id: str
+    title: str
+    intro: str = ""
+    cover: Path | None = None
+    chapters: list[Chapter] = field(default_factory=list)

novel_downloader/utils/epub/utils.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""
+novel_downloader.utils.epub.utils
+---------------------------------
+
+Pure utility functions for EPUB assembly, including:
+- Computing file hashes
+- Generating META-INF/container.xml
+- Constructing HTML snippets for the book intro and volume intro
+"""
+
+import hashlib
+from html import escape
+from pathlib import Path
+
+from .constants import (
+    CONTAINER_TEMPLATE,
+    IMAGE_FOLDER,
+    ROOT_PATH,
+)
+
+
+def hash_file(file_path: Path, chunk_size: int = 8192) -> str:
+    """
+    Compute the SHA256 hash of a file.
+
+    :param file_path: The Path object of the file to hash.
+    :param chunk_size: The chunk size to read the file (default: 8192).
+    :return: The SHA256 hash string (lowercase hex) of the file content.
+    """
+    h = hashlib.sha256()
+    with file_path.open("rb") as f:
+        while chunk := f.read(chunk_size):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def build_container_xml(
+    root_path: str = ROOT_PATH,
+) -> str:
+    """
+    Generate the XML content for META-INF/container.xml in an EPUB archive.
+
+    :param root_path: The folder where the OPF file is stored.
+    :return: A string containing the full XML for container.xml.
+    """
+    return CONTAINER_TEMPLATE.format(root_path=root_path)
+
+
+def build_book_intro(
+    book_name: str,
+    author: str,
+    serial_status: str,
+    subject: list[str],
+    word_count: str,
+    summary: str,
+) -> str:
+    """
+    Build the HTML snippet for the overall book introduction.
+
+    This includes:
+      - A main heading ("Book Introduction")
+      - A list of metadata items (title, author, categories, word count, status)
+      - A "Summary" subheading and one or more paragraphs of summary text
+
+    :return: A HTML string for inclusion in `intro.xhtml`
+    """
+    lines = []
+
+    lines.append("<div>")
+    lines.append("<h1>书籍简介</h1>")
+    lines.append('<div class="intro-info">')
+    lines.append("<ul>")
+
+    name_val = f"《{book_name}》" if book_name else ""
+    subj_val = ", ".join(subject) if subject else ""
+
+    li_lines = [
+        _li_line("书名", name_val),
+        _li_line("作者", author),
+        _li_line("分类", subj_val),
+        _li_line("字数", word_count),
+        _li_line("状态", serial_status),
+    ]
+    for li in li_lines:
+        if li:
+            lines.append(li)
+
+    lines.append("</ul>")
+    lines.append("</div>")
+
+    if summary:
+        lines.append('<p class="new-page-after"></p>')
+        lines.append("<h2>简介</h2>")
+        lines.append('<div class="intro-summary">')
+        for line in summary.splitlines():
+            s = line.strip()
+            if not s:
+                continue
+            lines.append(f"<p>{escape(s, quote=True)}</p>")
+        lines.append("</div>")
+
+    lines.append("</div>")
+    return "\n".join(lines)
+
+
+def build_volume_intro(
+    volume_title: str,
+    volume_intro_text: str = "",
+) -> str:
+    """
+    Build the HTML snippet for a single-volume introduction.
+
+    This includes:
+      - A decorative border image (top and bottom)
+      - A primary heading (volume main title)
+      - An optional secondary line (subtitle)
+      - One or more paragraphs of intro text
+
+    :param volume_title: e.g. "Volume 1 - The Beginning"
+    :param volume_intro_text: multiline intro text for this volume
+    :return: A HTML string for inclusion in `vol_<n>.xhtml`
+    """
+    line1, line2 = _split_volume_title(volume_title)
+
+    lines = []
+    lines.append("<div>")
+    lines.append('<div class="vol-header">')
+    lines.append(_vol_border_div_str(flip=False))
+    lines.append(f'<h1 class="vol-title-main">{escape(line1, quote=True)}</h1>')
+    lines.append(_vol_border_div_str(flip=True))
+    if line2:
+        lines.append(f'<h2 class="vol-title-sub">{escape(line2, quote=True)}</h2>')
+    lines.append("</div>")
+
+    if volume_intro_text:
+        lines.append('<p class="new-page-after"></p>')
+        lines.append('<div class="vol-intro-text">')
+        for line in volume_intro_text.splitlines():
+            s = line.strip()
+            if not s:
+                continue
+            lines.append(f"<p>{escape(s, quote=True)}</p>")
+        lines.append("</div>")
+
+    lines.append("</div>")
+    return "\n".join(lines)
+
+
+def _li_line(label: str, value: str) -> str:
+    if not value:
+        return ""
+    return f"<li>{escape(label, quote=True)}: {escape(value, quote=True)}</li>"
+
+
+def _vol_border_div_str(flip: bool = False) -> str:
+    classes = "vol-border" + (" flip" if flip else "")
+    return (
+        f'<div class="{classes}">'
+        f'<img src="../{IMAGE_FOLDER}/volume_border.png" alt="">'
+        f"</div>"
+    )
+
+
+def _split_volume_title(volume_title: str) -> tuple[str, str]:
+    """
+    Split volume title into two parts for better display.
+
+    :param volume_title: Original volume title string.
+    :return: Tuple of (line1, line2)
+    """
+    if "-" in volume_title:
+        parts = volume_title.split("-", 1)
+    elif " " in volume_title:
+        parts = volume_title.split(" ", 1)
+    else:
+        return volume_title, ""
+
+    return parts[0], parts[1]

novel_downloader/utils/file_utils/__init__.py

@@ -4,39 +4,14 @@ novel_downloader.utils.file_utils
 ---------------------------------
 
 High-level file I/O utility re-exports for convenience.
-
-This module aggregates commonly used low-level file utilities such as:
-- Path sanitization (for safe filenames)
-- Text normalization (e.g. Windows/Linux line endings)
-- JSON, plain text, and binary file reading/writing
-
-Included utilities:
-- sanitize_filename: remove invalid characters from filenames
-- normalize_txt_line_endings: standardize line endings in text files
-- save_as_json / save_as_txt: write dict or text to file
-- read_text_file / read_json_file / read_binary_file: load content from file
 """
 
-from .io import (
-    load_blacklisted_words,
-    load_text_resource,
-    read_binary_file,
-    read_json_file,
-    read_text_file,
-    save_as_json,
-    save_as_txt,
-)
-from .normalize import normalize_txt_line_endings
-from .sanitize import sanitize_filename
-
 __all__ = [
     "sanitize_filename",
-    "save_as_json",
-    "save_as_txt",
-    "read_text_file",
-    "read_json_file",
-    "read_binary_file",
-    "load_text_resource",
-    "load_blacklisted_words",
+    "write_file",
     "normalize_txt_line_endings",
 ]
+
+from .io import write_file
+from .normalize import normalize_txt_line_endings
+from .sanitize import sanitize_filename