v2.5.35: 优化部分下载失败时异常处理

Author: hect0x7

assets/docs/sources/tutorial/0_common_usage.md

@@ -82,25 +82,38 @@ from jmcomic import *
 # 客户端
 client = JmOption.default().new_jm_client()
 
-# 捕获jmcomic可能出现的异常
+# 捕获获取本子/章节详情时可能出现的异常
 try:
     # 请求本子实体类
     album: JmAlbumDetail = client.get_album_detail('427413')
 except MissingAlbumPhotoException as e:
     print(f'id={e.error_jmid}的本子不存在')
-    
+
 except JsonResolveFailException as e:
     print(f'解析json失败')
     # 响应对象
     resp = e.resp
     print(f'resp.text: {resp.text}, resp.status_code: {resp.status_code}')
-    
+
 except RequestRetryAllFailException as e:
     print(f'请求失败，重试次数耗尽')
-    
+
 except JmcomicException as e:
     # 捕获所有异常，用作兜底
     print(f'jmcomic遇到异常: {e}')
+
+# 多线程下载时，可能出现非当前线程下载失败，抛出异常，
+# 而JmDownloader有对应字段记录了这些线程发生的异常
+# 使用check_exception=True参数可以使downloader主动检查是否存在下载异常
+# 如果有，则当前线程会主动上抛一个PartialDownloadFailedException异常
+# 该参数主要用于主动检查部分下载失败的情况，
+# 因为非当前线程抛出的异常（比如下载章节的线程和下载图片的线程），这些线程如果抛出异常，
+# 当前线程是感知不到的，try-catch下载方法download_album不能捕获到其他线程发生的异常。
+try:
+    album, downloader = download_album(123, check_exception=True)
+except PartialDownloadFailedException as e:
+    downloader: JmDownloader = e.downloader
+    print(f'下载出现部分失败, 下载失败的章节: {downloader.download_failed_photo}, 下载失败的图片: {downloader.download_failed_image}')
 ```
 
 

src/jmcomic/api.py

@@ -79,7 +79,9 @@ def download_album(jm_album_id,
 def download_photo(jm_photo_id,
                    option=None,
                    downloader=None,
-                   callback=None):
+                   callback=None,
+                   check_exception=True,
+                   ):
     """
     下载一个章节（photo），参数同 download_album
     """
@@ -91,7 +93,8 @@ def download_photo(jm_photo_id,
 
         if callback is not None:
             callback(photo, dler)
-
+        if check_exception:
+            dler.raise_if_has_exception()
         return photo, dler
 
 

src/jmcomic/jm_downloader.py

@@ -193,7 +193,7 @@ def all_success(self) -> bool:
 
         注意！如果使用了filter机制，例如通过filter只下载3张图片，那么all_success也会为False
         """
-        if not self.has_no_download_failed_exception:
+        if self.has_download_failures:
             return False
 
         for album, photo_dict in self.download_success_dict.items():
@@ -207,8 +207,8 @@ def all_success(self) -> bool:
         return True
 
     @property
-    def has_no_download_failed_exception(self):
-        return len(self.download_failed_image) == 0 and len(self.download_failed_photo) == 0
+    def has_download_failures(self):
+        return len(self.download_failed_image) != 0 or len(self.download_failed_photo) != 0
 
     # 下面是回调方法
 
@@ -268,7 +268,7 @@ def after_image(self, image: JmImageDetail, img_save_path):
         )
 
     def raise_if_has_exception(self):
-        if self.has_no_download_failed_exception:
+        if not self.has_download_failures:
             return
         msg_ls = ['部分下载失败', '', '']
 

src/jmcomic/jm_entity.py

@@ -35,13 +35,6 @@ def is_album(cls):
     def is_page(cls):
         return False
 
-    @classmethod
-    def __alias__(cls):
-        # "JmAlbumDetail" -> "album" (本子)
-        # "JmPhotoDetail" -> "photo" (章节)
-        cls_name = cls.__name__
-        return cls_name[cls_name.index("m") + 1: cls_name.rfind("Detail")].lower()
-
 
 class IndexedEntity:
     def getindex(self, index: int):
@@ -136,6 +129,13 @@ def __str__(self):
 
     __repr__ = __str__
 
+    @classmethod
+    def __alias__(cls):
+        # "JmAlbumDetail" -> "album" (本子)
+        # "JmPhotoDetail" -> "photo" (章节)
+        cls_name = cls.__name__
+        return cls_name[cls_name.index("m") + 1: cls_name.rfind("Detail")].lower()
+
     @classmethod
     def get_dirname(cls, detail: 'DetailEntity', ref: str) -> str:
         """
@@ -258,7 +258,7 @@ def is_image(cls):
         return True
 
     def __str__(self):
-        return f'''{self.__class__.__name__}({self.__alias__()}-[{self.download_url}])'''
+        return f'''{self.__class__.__name__}(image-[{self.download_url}])'''
 
     __repr__ = __str__
 

src/jmcomic/jm_exception.py

@@ -62,6 +62,9 @@ class RequestRetryAllFailException(JmcomicException):
 class PartialDownloadFailedException(JmcomicException):
     description = '部分章节或图片下载失败异常'
 
+    @property
+    def downloader(self):
+        return self.from_context(ExceptionTool.CONTEXT_KEY_DOWNLOADER)
 
 class ExceptionTool:
     """
@@ -74,6 +77,7 @@ class ExceptionTool:
     CONTEXT_KEY_HTML = 'html'
     CONTEXT_KEY_RE_PATTERN = 'pattern'
     CONTEXT_KEY_MISSING_JM_ID = 'missing_jm_id'
+    CONTEXT_KEY_DOWNLOADER = 'downloader'
 
     @classmethod
     def raises(cls,