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

novel_downloader/core/interfaces/downloader.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""
+novel_downloader.core.interfaces.downloader
+-------------------------------------------
+
+This module defines the DownloaderProtocol, a structural interface
+that outlines the expected behavior of any downloader class.
+"""
+
+from collections.abc import Awaitable, Callable
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class DownloaderProtocol(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_id: str,
+        *,
+        progress_hook: Callable[[int, int], Awaitable[None]] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Download logic for a single book.
+
+        :param book_id: The identifier of the book.
+        :param progress_hook: (optional) Called after each chapter;
+                                args: completed_count, total_count.
+        """
+        ...
+
+    async def download_many(
+        self,
+        book_ids: list[str],
+        *,
+        progress_hook: Callable[[int, int], Awaitable[None]] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Batch download entry point.
+
+        :param book_ids: List of book IDs to download.
+        :param progress_hook: (optional) Called after each chapter;
+                                args: completed_count, total_count.
+        """
+        ...

novel_downloader/core/interfaces/{saver.py → exporter.py}

@@ -1,9 +1,9 @@
 #!/usr/bin/env python3
 """
-novel_downloader.core.interfaces.saver
---------------------------------------
+novel_downloader.core.interfaces.exporter
+-----------------------------------------
 
-Defines the SaverProtocol interface for persisting completed books in
+Defines the ExporterProtocol interface for persisting completed books in
 TXT, EPUB, Markdown, and PDF formats.
 """
 
@@ -11,23 +11,23 @@ from typing import Protocol, runtime_checkable
 
 
 @runtime_checkable
-class SaverProtocol(Protocol):
+class ExporterProtocol(Protocol):
     """
-    A saver must implement a method to persist a completed book as plain text.
+    A exporter must implement a method to persist a completed book as plain text.
 
-    It may also optionally implement an EPUB (or other format) saver.
+    It may also optionally implement an EPUB (or other format) exporter.
     """
 
-    def save(self, book_id: str) -> None:
+    def export(self, book_id: str) -> None:
         """
-        Save the book in the formats specified in config.
+        Export 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:
+    def export_as_txt(self, book_id: str) -> None:
         """
         Persist the assembled book as a .txt file.
 
@@ -35,7 +35,7 @@ class SaverProtocol(Protocol):
         """
         ...
 
-    def save_as_epub(self, book_id: str) -> None:
+    def export_as_epub(self, book_id: str) -> None:
         """
         Optional: Persist the assembled book as an .epub file.
 
@@ -43,7 +43,7 @@ class SaverProtocol(Protocol):
         """
         ...
 
-    def save_as_md(self, book_id: str) -> None:
+    def export_as_md(self, book_id: str) -> None:
         """
         Optional: Persist the assembled book as a Markdown (.md) file.
 
@@ -51,7 +51,7 @@ class SaverProtocol(Protocol):
         """
         ...
 
-    def save_as_pdf(self, book_id: str) -> None:
+    def export_as_pdf(self, book_id: str) -> None:
         """
         Optional: Persist the assembled book as a PDF file.
 

novel_downloader/core/interfaces/fetcher.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""
+novel_downloader.core.interfaces.fetcher
+----------------------------------------
+
+Defines the Async FetcherProtocol interface for fetching raw HTML or JSON
+for book info pages, individual chapters, managing request lifecycle
+"""
+
+import types
+from typing import Any, Protocol, Self, runtime_checkable
+
+from novel_downloader.models import LoginField
+
+
+@runtime_checkable
+class FetcherProtocol(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,
+        username: str = "",
+        password: str = "",
+        cookies: dict[str, str] | None = None,
+        attempt: int = 1,
+        **kwargs: Any,
+    ) -> bool:
+        """
+        Attempt to log in asynchronously.
+        :returns: True if login succeeded.
+        """
+        ...
+
+    async def get_book_info(
+        self,
+        book_id: str,
+        **kwargs: Any,
+    ) -> list[str]:
+        """
+        Fetch the raw HTML (or JSON) of the book info page asynchronously.
+
+        :param book_id: The book identifier.
+        :return: The page content as a string.
+        """
+        ...
+
+    async def get_book_chapter(
+        self,
+        book_id: str,
+        chapter_id: str,
+        **kwargs: Any,
+    ) -> list[str]:
+        """
+        Fetch the raw HTML (or JSON) of a single chapter asynchronously.
+
+        :param book_id: The book identifier.
+        :param chapter_id: The chapter identifier.
+        :return: The chapter content as string.
+        """
+        ...
+
+    async def get_bookcase(
+        self,
+        **kwargs: Any,
+    ) -> list[str]:
+        """
+        Optional: Retrieve the HTML content of the authenticated
+        user's bookcase page asynchronously.
+
+        :return: The HTML markup of the bookcase page.
+        """
+        ...
+
+    async def fetch(
+        self,
+        url: str,
+        **kwargs: Any,
+    ) -> str:
+        """
+        Perform a generic HTTP request and return the response body as text.
+
+        :param url: The URL to request.
+        :return: The response content as a string (HTML or JSON or plain text).
+        """
+        ...
+
+    async def init(
+        self,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Perform async initialization, such as
+        launching a browser or creating a session.
+
+        This should be called before using any other method
+        if initialization is required.
+        """
+        ...
+
+    async def close(self) -> None:
+        """
+        Shutdown and clean up any resources.
+        """
+        ...
+
+    async def load_state(self) -> bool:
+        """
+        Restore session state from a persistent storage,
+        allowing the requester to resume a previous authenticated session.
+
+        :return: True if the session state was successfully loaded and applied.
+        """
+        ...
+
+    async def save_state(self) -> bool:
+        """
+        Persist the current session state to a file
+        or other storage, so that it can be restored in future sessions.
+
+        :return: True if the session state was successfully saved.
+        """
+        ...
+
+    async def set_interactive_mode(self, enable: bool) -> bool:
+        """
+        Enable or disable interactive mode for manual login.
+
+        :param enable: True to enable, False to disable interactive mode.
+        :return: True if operation or login check succeeded, False otherwise.
+        """
+        ...
+
+    @property
+    def requester_type(self) -> str:
+        ...
+
+    @property
+    def is_logged_in(self) -> bool:
+        """
+        Indicates whether the requester is currently authenticated.
+        """
+        ...
+
+    @property
+    def login_fields(self) -> list[LoginField]:
+        ...
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        tb: types.TracebackType | None,
+    ) -> None:
+        ...
+
+    async def __aenter__(self) -> Self:
+        ...

novel_downloader/core/interfaces/parser.py

@@ -9,7 +9,7 @@ parsing individual chapter content, and setting parser context via book_id.
 
 from typing import Any, Protocol, runtime_checkable
 
-from novel_downloader.utils.chapter_storage import ChapterDict
+from novel_downloader.models import ChapterDict
 
 
 @runtime_checkable
@@ -17,33 +17,32 @@ 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.
+      - extract a single chapter's text from an HTML string
     """
 
     def parse_book_info(
         self,
-        html_str: list[str],
+        html_list: list[str],
         **kwargs: Any,
     ) -> 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.
+        :param html_list: The HTML list of a book's info pages.
         :return: A dict containing metadata like title, author, chapters list, etc.
         """
         ...
 
     def parse_chapter(
         self,
-        html_str: list[str],
+        html_list: list[str],
         chapter_id: str,
         **kwargs: Any,
     ) -> ChapterDict | None:
         """
         Parse and return the text content of one chapter.
 
-        :param html_str: The HTML of the chapter page.
+        :param html_list: The HTML list of the chapter pages.
         :param chapter_id: Identifier of the chapter being parsed.
         :return: The chapter's text.
         """

novel_downloader/core/parsers/__init__.py

@@ -9,6 +9,7 @@ for the novel_downloader framework.
 Modules:
 - biquge (笔趣阁)
 - esjzone (ESJ Zone)
+- linovelib (哔哩轻小说)
 - qianbi (铅笔小说)
 - qidian (起点中文网)
 - sfacg (SF轻小说)
@@ -19,11 +20,9 @@ Modules:
 from .biquge import BiqugeParser
 from .common import CommonParser
 from .esjzone import EsjzoneParser
+from .linovelib import LinovelibParser
 from .qianbi import QianbiParser
-from .qidian import (
-    QidianBrowserParser,
-    QidianSessionParser,
-)
+from .qidian import QidianParser
 from .sfacg import SfacgParser
 from .yamibo import YamiboParser
 
@@ -31,9 +30,9 @@ __all__ = [
     "BiqugeParser",
     "CommonParser",
     "EsjzoneParser",
+    "LinovelibParser",
     "QianbiParser",
-    "QidianBrowserParser",
-    "QidianSessionParser",
+    "QidianParser",
     "SfacgParser",
     "YamiboParser",
 ]

novel_downloader/core/parsers/base.py

@@ -17,9 +17,8 @@ import abc
 from pathlib import Path
 from typing import Any
 
-from novel_downloader.config import ParserConfig
 from novel_downloader.core.interfaces import ParserProtocol
-from novel_downloader.utils.chapter_storage import ChapterDict
+from novel_downloader.models import ChapterDict, ParserConfig
 
 
 class BaseParser(ParserProtocol, abc.ABC):
@@ -51,33 +50,30 @@ class BaseParser(ParserProtocol, abc.ABC):
     @abc.abstractmethod
     def parse_book_info(
         self,
-        html_str: list[str],
+        html_list: list[str],
         **kwargs: Any,
     ) -> dict[str, Any]:
         """
-        Parse a book info page and extract metadata and chapter structure.
+        Parse and return a dictionary of book information from the raw HTML.
 
-        Depending on the site structure, the return dict may include a
-        flat `chapters` list or nested `volumes` with chapter groups.
-
-        :param html_str: Raw HTML of the book info page.
-        :return: Parsed metadata and chapter structure as a dictionary.
+        :param html_list: The HTML list of a book's info pages.
+        :return: A dict containing metadata like title, author, chapters list, etc.
         """
         ...
 
     @abc.abstractmethod
     def parse_chapter(
         self,
-        html_str: list[str],
+        html_list: list[str],
         chapter_id: str,
         **kwargs: Any,
     ) -> ChapterDict | None:
         """
-        Parse a single chapter page and extract clean text or simplified HTML.
+        Parse and return the text content of one chapter.
 
-        :param html_str: Raw HTML of the chapter page.
+        :param html_list: The HTML list of the chapter pages.
         :param chapter_id: Identifier of the chapter being parsed.
-        :return: Cleaned chapter content as plain text or minimal HTML.
+        :return: The chapter's text.
         """
         ...
 

novel_downloader/core/parsers/biquge/main_parser.py

@@ -8,11 +8,10 @@ novel_downloader.core.parsers.biquge.main_parser
 import re
 from typing import Any
 
-from lxml import etree
-from lxml.etree import _Element
+from lxml import html
 
 from novel_downloader.core.parsers.base import BaseParser
-from novel_downloader.utils.chapter_storage import ChapterDict
+from novel_downloader.models import ChapterDict
 
 
 class BiqugeParser(BaseParser):
@@ -20,21 +19,21 @@ class BiqugeParser(BaseParser):
 
     def parse_book_info(
         self,
-        html_str: list[str],
+        html_list: list[str],
         **kwargs: Any,
     ) -> dict[str, Any]:
         """
         Parse a book info page and extract metadata and chapter structure.
 
-        :param html: Raw HTML of the book info page.
+        :param html_list: Raw HTML of the book info page.
         :return: Parsed metadata and chapter structure as a dictionary.
         """
-        if not html_str:
+        if not html_list:
             return {}
-        tree = etree.HTML(html_str[0])
+        tree = html.fromstring(html_list[0])
         result: dict[str, Any] = {}
 
-        def extract_text(elem: _Element | None) -> str:
+        def extract_text(elem: html.HtmlElement | None) -> str:
             if elem is None:
                 return ""
             return "".join(elem.itertext(tag=None)).strip()
@@ -79,7 +78,7 @@ class BiqugeParser(BaseParser):
                 text = "".join(elem.itertext()).strip()
                 in_main_volume = "正文" in text
             elif in_main_volume and elem.tag == "dd":
-                a: list[_Element] = elem.xpath("./a")
+                a: list[html.HtmlElement] = elem.xpath("./a")
                 if a:
                     title = "".join(a[0].itertext(tag=None)).strip()
                     url = a[0].get("href", "").strip()
@@ -96,20 +95,20 @@ class BiqugeParser(BaseParser):
 
     def parse_chapter(
         self,
-        html_str: list[str],
+        html_list: list[str],
         chapter_id: str,
         **kwargs: Any,
     ) -> ChapterDict | None:
         """
         Parse a single chapter page and extract clean text or simplified HTML.
 
-        :param html: Raw HTML of the chapter page.
+        :param html_list: 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.
         """
-        if not html_str:
+        if not html_list:
             return None
-        tree = etree.HTML(html_str[0], parser=None)
+        tree = html.fromstring(html_list[0], parser=None)
 
         # 提取标题
         title_elem = tree.xpath('//div[@class="bookname"]/h1')

novel_downloader/core/parsers/common/helper.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """
-novel_downloader.core.parsers.common.helpers
---------------------------------------------
+novel_downloader.core.parsers.common.helper
+-------------------------------------------
 
 Shared utility functions for parsing Common pages.
 """
@@ -13,7 +13,7 @@ from typing import Any, cast
 
 from bs4 import BeautifulSoup, Tag
 
-from novel_downloader.config import (
+from novel_downloader.models import (
     BookInfoRules,
     FieldRules,
     RuleStep,

novel_downloader/core/parsers/common/main_parser.py

@@ -9,11 +9,14 @@ Common pages.
 
 from typing import Any
 
-from novel_downloader.config import ParserConfig, SiteRules
 from novel_downloader.core.parsers.base import BaseParser
-from novel_downloader.utils.chapter_storage import ChapterDict
+from novel_downloader.models import (
+    ChapterDict,
+    ParserConfig,
+    SiteRules,
+)
 
-from .helper import HTMLExtractor
+# from .helper import HTMLExtractor
 
 
 class CommonParser(BaseParser):
@@ -37,58 +40,60 @@ class CommonParser(BaseParser):
 
     def parse_book_info(
         self,
-        html_str: list[str],
+        html_list: list[str],
         **kwargs: Any,
     ) -> dict[str, Any]:
         """
         Parse a book info page and extract metadata and chapter structure.
 
-        :param html: Raw HTML of the book info page.
+        :param html_list: Raw HTML of the book info page.
         :return: Parsed metadata and chapter structure as a dictionary.
         """
-        if not html_str:
+        if not html_list:
             return {}
-        extractor = HTMLExtractor(html_str[0])
-        rules = self._site_rule["book_info"]
-        return extractor.extract_book_info(rules)
+        # extractor = HTMLExtractor(html_list[0])
+        # rules = self._site_rule["book_info"]
+        # return extractor.extract_book_info(rules)
+        return {}
 
     def parse_chapter(
         self,
-        html_str: list[str],
+        html_list: list[str],
         chapter_id: str,
         **kwargs: Any,
     ) -> ChapterDict | None:
         """
         Parse a single chapter page and extract clean text or simplified HTML.
 
-        :param html: Raw HTML of the chapter page.
+        :param html_list: 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.
         """
-        if not html_str:
+        if not html_list:
             return None
-        extractor = HTMLExtractor(html_str[0])
-        chapter_rules = self._site_rule["chapter"]
-
-        # 必须有正文内容
-        content_steps = chapter_rules.get("content")
-        if not content_steps:
-            raise ValueError(f"No chapter content steps defined for site: {self._site}")
-
-        title_steps = chapter_rules.get("title")
-        title = extractor.extract_field(title_steps["steps"]) if title_steps else ""
-        content = extractor.extract_field(content_steps["steps"])
-        if not content:
-            return None
-
-        return {
-            "id": chapter_id,
-            "title": title or "Untitled",
-            "content": content,
-            "extra": {
-                "site": self._site,
-            },
-        }
+        # extractor = HTMLExtractor(html_list[0])
+        # chapter_rules = self._site_rule["chapter"]
+
+        # # 必须有正文内容
+        # content_steps = chapter_rules.get("content")
+        # if not content_steps:
+        #     raise ValueError(f"No chapter content steps for site: {self._site}")
+
+        # title_steps = chapter_rules.get("title")
+        # title = extractor.extract_field(title_steps["steps"]) if title_steps else ""
+        # content = extractor.extract_field(content_steps["steps"])
+        # if not content:
+        #     return None
+
+        # return {
+        #     "id": chapter_id,
+        #     "title": title or "Untitled",
+        #     "content": content,
+        #     "extra": {
+        #         "site": self._site,
+        #     },
+        # }
+        return None
 
     @property
     def site(self) -> str: