v2.2.2: 实现两个内置插件：find_update和zip，优化文档和代码示例 (#118) (#95)

Author: hect0x7

.github/workflows/test.yml

@@ -4,12 +4,11 @@ on:
   workflow_dispatch:
   push:
     branches: [ "dev" ]
-    paths-ignore:
-      - 'src/**/__init__.py'
-      - '.github/workflows/*'
-      - 'usage/workflow_download.py'
-      - 'assets/config/option_workflow_download.yml'
-      - 'assets/docs/*'
+    paths:
+      - 'src/**/*.py'
+      - 'test/**/*.py'
+      - '.github/workflows/test.yml'
+      - 'assets/config/option_test.yml'
 
 jobs:
   test: # This code is based on https://github.com/gaogaotiantian/viztracer/blob/master/.github/workflows/python-package.yml

README.md

@@ -6,6 +6,8 @@
 
 **友情提示：珍爱JM，为了减轻JM的服务器压力，请不要一次性爬取太多本子，西门🙏🙏🙏**.
 
+
+
 ## 安装教程
 
 * 通过pip官方源安装（推荐，并且更新也是这个命令）
@@ -19,6 +21,8 @@
   pip install -e ./
   ```
 
+
+
 ## 快速上手
 
 使用下面的两行代码，即可实现功能：把某个本子（album）里的所有章节（photo）下载到本地
@@ -33,15 +37,28 @@ jmcomic.download_album('422866')  # 传入要下载的album的id，即可下载
 # 如果你想要配置，请参考文件 assets/config/常用配置介绍.yml
 ```
 
-进阶使用可以参考本repo下usage文件夹内的示例代码文件:
+
+
+## 进阶使用
+
+进阶使用可以参考本repo下usage文件夹内的示例代码文件，下面是各个文件的作用，你可以挑感兴趣的阅读：
 
 - API上手介绍: `getting_started.py`
 - 使用API实现简单功能: `usage_simple.py`
+- 演示jmcomic模块的可自定义功能点: `usage_custom.py`
 - 使用API的Filter过滤功能: `usage_feature_filter.py`
+- 演示jmcomic模块的Plugin插件体系: `usage_feature_plugin.py`
+- 演示一个综合使用实例: `usage_advanced.py`
+  - 包括6个功能需求的介绍、实现方案和完整运行日志
+  - 实现方案非常简洁，充分jmcomic的便利性，以及强大的插件扩展机制
+
+
+以及一些趣味用法：
+
 - 测试你的ip可以访问哪些禁漫域名: `pick_domain.py`
 - 基于GitHub Actions下载本子: `workflow_download.py`
-- 演示jmcomic模块的自定义功能点: `usage_custom.py`
-- 演示jmcomic模块的Plugin插件体系: `usage_plugin.py`
+
+
 
 ## 项目特点
 
@@ -53,7 +70,7 @@ jmcomic.download_album('422866')  # 传入要下载的album的id，即可下载
   - 配置点有：`是否使用磁盘缓存` `并发下载图片数` `图片类型转换` `下载路径` `请求元信息（headers,cookies,proxies）`等
 - **可扩展性强**
   - **支持Plugin插件，可以方便地扩展功能，以及使用别人的插件**
-    - 目前内置支持的插件：`登录插件`，`硬件占用监控插件`
+    - 目前内置支持的插件有：`登录插件` `硬件占用监控插件` `只下载新章插件` `压缩文件插件` 
   - 支持自定义本子/章节/图片下载前后的回调函数
   - 支持自定义debug日志的开关/格式
   - 支持自定义Downloader/Option/Client/实体类
@@ -62,11 +79,15 @@ jmcomic.download_album('422866')  # 传入要下载的album的id，即可下载
 - **多线程下载**（可细化到一图一线程，效率极高）
 - 跟进了JM最新的图片分割算法（2023-02-08）
 
+
+
 ## 使用小说明
 
 * Python >= 3.7
 * 个人项目，文档和示例会有不及时之处，可以Issue提问
 
+
+
 ## 项目文件夹介绍
 
 * assets：存放一些非代码的资源文件
@@ -79,6 +100,8 @@ jmcomic.download_album('422866')  # 传入要下载的album的id，即可下载
 * tests：测试目录，存放测试代码，使用unittest
 * usage：用法目录，存放示例/使用代码
 
+
+
 ## 感谢以下项目
 
 ### 图片分割算法代码+禁漫移动端API

assets/config/option_plugin.yml

@@ -5,9 +5,21 @@ plugin:
     - plugin: usage-log # 实时打印硬件占用率的插件
       kwargs:
         interval: 0.5 # 间隔时间
-        enable_warning: true
+        enable_warning: true # 占用过大时发出预警
 
     - plugin: login # 登录插件
       kwargs:
         username: un
         password: pw
+
+    - plugin: find_update # 只下载新章插件
+      kwargs:
+        145504: 290266 # 下载本子145504的章节290266以后的新章
+
+  after_album:
+    - plugin: zip # 压缩文件插件
+      kwargs:
+        level: photo # 按照章节，一个章节一个压缩文件
+        filename_rule: Ptitle # 压缩文件的命名规则
+        zip_dir: D:/GitProject/dev/pip/jmcomic/ # 压缩文件存放的文件夹
+        delete_original_file: true # 压缩成功后，删除所有原文件和文件夹

src/jmcomic/__init__.py

@@ -2,7 +2,7 @@
 # 被依赖方 <--- 使用方
 # config <--- entity <--- toolkit <--- client <--- option <--- downloader
 
-__version__ = '2.2.1'
+__version__ = '2.2.2'
 
 from .api import *
 from .jm_plugin import *

src/jmcomic/api.py

@@ -4,6 +4,7 @@
 def download_batch(download_api,
                    jm_id_iter: Union[Iterable, Generator],
                    option=None,
+                   downloader=None,
                    ):
     """
     批量下载 album / photo
@@ -12,6 +13,7 @@ def download_batch(download_api,
     @param download_api: 下载api
     @param jm_id_iter: jmid (album_id, photo_id) 的迭代器
     @param option: 下载选项，对所有的jmid使用同一个，默认是 JmOption.default()
+    @param downloader: 下载器类
     """
     from common import multi_thread_launcher
 
@@ -23,41 +25,45 @@ def download_batch(download_api,
             JmcomicText.parse_to_album_id(jmid)
             for jmid in jm_id_iter
         ),
-        apply_each_obj_func=lambda aid: download_api(aid, option),
+        apply_each_obj_func=lambda aid: download_api(aid, option, downloader),
     )
 
 
