v2.1.19: 完善上手文档，优化option配置机制 (#109)

Author: hect0x7

src/jmcomic/__init__.py

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

src/jmcomic/jm_config.py

@@ -234,6 +234,61 @@ def new_postman(cls, session=False, **kwargs):
         'x-requested-with': 'XMLHttpRequest',
     }
 
+    # option 默认配置字典
+    default_option_dict: dict = {
+        'version': '2.0',
+        'debug': None,
+        'dir_rule': {'rule': 'Bd_Ptitle', 'base_dir': None},
+        'download': {
+            'cache': True,
+            'image': {'decode': True, 'suffix': None},
+            'threading': {'batch_count': 30},
+        },
+        'client': {
+            'cache': None,
+            'domain': [],
+            'postman': {
+                'type': 'cffi',
+                'meta_data': {
+                    'impersonate': 'chrome110',
+                    'headers': None,
+                }
+            },
+            'impl': 'html',
+            'retry_times': 5
+        }
+    }
+
+    @classmethod
+    def option_default_dict(cls) -> dict:
+        """
+        返回JmOption.default()的默认配置字典。
+        这样做是为了支持外界自行覆盖option默认配置字典
+        """
+        option_dict = cls.default_option_dict.copy()
+
+        # debug
+        if option_dict['debug'] is None:
+            option_dict['debug'] = cls.enable_jm_debug
+
+        # dir_rule.base_dir
+        dir_rule = option_dict['dir_rule']
+        if dir_rule['base_dir'] is None:
+            import os
+            dir_rule['base_dir'] = os.getcwd()
+
+        # client cache
+        client = option_dict['client']
+        if client['cache'] is None:
+            client['cache'] = True
+
+        # headers
+        meta_data = client['postman']['meta_data']
+        if meta_data['headers'] is None:
+            meta_data['headers'] = cls.headers()
+
+        return option_dict
+
 
 jm_debug = JmModuleConfig.jm_debug
 disable_jm_debug = JmModuleConfig.disable_jm_debug

src/jmcomic/jm_option.py

@@ -266,30 +266,7 @@ def new_jm_client(self, **kwargs) -> JmcomicClient:
 
     @classmethod
     def default_dict(cls) -> Dict:
-        return {
-            'version': '2.0',
-            'debug': True,
-            'dir_rule': {'rule': 'Bd_Ptitle', 'base_dir': workspace()},
-            'download': {
-                'cache': True,
-                'image': {'decode': True, 'suffix': None},
-                'threading': {'batch_count': 30},
-            },
-            'client': {
-                'cache': True,
-                'domain': [],
-                'postman': {
-                    'type': 'cffi',
-                    'meta_data': {
-                        'impersonate': 'chrome110',
-                        'cookies': None,
-                        'headers': JmModuleConfig.headers(),
-                    }
-                },
-                'impl': 'html',
-                'retry_times': 5
-            }
-        }
+        return JmModuleConfig.option_default_dict()
 
     @classmethod
     def default(cls):

usage/getting_started.py

@@ -14,24 +14,48 @@
 
 """
 --------------------
-    配置文件介绍
+    配置文件上手
 --------------------
 """
+from jmcomic import JmModuleConfig, JmOption, create_option
+
 # 先获取默认的JmOption对象
-jm_option = jmcomic.JmOption.default()
+option = JmOption.default()
 
 # 可以把对象保存为文件，方便编辑
-jm_option.to_file('./你的配置文件路名称.yml')  # yml格式
-jm_option.to_file('./你的配置文件路名称.json')  # json格式
+option.to_file('保存路径.yml')  # yml格式
+option.to_file('保存路径.json')  # json格式
 
 # 如果你修改了默认配置，现在想用你修改后的配置来下载，使用如下代码
-jm_option = jmcomic.create_option('./你的配置文件路名称.yml')
-jmcomic.download_album('23333', jm_option)
+option = JmOption.from_file('保存路径.yml')
+# 或者
+option = create_option('保存路径.yml')
+# 使用你的option配置来下载
+jmcomic.download_album('23333', option)
+
+
+"""
+
+--------------------
+    配置文件进阶
+--------------------
+
+定制option有几种方式？
 
-# 如果你只想做简单的配置，也可以使用如下形式
-# 具体可以写什么，请参考 JmOption.default_dict，你只需要覆盖里面的键值即可
-# 配置代理
-jm_option = JmOption.construct({
+方式1. 针对一个option对象生效
+    JmOption.construct({xxx: yyy})  -- 简单配置推荐
+    JmOption.from_file('配置文件路径') -- 复杂配置推荐
+    
+方式2. 针对所有option对象生效，全局配置，配置的优先级次于1
+    JmModuleConfig.default_option_dict['xxx'] = yyy
+
+下面以配置代理为例
+
+"""
+from jmcomic import JmOption, ProxyBuilder, download_album
+
+# 方式1. 定制一个option对象
+option = JmOption.construct({
     'client': {
         'postman': {
             'meta_data': {
@@ -40,34 +64,46 @@
         }
     }
 })
+# 调用下载api需要传入此option
+download_album('xxx', option)
+
+# 方式2. 使用全局配置
+JmModuleConfig.default_option_dict['client']['postman']['meta_data']['proxies'] = ProxyBuilder.clash_proxy()
+# 调用下载api**不需要**传入option
+download_album('xxx')
 
 
 """
 --------------------
     批量下载介绍
 --------------------
 """
+from jmcomic import download_album
+
 # 如果你想要批量下载，可以使用 list/set/tuple/生成器 作为第一个参数。
 # 第二个参数依然是可选的JmOption对象
-jmcomic.download_album(['422866', '1', '2', '3'])  # list
-jmcomic.download_album({'422866', '1', '2', '3'})  # set
-jmcomic.download_album(('422866', '1', '2', '3'))  # tuple
-jmcomic.download_album(aid for aid in ('422866', '1', '2', '3'))  # 生成器
+download_album(['422866', '1', '2', '3'])  # list
+download_album({'422866', '1', '2', '3'})  # set
+download_album(('422866', '1', '2', '3'))  # tuple
+download_album(aid for aid in ('422866', '1', '2', '3'))  # 生成器
 
 
 """
 --------------------
     获取域名介绍
 --------------------
 """
+from jmcomic import JmModuleConfig
+
 # 方式1: 访问禁漫发布页
-url_ls = jmcomic.JmModuleConfig.get_jmcomic_url_all()
+domain_ls = JmModuleConfig.get_jmcomic_url_all()
 print(url_ls)
 
 # 方式2: 访问禁漫的永久网域
-url = jmcomic.JmModuleConfig.get_jmcomic_url()
+url = JmModuleConfig.get_jmcomic_url()
 print(url)
 
-# 配置jmcomic模块的默认域名
-# 默认域名仅在option没有配置domain时被使用
-jmcomic.JmModuleConfig.DOMAIN = '18comic.vip'
+# Q：download_album(xxx)，没有传入option，那么访问JM使用的默认域名是什么?
+# A：默认域名是: JmModuleConfig.get_jmcomic_url()，如果想定制此默认域名：
+# 做法1: 定制option，见上
+# 做法2: JmModuleConfig.DOMAIN = '18comic.vip'