v2.1.5: 重构代码结构，使得更简洁可扩展 (#81)

Author: hect0x7

requirements-dev.txt

@@ -2,6 +2,3 @@ commonX
 curl_cffi
 PyYAML
 Pillow
-
-# for test
-pyperclip

src/jmcomic/__init__.py

@@ -2,6 +2,6 @@
 # 被依赖方 <--- 使用方
 # config <--- entity <--- toolkit <--- client <--- option
 
-__version__ = '2.1.4'
+__version__ = '2.1.5'
 
 from .api import *

src/jmcomic/api.py

@@ -15,118 +15,103 @@ def download_album(jm_album_id, option=None):
     option, jm_client = build_client(option)
     album: JmAlbumDetail = jm_client.get_album_detail(jm_album_id)
 
-    jm_debug('album',
-             f'本子获取成功: [{album.id}], '
-             f'作者: [{album.author}], '
-             f'章节数: [{len(album)}], '
-             f'标题: [{album.title}], '
-             )
-
-    def download_photo(photo: JmPhotoDetail,
-                       debug_topic='photo',
-                       ):
-        jm_client.check_photo(photo)
-
-        jm_debug(debug_topic,
-                 f'开始下载章节: {photo.id} ({photo.album_id}[{photo.index}/{len(album)}]), '
-                 f'标题: [{photo.title}], '
-                 f'图片数为[{len(photo)}]'
-                 )
-
-        download_by_photo_detail(photo, option)
-
-        jm_debug(debug_topic,
-                 f'章节下载完成: {photo.id} ({photo.album_id}[{photo.index}/{len(album)}])'
-                 )
-
-    thread_pool_executor(
-        iter_objs=album,
-        apply_each_obj_func=download_photo,
-    )
-
-    jm_debug('album', f'本子下载完成: [{album.id}]')
-
-
-def download_album_batch(jm_album_id_iter: Union[Iterable, Generator],
-                         option=None,
-                         wait_finish=True,
-                         ) -> List[Thread]:
-    """
-    批量下载album，每个album一个线程，使用的是同一个option。
-
-    @param jm_album_id_iter: album_id的可迭代对象
-    @param option: 下载选项，为空默认是 JmOption.default()
-    @param wait_finish: 是否要等待这些下载线程全部完成
-    @return 返回值是List[Thread]，里面是每个下载漫画的线程。
-    """
-    if option is None:
-        option = JmOption.default()
-
-    return thread_pool_executor(
-        iter_objs=((album_id, option) for album_id in jm_album_id_iter),
-        apply_each_obj_func=download_album,
-        wait_finish=wait_finish,
+    option.before_album(album)
+    execute_by_condition(
+        iter_obj=album,
+        apply=lambda photo: download_by_photo_detail(photo, option),
+        count_batch=option.decide_photo_batch_count(album)
     )
+    option.after_album(album)
 
 
 def download_photo(jm_photo_id, option=None):
     """
     下载一个本子的一章，入口api
     """
     option, jm_client = build_client(option)
-    photo_detail = jm_client.get_photo_detail(jm_photo_id)
-    download_by_photo_detail(photo_detail, option)
+    photo = jm_client.get_photo_detail(jm_photo_id)
+    download_by_photo_detail(photo, option)
 
 
-def download_by_photo_detail(photo_detail: JmPhotoDetail,
-                             option=None,
-                             ):
+def download_by_photo_detail(photo: JmPhotoDetail, option=None):
     """
-    下载一个本子的一章，根据 photo_detail
-    @param photo_detail: 本子章节信息
+    下载一个本子的一章，根据 photo
+    @param photo: 本子章节信息
     @param option: 选项
     """
     option, jm_client = build_client(option)
 
     # 下载准备
     use_cache = option.download_cache
     decode_image = option.download_image_decode
-    jm_client.check_photo(photo_detail)
+    jm_client.check_photo(photo)
 
     # 下载每个图片的函数
-    def download_image(index, image: JmImageDetail, debug_topic='image'):
-        img_save_path = option.decide_image_filepath(photo_detail, index)
-        debug_tag = f'{image.aid}/{image.filename} [{index + 1}/{len(photo_detail)}]'
+    def download_image(image: JmImageDetail):
+        img_save_path = option.decide_image_filepath(image)
 
         # 已下载过，缓存命中
         if use_cache is True and file_exists(img_save_path):
-            jm_debug(debug_topic,
-                     f'图片已存在: {debug_tag} ← [{img_save_path}]'
-                     )
+            image.is_exists = True
             return
 
-        # 开始下载
+        option.before_image(image, img_save_path)
         jm_client.download_by_image_detail(
             image,
             img_save_path,
             decode_image=decode_image,
         )
+        option.after_image(image, img_save_path)
+
+    option.before_photo(photo)
+    execute_by_condition(
+        iter_obj=photo,
+        apply=download_image,
+        count_batch=option.decide_image_batch_count(photo)
+    )
+    option.before_photo(photo)
 
-        jm_debug(debug_topic,
-                 f'图片下载完成: {debug_tag}, [{image.img_url}] → [{img_save_path}]'
-                 )
 
-    batch = option.download_threading_batch_count
-    if batch <= 0:
+def download_album_batch(jm_album_id_iter: Union[Iterable, Generator],
+                         option=None,
+                         wait_finish=True,
+                         ) -> List[Thread]:
+    """
+    批量下载album，每个album一个线程，使用的是同一个option。
+
+    @param jm_album_id_iter: album_id的可迭代对象
+    @param option: 下载选项，为空默认是 JmOption.default()
+    @param wait_finish: 是否要等待这些下载线程全部完成
+    @return 返回值是List[Thread]，里面是每个下载漫画的线程。
+    """
+    if option is None:
+        option = JmOption.default()
+
+    return thread_pool_executor(
+        iter_objs=((album_id, option) for album_id in jm_album_id_iter),
+        apply_each_obj_func=download_album,
+        wait_finish=wait_finish,
+    )
+
+
+def execute_by_condition(iter_obj, apply: Callable, count_batch: int):
+    """
+    章节/图片的下载调度逻辑
+    """
+    count_real = len(iter_obj)
+
+    if count_batch >= count_real:
+        # 一图一线程
         multi_thread_launcher(
-            iter_objs=enumerate(photo_detail),
-            apply_each_obj_func=download_image,
+            iter_objs=iter_obj,
+            apply_each_obj_func=apply,
         )
     else:
+        # 创建batch个线程的线程池，当图片数>batch时要等待。
         thread_pool_executor(
-            iter_objs=enumerate(photo_detail),
-            apply_each_obj_func=download_image,
-            max_workers=batch,
+            iter_objs=iter_obj,
+            apply_each_obj_func=apply,
+            max_workers=count_batch,
         )
 
 

src/jmcomic/jm_client_impl.py

@@ -31,7 +31,7 @@ def post(self, url, **kwargs):
         return self.request_with_retry(self.postman.post, url, **kwargs)
 
     def of_api_url(self, api_path, domain):
-        return f'{JmModuleConfig.PROT}{domain}{api_path}'
+        return JmcomicText.format_url(api_path, domain)
 
     def request_with_retry(self,
                            request,
@@ -52,9 +52,11 @@ def request_with_retry(self,
             self.fallback(request, url, domain_index, retry_count, **kwargs)
 
         if url.startswith('/'):
-            # path
-            domain = self.domain_list[domain_index]
-            url = self.of_api_url(url, domain)
+            # path → url
+            url = self.of_api_url(
+                api_path=url,
+                domain=self.domain_list[domain_index],
+            )
             jm_debug('api', url)
         else:
             # 图片url
@@ -154,13 +156,13 @@ def get_photo_detail(self, photo_id, fetch_album=True) -> JmPhotoDetail:
         resp = self.get_jm_html(f"/photo/{photo_id}")
 
         # 用 JmcomicText 解析 html，返回实体类
-        photo_detail = JmcomicText.analyse_jm_photo_html(resp.text)
+        photo = JmcomicText.analyse_jm_photo_html(resp.text)
 
         # 一并获取该章节的所处本子
         if fetch_album is True:
-            photo_detail.from_album = self.get_album_detail(photo_detail.album_id)
+            photo.from_album = self.get_album_detail(photo.album_id)
 
-        return photo_detail
+        return photo
 
     def search_album(self, search_query, main_tag=0, page=1) -> JmSearchPage:
         params = {

src/jmcomic/jm_client_interface.py

@@ -160,16 +160,28 @@ def of_api_url(self, api_path, domain):
     def enable_cache(self, debug=False):
         raise NotImplementedError
 
-    def check_photo(self, photo_detail: JmPhotoDetail):
+    def check_photo(self, photo: JmPhotoDetail):
+        """
+        photo来源有两种:
+        1. album[?]
+        2. client.get_photo_detail(?)
+
+        其中，只有[2]是可以包含下载图片的url信息的。
+        本方法会检查photo是不是[1]，
+        如果是[1]，通过请求获取[2]，然后把2中的一些重要字段更新到1中
+
+        @param photo: 被检查的JmPhotoDetail对象
+        """
         # 检查 from_album
-        if photo_detail.from_album is None:
-            photo_detail.from_album = self.get_album_detail(photo_detail.album_id)
+        if photo.from_album is None:
+            photo.from_album = self.get_album_detail(photo.album_id)
 
         # 检查 page_arr 和 data_original_domain
-        if photo_detail.page_arr is None or photo_detail.data_original_domain is None:
-            new = self.get_photo_detail(photo_detail.photo_id, False)
-            new.from_album = photo_detail.from_album
-            photo_detail.__dict__.update(new.__dict__)
+        if photo.page_arr is None or photo.data_original_domain is None:
+            new = self.get_photo_detail(photo.photo_id, False)
+            new.from_album = photo.from_album
+            photo.__dict__.update(new.__dict__)
+
 
 class JmUserClient:
 
@@ -232,14 +244,14 @@ def download_image(self,
             resp.transfer_to(img_save_path, scramble_id, decode_image, img_url)
 
     def download_by_image_detail(self,
-                                 img_detail: JmImageDetail,
+                                 image: JmImageDetail,
                                  img_save_path,
                                  decode_image=True,
                                  ):
         self.download_image(
-            img_detail.download_url,
+            image.download_url,
             img_save_path,
-            img_detail.scramble_id,
+            image.scramble_id,
             decode_image=decode_image,
         )