novel-downloader 1.1.0__py3-none-any.whl

novel_downloader/core/factory/requester_factory.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+novel_downloader.core.factory.requester_factory
+-----------------------------------------------
+
+This module implements a factory function for retrieving requester instances
+based on the target novel platform (site).
+
+- get_async_requester -> returns AsyncRequesterProtocol
+- get_sync_requester  -> returns RequesterProtocol
+- get_requester       -> dispatches to one of the above based on config.mode
+
+To add support for new sites or modes, extend the `_site_map` accordingly.
+"""
+
+from typing import Callable, Union
+
+from novel_downloader.config import RequesterConfig, load_site_rules
+from novel_downloader.core.interfaces import AsyncRequesterProtocol, RequesterProtocol
+from novel_downloader.core.requesters import (
+    CommonAsyncSession,
+    CommonSession,
+    QidianBrowser,
+    QidianSession,
+)
+
+_site_map: dict[
+    str,
+    dict[str, Callable[[RequesterConfig], RequesterProtocol]],
+] = {
+    "qidian": {
+        "session": QidianSession,
+        "browser": QidianBrowser,
+    },
+}
+
+
+def get_async_requester(
+    site: str,
+    config: RequesterConfig,
+) -> AsyncRequesterProtocol:
+    """
+    Returns an AsyncRequesterProtocol for the given site.
+
+    :param site: Site name (e.g., 'qidian')
+    :param config: Configuration for the requester
+    :return: An instance of a requester class
+    """
+    site_key = site.lower()
+    site_rules = load_site_rules()
+    site_rule = site_rules.get(site_key)
+    if site_rule is None:
+        raise ValueError(f"Unsupported site: {site}")
+    profile = site_rule["profile"]
+    return CommonAsyncSession(config, site_key, profile)
+
+
+def get_sync_requester(
+    site: str,
+    config: RequesterConfig,
+) -> RequesterProtocol:
+    """
+    Returns a RequesterProtocol for the given site.
+
+    :param site: Site name (e.g., 'qidian')
+    :param config: Configuration for the requester
+    :return: An instance of a requester class
+    """
+    site_key = site.lower()
+    site_entry = _site_map.get(site_key)
+
+    # site-specific implementation for this mode
+    if site_entry:
+        cls = site_entry.get(config.mode)
+        if cls:
+            return cls(config)
+
+    # fallback to CommonSession
+    site_rules = load_site_rules()
+    site_rule = site_rules.get(site_key)
+    if site_rule is None:
+        raise ValueError(f"Unsupported site: {site}")
+    profile = site_rule["profile"]
+    return CommonSession(config, site_key, profile)
+
+
+def get_requester(
+    site: str,
+    config: RequesterConfig,
+) -> Union[AsyncRequesterProtocol, RequesterProtocol]:
+    """
+    Dispatches to either get_async_requester or get_sync_requester
+    based on config.mode. Treats 'browser' and 'async' as async modes,
+    'session' as sync; anything else is an error.
+
+    :param site: Site name (e.g., 'qidian')
+    :param config: Configuration for the requester
+    :return: An instance of a requester class
+    """
+    mode = config.mode.lower()
+    if mode == "async":
+        return get_async_requester(site, config)
+    if mode in ("browser", "session"):
+        return get_sync_requester(site, config)
+    raise ValueError(f"Unknown mode '{config.mode}' for site '{site}'")

novel_downloader/core/factory/saver_factory.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+novel_downloader.core.factory.parser_factory
+--------------------------------------------
+
+This module implements a factory function for creating saver instances
+based on the site name and parser mode specified in the configuration.
+
+Currently supported:
+- Site: 'qidian'
+    - QidianSaver
+
+To add support for new sites or modes, extend the `_site_map` accordingly.
+"""
+
+from novel_downloader.config import SaverConfig, load_site_rules
+from novel_downloader.core.interfaces import SaverProtocol
+from novel_downloader.core.savers import (
+    CommonSaver,
+    QidianSaver,
+)
+
+_site_map = {
+    "qidian": QidianSaver,
+    # "biquge": ...
+}
+
+
+def get_saver(site: str, config: SaverConfig) -> SaverProtocol:
+    """
+    Returns a site-specific saver instance.
+
+    :param site: Site name (e.g., 'qidian')
+    :param config: Configuration for the saver
+    :return: An instance of a saver class
+    """
+    site_key = site.lower()
+
+    saver_class = _site_map.get(site_key)
+    if saver_class:
+        return saver_class(config)
+
+    # Fallback: check site_rules
+    site_rules = load_site_rules()
+    if site_key not in site_rules:
+        raise ValueError(f"Unsupported site: {site}")
+
+    return CommonSaver(config, site_key)

