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

novel_downloader/utils/{crypto_utils.py → crypto_utils/rc4.py}

@@ -1,13 +1,11 @@
 #!/usr/bin/env python3
 """
-novel_downloader.utils.crypto_utils
------------------------------------
+novel_downloader.utils.crypto_utils.rc4
+---------------------------------------
 
-Generic cryptographic utilities
+RC4 stream cipher for simple text encryption and decryption.
 """
 
-from __future__ import annotations
-
 import base64
 
 
@@ -22,16 +20,11 @@ def rc4_crypt(
     Encrypt or decrypt data using RC4 and Base64.
 
     :param key: RC4 key (will be encoded using the specified encoding).
-    :type key: str
     :param data: Plain-text (for 'encrypt') or Base64 cipher-text (for 'decrypt').
-    :type data: str
     :param mode: Operation mode, either 'encrypt' or 'decrypt'. Defaults to 'encrypt'.
-    :type mode: str, optional
     :param encoding: Character encoding for key and returned string. Defaults 'utf-8'.
-    :type encoding: str, optional
 
     :return: Base64 cipher-text (for encryption) or decoded plain-text (for decryption).
-    :rtype: str
 
     :raises ValueError: If mode is not 'encrypt' or 'decrypt'.
     """

novel_downloader/utils/epub/__init__.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+"""
+novel_downloader.utils.epub
+---------------------------
+
+Top-level package for EPUB export utilities.
+
+Key components:
+
+- EpubBuilder : orchestrates metadata, manifest, spine, navigation, and resources
+- Chapter, Volume : represent and render content sections and volume intros
+
+Usage example:
+
+```python
+builder = EpubBuilder(title="My Novel", author="Author Name", uid="uuid-1234")
+builder.chapters.append(Chapter(id="ch1", title="Chapter 1", content="<p>xxx</p>"))
+builder.export("output/my_novel.epub")
+```
+"""
+
+__all__ = [
+    "EpubBuilder",
+    "Chapter",
+    "Volume",
+    "StyleSheet",
+]
+
+from .builder import EpubBuilder
+from .models import (
+    Chapter,
+    StyleSheet,
+    Volume,
+)

novel_downloader/utils/epub/builder.py

@@ -0,0 +1,377 @@
+#!/usr/bin/env python3
+"""
+novel_downloader.utils.epub.builder
+-----------------------------------
+
+Orchestrates the end-to-end EPUB build process by:
+- Managing metadata (title, author, description, language, etc.)
+- Collecting and deduplicating resources (chapters, images, stylesheets)
+- Registering everything in the OPF manifest and spine
+- Generating nav.xhtml, toc.ncx, content.opf, and the zipped .epub file
+
+Provides:
+- methods to add chapters, volumes, images, and styles
+- a clean `export()` entry point that writes the final EPUB archive
+"""
+
+import zipfile
+from pathlib import Path
+from zipfile import ZIP_DEFLATED, ZIP_STORED
+
+from novel_downloader.utils.constants import (
+    CSS_INTRO_PATH,
+    VOLUME_BORDER_IMAGE_PATH,
+)
+
+from .constants import (
+    COVER_IMAGE_TEMPLATE,
+    CSS_FOLDER,
+    IMAGE_FOLDER,
+    IMAGE_MEDIA_TYPES,
+    ROOT_PATH,
+    TEXT_FOLDER,
+)
+from .documents import (
+    NavDocument,
+    NCXDocument,
+    OpfDocument,
+)
+from .models import (
+    Chapter,
+    ChapterEntry,
+    EpubResource,
+    ImageResource,
+    StyleSheet,
+    Volume,
+)
+from .utils import (
+    build_book_intro,
+    build_container_xml,
+    build_volume_intro,
+    hash_file,
+)
+
+
+class EpubBuilder:
+    def __init__(
+        self,
+        title: str,
+        author: str = "",
+        description: str = "",
+        cover_path: Path | None = None,
+        subject: list[str] | None = None,
+        serial_status: str = "",
+        word_count: str = "0",
+        uid: str = "",
+        language: str = "zh-CN",
+    ):
+        # metadata
+        self.title = title
+        self.author = author
+        self.description = description
+        self.language = language
+        self.subject = subject or []
+        self.serial_status = serial_status
+        self.word_count = word_count
+        self.uid = uid
+
+        # builder state
+        self.chapters: list[Chapter] = []
+        self.images: list[ImageResource] = []
+        self.styles: list[StyleSheet] = []
+        self._img_map: dict[str, str] = {}
+        self._img_idx = 0
+        self._vol_idx = 0
+
+        # core EPUB documents
+        self.nav = NavDocument(title=title, language=language)
+        self.ncx = NCXDocument(title=title, uid=uid)
+        self.opf = OpfDocument(
+            title=title,
+            author=author,
+            description=description,
+            uid=uid,
+            subject=self.subject,
+            language=language,
+        )
+
+        # register the nav & ncx items
+        self.opf.add_manifest_item(
+            "nav",
+            "nav.xhtml",
+            self.nav.media_type,
+            properties="nav",
+        )
+        self.opf.add_manifest_item("ncx", "toc.ncx", self.ncx.media_type)
+
+        self._init_styles()
+        self._init_cover(cover_path)
+        self._init_intro()
+
+    def add_image(self, image_path: Path) -> str:
+        """
+        Add an image resource (deduped by hash) and register it.
+        """
+        if not (image_path.exists() and image_path.is_file()):
+            return ""
+        h = hash_file(image_path)
+        if h in self._img_map:
+            return self._img_map[h]
+
+        ext = image_path.suffix.lower().lstrip(".")
+        mtype = IMAGE_MEDIA_TYPES.get(ext)
+        if not mtype:
+            return ""
+
+        res_id = f"img_{self._img_idx}"
+        filename = f"{res_id}.{ext}"
+        data = image_path.read_bytes()
+        img = ImageResource(id=res_id, data=data, media_type=mtype, filename=filename)
+        self.images.append(img)
+        self._register(img, folder=IMAGE_FOLDER, in_spine=False)
+
+        self._img_map[h] = filename
+        self._img_idx += 1
+        return filename
+
+    def add_chapter(self, chap: Chapter) -> None:
+        self.chapters.append(chap)
+        self._register(chap, folder=TEXT_FOLDER)
+        self.nav.add_chapter(chap.id, chap.title, f"{TEXT_FOLDER}/{chap.filename}")
+        self.ncx.add_chapter(chap.id, chap.title, f"{TEXT_FOLDER}/{chap.filename}")
+
+    def add_volume(self, volume: Volume) -> None:
+        """Add a volume cover, intro, and all its chapters to the EPUB."""
+        # volume-specific cover
+        if volume.cover:
+            filename = self.add_image(volume.cover)
+            cover_html = f'<img class="width100" src="../{IMAGE_FOLDER}/{filename}"/>'
+            cover_chap = Chapter(
+                id=f"vol_{self._vol_idx}_cover",
+                title=volume.title,
+                content=cover_html,
+                filename=f"vol_{self._vol_idx}_cover.xhtml",
+            )
+            self.chapters.append(cover_chap)
+            self._register(
+                cover_chap,
+                folder=TEXT_FOLDER,
+                properties="duokan-page-fullscreen",
+            )
+
+        # volume intro page
+        intro_content = build_volume_intro(volume.title, volume.intro)
+        vol_intro = Chapter(
+            id=f"vol_{self._vol_idx}",
+            title=volume.title,
+            content=intro_content,
+            css=[self.intro_css],
+            filename=f"vol_{self._vol_idx}.xhtml",
+        )
+        self.chapters.append(vol_intro)
+        self._register(vol_intro, folder=TEXT_FOLDER)
+
+        # nested chapters
+        entries: list[ChapterEntry] = []
+        for chap in volume.chapters:
+            self.chapters.append(chap)
+            self._register(chap, folder=TEXT_FOLDER)
+            entries.append(
+                ChapterEntry(
+                    id=chap.id,
+                    label=chap.title,
+                    src=f"{TEXT_FOLDER}/{chap.filename}",
+                )
+            )
+
+        # TOC updates
+        self.ncx.add_volume(
+            id=f"vol_{self._vol_idx}",
+            label=volume.title,
+            src=f"{TEXT_FOLDER}/{vol_intro.filename}",
+            chapters=entries,
+        )
+        self.nav.add_volume(
+            id=f"vol_{self._vol_idx}",
+            label=volume.title,
+            src=f"{TEXT_FOLDER}/{vol_intro.filename}",
+            chapters=entries,
+        )
+
+        self._vol_idx += 1
+
+    def add_stylesheet(self, css: StyleSheet) -> None:
+        """
+        Register an external CSS file in the EPUB.
+        """
+        self.styles.append(css)
+        self._register(css, folder=CSS_FOLDER, in_spine=False)
+
+    def export(self, output_path: str | Path) -> Path:
+        """
+        Build and export the current book as an EPUB file.
+
+        :param output_path: Path to save the final .epub file.
+        """
+        return self._build_epub(output_path=Path(output_path))
+
+    def _register(
+        self,
+        res: EpubResource,
+        folder: str,
+        in_spine: bool = True,
+        properties: str | None = None,
+    ) -> None:
+        """
+        Add resource to the manifest—and optionally to the spine.
+        """
+        href = f"{folder}/{res.filename}"
+        self.opf.add_manifest_item(res.id, href, res.media_type, properties)
+        if in_spine:
+            self.opf.add_spine_item(res.id, properties)
+
+    def _init_styles(self) -> None:
+        # volume border & intro CSS
+        self.intro_css = StyleSheet(
+            id="intro_style",
+            content=CSS_INTRO_PATH.read_text("utf-8"),
+            filename="intro_style.css",
+        )
+        self.styles.append(self.intro_css)
+        self._register(self.intro_css, folder=CSS_FOLDER, in_spine=False)
+
+        try:
+            border_bytes = VOLUME_BORDER_IMAGE_PATH.read_bytes()
+        except FileNotFoundError:
+            return
+        border = ImageResource(
+            id="img-volume-border",
+            data=border_bytes,
+            media_type="image/png",
+            filename="volume_border.png",
+        )
+        self.images.append(border)
+        self._register(border, folder=IMAGE_FOLDER, in_spine=False)
+
+    def _init_cover(self, cover_path: Path | None) -> None:
+        if not cover_path or not cover_path.is_file():
+            return
+        ext = cover_path.suffix.lower().lstrip(".")
+        mtype = IMAGE_MEDIA_TYPES.get(ext)
+        if not mtype:
+            return
+
+        data = cover_path.read_bytes()
+        cover_img = ImageResource(
+            id="cover-img",
+            data=data,
+            media_type=mtype,
+            filename=f"cover.{ext}",
+        )
+        self.images.append(cover_img)
+        self._register(
+            cover_img,
+            folder=IMAGE_FOLDER,
+            in_spine=False,
+            properties="cover-image",
+        )
+
+        cover_chapter = Chapter(
+            id="cover",
+            title="Cover",
+            content=COVER_IMAGE_TEMPLATE.format(ext=ext),
+            filename="cover.xhtml",
+        )
+        self.chapters.append(cover_chapter)
+        self._register(
+            cover_chapter,
+            folder=TEXT_FOLDER,
+            properties="duokan-page-fullscreen",
+        )
+        self.nav.add_chapter(
+            cover_chapter.id,
+            cover_chapter.title,
+            f"{TEXT_FOLDER}/{cover_chapter.filename}",
+        )
+        self.ncx.add_chapter(
+            cover_chapter.id,
+            cover_chapter.title,
+            f"{TEXT_FOLDER}/{cover_chapter.filename}",
+        )
+        self.opf.include_cover = True
+
+    def _init_intro(self) -> None:
+        intro_html = build_book_intro(
+            book_name=self.title,
+            author=self.author,
+            serial_status=self.serial_status,
+            subject=self.subject,
+            word_count=self.word_count,
+            summary=self.description,
+        )
+        intro = Chapter(
+            id="intro",
+            title="书籍简介",
+            content=intro_html,
+            filename="intro.xhtml",
+            css=[self.intro_css],
+        )
+        self.chapters.append(intro)
+        self._register(intro, folder=TEXT_FOLDER)
+        self.nav.add_chapter(intro.id, intro.title, f"{TEXT_FOLDER}/{intro.filename}")
+        self.ncx.add_chapter(intro.id, intro.title, f"{TEXT_FOLDER}/{intro.filename}")
+
+    def _build_epub(self, output_path: Path) -> Path:
+        """
+        Write out the .epub ZIP file.
+        """
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with zipfile.ZipFile(output_path, "w") as epub:
+            # must be first and uncompressed
+            epub.writestr(
+                "mimetype",
+                "application/epub+zip",
+                compress_type=ZIP_STORED,
+            )
+
+            # container
+            epub.writestr(
+                "META-INF/container.xml",
+                build_container_xml(),
+                compress_type=ZIP_DEFLATED,
+            )
+
+            # core documents
+            epub.writestr(
+                f"{ROOT_PATH}/nav.xhtml",
+                self.nav.to_xhtml(),
+                compress_type=ZIP_DEFLATED,
+            )
+            epub.writestr(
+                f"{ROOT_PATH}/toc.ncx",
+                self.ncx.to_xml(),
+                compress_type=ZIP_DEFLATED,
+            )
+            epub.writestr(
+                f"{ROOT_PATH}/content.opf",
+                self.opf.to_xml(),
+                compress_type=ZIP_DEFLATED,
+            )
+
+            # stylesheets
+            for css in self.styles:
+                path = f"{ROOT_PATH}/{CSS_FOLDER}/{css.filename}"
+                epub.writestr(path, css.content, compress_type=ZIP_DEFLATED)
+
+            # chapters
+            for chap in self.chapters:
+                path = f"{ROOT_PATH}/{TEXT_FOLDER}/{chap.filename}"
+                epub.writestr(path, chap.to_xhtml(), compress_type=ZIP_DEFLATED)
+
+            # images
+            for img in self.images:
+                path = f"{ROOT_PATH}/{IMAGE_FOLDER}/{img.filename}"
+                epub.writestr(path, img.data, compress_type=ZIP_DEFLATED)
+
+        return output_path

novel_downloader/utils/epub/constants.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""
+novel_downloader.utils.epub.constants
+-------------------------------------
+
+EPUB-specific constants used by the builder, including:
+- Directory names for OEBPS structure
+- XML namespace URIs
+- Package attributes and document-type declarations
+- Media type mappings for images
+- Template strings for container.xml and cover image HTML
+"""
+
+ROOT_PATH = "OEBPS"
+IMAGE_FOLDER = "Images"
+TEXT_FOLDER = "Text"
+CSS_FOLDER = "Styles"
+
+XHTML_NS = "http://www.w3.org/1999/xhtml"
+EPUB_NS = "http://www.idpf.org/2007/ops"
+XML_NS = "http://www.w3.org/XML/1998/namespace"
+NCX_NS = "http://www.daisy.org/z3986/2005/ncx/"
+OPF_NS = "http://www.idpf.org/2007/opf"
+DC_NS = "http://purl.org/dc/elements/1.1/"
+
+IMAGE_MEDIA_TYPES: dict[str, str] = {
+    "png": "image/png",
+    "jpg": "image/jpeg",
+    "jpeg": "image/jpeg",
+    "gif": "image/gif",
+    "svg": "image/svg+xml",
+    "webp": "image/webp",
+}
+
+CONTAINER_TEMPLATE = """\
+<?xml version="1.0" encoding="UTF-8"?>
+<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
+    <rootfiles>
+        <rootfile full-path="{root_path}/content.opf"
+            media-type="application/oebps-package+xml"/>
+    </rootfiles>
+</container>
+"""
+
+COVER_IMAGE_TEMPLATE = (
+    f'<div style="text-align: center; margin: 0; padding: 0;">'
+    f'<img src="../{IMAGE_FOLDER}/cover.{{ext}}" alt="cover" '
+    f'style="max-width: 100%; height: auto;" />'
+    f"</div>"
+)
+
+CSS_TMPLATE = (
+    f'<link href="../{CSS_FOLDER}/{{filename}}" '
+    f'rel="stylesheet" type="{{media_type}}"/>'
+)
+
+CHAP_TMPLATE = f"""\
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="{XHTML_NS}" xmlns:epub="{EPUB_NS}" lang="{{lang}}" xml:lang="{{lang}}">
+  <head>
+    <title>{{title}}</title>
+{{xlinks}}
+  </head>
+  <body>{{content}}</body>
+</html>
+"""
+
+NAV_TEMPLATE = f"""\
+<?xml version='1.0' encoding='utf-8'?>
+<!DOCTYPE html>
+<html xmlns="{XHTML_NS}" xmlns:epub="{EPUB_NS}" lang="{{lang}}" xml:lang="{{lang}}">
+  <head>
+    <title>{{title}}</title>
+  </head>
+  <body>
+    <nav epub:type="toc" id="{{id}}" role="doc-toc">
+      <h2>{{title}}</h2>
+      <ol>
+{{items}}
+      </ol>
+    </nav>
+  </body>
+</html>
+"""
+
+NCX_TEMPLATE = f"""\
+<?xml version='1.0' encoding='utf-8'?>
+<ncx xmlns="{NCX_NS}" version="2005-1">
+  <head>
+    <meta name="dtb:uid" content="{{uid}}"/>
+    <meta name="dtb:depth" content="{{depth}}"/>
+    <meta name="dtb:totalPageCount" content="0"/>
+    <meta name="dtb:maxPageNumber" content="0"/>
+  </head>
+  <docTitle>
+    <text>{{title}}</text>
+  </docTitle>
+  <navMap>
+{{navpoints}}
+  </navMap>
+</ncx>
+"""
+
+OPF_TEMPLATE = f"""\
+<?xml version='1.0' encoding='utf-8'?>
+<package xmlns="{OPF_NS}" xmlns:dc="{DC_NS}" xmlns:opf="{OPF_NS}" version="3.0" unique-identifier="id" prefix="rendition: http://www.idpf.org/vocab/rendition/#">
+  <metadata>
+{{metadata}}
+  </metadata>
+  <manifest>
+{{manifest_items}}
+  </manifest>
+  <spine{{spine_toc}}>
+{{spine_items}}
+  </spine>
+{{guide_section}}</package>
+"""  # noqa: E501