-def download_album(jm_album_id, option=None):
+def download_album(jm_album_id, option=None, downloader=None):
     """
     下载一个本子
     @param jm_album_id: 禁漫的本子的id，类型可以是str/int/iterable[str]。
     如果是iterable[str]，则会调用 download_album_batch
     @param option: 下载选项，为空默认是 JmOption.default()
+    @param downloader: 下载器类
     """
 
     if not isinstance(jm_album_id, (str, int)):
-        return download_batch(download_album, jm_album_id, option)
+        return download_batch(download_album, jm_album_id, option, downloader)
 
-    with new_downloader(option) as dler:
+    with new_downloader(option, downloader) as dler:
         dler.download_album(jm_album_id)
 
 
-def download_photo(jm_photo_id, option=None):
+def download_photo(jm_photo_id, option=None, downloader=None):
     """
     下载一个章节
     """
     if not isinstance(jm_photo_id, (str, int)):
         return download_batch(download_photo, jm_photo_id, option)
 
-    with new_downloader(option) as dler:
+    with new_downloader(option, downloader) as dler:
         dler.download_photo(jm_photo_id)
 
 
-def new_downloader(option=None):
+def new_downloader(option=None, downloader=None) -> JmDownloader:
     if option is None:
         option = JmModuleConfig.option_class().default()
 
-    return JmModuleConfig.downloader_class()(option)
+    if downloader is None:
+        downloader = JmModuleConfig.downloader_class()
+
+    return downloader(option)
 
 
 def create_option(filepath):

src/jmcomic/jm_client_impl.py

@@ -5,6 +5,7 @@ class AbstractJmClient(
     JmcomicClient,
     PostmanProxy,
 ):