novel_downloader/core/interfaces/__init__.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+novel_downloader.core.interfaces
+--------------------------------
+
+This package centralizes the protocol definitions used across the
+system to promote interface-based design and type-safe dependency
+injection.
+
+Included protocols:
+- DownloaderProtocol
+- ParserProtocol
+- RequesterProtocol
+- SaverProtocol
+"""
+
+from .async_downloader_protocol import AsyncDownloaderProtocol
+from .async_requester_protocol import AsyncRequesterProtocol
+from .downloader_protocol import DownloaderProtocol
+from .parser_protocol import ParserProtocol
+from .requester_protocol import RequesterProtocol
+from .saver_protocol import SaverProtocol
+
+__all__ = [
+    "AsyncDownloaderProtocol",
+    "AsyncRequesterProtocol",
+    "DownloaderProtocol",
+    "ParserProtocol",
+    "RequesterProtocol",
+    "SaverProtocol",
+]

novel_downloader/core/interfaces/async_downloader_protocol.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+novel_downloader.core.interfaces.async_downloader_protocol
+----------------------------------------------------------
+
+This module defines the AsyncDownloaderProtocol, a structural interface
+that outlines the expected behavior of any downloader class.
+"""
+
+from typing import List, Protocol
+
+
+class AsyncDownloaderProtocol(Protocol):
+    """
+    Protocol for fully‐asynchronous downloader classes.
+
+    Defines the expected interface for any downloader implementation,
+    including both batch and single book downloads,
+    as well as optional pre-download hooks.
+    """
+
+    async def download(self, book_ids: List[str]) -> None:
+        """
+        Batch download entry point.
+
+        :param book_ids: List of book IDs to download.
+        """
+        ...
+
+    async def download_one(self, book_id: str) -> None:
+        """
+        Download logic for a single book.
+
+        :param book_id: The identifier of the book.
+        """
+        ...

novel_downloader/core/interfaces/async_requester_protocol.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+novel_downloader.core.interfaces.async_requester_protocol
+--------------------------------------------------------
+
+Defines the AsyncRequesterProtocol interface for fetching raw HTML or JSON
+for book info pages, individual chapters, managing request lifecycle,
+and optionally retrieving a user's authenticated bookcase — all in async style.
+"""
+
+from typing import Optional, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class AsyncRequesterProtocol(Protocol):
+    """
+    An async requester must be able to fetch raw HTML/data for:
+      - a book's info page,
+      - a specific chapter page,
+    and manage login/shutdown asynchronously.
+    """
+
+    async def login(self, max_retries: int = 3, manual_login: bool = False) -> bool:
+        """
+        Attempt to log in asynchronously.
+        :returns: True if login succeeded.
+        """
+        ...
+
+    async def get_book_info(self, book_id: str, wait_time: Optional[int] = None) -> str:
+        """
+        Fetch the raw HTML (or JSON) of the book info page asynchronously.
+
+        :param book_id: The book identifier.
+        :param wait_time: Base number of seconds to wait before returning content.
+        :return: The page content as a string.
+        """
+        ...
+
+    async def get_book_chapter(
+        self, book_id: str, chapter_id: str, wait_time: Optional[int] = None
+    ) -> str:
+        """
+        Fetch the raw HTML (or JSON) of a single chapter asynchronously.
+
+        :param book_id: The book identifier.
+        :param chapter_id: The chapter identifier.
+        :param wait_time: Base number of seconds to wait before returning content.
+        :return: The chapter content as a string.
+        """
+        ...
+
+    async def get_bookcase(self, wait_time: Optional[int] = None) -> str:
+        """
+        Optional: Retrieve the HTML content of the authenticated
+        user's bookcase page asynchronously.
+
+        :param wait_time: Base number of seconds to wait before returning content.
+        :return: The HTML markup of the bookcase page.
+        """
+        ...
+
+    async def shutdown(self) -> None:
+        """
+        Shutdown and clean up any resources (e.g., close aiohttp session).
+        """
+        ...

novel_downloader/core/interfaces/downloader_protocol.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+novel_downloader.core.interfaces.downloader_protocol
+----------------------------------------------------
+
+This module defines the DownloaderProtocol, a structural interface
+that outlines the expected behavior of any downloader class.
+"""
+
+from typing import List, Protocol
+
+
+class DownloaderProtocol(Protocol):
+    """
+    Protocol for downloader classes.
+
+    Defines the expected interface for any downloader implementation,
+    including both batch and single book downloads,
+    as well as optional pre-download hooks.
+    """
+
+    def download(self, book_ids: List[str]) -> None:
+        """
+        Batch download entry point.
+
+        :param book_ids: List of book IDs to download.
+        """
+        ...
+
+    def download_one(self, book_id: str) -> None:
+        """
+        Download logic for a single book.
+
+        :param book_id: The identifier of the book.
+        """
+        ...

