novel-downloader 1.3.2__py3-none-any.whl → 1.4.0__py3-none-any.whl

novel_downloader/core/exporters/common/__init__.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+"""
+novel_downloader.core.exporters.common
+--------------------------------------
+
+This module provides the `CommonExporter` class for
+handling the saving process of novels.
+"""
+
+from .main_exporter import CommonExporter
+
+__all__ = ["CommonExporter"]

novel_downloader/core/{savers → exporters}/common/epub.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """
-novel_downloader.core.savers.common.epub
-----------------------------------------
+novel_downloader.core.exporters.common.epub
+-------------------------------------------
 
 Contains the logic for exporting novel content as a single `.epub` file.
 """
@@ -11,55 +11,32 @@ from __future__ import annotations
 import json
 from pathlib import Path
 from typing import TYPE_CHECKING
-from urllib.parse import unquote, urlparse
 
 from ebooklib import epub
 
-from novel_downloader.core.savers.epub_utils import (
+from novel_downloader.core.exporters.epub_utils import (
+    add_images_from_dir,
     chapter_txt_to_html,
     create_css_items,
     create_volume_intro,
     generate_book_intro_html,
     init_epub,
+    inline_remote_images,
 )
 from novel_downloader.utils.constants import (
-    DEFAULT_IMAGE_SUFFIX,
     EPUB_OPTIONS,
     EPUB_TEXT_FOLDER,
 )
 from novel_downloader.utils.file_utils import sanitize_filename
+from novel_downloader.utils.network import download_image
 from novel_downloader.utils.text_utils import clean_chapter_title
 
 if TYPE_CHECKING:
-    from .main_saver import CommonSaver
+    from .main_exporter import CommonExporter
 
 
-def _image_url_to_filename(url: str) -> str:
-    """
-    Parse and sanitize a image filename from a URL.
-    If no filename or suffix exists, fallback to default name and extension.
-
-    :param url: URL string
-    :return: Safe filename string
-    """
-    if not url:
-        return ""
-
-    parsed_url = urlparse(url)
-    path = unquote(parsed_url.path)
-    filename = Path(path).name
-
-    if not filename:
-        filename = "image"
-
-    if not Path(filename).suffix:
-        filename += DEFAULT_IMAGE_SUFFIX
-
-    return filename
-
-
-def common_save_as_epub(
-    saver: CommonSaver,
+def common_export_as_epub(
+    exporter: CommonExporter,
     book_id: str,
 ) -> None:
     """
@@ -75,12 +52,13 @@ def common_save_as_epub(
     :param saver: The saver instance, carrying config and path info.
     :param book_id: Identifier of the novel (used as subdirectory name).
     """
-    TAG = "[saver]"
-    site = saver.site
-    config = saver._config
+    TAG = "[exporter]"
+    config = exporter._config
     # --- Paths & options ---
-    raw_base = saver.raw_data_dir / site / book_id
-    out_dir = saver.output_dir
+    raw_base = exporter._raw_data_dir / book_id
+    img_dir = exporter._cache_dir / book_id / "images"
+    out_dir = exporter.output_dir
+    img_dir.mkdir(parents=True, exist_ok=True)
     out_dir.mkdir(parents=True, exist_ok=True)
 
     # --- Load book_info.json ---
@@ -89,21 +67,27 @@ def common_save_as_epub(
         info_text = info_path.read_text(encoding="utf-8")
         book_info = json.loads(info_text)
     except Exception as e:
-        saver.logger.error("%s Failed to load %s: %s", TAG, info_path, e)
+        exporter.logger.error("%s Failed to load %s: %s", TAG, info_path, e)
         return
 
     book_name = book_info.get("book_name", book_id)
-    saver.logger.info(
+    exporter.logger.info(
         "%s Starting EPUB generation: %s (ID: %s)", TAG, book_name, book_id
     )
 
     # --- Generate intro + cover ---
     intro_html = generate_book_intro_html(book_info)
     cover_path: Path | None = None
-    if config.include_cover:
-        cover_filename = _image_url_to_filename(book_info.get("cover_url", ""))
-        if cover_filename:
-            cover_path = raw_base / cover_filename
+    cover_url = book_info.get("cover_url", "")
+    if config.include_cover and cover_url:
+        cover_path = download_image(
+            cover_url,
+            raw_base,
+            target_name="cover",
+            on_exist="overwrite",
+        )
+        if not cover_path:
+            exporter.logger.warning("Failed to download cover from %s", cover_url)
 
     # --- Initialize EPUB ---
     book, spine, toc_list = init_epub(
@@ -124,7 +108,7 @@ def common_save_as_epub(
     for vol_index, vol in enumerate(volumes, start=1):
         raw_vol_name = vol.get("volume_name", "").strip()
         vol_name = clean_chapter_title(raw_vol_name) or f"Unknown Volume {vol_index}"
-        saver.logger.info("Processing volume %d: %s", vol_index, vol_name)
+        exporter.logger.info("Processing volume %d: %s", vol_index, vol_name)
 
         # Volume intro
         vol_intro = epub.EpubHtml(
@@ -148,12 +132,12 @@ def common_save_as_epub(
             chap_id = chap.get("chapterId")
             chap_title = chap.get("title", "")
             if not chap_id:
-                saver.logger.warning("%s Missing chapterId, skipping: %s", TAG, chap)
+                exporter.logger.warning("%s Missing chapterId, skipping: %s", TAG, chap)
                 continue
 
-            chapter_data = saver._get_chapter(book_id, chap_id)
+            chapter_data = exporter._get_chapter(book_id, chap_id)
             if not chapter_data:
-                saver.logger.info(
+                exporter.logger.info(
                     "%s Missing chapter file: %s (%s), skipping.",
                     TAG,
                     chap_title,
@@ -162,9 +146,11 @@ def common_save_as_epub(
                 continue
 
             title = clean_chapter_title(chapter_data.get("title", "")) or chap_id
+            content: str = chapter_data.get("content", "")
+            content = inline_remote_images(content, img_dir)
             chap_html = chapter_txt_to_html(
                 chapter_title=title,
-                chapter_text=chapter_data.get("content", ""),
+                chapter_text=content,
                 author_say=chapter_data.get("author_say", ""),
             )
 
@@ -182,14 +168,16 @@ def common_save_as_epub(
 
         toc_list.append((section, chapter_items))
 
+    book = add_images_from_dir(book, img_dir)
+
     # --- 5. Finalize EPUB ---
-    saver.logger.info("%s Building TOC and spine...", TAG)
+    exporter.logger.info("%s Building TOC and spine...", TAG)
     book.toc = toc_list
     book.spine = spine
     book.add_item(epub.EpubNcx())
     book.add_item(epub.EpubNav())
 
-    out_name = saver.get_filename(
+    out_name = exporter.get_filename(
         title=book_name,
         author=book_info.get("author"),
         ext="epub",
@@ -198,7 +186,7 @@ def common_save_as_epub(
 
     try:
         epub.write_epub(out_path, book, EPUB_OPTIONS)
-        saver.logger.info("%s EPUB successfully written to %s", TAG, out_path)
+        exporter.logger.info("%s EPUB successfully written to %s", TAG, out_path)
     except Exception as e:
-        saver.logger.error("%s Failed to write EPUB to %s: %s", TAG, out_path, e)
+        exporter.logger.error("%s Failed to write EPUB to %s: %s", TAG, out_path, e)
     return

novel_downloader/core/{savers/common/main_saver.py → exporters/common/main_exporter.py}

@@ -1,52 +1,44 @@
 #!/usr/bin/env python3
 """
-novel_downloader.core.savers.common.main_saver
-----------------------------------------------
+novel_downloader.core.exporters.common.main_exporter
+----------------------------------------------------
 
-This module implements the `QidianSaver` class, a concrete saver for handling
-novel data from Qidian (起点中文网). It defines the logic to compile, structure,
-and export novel content in plain text format based on the platform's metadata
-and chapter files.
+This module implements the `CommonExporter` class, a concrete exporter for handling
+novel data. It defines the logic to compile, structure, and export novel content
+in plain text format based on the platform's metadata and chapter files.
 """
 
 from collections.abc import Mapping
 from typing import Any
 
-from novel_downloader.config.models import SaverConfig
+from novel_downloader.core.exporters.base import BaseExporter
+from novel_downloader.models import ExporterConfig
 from novel_downloader.utils.chapter_storage import ChapterStorage
 
-from ..base import BaseSaver
-from .txt import common_save_as_txt
+from .txt import common_export_as_txt
 
 
-class CommonSaver(BaseSaver):
+class CommonExporter(BaseExporter):
     """
-    CommonSaver is a saver that processes and exports novels.
-    It extends the BaseSaver interface and provides
-    logic for exporting full novels as plain text (.txt) files.
+    CommonExporter is a exporter that processes and exports novels.
+    It extends the BaseExporter interface and provides
+    logic for exporting full novels as plain text (.txt) files
+    and EPUB (.epub) files.
     """
 
     def __init__(
         self,
-        config: SaverConfig,
+        config: ExporterConfig,
         site: str,
         chap_folders: list[str] | None = None,
     ):
-        """
-        Initialize the common saver with site information.
-
-        :param config: A SaverConfig object that defines
-                        save paths, formats, and options.
-        :param site: Identifier for the site the saver is handling.
-        """
-        super().__init__(config)
-        self._site = site
+        super().__init__(config, site)
         self._chapter_storage_cache: dict[str, list[ChapterStorage]] = {}
         self._chap_folders: list[str] = chap_folders or ["chapters"]
 
-    def save_as_txt(self, book_id: str) -> None:
+    def export_as_txt(self, book_id: str) -> None:
         """
-        Compile and save a complete novel as a single .txt file.
+        Compile and export a complete novel as a single .txt file.
 
         Processing steps:
             1. Load book metadata from `book_info.json`, including title,
@@ -60,9 +52,9 @@ class CommonSaver(BaseSaver):
         :param book_id: The book identifier (used to locate raw data)
         """
         self._init_chapter_storages(book_id)
-        return common_save_as_txt(self, book_id)
+        return common_export_as_txt(self, book_id)
 
-    def save_as_epub(self, book_id: str) -> None:
+    def export_as_epub(self, book_id: str) -> None:
         """
         Persist the assembled book as a EPUB (.epub) file.
 
@@ -70,14 +62,14 @@ class CommonSaver(BaseSaver):
         :raises NotImplementedError: If the method is not overridden.
         """
         try:
-            from .epub import common_save_as_epub
+            from .epub import common_export_as_epub
         except ImportError as err:
             raise NotImplementedError(
                 "EPUB export not supported. Please install 'ebooklib'"
             ) from err
 
         self._init_chapter_storages(book_id)
-        return common_save_as_epub(self, book_id)
+        return common_export_as_epub(self, book_id)
 
     @property
     def site(self) -> str:
@@ -88,15 +80,6 @@ class CommonSaver(BaseSaver):
         """
         return self._site
 
-    @site.setter
-    def site(self, value: str) -> None:
-        """
-        Set the site identifier.
-
-        :param value: New site string to set.
-        """
-        self._site = value
-
     def _get_chapter(
         self,
         book_id: str,
@@ -109,7 +92,9 @@ class CommonSaver(BaseSaver):
         return {}
 
     def _init_chapter_storages(self, book_id: str) -> None:
-        raw_base = self.raw_data_dir / self._site / book_id
+        if book_id in self._chapter_storage_cache:
+            return
+        raw_base = self._raw_data_dir / book_id
         self._chapter_storage_cache[book_id] = [
             ChapterStorage(
                 raw_base=raw_base,
@@ -118,3 +103,15 @@ class CommonSaver(BaseSaver):
             )
             for ns in self._chap_folders
         ]
+
+    def _on_close(self) -> None:
+        """
+        Close all ChapterStorage connections in the cache.
+        """
+        for storages in self._chapter_storage_cache.values():
+            for storage in storages:
+                try:
+                    storage.close()
+                except Exception as e:
+                    self.logger.warning("Failed to close storage %s: %s", storage, e)
+        self._chapter_storage_cache.clear()

novel_downloader/core/{savers → exporters}/common/txt.py

@@ -1,13 +1,13 @@
 #!/usr/bin/env python3
 """
-novel_downloader.core.savers.common.txt
----------------------------------------
+novel_downloader.core.exporters.common.txt
+------------------------------------------
 
 Contains the logic for exporting novel content as a single `.txt` file.
 
 This module defines `common_save_as_txt` function, which assembles and formats
 a novel based on metadata and chapter files found in the raw data directory.
-It is intended to be used by `CommonSaver` as part of the save/export process.
+It is intended to be used by `CommonExporter` as part of the save/export process.
 """
 
 from __future__ import annotations
@@ -22,33 +22,29 @@ from novel_downloader.utils.text_utils import (
 )
 
 if TYPE_CHECKING:
-    from .main_saver import CommonSaver
+    from .main_exporter import CommonExporter
 
 
-def common_save_as_txt(
-    saver: CommonSaver,
+def common_export_as_txt(
+    exporter: CommonExporter,
     book_id: str,
 ) -> None:
     """
     将 save_path 文件夹中该小说的所有章节 json 文件合并保存为一个完整的 txt 文件,
     并保存到 out_path 下
-    假设章节文件名格式为 `{chapterId}.json`
 
-    处理流程：
+    处理流程:
       1. 从 book_info.json 中加载书籍信息 (包含书名、作者、简介及卷章节列表)
-      2. 遍历各卷, 每个卷先追加卷标题, 然后依次追加该卷下各章节的标题和内容,
-         同时记录最后一个章节标题作为“原文截至”
-      3. 将书籍元信息 (书名、作者、原文截至、内容简介) 与所有章节内容拼接,
-         构成最终完整文本
+      2. 遍历各卷, 每个卷先追加卷标题, 然后依次追加该卷下各章节的标题和内容
+      3. 将书籍元信息 (书名、作者、原文截至、内容简介) 与所有章节内容拼接
       4. 将最终结果保存到 out_path 下 (例如：`{book_name}.txt`)
 
     :param book_id: Identifier of the novel (used as subdirectory name).
     """
-    TAG = "[saver]"
-    site = saver.site
+    TAG = "[Exporter]"
     # --- Paths & options ---
-    raw_base = saver.raw_data_dir / site / book_id
-    out_dir = saver.output_dir
+    raw_base = exporter._raw_data_dir / book_id
+    out_dir = exporter.output_dir
     out_dir.mkdir(parents=True, exist_ok=True)
 
     # --- Load book_info.json ---
@@ -57,7 +53,7 @@ def common_save_as_txt(
         info_text = info_path.read_text(encoding="utf-8")
         book_info = json.loads(info_text)
     except Exception as e:
-        saver.logger.error("%s Failed to load %s: %s", TAG, info_path, e)
+        exporter.logger.error("%s Failed to load %s: %s", TAG, info_path, e)
         return
 
     # --- Compile chapters ---
@@ -71,17 +67,17 @@ def common_save_as_txt(
         if vol_name:
             volume_header = f"\n\n{'=' * 6} {vol_name} {'=' * 6}\n\n"
             parts.append(volume_header)
-            saver.logger.info("%s Processing volume: %s", TAG, vol_name)
+            exporter.logger.info("%s Processing volume: %s", TAG, vol_name)
         for chap in vol.get("chapters", []):
             chap_id = chap.get("chapterId")
             chap_title = chap.get("title", "")
             if not chap_id:
-                saver.logger.warning("%s Missing chapterId, skipping: %s", TAG, chap)
+                exporter.logger.warning("%s Missing chapterId, skipping: %s", TAG, chap)
                 continue
 
-            chapter_data = saver._get_chapter(book_id, chap_id)
+            chapter_data = exporter._get_chapter(book_id, chap_id)
             if not chapter_data:
-                saver.logger.info(
+                exporter.logger.info(
                     "%s Missing chapter file in: %s (%s), skipping.",
                     TAG,
                     chap_title,
@@ -134,13 +130,13 @@ def common_save_as_txt(
     final_text = header + "\n\n" + "\n\n".join(parts).strip()
 
     # --- Determine output file path ---
-    out_name = saver.get_filename(title=name, author=author, ext="txt")
+    out_name = exporter.get_filename(title=name, author=author, ext="txt")
     out_path = out_dir / out_name
 
     # --- Save final text ---
     try:
         save_as_txt(content=final_text, filepath=out_path)
-        saver.logger.info("%s Novel saved to: %s", TAG, out_path)
+        exporter.logger.info("%s Novel saved to: %s", TAG, out_path)
     except Exception as e:
-        saver.logger.error("%s Failed to save file: %s", TAG, e)
+        exporter.logger.error("%s Failed to save file: %s", TAG, e)
     return

novel_downloader/core/exporters/epub_utils/__init__.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""
+novel_downloader.core.exporters.epub_utils
+------------------------------------------
+
+This package provides utility functions for constructing EPUB files,
+including:
+
+- CSS inclusion (css_builder)
+- Image embedding (image_loader)
+- EPUB book initialization (initializer)
+- Chapter text-to-HTML conversion (text_to_html)
+- Volume intro HTML generation (volume_intro)
+"""
+
+from .css_builder import create_css_items
+from .image_loader import (
+    add_images_from_dir,
+    add_images_from_dirs,
+    add_images_from_list,
+)
+from .initializer import init_epub
+from .text_to_html import (
+    chapter_txt_to_html,
+    generate_book_intro_html,
+    inline_remote_images,
+)
+from .volume_intro import create_volume_intro
+
+__all__ = [
+    "create_css_items",
+    "add_images_from_dir",
+    "add_images_from_dirs",
+    "add_images_from_list",
+    "init_epub",
+    "chapter_txt_to_html",
+    "create_volume_intro",
+    "generate_book_intro_html",
+    "inline_remote_images",
+]

novel_downloader/core/{savers → exporters}/epub_utils/css_builder.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python3
 """
-novel_downloader.core.savers.epub_utils.css_builder
+novel_downloader.core.exporters.epub_utils.css_builder
+------------------------------------------------------
 
 Reads local CSS files and wraps them into epub.EpubItem objects,
 returning a list ready to be added to the EPUB.

novel_downloader/core/exporters/epub_utils/image_loader.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""
+novel_downloader.core.exporters.epub_utils.image_loader
+-------------------------------------------------------
+
+Utilities for embedding image files into an EpubBook.
+"""
+
+import logging
+from collections.abc import Iterable, Sequence
+from pathlib import Path
+
+from ebooklib import epub
+
+from novel_downloader.utils.constants import EPUB_IMAGE_FOLDER
+
+logger = logging.getLogger(__name__)
+
+_SUPPORTED_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",
+}
+_DEFAULT_IMAGE_MEDIA_TYPE = "image/jpeg"
+
+
+def add_images_from_list(
+    book: epub.EpubBook,
+    image_list: Sequence[str | Path],
+) -> epub.EpubBook:
+    """
+    Add a list of image files to the EPUB's image folder.
+
+    :param book: The EpubBook object to modify.
+    :param image_list: List of paths to image files.
+    :return: The same EpubBook instance, with images added.
+    """
+    for img_path in image_list:
+        img_path = Path(img_path)
+        if not img_path.is_file():
+            continue
+
+        suffix = img_path.suffix.lower().lstrip(".")
+        media_type = _SUPPORTED_IMAGE_MEDIA_TYPES.get(suffix)
+        if media_type is None:
+            media_type = _DEFAULT_IMAGE_MEDIA_TYPE
+            logger.warning(
+                "Unknown image suffix '%s' - defaulting media_type to %s",
+                suffix,
+                media_type,
+            )
+
+        try:
+            content = img_path.read_bytes()
+            item = epub.EpubItem(
+                uid=f"img_{img_path.stem}",
+                file_name=f"{EPUB_IMAGE_FOLDER}/{img_path.name}",
+                media_type=media_type,
+                content=content,
+            )
+            book.add_item(item)
+            logger.debug("Embedded image: %s", img_path.name)
+        except Exception:
+            logger.exception("Failed to embed image %s", img_path)
+
+    return book
+
+
+def add_images_from_dir(
+    book: epub.EpubBook,
+    image_dir: str | Path,
+) -> epub.EpubBook:
+    """
+    Load every file in `image_dir` into the EPUB's image folder.
+
+    :param book: The EpubBook object to modify.
+    :param image_dir: Path to the directory containing image files.
+    :return: The same EpubBook instance, with images added.
+    """
+    image_dir = Path(image_dir)
+    if not image_dir.is_dir():
+        logger.warning("Image directory not found or not a directory: %s", image_dir)
+        return book
+
+    for img_path in image_dir.iterdir():
+        if not img_path.is_file():
+            continue
+
+        suffix = img_path.suffix.lower().lstrip(".")
+        media_type = _SUPPORTED_IMAGE_MEDIA_TYPES.get(suffix)
+        if media_type is None:
+            media_type = _DEFAULT_IMAGE_MEDIA_TYPE
+            logger.warning(
+                "Unknown image suffix '%s' - defaulting media_type to %s",
+                suffix,
+                media_type,
+            )
+
+        try:
+            content = img_path.read_bytes()
+            item = epub.EpubItem(
+                uid=f"img_{img_path.stem}",
+                file_name=f"{EPUB_IMAGE_FOLDER}/{img_path.name}",
+                media_type=media_type,
+                content=content,
+            )
+            book.add_item(item)
+            logger.debug("Embedded image: %s", img_path.name)
+        except Exception:
+            logger.exception("Failed to embed image %s", img_path)
+
+    return book
+
+
+def add_images_from_dirs(
+    book: epub.EpubBook,
+    image_dirs: Iterable[str | Path],
+) -> epub.EpubBook:
+    """
+    Add all images from multiple directories into the given EpubBook.
+
+    :param book: The EpubBook object to modify.
+    :param image_dirs: An iterable of directory paths to scan for images.
+    :return: The same EpubBook instance, with all images added.
+    """
+    for img_dir in image_dirs:
+        book = add_images_from_dir(book, img_dir)
+    return book

novel_downloader/core/{savers → exporters}/epub_utils/initializer.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python3
 """
-novel_downloader.core.savers.epub_utils.initializer
+novel_downloader.core.exporters.epub_utils.initializer
+------------------------------------------------------
 
 Initializes an epub.EpubBook object, sets metadata
 (identifier, title, author, language, description),
@@ -41,10 +42,12 @@ def init_epub(
     """
     book = epub.EpubBook()
     book.set_identifier(str(book_id))
-    book.set_title(book_info.get("book_name", "未找到书名"))
+    book_name = book_info.get("book_name") or book_info.get("volume_name", "未找到书名")
+    book.set_title(book_name)
     book.set_language("zh-CN")
     book.add_author(book_info.get("author", "未找到作者"))
-    book.add_metadata("DC", "description", book_info.get("summary", "未找到作品简介"))
+    desc = book_info.get("summary") or book_info.get("volume_intro", "未找到作品简介")
+    book.add_metadata("DC", "description", desc)
 
     spine = []