Merge branch 'hect0x7:master' into master

Author: Greeay7

.github/release.yml

@@ -0,0 +1,21 @@
+# .github/release.yml
+
+changelog:
+  exclude:
+    labels:
+      - ignore-for-release
+    authors:
+      - octocat
+  categories:
+    - title: 🏕 Features
+      labels:
+        - '*'
+      exclude:
+        labels:
+          - dependencies
+    - title: 👒 Dependencies
+      labels:
+        - dependencies
+    - title: Other Changes
+      labels:
+        - "*"

.github/workflows/download_dispatch.yml

@@ -31,6 +31,15 @@ on:
         default: ''
         required: false
 
+      PDF_OPTION:
+        description: '是否要下载后将图片合并为pdf文件'
+        required: false
+        type: choice
+        options:
+          - 否
+          - 是 | 本子维度合并pdf
+          - 是 | 章节维度合并pdf
+
       ZIP_NAME:
         type: string
         default: 本子.tar.gz
@@ -68,6 +77,7 @@ jobs:
       ZIP_NAME: ${{ github.event.inputs.ZIP_NAME }}
       UPLOAD_NAME: ${{ github.event.inputs.UPLOAD_NAME }}
       IMAGE_SUFFIX: ${{ github.event.inputs.IMAGE_SUFFIX }}
+      PDF_OPTION: ${{ github.event.inputs.PDF_OPTION }}
 
       # 登录相关secrets
       JM_USERNAME: ${{ secrets.JM_USERNAME }}
@@ -95,6 +105,11 @@ jobs:
           python -m pip install --upgrade pip
           pip install -r requirements-dev.txt
 
+      - name: Install img2pdf
+        if: inputs.PDF_OPTION != '否'
+        run: |
+          pip install img2pdf
+
       - name: 安装jmcomic（pip）
         if: ${{ github.ref != 'refs/heads/dev' }}
         run: |

.github/workflows/release_auto.yml

@@ -10,6 +10,9 @@ on:
 jobs:
   release:
     runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: write
     if: startsWith(github.event.head_commit.message, 'v')
     steps:
       - uses: actions/checkout@v4
@@ -26,12 +29,13 @@ jobs:
           python .github/release.py "$commit_message"
 
       - name: Create Release
-        uses: softprops/action-gh-release@v1
+        uses: softprops/action-gh-release@v2
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
           tag_name: ${{ steps.tb.outputs.tag }}
           body_path: release_body.txt
+          generate_release_notes: true
 
       - name: Build
         run: |
@@ -40,5 +44,5 @@ jobs:
 
       - name: Release PYPI
         uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          password: ${{ secrets.PYPI_JMCOMIC }}
+#        with:
+#          password: ${{ secrets.PYPI_JMCOMIC }}

README.md

@@ -1,14 +1,32 @@
-# Python API For JMComic (禁漫天堂)
+<!-- 顶部标题 & 统计徽章 -->
+<div align="center">
+  <h1 style="margin-top: 0" align="center">Python API for JMComic</h1>
+  <p align="center">
+  <strong>提供 Python API 访问禁漫天堂（网页端 & 移动端），集成 GitHub Actions 下载器🚀</strong>
+  </p>
 
