novel-downloader 1.1.0__py3-none-any.whl

novel_downloader/core/savers/base_saver.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+novel_downloader.core.savers.base_saver
+---------------------------------------
+
+This module provides an abstract base class `BaseSaver` that defines the
+common interface and reusable logic for saving assembled novel content
+into various output formats.
+"""
+
+import abc
+import logging
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from novel_downloader.config.models import SaverConfig
+from novel_downloader.core.interfaces import SaverProtocol
+
+logger = logging.getLogger(__name__)
+
+
+class SafeDict(Dict[str, Any]):
+    def __missing__(self, key: str) -> str:
+        return "{{{}}}".format(key)
+
+
+class BaseSaver(SaverProtocol, abc.ABC):
+    """
+    BaseSaver defines the interface and common structure for
+    saving assembled book content into various formats
+    such as TXT, EPUB, Markdown, or PDF.
+    """
+
+    def __init__(self, config: SaverConfig):
+        """
+        Initialize the saver with given configuration.
+
+        :param config: A SaverConfig object that defines
+                        save paths, formats, and options.
+        """
+        self._config = config
+
+        self._raw_data_dir = Path(config.raw_data_dir)
+        self._output_dir = Path(config.output_dir)
+        self._raw_data_dir.mkdir(parents=True, exist_ok=True)
+        self._output_dir.mkdir(parents=True, exist_ok=True)
+
+        self._filename_template = config.filename_template
+
+    def save(self, book_id: str) -> None:
+        """
+        Save the book in the formats specified in config.
+        If a method is not implemented or fails, log the error and continue.
+
+        :param book_id: The book identifier (used for filename, lookup, etc.)
+        """
+        TAG = "[Saver]"
+        actions = [
+            ("make_txt", self.save_as_txt),
+            ("make_epub", self.save_as_epub),
+            ("make_md", self.save_as_md),
+            ("make_pdf", self.save_as_pdf),
+        ]
+
+        for flag_name, save_method in actions:
+            if getattr(self._config, flag_name, False):
+                try:
+                    logger.info(
+                        "%s Attempting to save book_id '%s' as %s...",
+                        TAG,
+                        book_id,
+                        flag_name,
+                    )
+                    save_method(book_id)
+                    logger.info("%s Successfully saved as %s.", TAG, flag_name)
+                except NotImplementedError as e:
+                    logger.warning(
+                        "%s Save method for %s not implemented: %s",
+                        TAG,
+                        flag_name,
+                        str(e),
+                    )
+                except Exception as e:
+                    logger.error(
+                        "%s Error while saving as %s: %s", TAG, flag_name, str(e)
+                    )
+        return
+
+    @abc.abstractmethod
+    def save_as_txt(self, book_id: str) -> None:
+        """
+        Persist the assembled book as a .txt file.
+
+        This method must be implemented by all subclasses.
+
+        :param book_id: The book identifier (used for filename, lookup, etc.)
+        """
+        ...
+
+    def save_as_epub(self, book_id: str) -> None:
+        """
+        Optional: Persist the assembled book as a EPUB (.epub) file.
+
+        :param book_id: The book identifier.
+        :raises NotImplementedError: If the method is not overridden.
+        """
+        raise NotImplementedError("EPUB export not supported by this saver.")
+
+    def save_as_md(self, book_id: str) -> None:
+        """
+        Optional: Persist the assembled book as a Markdown file.
+
+        :param book_id: The book identifier.
+        :raises NotImplementedError: If the method is not overridden.
+        """
+        raise NotImplementedError("Markdown export not supported by this saver.")
+
+    def save_as_pdf(self, book_id: str) -> None:
+        """
+        Optional: Persist the assembled book as a PDF file.
+
+        :param book_id: The book identifier.
+        :raises NotImplementedError: If the method is not overridden.
+        """
+        raise NotImplementedError("PDF export not supported by this saver.")
+
+    def get_filename(
+        self,
+        *,
+        title: str,
+        author: Optional[str] = None,
+        ext: str = "txt",
+        **extra_fields: str,
+    ) -> str:
+        """
+        Generate a filename based on the configured template and metadata fields.
+
+        :param title: Book title (required).
+        :param author: Author name (optional).
+        :param ext: File extension (e.g., "txt", "epub").
+        :param extra_fields: Any additional fields used in the filename template.
+        :return: Formatted filename with extension.
+        """
+        # Merge all fields with defaults
+        context = SafeDict(title=title, author=author or "", **extra_fields)
+
+        name = self._filename_template.format_map(context)
+
+        if self._config.append_timestamp:
+            name += f"_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+
+        return f"{name}.{ext}"
+
+    @property
+    def output_dir(self) -> Path:
+        """Access the output directory for saving files."""
+        return self._output_dir
+
+    @property
+    def raw_data_dir(self) -> Path:
+        """Access the raw data directory."""
+        return self._raw_data_dir
+
+    @property
+    def filename_template(self) -> str:
+        """Access the filename template."""
+        return self._filename_template

novel_downloader/core/savers/common_saver/__init__.py

@@ -0,0 +1,13 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+novel_downloader.core.savers.common_saver
+-----------------------------------------
+
+This module provides the `CommonSaver` class for handling the saving process
+of novels.
+"""
+
+from .main_saver import CommonSaver
+
+__all__ = ["CommonSaver"]

novel_downloader/core/savers/common_saver/common_epub.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+novel_downloader.core.savers.common_saver.common_epub
+-----------------------------------------------------
+
+Contains the logic for exporting novel content as a single `.epub` file.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING, List, Optional
+from urllib.parse import unquote, urlparse
+
+from ebooklib import epub
+
+from novel_downloader.core.savers.epub_utils import (
+    chapter_txt_to_html,
+    create_css_items,
+    create_volume_intro,
+    generate_book_intro_html,
+    init_epub,
+)
+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.text_utils import clean_chapter_title
+
+if TYPE_CHECKING:
+    from .main_saver import CommonSaver
+
+logger = logging.getLogger(__name__)
+
+CHAPTER_FOLDERS: List[str] = [
+    "chapters",
+    "encrypted_chapters",
+]
+
+
+def _find_chapter_file(
+    raw_base: Path,
+    chapter_id: str,
+) -> Optional[Path]:
+    """
+    Search for `<chapter_id>.json` under each folder in CHAPTER_FOLDERS
+    inside raw_data_dir/site/book_id. Return the first existing Path,
+    or None if not found.
+    """
+    for folder in CHAPTER_FOLDERS:
+        candidate = raw_base / folder / f"{chapter_id}.json"
+        if candidate.exists():
+            return candidate
+    return None
+
+
+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,
+    book_id: str,
+) -> None:
+    """
+    Export a single novel (identified by `book_id`) to an EPUB file.
+
+    This function will:
+      1. Load `book_info.json` for metadata.
+      2. Generate introductory HTML and optionally include the cover image.
+      3. Initialize the EPUB container.
+      4. Iterate through volumes and chapters, convert each to XHTML.
+      5. Assemble the spine, TOC, CSS and write out the final `.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
+    # --- Paths & options ---
+    raw_base = saver.raw_data_dir / site / book_id
+    out_dir = saver.output_dir
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    # --- Load book_info.json ---
+    info_path = raw_base / "book_info.json"
+    try:
+        info_text = info_path.read_text(encoding="utf-8")
+        book_info = json.loads(info_text)
+    except Exception as e:
+        logger.error("%s Failed to load %s: %s", TAG, info_path, e)
+        return
+
+    book_name = book_info.get("book_name", book_id)
+    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: Optional[Path] = 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
+
+    # --- Initialize EPUB ---
+    book, spine, toc_list = init_epub(
+        book_info=book_info,
+        book_id=book_id,
+        intro_html=intro_html,
+        book_cover_path=cover_path,
+        include_toc=config.include_toc,
+    )
+    for css in create_css_items(
+        include_main=True,
+        include_volume=True,
+    ):
+        book.add_item(css)
+
+    # --- Compile chapters ---
+    volumes = book_info.get("volumes", [])
+    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}"
+        logger.info("Processing volume %d: %s", vol_index, vol_name)
+
+        # Volume intro
+        vol_intro = epub.EpubHtml(
+            title=vol_name,
+            file_name=f"{EPUB_TEXT_FOLDER}/volume_intro_{vol_index}.xhtml",
+            lang="zh",
+        )
+        vol_intro.content = create_volume_intro(vol_name, vol.get("volume_intro", ""))
+        vol_intro.add_link(
+            href="../Styles/volume-intro.css",
+            rel="stylesheet",
+            type="text/css",
+        )
+        book.add_item(vol_intro)
+        spine.append(vol_intro)
+
+        section = epub.Section(vol_name, vol_intro.file_name)
+        chapter_items: List[epub.EpubHtml] = []
+
+        for chap in vol.get("chapters", []):
+            chap_id = chap.get("chapterId")
+            chap_title = chap.get("title", "")
+            if not chap_id:
+                logger.warning("%s Missing chapterId, skipping: %s", TAG, chap)
+                continue
+
+            json_path = _find_chapter_file(raw_base, chap_id)
+            if json_path is None:
+                logger.info(
+                    "%s Missing chapter file: %s (%s), skipping.",
+                    TAG,
+                    chap_title,
+                    chap_id,
+                )
+                continue
+
+            try:
+                data = json.loads(json_path.read_text(encoding="utf-8"))
+                title = clean_chapter_title(data.get("title", "")) or chap_id
+                chap_html = chapter_txt_to_html(
+                    chapter_title=title,
+                    chapter_text=data.get("content", ""),
+                    author_say=data.get("author_say", ""),
+                )
+            except Exception as e:
+                logger.error("%s Error parsing chapter %s: %s", TAG, json_path, e)
+                continue
+
+            chap_path = f"{EPUB_TEXT_FOLDER}/{chap_id}.xhtml"
+            item = epub.EpubHtml(title=chap_title, file_name=chap_path, lang="zh")
+            item.content = chap_html
+            item.add_link(
+                href="../Styles/main.css",
+                rel="stylesheet",
+                type="text/css",
+            )
+            book.add_item(item)
+            spine.append(item)
+            chapter_items.append(item)
+
+        toc_list.append((section, chapter_items))
+
+    # --- 5. Finalize EPUB ---
+    logger.info("%s Building TOC and spine...", TAG)
+    book.toc = tuple(toc_list)
+    book.spine = spine
+    book.add_item(epub.EpubNcx())
+    book.add_item(epub.EpubNav())
+
+    out_name = saver.get_filename(
+        title=book_name,
+        author=book_info.get("author"),
+        ext="epub",
+    )
+    out_path = out_dir / sanitize_filename(out_name)
+
+    try:
+        epub.write_epub(out_path, book, EPUB_OPTIONS)
+        logger.info("%s EPUB successfully written to %s", TAG, out_path)
+    except Exception as e:
+        logger.error("%s Failed to write EPUB to %s: %s", TAG, out_path, e)
+    return

novel_downloader/core/savers/common_saver/common_txt.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+novel_downloader.core.savers.common_saver.qidian_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.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING, List, Optional
+
+from novel_downloader.utils.file_utils import save_as_txt
+from novel_downloader.utils.text_utils import clean_chapter_title, format_chapter
+
+if TYPE_CHECKING:
+    from .main_saver import CommonSaver
+
+logger = logging.getLogger(__name__)
+
+CHAPTER_FOLDERS: List[str] = [
+    "chapters",
+    "encrypted_chapters",
+]
+
+
+def _find_chapter_file(
+    raw_base: Path,
+    chapter_id: str,
+) -> Optional[Path]:
+    """
+    Search for `<chapter_id>.json` under each folder in CHAPTER_FOLDERS
+    inside raw_data_dir/site/book_id. Return the first existing Path,
+    or None if not found.
+    """
+    for folder in CHAPTER_FOLDERS:
+        candidate = raw_base / folder / f"{chapter_id}.json"
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def common_save_as_txt(
+    saver: CommonSaver,
+    book_id: str,
+) -> None:
+    """
+    将 save_path 文件夹中该小说的所有章节 json 文件合并保存为一个完整的 txt 文件,
+    并保存到 out_path 下
+    假设章节文件名格式为 `{chapterId}.json`
+
+    处理流程：
+      1. 从 book_info.json 中加载书籍信息 (包含书名、作者、简介及卷章节列表)
+      2. 遍历各卷, 每个卷先追加卷标题, 然后依次追加该卷下各章节的标题和内容,
+         同时记录最后一个章节标题作为“原文截至”
+      3. 将书籍元信息 (书名、作者、原文截至、内容简介) 与所有章节内容拼接,
+         构成最终完整文本
+      4. 将最终结果保存到 out_path 下 (例如：`{book_name}.txt`)
+
+    :param book_id: Identifier of the novel (used as subdirectory name).
+    """
+    TAG = "[saver]"
+    site = saver.site
+    # --- Paths & options ---
+    raw_base = saver.raw_data_dir / site / book_id
+    out_dir = saver.output_dir
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    # --- Load book_info.json ---
+    info_path = raw_base / "book_info.json"
+    try:
+        info_text = info_path.read_text(encoding="utf-8")
+        book_info = json.loads(info_text)
+    except Exception as e:
+        logger.error("%s Failed to load %s: %s", TAG, info_path, e)
+        return
+
+    # --- Compile chapters ---
+    parts: List[str] = []
+    latest_chapter: str = ""
+    volumes = book_info.get("volumes", [])
+
+    for vol in volumes:
+        vol_name = vol.get("volume_name", "").strip()
+        vol_name = clean_chapter_title(vol_name)
+        if vol_name:
+            volume_header = f"\n\n{'=' * 6} {vol_name} {'=' * 6}\n\n"
+            parts.append(volume_header)
+            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:
+                logger.warning("%s Missing chapterId, skipping: %s", TAG, chap)
+                continue
+
+            # Find the JSON file in one of the known subfolders
+            json_path = _find_chapter_file(raw_base, chap_id)
+            if json_path is None:
+                logger.info(
+                    "%s Missing chapter file in: %s (%s), skipping.",
+                    TAG,
+                    chap_title,
+                    chap_id,
+                )
+                continue
+
+            try:
+                chapter_data = json.loads(json_path.read_text(encoding="utf-8"))
+            except Exception as e:
+                logger.error("%s Error reading %s: %s", TAG, json_path, e)
+                continue
+
+            # Extract structured fields
+            title = chapter_data.get("title", chap_title).strip()
+            content = chapter_data.get("content", "").strip()
+            author_say = chapter_data.get("author_say", "").strip()
+            clean_title = clean_chapter_title(title)
+
+            parts.append(format_chapter(clean_title, content, author_say))
+            latest_chapter = clean_title
+
+    # --- Build header ---
+    name = book_info.get("book_name")
+    author = book_info.get("author")
+    words = book_info.get("word_count")
+    updated = book_info.get("update_time")
+    summary = book_info.get("summary")
+
+    header_lines = []
+
+    if name:
+        header_lines.append(f"书名: {name}")
+
+    if author:
+        header_lines.append(f"作者: {author}")
+
+    if words:
+        header_lines.append(f"总字数: {words}")
+
+    if updated:
+        header_lines.append(f"更新日期: {updated}")
+
+    header_lines.append(f"原文截至: {latest_chapter}")
+
+    if summary:
+        header_lines.append("内容简介:")
+        header_lines.append(summary)
+
+    header_lines.append("")
+    header_lines.append("-" * 10)
+    header_lines.append("")
+
+    header = "\n".join(header_lines)
+
+    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_path = out_dir / out_name
+
+    # --- Save final text ---
+    try:
+        save_as_txt(content=final_text, filepath=out_path)
+        logger.info("%s Novel saved to: %s", TAG, out_path)
+    except Exception as e:
+        logger.error("%s Failed to save file: %s", TAG, e)
+    return

novel_downloader/core/savers/common_saver/main_saver.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+novel_downloader.core.savers.common_saver.main_saver
+----------------------------------------------------
+
+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.
+"""
+
+from novel_downloader.config.models import SaverConfig
+
+from ..base_saver import BaseSaver
+from .common_txt import common_save_as_txt
+
+
+class CommonSaver(BaseSaver):
+    """
+    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.
+    """
+
+    def __init__(self, config: SaverConfig, site: str):
+        """
+        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
+
+    def save_as_txt(self, book_id: str) -> None:
+        """
+        Compile and save a complete novel as a single .txt file.
+
+        Processing steps:
+            1. Load book metadata from `book_info.json`, including title,
+               author, summary, and chapter structure.
+            2. Iterate through all volumes and chapters, appending each
+               volume/chapter title and content.
+            3. Combine metadata and content into a final formatted text.
+            4. Save the final result to the output directory using the
+               configured filename template.
+
+        :param book_id: The book identifier (used to locate raw data)
+        """
+        return common_save_as_txt(self, book_id)
+
+    def save_as_epub(self, book_id: str) -> None:
+        """
+        Persist the assembled book as a EPUB (.epub) file.
+
+        :param book_id: The book identifier.
+        :raises NotImplementedError: If the method is not overridden.
+        """
+        try:
+            from .common_epub import common_save_as_epub
+        except ImportError:
+            raise NotImplementedError(
+                "EPUB export not supported. Please install 'ebooklib'"
+            )
+
+        return common_save_as_epub(self, book_id)
+
+    @property
+    def site(self) -> str:
+        """
+        Get the site identifier.
+
+        :return: The site string.
+        """
+        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

novel_downloader/core/savers/epub_utils/__init__.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+novel_downloader.core.savers.epub_utils
+---------------------------------------
+
+This package provides utility functions for constructing EPUB files,
+including:
+
+- CSS inclusion (create_css_items)
+- EPUB book initialization (init_epub)
+- Chapter text-to-HTML conversion (chapter_txt_to_html)
+- Volume intro HTML generation (create_volume_intro)
+"""
+
+from .css_builder import create_css_items
+from .initializer import init_epub
+from .text_to_html import chapter_txt_to_html, generate_book_intro_html
+from .volume_intro import create_volume_intro
+
+__all__ = [
+    "create_css_items",
+    "init_epub",
+    "chapter_txt_to_html",
+    "create_volume_intro",
+    "generate_book_intro_html",
+]