v2.5.1: 更新文档，增加option配置和log自定义说明; 优化download api，有返回值对外界更友好; 重构异常处理，异常类别更清晰; 扩大请求重试的范围，加入json格式检查; (#197) [skip ci]

Author: hect0x7

assets/docs/sources/option_file_syntax.md

@@ -15,6 +15,10 @@ JmOption.default().to_file('./option.yml') # 创建默认option，导出为optio
 ## 2. option常规配置项
 
 ```yml
+# 开启jmcomic的日志输入，默认为true
+# 对日志有需求的可进一步参考文档
+log: true
+
 # 配置客户端相关
 client:
   # impl: 客户端实现类，不配置默认会使用JmModuleConfig.DEFAULT_CLIENT_IMPL
@@ -32,6 +36,10 @@ client:
     - 18comic.vip
     - 18comic.org
 
+  # retry_times: 请求失败重试次数，默认为5
+  retry_times: 5
+
+  # postman: 请求配置
   postman:
     meta_data:
       # proxies: 代理配置，默认是 system，表示使用系统代理。

assets/docs/sources/tutorial/11_log_custom.md

@@ -0,0 +1,55 @@
+# 日志自定义 - 如果你不想看到那么多的日志
+
+本文档缘起于 GitHub Discussions: [discussions/195](https://github.com/hect0x7/JMComic-Crawler-Python/discussions/195)
+
+下面是这个问题的解决方法：
+
+## 1. 日志完全开启/关闭
+
+使用代码：
+
+```
+from jmcomic import disable_jm_log 
+disable_jm_log()
+```
+
+使用配置：
+
+```yml
+log: false
+```
+
+## 2. 日志过滤，只保留特定topic
+
+使用插件配置
+
+```yml
+log: true
+
+plugins:
+  after_init:
+    - plugin: log_topic_filter # 日志topic过滤插件
+      kwargs:
+        whitelist: [ # 只保留api和html，这两个是Client发请求时会打的日志topic
+          'api',
+          'html',
+        ]
+```
+
+## 3. 屏蔽插件的日志
+
+给插件配置加上一个`log`配置项即可
+
+```yml
+plugins:
+  after_init:
+    - plugin: client_proxy # 提高移动端的请求效率的插件
+      log: false # 插件自身不打印日志
+      kwargs:
+        proxy_client_key: cl_proxy_future
+        whitelist: [ api, ]
+```
+
+## 4. 完全自定义 jmcomic 日志
+
+你可以自定义jmcomic的模块日志打印函数，参考文档：[模块自定义](./4_module_custom.md#自定义log)

assets/docs/sources/tutorial/9_custom_download_dir_name.md

@@ -102,7 +102,7 @@ JmModuleConfig.PFIELD_ADVICE['myname'] = lambda photo: f'【{photo.id}】{photo.
 
 ### 文件夹名=第x话+标题
 
-```python
+```yml
 # 直接使用内置字段 indextitle 即可
 dir_rule:
   rule: Bd_Pindextitle

src/jmcomic/__init__.py

@@ -2,7 +2,7 @@
 # 被依赖方 <--- 使用方
 # config <--- entity <--- toolkit <--- client <--- option <--- downloader
 
-__version__ = '2.5.0'
+__version__ = '2.5.1'
 
 from .api import *
 from .jm_plugin import *
@@ -11,8 +11,8 @@
 gb = dict(filter(lambda pair: isinstance(pair[1], type), globals().items()))
 
 
-def register_jmcomic_component(gb: dict, method, valid_interface: type):
-    for v in gb.values():
+def register_jmcomic_component(variables: Dict[str, Any], method, valid_interface: type):
+    for v in variables.values():
         if v != valid_interface and issubclass(v, valid_interface):
             method(v)
 

src/jmcomic/api.py

@@ -5,7 +5,7 @@ def download_batch(download_api,
                    jm_id_iter: Union[Iterable, Generator],
                    option=None,
                    downloader=None,
-                   ):
+                   ) -> Set[Tuple[JmAlbumDetail, JmDownloader]]:
     """
     批量下载 album / photo
 
@@ -21,42 +21,73 @@ def download_batch(download_api,
     if option is None:
         option = JmModuleConfig.option_class().default()
 
-    return multi_thread_launcher(
+    result = set()
+
+    def callback(*ret):
+        result.add(ret)
+
+    multi_thread_launcher(
         iter_objs=set(
             JmcomicText.parse_to_jm_id(jmid)
             for jmid in jm_id_iter
         ),
-        apply_each_obj_func=lambda aid: download_api(aid, option, downloader),
+        apply_each_obj_func=lambda aid: download_api(aid,
+                                                     option,
+                                                     downloader,
+                                                     callback=callback,
+                                                     ),
+        wait_finish=True
     )
 
+    return result
+
 
-def download_album(jm_album_id, option=None, downloader=None):
+def download_album(jm_album_id,
+                   option=None,
+                   downloader=None,
+                   callback=None,
+                   ):
     """
     下载一个本子（album），包含其所有的章节（photo）
 
-    当jm_album_id不是str或int时，相当于调用 download_batch(download_album, jm_album_id, option, downloader)
+    当jm_album_id不是str或int时，视为批量下载，相当于调用 download_batch(download_album, jm_album_id, option, downloader)
 
     :param jm_album_id: 本子的禁漫车号
     :param option: 下载选项
     :param downloader: 下载器类
+    :param callback: 返回值回调函数，可以拿到 album 和 downloader
+    :return: 对于的本子实体类，下载器（如果是上述的批量情况，返回值为download_batch的返回值）
     """
 
     if not isinstance(jm_album_id, (str, int)):
         return download_batch(download_album, jm_album_id, option, downloader)
 
     with new_downloader(option, downloader) as dler:
-        dler.download_album(jm_album_id)
+        album = dler.download_album(jm_album_id)
 
+        if callback is not None:
+            callback(album, dler)
 
-def download_photo(jm_photo_id, option=None, downloader=None):
+        return album, dler
+
+
+def download_photo(jm_photo_id,
+                   option=None,
+                   downloader=None,
+                   callback=None):
     """
     下载一个章节（photo），参数同 download_album
     """
     if not isinstance(jm_photo_id, (str, int)):
         return download_batch(download_photo, jm_photo_id, option)
 
     with new_downloader(option, downloader) as dler:
-        dler.download_photo(jm_photo_id)
+        photo = dler.download_photo(jm_photo_id)
+
+        if callback is not None:
+            callback(photo, dler)
+
+        return photo, dler
 
 
 def new_downloader(option=None, downloader=None) -> JmDownloader:

src/jmcomic/jm_client_impl.py

@@ -45,22 +45,22 @@ def of_api_url(self, api_path, domain):
 
     def get_jm_image(self, img_url) -> JmImageResp:
 
-        def judge(resp):
+        def callback(resp):
             """
             使用此方法包装 self.get，使得图片数据为空时，判定为请求失败时，走重试逻辑
             """
             resp = JmImageResp(resp)
             resp.require_success()
             return resp
 
-        return self.get(img_url, judge=judge, headers=JmModuleConfig.new_html_headers())
+        return self.get(img_url, callback=callback, headers=JmModuleConfig.new_html_headers())
 
     def request_with_retry(self,
                            request,
                            url,
                            domain_index=0,
                            retry_count=0,
-                           judge=lambda resp: resp,
+                           callback=None,
                            **kwargs,
                            ):
         """
@@ -74,7 +74,7 @@ def request_with_retry(self,
         :param url: 图片url / path (/album/xxx)
         :param domain_index: 域名下标
         :param retry_count: 重试次数
-        :param judge: 判定响应是否成功
+        :param callback: 回调，可以接收resp返回新的resp，也可以抛出异常强制重试
         :param kwargs: 请求方法的kwargs
         """
         if domain_index >= len(self.domain_list):
@@ -104,19 +104,32 @@ def request_with_retry(self,
 
         try:
             resp = request(url, **kwargs)
-            return judge(resp)
-        except KeyboardInterrupt as e:
-            raise e
+
+            # 回调，可以接收resp返回新的resp，也可以抛出异常强制重试
+            if callback is not None:
+                resp = callback(resp)
+
+            # 依然是回调，在最后返回之前，还可以判断resp是否重试
+            resp = self.raise_if_resp_should_retry(resp)
+
+            return resp
         except Exception as e:
             if self.retry_times == 0:
                 raise e
 
             self.before_retry(e, kwargs, retry_count, url)
 
         if retry_count < self.retry_times:
-            return self.request_with_retry(request, url, domain_index, retry_count + 1, judge, **kwargs)
+            return self.request_with_retry(request, url, domain_index, retry_count + 1, callback, **kwargs)
         else:
-            return self.request_with_retry(request, url, domain_index + 1, 0, judge, **kwargs)
+            return self.request_with_retry(request, url, domain_index + 1, 0, callback, **kwargs)
+
+    # noinspection PyMethodMayBeStatic
+    def raise_if_resp_should_retry(self, resp):
+        """
+        依然是回调，在最后返回之前，还可以判断resp是否重试
+        """
+        return resp
 
     def update_request_with_specify_domain(self, kwargs: dict, domain: str):
         """
@@ -269,12 +282,12 @@ def get_photo_detail(self,
 
         return photo
 
-    def fetch_detail_entity(self, apid, prefix):
+    def fetch_detail_entity(self, jmid, prefix):
         # 参数校验
-        apid = JmcomicText.parse_to_jm_id(apid)
+        jmid = JmcomicText.parse_to_jm_id(jmid)
 
         # 请求
-        resp = self.get_jm_html(f"/{prefix}/{apid}")
+        resp = self.get_jm_html(f"/{prefix}/{jmid}")
 
         # 用 JmcomicText 解析 html，返回实体类
         if prefix == 'album':
@@ -474,10 +487,10 @@ def album_comment(self,
         return ret
 
     @classmethod
-    def require_resp_success_else_raise(cls, resp, orig_req_url: str):
+    def require_resp_success_else_raise(cls, resp, url: str):
         """
         :param resp: 响应对象
-        :param orig_req_url: /photo/12412312
+        :param url: /photo/12412312
         """
         resp_url: str = resp.url
 
@@ -490,11 +503,11 @@ def require_resp_success_else_raise(cls, resp, orig_req_url: str):
 
         # 3. 检查错误类型
         def match_case(error_path):
-            return resp_url.endswith(error_path) and not orig_req_url.endswith(error_path)
+            return resp_url.endswith(error_path) and not url.endswith(error_path)
 
         # 3.1 album_missing
         if match_case('/error/album_missing'):
-            ExceptionTool.raise_missing(resp, orig_req_url)
+            ExceptionTool.raise_missing(resp, JmcomicText.parse_to_jm_id(url))
 
         # 3.2 user_missing
         if match_case('/error/user_missing'):
@@ -639,17 +652,17 @@ def get_scramble_id(self, photo_id, album_id=None):
 
         return scramble_id
 
-    def fetch_detail_entity(self, apid, clazz):
+    def fetch_detail_entity(self, jmid, clazz):
         """
         请求实体类
         """
-        apid = JmcomicText.parse_to_jm_id(apid)
+        jmid = JmcomicText.parse_to_jm_id(jmid)
         url = self.API_ALBUM if issubclass(clazz, JmAlbumDetail) else self.API_CHAPTER
-        resp = self.req_api(
+        resp = self.req_api(self.append_params_to_url(
             url,
-            params={
-                'id': apid,
-            },
+            {
+                'id': jmid
+            })
         )
 
         return JmApiAdaptTool.parse_entity(resp.res_data, clazz)
@@ -886,18 +899,57 @@ def decide_headers_and_ts(self, kwargs, url):
         return ts
 
     @classmethod
-    def require_resp_success(cls, resp: JmApiResp, orig_req_url: str):
+    def require_resp_success(cls, resp: JmApiResp, url: Optional[str] = None):
+        """
+
+        :param resp: 响应对象
+        :param url: 请求路径，例如 /setting
+        """
         resp.require_success()
 
         # 1. 检查是否 album_missing
         # json: {'code': 200, 'data': []}
         data = resp.model().data
         if isinstance(data, list) and len(data) == 0:
-            ExceptionTool.raise_missing(resp, orig_req_url)
+            ExceptionTool.raise_missing(resp, JmcomicText.parse_to_jm_id(url))
 
         # 2. 是否是特殊的内容
         # 暂无
 
+    def raise_if_resp_should_retry(self, resp):
+        """
+        该方法会判断resp返回值是否是json格式，
+        如果不是，大概率是禁漫内部异常，需要进行重试
+
+        由于完整的json格式校验会有性能开销，所以只做简单的检查，
+        只校验第一个有效字符是不是 '{'，如果不是，就认为异常数据，需要重试
+
+        :param resp: 响应对象
+        :return: resp
+        """
+        if isinstance(resp, JmResp):
+            # 不对包装过的resp对象做校验，包装者自行校验
+            # 例如图片请求
+            return resp
+
+        url = resp.request.url
+
+        if self.API_SCRAMBLE in url:
+            # /chapter_view_template 这个接口不是返回json数据，不做检查
+            return resp
+
+        text = resp.text
+        for char in text:
+            if char not in (' ', '\n', '\t'):
+                # 找到第一个有效字符
+                ExceptionTool.require_true(
+                    char == '{',
+                    f'请求不是json格式，强制重试！响应文本: [{resp.text}]'
+                )
+                return resp
+
+        ExceptionTool.raises_resp(f'响应无数据！request_url=[{url}]', resp)
+
     def after_init(self):
         # 保证拥有cookies，因为移动端要求必须携带cookies，否则会直接跳转同一本子【禁漫娘】
         if JmModuleConfig.flag_api_client_require_cookies: