feat: 接入 Python logging 并重构规范 jm_log，修复 ExceptionListener 参数规范

Author: hect0x7

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

@@ -8,9 +8,13 @@
 
 使用代码：
 
-```
+```python
 from jmcomic import disable_jm_log 
 disable_jm_log()
+
+# 推荐使用 Python 原生的 logging 控制
+import logging
+logging.getLogger("jmcomic").setLevel(logging.WARNING) # 只显示警告以上的日志
 ```
 
 使用配置：

assets/docs/sources/tutorial/4_module_custom.md

@@ -137,24 +137,32 @@ def custom_album_photo_image_detail_class():
 ```python
 def custom_jm_log():
     """
-    该函数演示自定义log
+    该函数演示如何接管和自定义日志输出
     """
 
-    # jmcomic模块在运行过程中会使用 jm_log() 这个函数进行打印信息
-    # jm_log() 这个函数 最后会调用 JmModuleConfig.EXECUTOR_LOG 函数
-    # 你可以写一个自己的函数，替换 JmModuleConfig.EXECUTOR_LOG，实现自定义log
+    # jmcomic 项目默认使用内置的 Python logging 模块
+    # 其日志记录器的名字固定为 "jmcomic"
 
-    # 1. 自定义log函数
-    def my_log(topic: str, msg: str):
+    # 【推荐方式】直接配置原生的 logging logger
+    import logging
+    jm_logger = logging.getLogger("jmcomic")
+    
+    # 例如，取消默认往下游控制台打印的 Handler，转存到文件中
+    jm_logger.handlers.clear()
+    jm_logger.addHandler(logging.FileHandler("jm_download.log", encoding="utf-8"))
+    
+    # 【向后兼容方式/遗留用法】
+    # 你依然可以通过替换全局配置类的 EXECUTOR_LOG 函数暴力接管日志
+    def my_custom_log(topic: str, msg, e: Exception = None):
         """
-        这个log函数的参数列表必须包含两个参数，topic和msg
         @param topic: log主题，例如 'album.before', 'req.error', 'plugin.error'
-        @param msg: 具体log的信息
+        @param msg: 具体log的信息，也可以直接传入 Exception 对象（底层会自动适配）
+        @param e: 可选，异常对象（当 msg 本身就是 Exception 时无需传）
         """
         pass
 
-    # 2. 让my_log生效
-    JmModuleConfig.EXECUTOR_LOG = my_log
+    # 生效自定义的 proxy
+    JmModuleConfig.EXECUTOR_LOG = my_custom_log
 ```
 
 

src/jmcomic/__init__.py

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

src/jmcomic/jm_config.py

@@ -1,5 +1,9 @@
+import logging
+
 from common import time_stamp, field_cache, ProxyBuilder
 
+jm_logger = logging.getLogger('jmcomic')
+
 
 def shuffled(lines):
     from random import shuffle
@@ -9,9 +13,27 @@ def shuffled(lines):
     return ls
 
 
-def default_jm_logging(topic: str, msg: str):
-    from common import format_ts, current_thread
-    print('[{}] [{}]:【{}】{}'.format(format_ts(), current_thread().name, topic, msg))
+def setup_default_jm_logger():
+    # 为了保持原有默认向下兼容，如果没有 handler，我们加一个控制台 handler
+    if not jm_logger.handlers:
+        import sys
+        handler = logging.StreamHandler(sys.stdout)
+        formatter = logging.Formatter('[%(asctime)s] [%(threadName)s]:【%(topic)s】%(message)s', datefmt='%Y-%m-%d %H:%M:%S')
+        handler.setFormatter(formatter)
+        jm_logger.addHandler(handler)
+        jm_logger.setLevel(logging.INFO)
+
+
+def default_jm_logging(topic: str, msg, e: Exception = None):
+    # 支持 jm_log('topic', e) 的简写
+    if isinstance(msg, BaseException):
+        e = msg
+        msg = str(msg)
+    extra = {'topic': topic}
+    if e is not None:
+        jm_logger.error(msg, extra=extra, exc_info=e)
+    else:
+        jm_logger.info(msg, extra=extra)
 
 
 # 禁漫常量
@@ -382,11 +404,10 @@ def get_fix_ts_token_tokenparam(cls):
         token, tokenparam = JmCryptoTool.token_and_tokenparam(ts)
         return ts, token, tokenparam
 
-    # noinspection PyUnusedLocal
     @classmethod
-    def jm_log(cls, topic: str, msg: str):
+    def jm_log(cls, topic: str, msg: str, e: Exception = None):
         if cls.FLAG_ENABLE_JM_LOG is True:
-            cls.EXECUTOR_LOG(topic, msg)
+            cls.EXECUTOR_LOG(topic, msg, e)
 
     @classmethod
     def disable_jm_log(cls):
@@ -507,5 +528,7 @@ def register_exception_listener(cls, etype, listener):
         cls.REGISTRY_EXCEPTION_LISTENER[etype] = listener
 
 
+setup_default_jm_logger()
+
 jm_log = JmModuleConfig.jm_log
 disable_jm_log = JmModuleConfig.disable_jm_log

src/jmcomic/jm_exception.py

@@ -6,6 +6,7 @@ class JmcomicException(Exception):
     description = 'jmcomic 模块异常'
 
     def __init__(self, msg: str, context: dict):
+        super().__init__(msg)
         self.msg = msg
         self.context = context
 

src/jmcomic/jm_option.py

@@ -541,7 +541,7 @@ def call_all_plugin(self, group: str, safe=True, **extra):
                 self.invoke_plugin(pclass, kwargs, extra, pinfo)
             except BaseException as e:
                 if safe is True:
-                    traceback_print_exec()
+                    jm_log('plugin.exception', e)
                 else:
                     raise e
 

src/jmcomic/jm_plugin.py

@@ -552,15 +552,19 @@ def invoke(self, whitelist) -> None:
         if whitelist is not None:
             whitelist = set(whitelist)
 
-        old_jm_log = JmModuleConfig.EXECUTOR_LOG
+        import logging
+        from jmcomic import jm_logger
 
-        def new_jm_log(topic, msg):
-            if whitelist is not None and topic not in whitelist:
-                return
-
-            old_jm_log(topic, msg)
+        class TopicFilter(logging.Filter):
+            def filter(self, record):
+                topic = getattr(record, 'topic', None)
+                if whitelist is not None and topic is not None and topic not in whitelist:
+                    return False
+                return True
 
-        JmModuleConfig.EXECUTOR_LOG = new_jm_log
+        # 删除旧的同类 filter 避免重复
+        jm_logger.filters = [f for f in jm_logger.filters if not isinstance(f, TopicFilter)]
+        jm_logger.addFilter(TopicFilter())
 
 
 class AutoSetBrowserCookiesPlugin(JmOptionPlugin):
@@ -1286,9 +1290,7 @@ def do_request(domain):
                 try:
                     return do_request(domain)
                 except Exception as e:
-                    from common import traceback_print_exec
-                    traceback_print_exec()
-                    jm_log('req.error', str(e))
+                    jm_log('req.error', e)
                     self.update_failed_count(client, domain)
 
         return client.fallback(request, url, 0, 0, is_image, **kwargs)