+    client_key: None
 
     def __init__(self,
                  postman: Postman,
@@ -153,6 +154,7 @@ def fallback(self, request, url, domain_index, retry_count, **kwargs):
 
 # 基于网页实现的JmClient
 class JmHtmlClient(AbstractJmClient):
+    client_key = 'html'
 
     def get_album_detail(self, album_id) -> JmAlbumDetail:
         # 参数校验
@@ -366,6 +368,7 @@ def check_special_http_code(cls, resp):
 
 
 class JmApiClient(AbstractJmClient):
+    client_key = 'api'
     API_SEARCH = '/search'
 
     def search_album(self, search_query, main_tag=0, page=1) -> JmApiResp:
@@ -437,5 +440,5 @@ def save_image_resp(self, *args, **kwargs):
         self.future_list.append(future)
 
 
-JmModuleConfig.CLASS_CLIENT_IMPL['html'] = JmHtmlClient
-JmModuleConfig.CLASS_CLIENT_IMPL['api'] = JmApiClient
+JmModuleConfig.register_client(JmHtmlClient)
+JmModuleConfig.register_client(JmApiClient)

src/jmcomic/jm_config.py

@@ -297,6 +297,10 @@ def option_default_dict(cls) -> dict:
     def register_plugin(cls, plugin_class):
         cls.plugin_registry[plugin_class.plugin_key] = plugin_class
 
+    @classmethod
+    def register_client(cls, client_class):
+        cls.CLASS_CLIENT_IMPL[client_class.client_key] = client_class
+
 
 jm_debug = JmModuleConfig.jm_debug
 disable_jm_debug = JmModuleConfig.disable_jm_debug

src/jmcomic/jm_downloader.py

@@ -38,7 +38,7 @@ def before_photo(self, photo: JmPhotoDetail):
 
     def after_photo(self, photo: JmPhotoDetail):
         jm_debug('photo.after',
-                 f'章节下载完成: {photo.id} ({photo.album_id}[{photo.index}/{len(photo.from_album)}])')
+                 f'章节下载完成: [{photo.id}] ({photo.album_id}[{photo.index}/{len(photo.from_album)}])')
 
     def before_image(self, image: JmImageDetail, img_save_path):
         if image.is_exists:
@@ -65,6 +65,9 @@ def __init__(self, option: JmOption) -> None:
         self.use_cache = self.option.download_cache
         self.decode_image = self.option.download_image_decode
 
+        # 收集所有下载的image，为plugin提供数据
+        self.all_downloaded: Dict[JmAlbumDetail, Dict[JmPhotoDetail, List[Tuple[str, JmImageDetail]]]] = {}
+
     def download_album(self, album_id):
         client = self.client_for_album(album_id)
         album = client.get_album_detail(album_id)
@@ -121,6 +124,9 @@ def execute_by_condition(self,
         iter_objs = self.filter_iter_objs(iter_objs)
         count_real = len(iter_objs)
 
+        if count_real == 0:
+            return
+
         if count_batch >= count_real:
             # 一个图/章节 对应 一个线程
             multi_thread_launcher(
@@ -162,6 +168,34 @@ def client_for_photo(self, jm_photo_id) -> JmcomicClient:
         """
         return self.option.build_jm_client()
 
+    # 下面是回调方法
+
+    def before_album(self, album: JmAlbumDetail):
+        super().before_album(album)
+        self.all_downloaded.setdefault(album, {})
+
+    def before_photo(self, photo: JmPhotoDetail):
+        super().before_photo(photo)
+        self.all_downloaded.setdefault(photo.from_album, {})
+        self.all_downloaded[photo.from_album].setdefault(photo, [])
+
+    def after_album(self, album: JmAlbumDetail):
+        super().after_album(album)
+        self.option.call_all_plugin(
+            'after_album',
+            album=album,
+            downloader=self,
+        )
+
+    def after_image(self, image: JmImageDetail, img_save_path):
+        super().after_image(image, img_save_path)
+        photo = image.from_photo
+        album = photo.from_album
+
+        self.all_downloaded.get(album).get(photo).append((img_save_path, image))
+
+    # 下面是对with语法的支持
+
     def __enter__(self):
         return self