novel-downloader 1.4.1__tar.gz → 1.4.3__tar.gz

{novel_downloader-1.4.1 → novel_downloader-1.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: novel-downloader
-Version: 1.4.1
+Version: 1.4.3
 Summary: A command-line tool for downloading Chinese web novels from Qidian and similar platforms.
 Author-email: Saudade Z <saudadez217@gmail.com>
 License: MIT License
@@ -46,7 +46,6 @@ Requires-Dist: aiohttp
 Requires-Dist: playwright
 Requires-Dist: lxml
 Requires-Dist: platformdirs
-Requires-Dist: ebooklib
 Provides-Extra: dev
 Requires-Dist: black; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
@@ -55,6 +54,7 @@ Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: pytest-mock; extra == "dev"
 Requires-Dist: types-requests; extra == "dev"
+Requires-Dist: types-lxml; extra == "dev"
 Requires-Dist: types-PyYAML; extra == "dev"
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: commitizen; extra == "dev"
@@ -109,6 +109,8 @@ playwright install
 pip install novel-downloader[font-recovery]
 ```
 
+- 详细可见: [安装](https://github.com/BowenZ217/novel-downloader/blob/main/docs/1-installation.md)
+
 ---
 
 ### CLI 模式
@@ -180,6 +182,7 @@ pip install .
 - [CLI 使用示例](https://github.com/BowenZ217/novel-downloader/blob/main/docs/6-cli-usage-examples.md)
 - [复制 Cookies](https://github.com/BowenZ217/novel-downloader/blob/main/docs/copy-cookies.md)
 - [文件保存](https://github.com/BowenZ217/novel-downloader/blob/main/docs/file-saving.md)
+- [模块与接口文档](https://github.com/BowenZ217/novel-downloader/blob/main/docs/api/README.md)
 - [TODO](https://github.com/BowenZ217/novel-downloader/blob/main/docs/todo.md)
 - [开发](https://github.com/BowenZ217/novel-downloader/blob/main/docs/develop.md)
 - [项目说明](#项目说明)

{novel_downloader-1.4.1 → novel_downloader-1.4.3}/README.md

@@ -38,6 +38,8 @@ playwright install
 pip install novel-downloader[font-recovery]
 ```
 
+- 详细可见: [安装](https://github.com/BowenZ217/novel-downloader/blob/main/docs/1-installation.md)
+
 ---
 
 ### CLI 模式
@@ -109,6 +111,7 @@ pip install .
 - [CLI 使用示例](https://github.com/BowenZ217/novel-downloader/blob/main/docs/6-cli-usage-examples.md)
 - [复制 Cookies](https://github.com/BowenZ217/novel-downloader/blob/main/docs/copy-cookies.md)
 - [文件保存](https://github.com/BowenZ217/novel-downloader/blob/main/docs/file-saving.md)
+- [模块与接口文档](https://github.com/BowenZ217/novel-downloader/blob/main/docs/api/README.md)
 - [TODO](https://github.com/BowenZ217/novel-downloader/blob/main/docs/todo.md)
 - [开发](https://github.com/BowenZ217/novel-downloader/blob/main/docs/develop.md)
 - [项目说明](#项目说明)

{novel_downloader-1.4.1 → novel_downloader-1.4.3}/novel_downloader/__init__.py

@@ -6,7 +6,7 @@ novel_downloader
 Core package for the Novel Downloader project.
 """
 
-__version__ = "1.4.1"
+__version__ = "1.4.3"
 
 __author__ = "Saudade Z"
 __email__ = "saudadez217@gmail.com"

{novel_downloader-1.4.1 → novel_downloader-1.4.3}/novel_downloader/cli/download.py

@@ -9,6 +9,7 @@ Download novels from supported sites via CLI.
 import asyncio
 import getpass
 from argparse import Namespace, _SubParsersAction
+from collections.abc import Iterable
 from dataclasses import asdict
 from pathlib import Path
 from typing import Any
@@ -21,7 +22,7 @@ from novel_downloader.core.factory import (
     get_parser,
 )
 from novel_downloader.core.interfaces import FetcherProtocol
-from novel_downloader.models import LoginField
+from novel_downloader.models import BookConfig, LoginField
 from novel_downloader.utils.cookies import resolve_cookies
 from novel_downloader.utils.i18n import t
 from novel_downloader.utils.logger import setup_logging
@@ -36,6 +37,9 @@ def register_download_subcommand(subparsers: _SubParsersAction) -> None:  # type
     )
     parser.add_argument("--config", type=str, help=t("help_config"))
 
+    parser.add_argument("--start", type=str, help=t("download_option_start"))
+    parser.add_argument("--end", type=str, help=t("download_option_end"))
+
     parser.set_defaults(func=handle_download)
 
 
@@ -44,7 +48,11 @@ def handle_download(args: Namespace) -> None:
 
     site: str = args.site
     config_path: Path | None = Path(args.config) if args.config else None
-    book_ids: list[str] = args.book_ids or []
+    book_ids: list[BookConfig] = _cli_args_to_book_configs(
+        args.book_ids,
+        args.start,
+        args.end,
+    )
 
     print(t("download_site_info", site=site))
 
@@ -63,25 +71,73 @@ def handle_download(args: Namespace) -> None:
             print(t("download_fail_get_ids", err=str(e)))
             return
 
-    invalid_ids = {"0000000000"}
-    valid_book_ids = set(book_ids) - invalid_ids
+    valid_books = _filter_valid_book_configs(book_ids)
 
     if not book_ids:
         print(t("download_no_ids"))
         return
 
-    if not valid_book_ids:
+    if not valid_books:
         print(t("download_only_example", example="0000000000"))
         print(t("download_edit_config"))
         return
 
-    asyncio.run(_download(adapter, site, valid_book_ids))
+    asyncio.run(_download(adapter, site, valid_books))
+
+
+def _cli_args_to_book_configs(
+    book_ids: list[str],
+    start_id: str | None,
+    end_id: str | None,
+) -> list[BookConfig]:
+    """
+    Convert CLI book_ids and optional --start/--end into a list of BookConfig.
+    Only the first book_id uses start/end; others are minimal.
+    """
+    if not book_ids:
+        return []
+
+    result: list[BookConfig] = []
+
+    first: BookConfig = {"book_id": book_ids[0]}
+    if start_id:
+        first["start_id"] = start_id
+    if end_id:
+        first["end_id"] = end_id
+    result.append(first)
+
+    for book_id in book_ids[1:]:
+        result.append({"book_id": book_id})
+
+    return result
+
+
+def _filter_valid_book_configs(
+    books: list[BookConfig],
+    invalid_ids: Iterable[str] = ("0000000000",),
+) -> list[BookConfig]:
+    """
+    Filter a list of BookConfig:
+    - Removes entries with invalid or placeholder book_ids
+    - Deduplicates based on book_id while preserving order
+    """
+    seen = set(invalid_ids)
+    result: list[BookConfig] = []
+
+    for book in books:
+        book_id = book["book_id"]
+        if book_id in seen:
+            continue
+        seen.add(book_id)
+        result.append(book)
+
+    return result
 
 
 async def _download(
     adapter: ConfigAdapter,
     site: str,
-    valid_book_ids: set[str],
+    valid_books: list[BookConfig],
 ) -> None:
     downloader_cfg = adapter.get_downloader_config()
     fetcher_cfg = adapter.get_fetcher_config()
@@ -105,14 +161,17 @@ async def _download(
         downloader = get_downloader(
             fetcher=fetcher,
             parser=parser,
-            exporter=exporter,
             site=site,
             config=downloader_cfg,
         )
 
-        for book_id in valid_book_ids:
-            print(t("download_downloading", book_id=book_id, site=site))
-            await downloader.download(book_id, progress_hook=_print_progress)
+        for book in valid_books:
+            print(t("download_downloading", book_id=book["book_id"], site=site))
+            await downloader.download(
+                book,
+                progress_hook=_print_progress,
+            )
+            await asyncio.to_thread(exporter.export, book["book_id"])
 
         if downloader_cfg.login_required and fetcher.is_logged_in:
             await fetcher.save_state()

{novel_downloader-1.4.1 → novel_downloader-1.4.3}/novel_downloader/config/adapter.py

@@ -10,6 +10,7 @@ site name into structured dataclass-based config models.
 from typing import Any
 
 from novel_downloader.models import (
+    BookConfig,
     DownloaderConfig,
     ExporterConfig,
     FetcherConfig,
@@ -126,6 +127,7 @@ class ConfigAdapter:
         site_cfg = self._get_site_cfg()
         return ParserConfig(
             cache_dir=gen.get("cache_dir", "./novel_cache"),
+            use_truncation=site_cfg.get("use_truncation", True),
             decode_font=font_ocr.get("decode_font", False),
             use_freq=font_ocr.get("use_freq", False),
             use_ocr=font_ocr.get("use_ocr", True),
@@ -169,22 +171,54 @@ class ConfigAdapter:
             split_mode=site_cfg.get("split_mode", "book"),
         )
 
-    def get_book_ids(self) -> list[str]:
+    def get_book_ids(self) -> list[BookConfig]:
         """
         从 config["sites"][site]["book_ids"] 中提取目标书籍列表
         """
         site_cfg = self._get_site_cfg()
-        raw_ids = site_cfg.get("book_ids", [])
+        raw = site_cfg.get("book_ids", [])
 
-        if isinstance(raw_ids, str):
-            return [raw_ids]
+        if isinstance(raw, str | int):
+            return [{"book_id": str(raw)}]
 
-        if isinstance(raw_ids, int):
-            return [str(raw_ids)]
+        if isinstance(raw, dict):
+            return [self._dict_to_book_config(raw)]
 
-        if not isinstance(raw_ids, list):
+        if not isinstance(raw, list):
             raise ValueError(
-                f"book_ids must be a list or string, got {type(raw_ids).__name__}"
+                f"book_ids must be a list or string, got {type(raw).__name__}"
             )
 
-        return [str(book_id) for book_id in raw_ids]
+        result: list[BookConfig] = []
+        for item in raw:
+            try:
+                if isinstance(item, str | int):
+                    result.append({"book_id": str(item)})
+                elif isinstance(item, dict):
+                    result.append(self._dict_to_book_config(item))
+            except ValueError:
+                continue
+
+        return result
+
+    @staticmethod
+    def _dict_to_book_config(data: dict[str, Any]) -> BookConfig:
+        """
+        Converts a dict to BookConfig with type normalization.
+        Raises ValueError if 'book_id' is missing.
+        """
+        if "book_id" not in data:
+            raise ValueError("Missing required field 'book_id'")
+
+        result: BookConfig = {"book_id": str(data["book_id"])}
+
+        if "start_id" in data:
+            result["start_id"] = str(data["start_id"])
+
+        if "end_id" in data:
+            result["end_id"] = str(data["end_id"])
+
+        if "ignore_ids" in data:
+            result["ignore_ids"] = [str(x) for x in data["ignore_ids"]]
+
+        return result

{novel_downloader-1.4.1 → novel_downloader-1.4.3}/novel_downloader/core/__init__.py

@@ -14,8 +14,26 @@ downloading and processing online novel content, including:
 - Exporter: Responsible for exporting downloaded data into various output formats.
 """
 
-from .factory import get_parser
+from .factory import (
+    get_downloader,
+    get_exporter,
+    get_fetcher,
+    get_parser,
+)
+from .interfaces import (
+    DownloaderProtocol,
+    ExporterProtocol,
+    FetcherProtocol,
+    ParserProtocol,
+)
 
 __all__ = [
+    "get_downloader",
+    "get_exporter",
+    "get_fetcher",
     "get_parser",
+    "DownloaderProtocol",
+    "ExporterProtocol",
+    "FetcherProtocol",
+    "ParserProtocol",
 ]

{novel_downloader-1.4.1 → novel_downloader-1.4.3}/novel_downloader/core/downloaders/base.py

@@ -15,11 +15,10 @@ from typing import Any
 
 from novel_downloader.core.interfaces import (
     DownloaderProtocol,
-    ExporterProtocol,
     FetcherProtocol,
     ParserProtocol,
 )
-from novel_downloader.models import DownloaderConfig
+from novel_downloader.models import BookConfig, DownloaderConfig
 
 
 class BaseDownloader(DownloaderProtocol, abc.ABC):
@@ -34,13 +33,11 @@ class BaseDownloader(DownloaderProtocol, abc.ABC):
         self,
         fetcher: FetcherProtocol,
         parser: ParserProtocol,
-        exporter: ExporterProtocol,
         config: DownloaderConfig,
         site: str,
     ):
         self._fetcher = fetcher
         self._parser = parser
-        self._exporter = exporter
         self._config = config
         self._site = site
 
@@ -53,7 +50,7 @@ class BaseDownloader(DownloaderProtocol, abc.ABC):
 
     async def download_many(
         self,
-        book_ids: list[str],
+        books: list[BookConfig],
         *,
         progress_hook: Callable[[int, int], Awaitable[None]] | None = None,
         **kwargs: Any,
@@ -61,33 +58,34 @@ class BaseDownloader(DownloaderProtocol, abc.ABC):
         """
         Download multiple books with pre-download hook and error handling.
 
-        :param book_ids: A list of book identifiers to download.
-        :param progress_hook: (optional) Called after each chapter;
+        :param books: List of BookConfig entries.
+        :param progress_hook: Optional async callback after each chapter.
                                 args: completed_count, total_count.
         """
         if not await self._ensure_ready():
+            book_ids = [b["book_id"] for b in books]
             self.logger.warning(
-                "[%s] login failed, skipping download of %s",
+                "[%s] login failed, skipping download of books: %s",
                 self._site,
-                book_ids,
+                ", ".join(book_ids) or "<none>",
             )
             return
 
-        for book_id in book_ids:
+        for book in books:
             try:
                 await self._download_one(
-                    book_id,
+                    book,
                     progress_hook=progress_hook,
                     **kwargs,
                 )
             except Exception as e:
-                self._handle_download_exception(book_id, e)
+                self._handle_download_exception(book, e)
 
         await self._finalize()
 
     async def download(
         self,
-        book_id: str,
+        book: BookConfig,
         *,
         progress_hook: Callable[[int, int], Awaitable[None]] | None = None,
         **kwargs: Any,
@@ -95,33 +93,34 @@ class BaseDownloader(DownloaderProtocol, abc.ABC):
         """
         Download a single book with pre-download hook and error handling.
 
-        :param book_id: The identifier of the book to download.
-        :param progress_hook: (optional) Called after each chapter;
+        :param book: BookConfig with at least 'book_id'.
+        :param progress_hook: Optional async callback after each chapter.
                                 args: completed_count, total_count.
         """
         if not await self._ensure_ready():
             self.logger.warning(
-                "[%s] login failed, skipping download of %s",
+                "[%s] login failed, skipping download of book: %s (%s-%s)",
                 self._site,
-                book_id,
+                book["book_id"],
+                book.get("start_id", "-"),
+                book.get("end_id", "-"),
             )
-            return
 
         try:
             await self._download_one(
-                book_id,
+                book,
                 progress_hook=progress_hook,
                 **kwargs,
             )
         except Exception as e:
-            self._handle_download_exception(book_id, e)
+            self._handle_download_exception(book, e)
 
         await self._finalize()
 
     @abc.abstractmethod
     async def _download_one(
         self,
-        book_id: str,
+        book: BookConfig,
         *,
         progress_hook: Callable[[int, int], Awaitable[None]] | None = None,
         **kwargs: Any,
@@ -156,10 +155,6 @@ class BaseDownloader(DownloaderProtocol, abc.ABC):
     def parser(self) -> ParserProtocol:
         return self._parser
 
-    @property
-    def exporter(self) -> ExporterProtocol:
-        return self._exporter
-
     @property
     def config(self) -> DownloaderConfig:
         return self._config
@@ -208,19 +203,21 @@ class BaseDownloader(DownloaderProtocol, abc.ABC):
     def download_workers(self) -> int:
         return self._config.download_workers
 
-    def _handle_download_exception(self, book_id: str, error: Exception) -> None:
+    def _handle_download_exception(self, book: BookConfig, error: Exception) -> None:
         """
         Handle download errors in a consistent way.
 
         This method can be overridden or extended to implement retry logic, etc.
 
-        :param book_id: The ID of the book that failed.
+        :param book: The book that failed.
         :param error: The exception raised during download.
         """
         self.logger.warning(
-            "[%s] Failed to download %r: %s",
+            "[%s] Failed to download (book_id=%s, start=%s, end=%s): %s",
             self.__class__.__name__,
-            book_id,
+            book.get("book_id", "<unknown>"),
+            book.get("start_id", "-"),
+            book.get("end_id", "-"),
             error,
         )
 

{novel_downloader-1.4.1 → novel_downloader-1.4.3}/novel_downloader/core/downloaders/biquge.py

@@ -7,7 +7,6 @@ novel_downloader.core.downloaders.biquge
 
 from novel_downloader.core.downloaders.common import CommonDownloader
 from novel_downloader.core.interfaces import (
-    ExporterProtocol,
     FetcherProtocol,
     ParserProtocol,
 )
@@ -21,7 +20,6 @@ class BiqugeDownloader(CommonDownloader):
         self,
         fetcher: FetcherProtocol,
         parser: ParserProtocol,
-        exporter: ExporterProtocol,
         config: DownloaderConfig,
     ):
-        super().__init__(fetcher, parser, exporter, config, "biquge")
+        super().__init__(fetcher, parser, config, "biquge")

{novel_downloader-1.4.1 → novel_downloader-1.4.3}/novel_downloader/core/downloaders/common.py

@@ -12,7 +12,13 @@ from contextlib import suppress
 from typing import Any, cast
 
 from novel_downloader.core.downloaders.base import BaseDownloader
-from novel_downloader.models import ChapterDict, CidTask, HtmlTask, RestoreTask
+from novel_downloader.models import (
+    BookConfig,
+    ChapterDict,
+    CidTask,
+    HtmlTask,
+    RestoreTask,
+)
 from novel_downloader.utils.chapter_storage import ChapterStorage
 from novel_downloader.utils.file_utils import save_as_json, save_as_txt
 from novel_downloader.utils.time_utils import (
@@ -28,7 +34,7 @@ class CommonDownloader(BaseDownloader):
 
     async def _download_one(
         self,
-        book_id: str,
+        book: BookConfig,
         *,
         progress_hook: Callable[[int, int], Awaitable[None]] | None = None,
         **kwargs: Any,
@@ -36,9 +42,13 @@ class CommonDownloader(BaseDownloader):
         """
         The full download logic for a single book.
 
-        :param book_id: The identifier of the book to download.
+        :param book: BookConfig with at least 'book_id'.
         """
         TAG = "[Downloader]"
+        book_id = book["book_id"]
+        start_id = book.get("start_id")
+        end_id = book.get("end_id")
+        ignore_set = set(book.get("ignore_ids", []))
 
         raw_base = self.raw_data_dir / book_id
         cache_base = self.cache_dir / book_id
@@ -145,6 +155,10 @@ class CommonDownloader(BaseDownloader):
                     cid_queue.task_done()
                     continue
 
+                if cid in ignore_set:
+                    cid_queue.task_done()
+                    continue
+
                 try:
                     async with semaphore:
                         html_list = await self.fetcher.get_book_chapter(book_id, cid)
@@ -369,15 +383,33 @@ class CommonDownloader(BaseDownloader):
             )
         )
 
+        found_start = start_id is None
+        stop_early = False
         last_cid: str | None = None
+
         for vol_idx, vol in enumerate(vols):
             chapters = vol.get("chapters", [])
             for chap_idx, chap in enumerate(chapters):
+                if stop_early:
+                    break
+
                 cid = chap.get("chapterId")
+
+                # Skip until reaching start_id
+                if not found_start:
+                    if cid == start_id:
+                        found_start = True
+                    else:
+                        completed_count += 1
+                        last_cid = cid
+                        continue
+
+                # Stop when reaching end_id
+                if end_id is not None and cid == end_id:
+                    stop_early = True
+
                 if cid and normal_cs.exists(cid) and self.skip_existing:
                     completed_count += 1
-                    if progress_hook:
-                        await progress_hook(completed_count, total_chapters)
                     last_cid = cid
                     continue
 
@@ -389,8 +421,12 @@ class CommonDownloader(BaseDownloader):
                         prev_cid=last_cid,
                     )
                 )
+
                 last_cid = cid
 
+            if stop_early:
+                break
+
         await restore_queue.join()
         await cid_queue.join()
         await html_queue.join()
@@ -404,8 +440,6 @@ class CommonDownloader(BaseDownloader):
         normal_cs.close()
         save_as_json(book_info, info_path)
 
-        await asyncio.to_thread(self.exporter.export, book_id)
-
         self.logger.info(
             "%s Novel '%s' download completed.",
             TAG,

{novel_downloader-1.4.1 → novel_downloader-1.4.3}/novel_downloader/core/downloaders/esjzone.py

@@ -7,7 +7,6 @@ novel_downloader.core.downloaders.esjzone
 
 from novel_downloader.core.downloaders.common import CommonDownloader
 from novel_downloader.core.interfaces import (
-    ExporterProtocol,
     FetcherProtocol,
     ParserProtocol,
 )
@@ -21,7 +20,6 @@ class EsjzoneDownloader(CommonDownloader):
         self,
         fetcher: FetcherProtocol,
         parser: ParserProtocol,
-        exporter: ExporterProtocol,
         config: DownloaderConfig,
     ):
-        super().__init__(fetcher, parser, exporter, config, "esjzone")
+        super().__init__(fetcher, parser, config, "esjzone")

{novel_downloader-1.4.1 → novel_downloader-1.4.3}/novel_downloader/core/downloaders/linovelib.py

@@ -7,7 +7,6 @@ novel_downloader.core.downloaders.linovelib
 
 from novel_downloader.core.downloaders.common import CommonDownloader
 from novel_downloader.core.interfaces import (
-    ExporterProtocol,
     FetcherProtocol,
     ParserProtocol,
 )
@@ -21,7 +20,6 @@ class LinovelibDownloader(CommonDownloader):
         self,
         fetcher: FetcherProtocol,
         parser: ParserProtocol,
-        exporter: ExporterProtocol,
         config: DownloaderConfig,
     ):
-        super().__init__(fetcher, parser, exporter, config, "linovelib")
+        super().__init__(fetcher, parser, config, "linovelib")

{novel_downloader-1.4.1 → novel_downloader-1.4.3}/novel_downloader/core/downloaders/qianbi.py

@@ -7,7 +7,6 @@ novel_downloader.core.downloaders.qianbi
 
 from novel_downloader.core.downloaders.common import CommonDownloader
 from novel_downloader.core.interfaces import (
-    ExporterProtocol,
     FetcherProtocol,
     ParserProtocol,
 )
@@ -21,7 +20,6 @@ class QianbiDownloader(CommonDownloader):
         self,
         fetcher: FetcherProtocol,
         parser: ParserProtocol,
-        exporter: ExporterProtocol,
         config: DownloaderConfig,
     ):
-        super().__init__(fetcher, parser, exporter, config, "qianbi")
+        super().__init__(fetcher, parser, config, "qianbi")