novel_downloader/core/interfaces/parser_protocol.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+novel_downloader.core.interfaces.parser_protocol
+------------------------------------------------
+
+Defines the ParserProtocol interface for extracting book metadata,
+parsing individual chapter content, and setting parser context via book_id.
+"""
+
+from typing import Any, Dict, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ParserProtocol(Protocol):
+    """
+    A parser must be able to:
+      - extract book metadata from an HTML string,
+      - extract a single chapter's text from an HTML string,
+      - accept a book_id context for multi-step workflows.
+    """
+
+    def parse_book_info(self, html_str: str) -> Dict[str, Any]:
+        """
+        Parse and return a dictionary of book information from the raw HTML.
+
+        :param html_str: The HTML of a book's info page.
+        :return: A dict containing metadata like title, author, chapters list, etc.
+        """
+        ...
+
+    def parse_chapter(self, html_str: str, chapter_id: str) -> Dict[str, Any]:
+        """
+        Parse and return the text content of one chapter.
+
+        :param html_str: The HTML of the chapter page.
+        :param chapter_id: Identifier of the chapter being parsed.
+        :return: The chapter's text.
+        """
+        ...

novel_downloader/core/interfaces/requester_protocol.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+novel_downloader.core.interfaces.requester_protocol
+--------------------------------------------------
+
+Defines the RequesterProtocol interface for fetching raw HTML or JSON
+for book info pages, individual chapters, managing request lifecycle,
+and optionally retrieving a user's authenticated bookcase.
+"""
+
+from typing import Optional, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class RequesterProtocol(Protocol):
+    """
+    A requester must be able to fetch raw HTML/data for:
+      - a book's info page,
+      - a specific chapter page.
+    """
+
+    def login(self, max_retries: int = 3, manual_login: bool = False) -> bool:
+        """
+        Attempt to log in
+        """
+        ...
+
+    def get_book_info(self, book_id: str, wait_time: Optional[int] = None) -> str:
+        """
+        Fetch the raw HTML (or JSON) of the book info page.
+
+        :param book_id: The book identifier.
+        :param wait_time: Base number of seconds to wait before returning content.
+        :return: The page content as a string.
+        """
+        ...
+
+    def get_book_chapter(
+        self, book_id: str, chapter_id: str, wait_time: Optional[int] = None
+    ) -> str:
+        """
+        Fetch the raw HTML (or JSON) of a single chapter.
+
+        :param book_id: The book identifier.
+        :param chapter_id: The chapter identifier.
+        :param wait_time: Base number of seconds to wait before returning content.
+        :return: The chapter content as a string.
+        """
+        ...
+
+    def shutdown(self) -> None:
+        """
+        Shutdown and cleans up resources.
+        """
+        ...
+
+    def get_bookcase(self, wait_time: Optional[int] = None) -> str:
+        """
+        Optional: Retrieve the HTML content of the authenticated user's bookcase page.
+
+        :param wait_time: Base number of seconds to wait before returning content.
+        :return: The HTML markup of the bookcase page.
+        """
+        ...

novel_downloader/core/interfaces/saver_protocol.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+novel_downloader.core.interfaces.saver_protocol
+------------------------------------------------
+
+Defines the SaverProtocol interface for persisting completed books in
+TXT, EPUB, Markdown, and PDF formats.
+"""
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class SaverProtocol(Protocol):
+    """
+    A saver must implement a method to persist a completed book as plain text.
+
+    It may also optionally implement an EPUB (or other format) saver.
+    """
+
+    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.)
+        """
+        ...
+
+    def save_as_txt(self, book_id: str) -> None:
+        """
+        Persist the assembled book as a .txt file.
+
+        :param book_id: The book identifier (used for filename or lookup).
+        """
+        ...
+
+    def save_as_epub(self, book_id: str) -> None:
+        """
+        Optional: Persist the assembled book as an .epub file.
+
+        :param book_id: The book identifier.
+        """
+        ...
+
+    def save_as_md(self, book_id: str) -> None:
+        """
+        Optional: Persist the assembled book as a Markdown (.md) file.
+
+        :param book_id: The book identifier.
+        """
+        ...
+
+    def save_as_pdf(self, book_id: str) -> None:
+        """
+        Optional: Persist the assembled book as a PDF file.
+
+        :param book_id: The book identifier.
+        """
+        ...

novel_downloader/core/parsers/__init__.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+novel_downloader.core.parsers
+-----------------------------
+
+This package defines all site-specific parsing modules
+for the novel_downloader framework.
+
+Currently supported:
+- Qidian (起点中文网) via browser-rendered page parsing.
+
+Modules:
+- qidian_parser
+- common_parser
+"""
+
+from .common_parser import CommonParser
+from .qidian_parser import (
+    QidianBrowserParser,
+    QidianSessionParser,
+)
+
+__all__ = [
+    "CommonParser",
+    "QidianBrowserParser",
+    "QidianSessionParser",
+]

novel_downloader/core/parsers/base_parser.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+novel_downloader.core.parsers.base_parser
+-----------------------------------------
+
+This module defines the BaseParser abstract class, which implements the
+ParserProtocol interface and provides a structured foundation for
+site-specific parsers.
+
+BaseParser manages internal parser state and enforces
+a standard parsing interface for:
+- Book info pages (e.g. metadata, chapter list)
+- Chapter pages (e.g. textual content)
+"""
+
+import abc
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from novel_downloader.config import ParserConfig
+from novel_downloader.core.interfaces import ParserProtocol
+
+
+class BaseParser(ParserProtocol, abc.ABC):
+    """
+    BaseParser defines the interface for extracting book metadata and chapter content
+    from raw HTML.
+
+    This base class manages internal book state (e.g. current book ID) and supports
+    configuration-driven behavior such as content cleaning or formatting.
+
+    Subclasses must implement actual parsing logic for specific sites.
+    """
+
+    def __init__(self, config: ParserConfig):
+        """
+        Initialize the parser with a configuration object.
+
+        :param config: ParserConfig object controlling parsing behavior.
+        """
+        self._config = config
+        self._book_id: Optional[str] = None
+
+        self._base_cache_dir = Path(config.cache_dir)
+
+    @abc.abstractmethod
+    def parse_book_info(self, html: str) -> Dict[str, Any]:
+        """
+        Parse a book info page and extract metadata and chapter structure.
+
+        Depending on the site structure, the return dict may include a
+        flat `chapters` list or nested `volumes` with chapter groups.
+
+        :param html: Raw HTML of the book info page.
+        :return: Parsed metadata and chapter structure as a dictionary.
+        """
+        ...
+
+    @abc.abstractmethod
+    def parse_chapter(self, html_str: str, chapter_id: str) -> Dict[str, Any]:
+        """
+        Parse a single chapter page and extract clean text or simplified HTML.
+
+        :param html: Raw HTML of the chapter page.
+        :param chapter_id: Identifier of the chapter being parsed.
+        :return: Cleaned chapter content as plain text or minimal HTML.
+        """
+        ...
+
+    @property
+    def book_id(self) -> Optional[str]:
+        """
+        Current book ID in context.
+
+        :return: The current book identifier.
+        """
+        return self._book_id
+
+    @book_id.setter
+    def book_id(self, value: str) -> None:
+        """
+        Set current book ID and update debug paths if needed.
+
+        :param value: Book identifier.
+        """
+        self._book_id = value
+        self._on_book_id_set()
+
+    def _on_book_id_set(self) -> None:
+        """
+        Hook called when a new book ID is set.
+        Subclasses can override this to initialize
+        book-related folders or states.
+        """
+        pass

novel_downloader/core/parsers/common_parser/__init__.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+novel_downloader.core.parsers.common_parser
+-------------------------------------------
+
+This module provides a CommonParser class that implements
+general-purpose parsing logic for extracting novel metadata
+and chapter content based on site-specific rules.
+"""
+
+from .main_parser import CommonParser
+
+__all__ = ["CommonParser"]