-本项目封装了一套可用于爬取JM的Python API.
+[![GitHub](https://img.shields.io/badge/-GitHub-181717?logo=github)](https://github.com/hect0x7)
+[![Stars](https://img.shields.io/github/stars/hect0x7/JMComic-Crawler-Python?color=orange&label=stars&style=flat)](https://github.com/hect0x7/JMComic-Crawler-Python/stargazers)
+[![Forks](https://img.shields.io/github/forks/hect0x7/JMComic-Crawler-Python?color=green&label=forks&style=flat)](https://github.com/hect0x7/JMComic-Crawler-Python/forks)
+[![GitHub latest releases](https://img.shields.io/github/v/release/hect0x7/JMComic-Crawler-Python?color=blue&label=version)](https://github.com/hect0x7/JMComic-Crawler-Python/releases/latest)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/jmcomic?style=flat&color=hotpink)](https://pepy.tech/projects/jmcomic)
+[![Licence](https://img.shields.io/github/license/hect0x7/JMComic-Crawler-Python?color=red)](https://github.com/hect0x7/JMComic-Crawler-Python)
 
-你可以通过简单的几行Python代码，实现下载JM上的本子到本地，并且是处理好的图片。
+</div>
+
+
+
+
+> 本项目封装了一套可用于爬取JM的Python API.
+> 
+> 你可以通过简单的几行Python代码，实现下载JM上的本子到本地，并且是处理好的图片。
+> 
+> **友情提示：珍爱JM，为了减轻JM的服务器压力，请不要一次性爬取太多本子，西门🙏🙏🙏**.
 
 [【指路】教程：使用GitHub Actions下载禁漫本子](./assets/docs/sources/tutorial/1_github_actions.md)
 
 [【指路】教程：导出并下载你的禁漫收藏夹数据](./assets/docs/sources/tutorial/10_export_favorites.md)
 
-**友情提示：珍爱JM，为了减轻JM的服务器压力，请不要一次性爬取太多本子，西门🙏🙏🙏**.
 
 ## 项目介绍
 
@@ -47,11 +65,11 @@
 
 ### 1. 下载本子方法
 
-只需要使用如下代码，就可以下载本子`JM422866`的所有章节的图片：
+只需要使用如下代码，就可以下载本子`JM123`的所有章节的图片：
 
 ```python
 import jmcomic  # 导入此模块，需要先安装.
-jmcomic.download_album('422866')  # 传入要下载的album的id，即可下载整个album到本地.
+jmcomic.download_album('123')  # 传入要下载的album的id，即可下载整个album到本地.
 ```
 
 上面的 `download_album`方法还有一个参数`option`，可用于控制下载配置，配置包括禁漫域名、网络代理、图片格式转换、插件等等。
@@ -80,8 +98,8 @@ import jmcomic
 # 创建配置对象
 option = jmcomic.create_option_by_file('你的配置文件路径，例如 D:/option.yml')
 # 使用option对象来下载本子
-jmcomic.download_album(422866, option)
-# 等价写法: option.download_album(422866)
+jmcomic.download_album(123, option)
+# 等价写法: option.download_album(123)
 ```
 
 ### 3. 使用命令行
@@ -91,10 +109,10 @@ jmcomic.download_album(422866, option)
 
 示例：
 
-下载本子422866的命令
+下载本子123的命令
 
 ```sh
-jmcomic 422866
+jmcomic 123
 ```
 同时下载本子123, 章节456的命令
 ```sh
@@ -142,7 +160,7 @@ jmcomic 123
 
   - 不配置也能使用，十分方便
   - 配置可以从配置文件生成，支持多种文件格式
-  - 配置点有：`请求域名` `客户端实现` `是否使用磁盘缓存` `同时下载的章节/图片数量` `图片格式转换` `下载路径规则` `请求元信息（headers,cookies,proxies）`
+  - 配置点有：`请求域名` `客户端实现` `是否使用磁盘缓存` `同时下载的章节/图片数量` `图片格式转换` `下载路径规则` `请求元信息（headers,cookies,proxies)` `中文繁/简转换` 
     等
 - **可扩展性强**
 
@@ -165,7 +183,7 @@ jmcomic 123
 
 ## 使用小说明
 
-* Python >= 3.7
+* Python >= 3.7，建议3.9以上，因为jmcomic的依赖库可能会不支持3.9以下的版本。
 * 个人项目，文档和示例会有不及时之处，可以Issue提问
 
 ## 项目文件夹介绍

assets/docs/sources/option_file_syntax.md

@@ -109,12 +109,23 @@ dir_rule:
   # 规则: 根目录 / 本子id / 章节序号 / 图片文件
   # rule: 'Bd  / Aid   / Pindex'
   # rule: 'Bd_Aid_Pindex'
-
   # 默认规则是: 根目录 / 章节标题 / 图片文件
-  rule: Bd_Ptitle
+  rule: Bd / Ptitle
   # jmcomic v2.5.36 以后，支持使用python的f-string的语法组合文件夹名，下为示例
   # rule: Bd / Aauthor / (JM{Aid}-{Pindex})-{Pname}
   # {}大括号里的内容同样是写 Axxx 或 Pxxx，其他语法自行参考python f-string的语法
+  # 另外，rule开头的Bd可忽略不写，因为程序会自动插入Bd
+
+  # normalize_zh: 可选。控制是否对目录/文件名中的中文进行繁简体规范化。
+  #   - None（默认）：不做任何转换，保持历史行为
+  #   - zh-cn：将中文文本规范为简体
+  #   - zh-tw：将中文文本规范为繁体
+  # 该功能依赖可选库 `zhconv`（非必需），若未安装或转换失败，程序会回退到原字符串并继续工作，不会影响下载流程。
+  # 示例：
+  # dir_rule:
+  #   base_dir: D:/a/b/c/
+  #   rule: Bd / Ptitle
+  #   normalize_zh: zh-cn
 ```
 
 ## 3. option插件配置项
@@ -194,6 +205,15 @@ plugins:
         album_photo_dict:
           324930: 424507
 
+  before_album:
+    - plugin: download_cover # 额外下载本子封面的插件
+      kwargs:
+        size: '_3x4' # 可选项，禁漫搜索页的封面图尺寸是 4x3，和详情页不一样，想下搜索页的封面就设置此项
+        dir_rule: # 封面图存放路径规则，写法同上
+          base_dir: D:/a/b/c/
+          rule: '{Atitle}/{Aid}_cover.jpg'
+    
+
   after_album:
     - plugin: zip # 压缩文件插件
       kwargs:
@@ -279,6 +299,8 @@ plugins:
       kwargs:
         pdf_dir: D:/pdf/ # pdf存放文件夹
         filename_rule: Pid # pdf命名规则，P代表photo, id代表使用photo.id也就是章节id
+        encrypt: # pdf密码，可选配置项
+          password: 123 # 密码
 
     # img2pdf也支持合并整个本子，把上方的after_photo改为after_album即可。
     # https://github.com/hect0x7/JMComic-Crawler-Python/discussions/258

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

@@ -38,7 +38,7 @@ download_album(123, option)
 option.download_album(123)
 ```
 
-## 获取本子/章节/图片的实体类，下载图片
+## 获取本子/章节/图片的实体类，下载图片/封面图
 
 ```python
 from jmcomic import *
@@ -49,23 +49,26 @@ client = JmOption.default().new_jm_client()
 # 本子实体类
 album: JmAlbumDetail = client.get_album_detail('427413')
 
+# 下载本子封面图，保存为 cover.png （图片后缀可指定为jpg、webp等）
+client.download_album_cover('427413', './cover.png')
+
 
 def fetch(photo: JmPhotoDetail):
     # 章节实体类
     photo = client.get_photo_detail(photo.photo_id, False)
     print(f'章节id: {photo.photo_id}')
-    
+
     # 图片实体类
     image: JmImageDetail
     for image in photo:
         print(f'图片url: {image.img_url}')
-        
+
     # 下载单个图片
     client.download_by_image_detail(image, './a.jpg')
     # 如果是已知未混淆的图片，也可以直接使用url来下载
     random_image_domain = JmModuleConfig.DOMAIN_IMAGE_LIST[0]
     client.download_image(f'https://{random_image_domain}/media/albums/416130.jpg', './a.jpg')
-    
+
 
 # 多线程发起请求
 multi_thread_launcher(
@@ -126,6 +129,8 @@ client = JmOption.default().new_jm_client()
 
 # 分页查询，search_site就是禁漫网页上的【站内搜索】
 page: JmSearchPage = client.search_site(search_query='+MANA +无修正', page=1)
+print(f'结果总数: {page.total}, 分页大小: {page.page_size}，页数: {page.page_count}')
+
 # page默认的迭代方式是page.iter_id_title()，每次迭代返回 albun_id, title
 for album_id, title in page:
     print(f'[{album_id}]: {title}')
@@ -168,10 +173,10 @@ from jmcomic import *
 
 option = JmOption.default()
 client = option.new_jm_client()
-client.login('用户名', '密码') # 也可以使用login插件/配置cookies
+client.login('用户名', '密码')  # 也可以使用login插件/配置cookies
 
 # 遍历全部收藏的所有页
-for page in cl.favorite_folder_gen(): # 如果你只想获取特定收藏夹，需要添加folder_id参数
+for page in client.favorite_folder_gen():  # 如果你只想获取特定收藏夹，需要添加folder_id参数
     # 遍历每页结果
     for aid, atitle in page.iter_id_title():
         # aid: 本子的album_id
@@ -183,9 +188,9 @@ for page in cl.favorite_folder_gen(): # 如果你只想获取特定收藏夹，
 
 # 获取特定收藏夹的单页，使用favorite_folder方法
 page = client.favorite_folder(page=1,
-                          order_by=JmMagicConstants.ORDER_BY_LATEST,
-                          folder_id='0' # 收藏夹id
-                          )
+                              order_by=JmMagicConstants.ORDER_BY_LATEST,
+                              folder_id='0'  # 收藏夹id
+                              )
 ```
 
 ## 分类 / 排行榜
@@ -214,7 +219,7 @@ page: JmCategoryPage = cl.categories_filter(
     page=1,
     time=JmMagicConstants.TIME_ALL,  # 时间选择全部，具体可以写什么请见JmMagicConstants
     category=JmMagicConstants.CATEGORY_ALL,  # 分类选择全部，具体可以写什么请见JmMagicConstants
-    order_by=JmMagicConstants.ORDER_BY_LATEST,  # 按照观看数排序，具体可以写什么请见JmMagicConstants
+    order_by=JmMagicConstants.ORDER_BY_VIEW,  # 按照观看数排序，具体可以写什么请见JmMagicConstants
 )
 
 # 月排行，底层实现也是调的categories_filter

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

@@ -102,6 +102,8 @@ def custom_album_photo_image_detail_class():
     dir_rule:
         base_dir: ${workspace}
         rule: Bd_Acustom_Pcustom
+        # 可选：对目录名进行繁/简体规范化（None/zh-cn/zh-tw），默认不启用
+        # normalize_zh: zh-cn
     
     上面的Acustom，Pcustom都是自定义字段
     如果你想要使用这种自定义字段，你就需要替换默认的实体类，方式如下

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

@@ -58,6 +58,26 @@ D:/a/b/c/ddd/00003.webp
 除了Pxxx，你还可以写Axxx，表示这个章节所在的本子的属性xxx，详见本子实体类 JmAlbumDetail。
 
 
+## 1.1 简繁体统一（normalize_zh）
+
+在一些源站中，同一作品或章节名称可能存在简体/繁体差异，导致在不同环境下生成重复或不一致的文件夹名。v2.6.10 引入了 `dir_rule.normalize_zh` 配置，用于可选地对目录名进行繁/简体规范化。
+
+示例用法：
+
+```yaml
+dir_rule:
+  base_dir: D:/a/b/c/
+  rule: Bd / Ptitle
+  normalize_zh: zh-cn # 可选值：None（默认，不转换）/ zh-cn / zh-tw
+```
+
+说明：
+
+- 当 `normalize_zh` 为 `zh-cn` 时，会把目录名中的中文规范为简体；为 `zh-tw` 时规范为繁体；为 `None` 或不配置时维持历史行为（不转换）。
+
+- 该功能依赖可选库 `zhconv`（非必需），若未安装或转换失败，系统会回退为原始字符串并继续下载，不会导致失败。
+
+
 ## 2. 自定义字段名
 
 上述例子使用了title字段，如果你想自定义一个字段，然后在DirRule中使用自定义字段，该怎么做？

assets/option/option_test_api.yml

@@ -1,6 +1,7 @@
 # GitHub Actions 测试用
 # 移动端配置
 dir_rule:
+  normalize_zh: zh-cn
   rule: Bd_Aauthor_Aid_Pindextitle
 
 client:
@@ -25,4 +26,10 @@ plugins:
     - plugin: client_proxy
       kwargs:
         proxy_client_key: photo_concurrent_fetcher_proxy
-        whitelist: [ api, ]
+        whitelist: [ api, ]
+
+    - plugin: advanced_retry
+      kwargs:
+        retry_config:
+          retry_rounds: 3 # 一共对域名列表重试3轮
+          retry_domain_max_times: 5 # 当一个域名重试次数超过5次，忽略该域名，不再重试