v2.0.21: 更新禁漫API域名和版本号; 将合并PDF/ZIP/长图的功能简化为 Feature，方便小白使用; 增加美观日志; bugfix和优化文档

Author: hect0x7

assets/docs/sources/index.md

@@ -17,7 +17,7 @@
 
 - [快速上手(GitHub README)](https://github.com/hect0x7/JMComic-Crawler-Python/tree/master?tab=readme-ov-file#%E5%BF%AB%E9%80%9F%E4%B8%8A%E6%89%8B)
 - [常用类和方法演示](tutorial/0_common_usage.md)
-- [下载同时转 PDF/ZIP/长图](tutorial/13_export_and_feature.md)
+- [下载后转为 PDF / ZIP / 长图](tutorial/13_export_and_feature.md)
 - [option配置以及插件写法](./option_file_syntax.md)
 
 ## 特殊用法教程

assets/docs/sources/option_file_syntax.md

@@ -236,15 +236,15 @@ plugins:
         filename_rule: Atitle # 压缩文件的命名规则
         # 请注意⚠ [https://github.com/hect0x7/JMComic-Crawler-Python/issues/223#issuecomment-2045227527]
         # filename_rule和所在钩子有对应关系
-        # 如果配置在 after_photo 下, filename_rule只能写 Pxxx
-        # 如果配置在 after_album 下, filename_rule只能写 Axxx
+        # 如果配置在 after_photo 下, filename_rule 可以写 Pxxx 和Axxx
+        # 如果配置在 after_album 下, filename_rule 只能写 Axxx，不能写 Pxxx
 
         # zip插件也支持dir_rule配置项，可以替代旧版本的zip_dir和filename_rule
         # 请注意⚠ 使用此配置项会使filename_rule，zip_dir，suffix三个配置项无效，与这三个配置项同时存在时仅会使用dir_rule
         # 示例如下:
         # dir_rule: # 新配置项，可取代旧的zip_dir和filename_rule
-        #   base_dir: D:/jmcomic-zip
-        #   rule: 'Bd / {Atitle} / [{Pid}]-{Ptitle}.zip'  # 设置压缩文件夹规则，中间Atitle表示创建一层文件夹，名称是本子标题。[{Pid}]-{Ptitle}.zip 表示压缩文件的命名规则(需显式写出后缀名)
+        #   base_dir: D:/jmcomic-download/
+        #   rule: 'Bd / zip / JM{Aid}-{Atitle}.zip'  # 设置压缩文件夹规则，Bd指代base_dir，中间zip表示在{base_dir}下创建一个名为zip的文件夹，JM{Aid}-{Atitle}.zip 表示压缩文件的命名规则(需显式写出后缀名)
 
         delete_original_file: true # 压缩成功后，删除所有原文件和文件夹
 

assets/docs/sources/tutorial/13_export_and_feature.md

@@ -1,4 +1,4 @@
-# Feature 机制——下载附加行为
+# 教程：下载后转为 PDF / ZIP / 长图
 
 ## 1. 需求场景
 
@@ -37,17 +37,13 @@ download_album('123', extra=Feature.export_pdf)
 download_album('123', option, extra=Feature.export_pdf)
 ```
 
-**效果**：在本子下载完以后，额外在**当前工作目录**下生成包含所有本子图片的 PDF 文件：
+**效果**：在本子下载完以后，默认在**下载根目录**下生成包含所有本子图片的 PDF 文件。如果你没有自定义过option，下载根目录就是你的工作目录（即你运行python脚本或cli的目录）。如果你配置过option，会放在dir_rule.base_dir下面。
 
 ```text
 ./
 ├── [JM123]本子标题.pdf       ← 整本合并为 1 个 PDF，注意pdf文件名的格式，默认包含本子禁漫车号+本子标题
 ```
 
-> 💡 **小白提示：当前工作目录在哪？**
->
-> 默认情况下，文件会直接出现在你**运行 Python 脚本的那个文件夹里**。如果你不知道具体是哪，可以看后面的【自定义参数】章节，手动指定你想保存到的文件夹。
-
 ### 2.2 需要多种导出格式（PDF、ZIP等）——直接组合 Feature
 
 用 `+` 号组合，同时导出多种格式：
@@ -61,7 +57,7 @@ download_album('123', option, extra=[Feature.export_pdf, Feature.export_zip])
 download_album('123', option, extra=Feature.export_pdf | Feature.export_zip)
 ```
 
-效果同pdf，会在本子下载完以后，额外在当前工作目录下，生成包含所有本子图片的 PDF 文件和 ZIP 文件：
+效果同pdf，会在本子下载完以后，额外在对应的下载目录下，生成包含所有本子图片的 PDF 文件和 ZIP 文件：
 
 ```text
 ./
@@ -85,9 +81,10 @@ download_album('123', option, extra=Feature.export_pdf(
 ```
 
 > 💡 **小白必读：命名规则（filename_rule）的小知识**
-> - `A` 开头的占位符（如 `Atitle`, `Aid`）代表 **Album (本子)**，适用于 `download_album`。
-> - `P` 开头的占位符（如 `Ptitle`, `Pid`）代表 **Photo (章节)**，适用于 `download_photo`。
-> - 如果在下载整本（Album）时强行使用章节级（Photo）的规则，程序会因为不知道该用哪一章的标题而报错。
+> - `A` 开头的占位符（如 `Atitle`, `Aid`）代表 **Album (本子)**。
+> - `P` 开头的占位符（如 `Ptitle`, `Pid`）代表 **Photo (章节)**。
+> - `download_photo` （下载单章）时，由于程序既知道当前章节，也知道它属于哪个本子，所以 **`Pxxx` 和 `Axxx` 都可以用**。
+> - `download_album` （下载整本）时，由于是按本子合并的，程序没有具体的“当前章节”，此时 **只能用 `Axxx`，不能用 `Pxxx`**，否则会报错。
 
 ```python
 # 示例 2：全都要——ZIP 存盘 + 长图阅读
@@ -107,7 +104,7 @@ from jmcomic import download_photo, Feature
 download_photo('456', option, extra=Feature.export_pdf)
 ```
 
-效果：在当前工作目录下生成以章节标题命名的 PDF：
+效果：在对应的下载目录下生成以章节标题命名的 PDF：
 
 ```text
 ./
@@ -122,12 +119,12 @@ download_photo('456', option, extra=Feature.export_pdf)
 
 | 调用方式            | Feature.export_pdf | Feature.export_zip | Feature.export_long_img |
 |-----------------|-------------------|-------------------|----------------------|
-| `download_album` | 整本合并为 1 个 PDF<br>`[本子标题].pdf` | 整本打包为 1 个 ZIP<br>`[本子标题].zip` | 所有章节合并为 1 张长图<br>`[本子ID].png` |
-| `download_photo` | 该章节导出为 PDF<br>`[章节标题].pdf` | 该章节打包为 ZIP<br>`[章节标题].zip` | 该章节拼接为长图<br>`[章节ID].png` |
+| `download_album` | 整本合并为 1 个 PDF<br>`[JM本子号]本子标题.pdf` | 整本打包为 1 个 ZIP<br>`[JM本子号]本子标题.zip` | 所有章节合并为 1 张长图<br>`[JM本子号]本子标题.png` |
+| `download_photo` | 该章节导出为 PDF<br>`[JM章节号]章节标题.pdf` | 该章节打包为 ZIP<br>`[JM章节号]章节标题.zip` | 该章节拼接为长图<br>`[JM章节号]章节标题.png` |
 
 当你显式传入参数时（如 `filename_rule='Ptitle'`），**你的配置优先**，不会被自适应覆盖。
 
-> 💡 **提示**：更多可选参数（如加密密码 `encrypt`、后缀名 `suffix` 等），参考 [Plugin 插件参数大全](./6_plugin.md#参数)。
+> 💡 **提示**：更多可选参数（如加密密码 `encrypt`、后缀名 `suffix` 等），参考 [Plugin 插件参数大全](../option_file_syntax.md#3-option插件配置项)。
 
 ## 3. 传统写法（YAML 插件配置）
 

src/jmcomic/jm_config.py

@@ -102,7 +102,7 @@ class JmMagicConstants:
     APP_TOKEN_SECRET_2 = '18comicAPPContent'
     APP_DATA_SECRET = '185Hcomic3PAPP7R'
     API_DOMAIN_SERVER_SECRET = 'diosfjckwpqpdfjkvnqQjsik'
-    APP_VERSION = '2.0.19'
+    APP_VERSION = '2.0.21'
 
 
 # 模块级别共用配置
@@ -153,10 +153,11 @@ class JmModuleConfig:
 
     # 移动端API域名
     DOMAIN_API_LIST = shuffled('''
-    www.cdnaspa.vip
-    www.cdnaspa.club
-    www.cdnplaystation6.vip
-    www.cdnplaystation6.cc
+    www.cdnhjk.net
+    www.cdngwc.cc
+    www.cdngwc.net
+    www.cdngwc.club
+    www.cdnhjk.cc
     ''')
 
     DOMAIN_API_UPDATED_LIST = None

src/jmcomic/jm_downloader.py

@@ -13,12 +13,12 @@ def wrapper(self, *args, **kwargs):
             detail: JmBaseEntity = args[0]
             if detail.is_image():
                 detail: JmImageDetail
-                jm_log('image.failed', f'图片下载失败: [{detail.download_url}], 异常: [{e}]')
+                jm_log('image.failed', f'图片下载失败: [{detail.download_url}], 异常: [{e}]', e)
                 self.download_failed_image.append((detail, e))
 
             elif detail.is_photo():
                 detail: JmPhotoDetail
-                jm_log('photo.failed', f'章节下载失败: [{detail.id}], 异常: [{e}]')
+                jm_log('photo.failed', f'章节下载失败: [{detail.id}], 异常: [{e}]', e)
                 self.download_failed_photo.append((detail, e))
 
             raise e
@@ -54,14 +54,14 @@ def after_photo(self, photo: JmPhotoDetail):
                f'章节下载完成: [{photo.id}] ({photo.album_id}[{photo.index}/{len(photo.from_album)}])')
 
     def before_image(self, image: JmImageDetail, img_save_path):
-        if image.exists:
+        if image.exists and image.cache:
             jm_log('image.before',
                    f'图片已存在: {image.tag} ← [{img_save_path}]'
                    )
-        else:
-            jm_log('image.before',
-                   f'图片准备下载: {image.tag}, [{image.img_url}] → [{img_save_path}]'
-                   )
+            return
+        jm_log('image.before',
+               f'图片准备下载: {image.tag}, [{image.img_url}] → [{img_save_path}]'
+               )
 
     def after_image(self, image: JmImageDetail, img_save_path):
         jm_log('image.after',
@@ -125,18 +125,18 @@ def download_by_image_detail(self, image: JmImageDetail):
 
         image.save_path = img_save_path
         image.exists = file_exists(img_save_path)
+        image.cache = self.option.decide_download_cache(image)
 
         self.before_image(image, img_save_path)
 
         if image.skip:
             return
 
         # let option decide use_cache and decode_image
-        use_cache = self.option.decide_download_cache(image)
         decode_image = self.option.decide_download_image_decode(image)
 
         # skip download
-        if use_cache is True and image.exists:
+        if image.cache and image.exists:
             return
 
         self.client.download_by_image_detail(
@@ -311,7 +311,8 @@ def _invoke_features_for(self, when: str, **kwargs):
                 try:
                     feature.invoke(self.option, feature_from=feature_from, when=when, **kwargs)
                 except Exception as e:
-                    jm_log('downloader.feature.exception', f'Feature执行失败: [{feature}], 来源: [{feature_from}], 异常: [{e}]')
+                    jm_log('downloader.feature.exception', f'Feature执行失败: [{feature}], 来源: [{feature_from}], 异常: [{e}]',
+                           e)
 
     def raise_if_has_exception(self):
         if not self.has_download_failures:

src/jmcomic/jm_entity.py

@@ -11,6 +11,7 @@ def __init__(self):
         self.save_path: str = ''
         self.exists: bool = False
         self.skip = False
+        self.cache = True
 
 
 class JmBaseEntity:
@@ -125,17 +126,23 @@ def idoname(self):
         return f'[{self.id}] {self.oname}'
 
     def __str__(self):
-        return f'''{self.__class__.__name__}({self.__alias__()}-{self.id}: "{self.title}")'''
+        return f'''{self.__class__.__name__}({self.alias_en()}-{self.id}: "{self.title}")'''
 
     __repr__ = __str__
 
     @classmethod
-    def __alias__(cls):
+    def alias_en(cls):
         # "JmAlbumDetail" -> "album" (本子)
         # "JmPhotoDetail" -> "photo" (章节)
         cls_name = cls.__name__
         return cls_name[cls_name.index("m") + 1: cls_name.rfind("Detail")].lower()
 
+    @classmethod
+    def alias_cn(cls) -> str:
+        # "JmAlbumDetail" -> "album" (本子)
+        # "JmPhotoDetail" -> "photo" (章节)
+        return "本子" if issubclass(cls, JmAlbumDetail) else "章节"
+
     @classmethod
     def get_dirname(cls, detail: 'DetailEntity', ref: str) -> str:
         """

src/jmcomic/jm_feature.py

@@ -107,7 +107,7 @@ def invoke(self, option: JmOption, feature_from: str, when: str, **extra):
         ExceptionTool.require_true(pclass is not None, f'PluginFeature 引用了未注册的插件: {self.plugin_key}, from {feature_from}, when {when}')
 
         # 根据 feature_from 动态适配参数
-        plugin_kwargs: dict = self._adapt_plugin_kwargs(feature_from, when)
+        plugin_kwargs: dict = self._adapt_plugin_kwargs(option, feature_from, when)
 
         option.invoke_plugin(
             pclass=pclass,
@@ -116,13 +116,22 @@ def invoke(self, option: JmOption, feature_from: str, when: str, **extra):
             pinfo={'plugin': self.plugin_key, 'kwargs': plugin_kwargs},
         )
 
-    def _adapt_plugin_kwargs(self, feature_from: str, when: str) -> dict:
+    def _adapt_plugin_kwargs(self, option: JmOption, feature_from: str, when: str) -> dict:
         """
         根据feature_from和when动态确定以下插件参数:
         filename_rule
         """
         kwargs = self.kwargs.copy()
         kwargs.setdefault('filename_rule', '[JM{Aid}]{Atitle}' if when == 'after_album' else '[JM{Pid}]{Ptitle}')
+
+        # 动态适配导出目录：当且仅当用户未自定义目录时，根据插件类型自动将 dir 导向 option.dir_rule.base_dir
+        if self.plugin_key == 'zip':
+            kwargs.setdefault('zip_dir', option.dir_rule.base_dir)
+        elif self.plugin_key == 'img2pdf':
+            kwargs.setdefault('pdf_dir', option.dir_rule.base_dir)
+        elif self.plugin_key == 'long_img':
+            kwargs.setdefault('img_dir', option.dir_rule.base_dir)
+
         return kwargs
 
     def __repr__(self):
@@ -159,6 +168,6 @@ def __repr__(self):
 
 
 # 内置的 PluginFeature
-Feature.export_pdf = PluginFeature(Img2pdfPlugin.plugin_key, pdf_dir='./')
-Feature.export_zip = PluginFeature(ZipPlugin.plugin_key, zip_dir='./')
-Feature.export_long_img = PluginFeature(LongImgPlugin.plugin_key, img_dir='./')
+Feature.export_pdf = PluginFeature(Img2pdfPlugin.plugin_key)
+Feature.export_zip = PluginFeature(ZipPlugin.plugin_key)
+Feature.export_long_img = PluginFeature(LongImgPlugin.plugin_key)

src/jmcomic/jm_option.py

@@ -91,7 +91,7 @@ def apply_rule_to_path(self, album, photo, only_album_rules=False) -> str:
                 path = parser(album, photo, rule)
             except BaseException as e:
                 # noinspection PyUnboundLocalVariable
-                jm_log('dir_rule', f'路径规则"{rule}"的解析出错: {e}, album={album}, photo={photo}')
+                jm_log('dir_rule', f'路径规则"{rule}"的解析出错: {e}, album={album}, photo={photo}', e)
                 raise e
             if parser != self.parse_bd_rule:
                 # 根据配置 normalize_zh 进行繁简体统一
@@ -580,19 +580,19 @@ def merge_default_dict(cls, user_dict, default_dict=None):
 
     def download_album(self,
                        album_id,
-                       downloader=None,
-                       callback=None,
+                       *args,
+                       **kwargs,
                        ):
         from .api import download_album
-        download_album(album_id, self, downloader, callback)
+        download_album(album_id, self, *args, **kwargs)
 
     def download_photo(self,
                        photo_id,
-                       downloader=None,
-                       callback=None
+                       *args,
+                       **kwargs,
                        ):
         from .api import download_photo
-        download_photo(photo_id, self, downloader, callback)
+        download_photo(photo_id, self, *args, **kwargs)
 
     # 下面的方法为调用插件提供支持
 
@@ -684,13 +684,13 @@ def handle_plugin_valid_exception(self, e, pinfo: dict, kwargs: dict, _plugin, _
     # noinspection PyMethodMayBeStatic,PyUnusedLocal
     def handle_plugin_unexpected_error(self, e, pinfo: dict, kwargs: dict, _plugin, pclass):
         msg = str(e)
-        jm_log('plugin.error', f'插件 [{pclass.plugin_key}]，运行遇到未捕获异常，异常信息: [{msg}]')
+        jm_log('plugin.error', f'插件 [{pclass.plugin_key}]，运行遇到未捕获异常，异常信息: [{msg}]', e)
         raise e
 
     # noinspection PyMethodMayBeStatic,PyUnusedLocal
     def handle_plugin_jmcomic_exception(self, e, pinfo: dict, kwargs: dict, _plugin, pclass):
         msg = str(e)
-        jm_log('plugin.exception', f'插件 [{pclass.plugin_key}] 调用失败，异常信息: [{msg}]')
+        jm_log('plugin.exception', f'插件 [{pclass.plugin_key}] 调用失败，异常信息: [{msg}]', e)
         raise e
 
     # noinspection PyMethodMayBeStatic

src/jmcomic/jm_plugin.py

@@ -36,7 +36,7 @@ def build(cls, option: JmOption) -> 'JmOptionPlugin':
         return cls(option)
 
     def log(self, msg, topic=None):
-        if self.log_enable:
+        if not self.log_enable:
             return
 
         jm_log(
@@ -136,7 +136,7 @@ def decide_filepath(self,
             filepath = os.path.join(base_dir, DirRule.apply_rule_to_filename(album, photo, filename_rule) + fix_suffix(suffix))
 
         mkdir_if_not_exists(base_dir)
-        return filepath
+        return fix_filepath(filepath)
 
 
 class JmLoginPlugin(JmOptionPlugin):
@@ -380,7 +380,9 @@ def zip_photo(self, photo, image_list: list, zip_path: str, path_to_delete, encr
                 relpath = os.path.relpath(abspath, photo_dir)
                 f.write(abspath, relpath)
 
-        self.log(f'压缩章节[{photo.photo_id}]成功 → {zip_path}', 'finish')
+        # 打印结果
+        self.log(f'{photo.alias_cn()}压缩成功！'
+                 f'[{photo}] → [{zip_path}]', 'finish')
         path_to_delete.append(self.unified_path(photo_dir))
 
     @staticmethod
@@ -403,7 +405,9 @@ def zip_album(self, album, photo_dict: dict, zip_path, path_to_delete, encrypt_d
                     abspath = os.path.join(photo_dir, file)
                     relpath = os.path.relpath(abspath, album_dir)
                     f.write(abspath, relpath)
-        self.log(f'压缩本子[{album.album_id}]成功 → {zip_path}', 'finish')
+        # 打印结果
+        self.log(f'{album.alias_cn()}压缩成功！'
+                 f'[{album}] → [{zip_path}]', 'finish')
 
     def after_zip(self, path_to_delete: List[str]):
         # 删除所有原文件
@@ -786,7 +790,13 @@ def invoke(self,
         if not result:
             return
         img_path_ls, img_dir_ls = result
-        self.log(f'Convert Successfully: JM{album or photo} → {pdf_filepath}')
+
+        # noinspection PyTypeChecker
+        detail: DetailEntity = album or photo
+
+        # 打印结果
+        self.log(f'{detail.alias_cn()}合并PDF成功！'
+                 f'[{detail}] → [{pdf_filepath}]', 'finish')
 
         # 执行删除
         img_path_ls += img_dir_ls
@@ -863,7 +873,12 @@ def invoke(self,
         img_path_ls = self.write_img_2_long_img(long_img_path, album, photo)
         if not img_path_ls:
             return
-        self.log(f'Convert Successfully: JM{album or photo} → {long_img_path}')
+        # noinspection PyTypeChecker
+        detail: DetailEntity = album or photo
+
+        # 打印结果
+        self.log(f'{detail.alias_cn()}合并长图成功！'
+                 f'[{detail}] → [{long_img_path}]', 'finish')
 
         # 执行删除
         self.execute_deletion(img_path_ls)