novel-downloader 1.1.1__py3-none-any.whl → 1.2.0__py3-none-any.whl

novel_downloader/core/factory/downloader_factory.py

@@ -7,19 +7,24 @@ novel_downloader.core.factory.downloader_factory
 This module implements a factory function for creating downloader instances
 based on the site name and parser mode specified in the configuration.
 
-Currently supported:
-- Site: 'qidian'
-    - QidianDownloader
+- get_async_downloader -> always returns a CommonAsyncDownloader
+- get_sync_downloader  -> returns a site-specific downloader or CommonDownloader
+- get_downloader       -> 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 Union
+
 from novel_downloader.config import DownloaderConfig, load_site_rules
 from novel_downloader.core.downloaders import (
+    CommonAsyncDownloader,
     CommonDownloader,
     QidianDownloader,
 )
 from novel_downloader.core.interfaces import (
+    AsyncDownloaderProtocol,
+    AsyncRequesterProtocol,
     DownloaderProtocol,
     ParserProtocol,
     RequesterProtocol,
@@ -32,7 +37,42 @@ _site_map = {
 }
 
 
-def get_downloader(
+def get_async_downloader(
+    requester: AsyncRequesterProtocol,
+    parser: ParserProtocol,
+    saver: SaverProtocol,
+    site: str,
+    config: DownloaderConfig,
+) -> AsyncDownloaderProtocol:
+    """
+    Returns an AsyncDownloaderProtocol for the given site.
+
+    :param requester: Requester implementation
+    :param parser: Parser implementation
+    :param saver: Saver implementation
+    :param site: Site name (e.g., 'qidian')
+    :param config: Downloader configuration
+
+    :return: An instance of a downloader class
+
+    :raises ValueError: If a site-specific downloader does not support async mode.
+    :raises TypeError: If the provided requester does not match the required protocol
+                    for the chosen mode (sync vs async).
+    """
+    site_key = site.lower()
+
+    if not isinstance(requester, AsyncRequesterProtocol):
+        raise TypeError("Async mode requires an AsyncRequesterProtocol")
+
+    site_rules = load_site_rules()
+    site_rule = site_rules.get(site_key)
+    if site_rule is None:
+        raise ValueError(f"Unsupported site: {site}")
+
+    return CommonAsyncDownloader(requester, parser, saver, config, site_key)
+
+
+def get_sync_downloader(
     requester: RequesterProtocol,
     parser: ParserProtocol,
     saver: SaverProtocol,
@@ -40,23 +80,70 @@ def get_downloader(
     config: DownloaderConfig,
 ) -> DownloaderProtocol:
     """
-    Returns a site-specific downloader instance.
+    Returns a DownloaderProtocol for the given site.
+    First tries a site-specific downloader (e.g. QidianDownloader),
+    otherwise falls back to CommonDownloader.
 
     :param requester: Requester implementation
     :param parser: Parser implementation
     :param saver: Saver implementation
     :param site: Site name (e.g., 'qidian')
     :param config: Downloader configuration
+
     :return: An instance of a downloader class
+
+    :raises ValueError: If a site-specific downloader does not support async mode.
+    :raises TypeError: If the provided requester does not match the required protocol
+                    for the chosen mode (sync vs async).
     """
     site_key = site.lower()
 
+    if not isinstance(requester, RequesterProtocol):
+        raise TypeError("Sync mode requires a RequesterProtocol")
+
+    # site-specific
     if site_key in _site_map:
-        downloader_class = _site_map[site_key]
-        return downloader_class(requester, parser, saver, config)
+        return _site_map[site_key](requester, parser, saver, config)
 
+    # fallback
     site_rules = load_site_rules()
-    if site_key not in site_rules:
+    site_rule = site_rules.get(site_key)
+    if site_rule is None:
         raise ValueError(f"Unsupported site: {site}")
 
     return CommonDownloader(requester, parser, saver, config, site_key)
+
+
+def get_downloader(
+    requester: Union[AsyncRequesterProtocol, RequesterProtocol],
+    parser: ParserProtocol,
+    saver: SaverProtocol,
+    site: str,
+    config: DownloaderConfig,
+) -> Union[AsyncDownloaderProtocol, DownloaderProtocol]:
+    """
+    Dispatches to get_async_downloader if config.mode == 'async',
+    otherwise to get_sync_downloader.
+
+    :param requester: Requester implementation
+    :param parser: Parser implementation
+    :param saver: Saver implementation
+    :param site: Site name (e.g., 'qidian')
+    :param config: Downloader configuration
+
+    :return: An instance of a downloader class
+
+    :raises ValueError: If a site-specific downloader does not support async mode.
+    :raises TypeError: If the provided requester does not match the required protocol
+                    for the chosen mode (sync vs async).
+    """
+    mode = config.mode.lower()
+    if mode == "async":
+        if not isinstance(requester, AsyncRequesterProtocol):
+            raise TypeError("Async mode requires an AsyncRequesterProtocol")
+        return get_async_downloader(requester, parser, saver, site, config)
+    if mode in ("browser", "session"):
+        if not isinstance(requester, RequesterProtocol):
+            raise TypeError("Sync mode requires a RequesterProtocol")
+        return get_sync_downloader(requester, parser, saver, site, config)
+    raise ValueError(f"Unknown mode '{config.mode}' for site '{site}'")

novel_downloader/core/factory/requester_factory.py

@@ -7,56 +7,100 @@ novel_downloader.core.factory.requester_factory
 This module implements a factory function for retrieving requester instances
 based on the target novel platform (site).
 
-Currently supported:
-- Site: 'qidian'
-    - Modes:
-        - 'browser': QidianBrowser
-        - 'session': (Not implemented yet)
+- 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 RequesterProtocol
+from novel_downloader.core.interfaces import AsyncRequesterProtocol, RequesterProtocol
 from novel_downloader.core.requesters import (
+    CommonAsyncSession,
     CommonSession,
     QidianBrowser,
     QidianSession,
 )
 
-_site_map = {
+_site_map: dict[
+    str,
+    dict[str, Callable[[RequesterConfig], RequesterProtocol]],
+] = {
     "qidian": {
-        "browser": QidianBrowser,
         "session": QidianSession,
+        "browser": QidianBrowser,
     },
-    # "biquge": ...
 }
 
 
-def get_requester(site: str, config: RequesterConfig) -> RequesterProtocol:
+def get_async_requester(
+    site: str,
+    config: RequesterConfig,
+) -> AsyncRequesterProtocol:
     """
-    Returns a site-specific requester instance.
+    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:
-        requester_class = (
-            site_entry.get(config.mode) if isinstance(site_entry, dict) else site_entry
-        )
-        if requester_class:
-            return requester_class(config)
-        raise ValueError(f"Unsupported mode '{config.mode}' for site '{site}'")
-
-    # Fallback: Load site rules
+        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)
+
 
-    site_profile = site_rule["profile"]
-    return CommonSession(config, site_key, site_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/interfaces/__init__.py

@@ -15,12 +15,16 @@ Included protocols:
 - 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",

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/requesters/__init__.py

@@ -14,13 +14,17 @@ Subpackages:
 - qidian_requester: Handles all Qidian-related requesting logic.
 """
 
-from .common_requester import CommonSession
+from .common_requester import (
+    CommonAsyncSession,
+    CommonSession,
+)
 from .qidian_requester import (
     QidianBrowser,
     QidianSession,
 )
 
 __all__ = [
+    "CommonAsyncSession",
     "CommonSession",
     "QidianBrowser",
     "QidianSession",