feat(image): 增加对 JPEG 和 HEIC 图片格式的支持

- 在图片下载功能中添加了对 JPEG 和 HEIC 格式的支持
- 更新了相关模块和文档以支持新功能

Closes #229

README.md

@@ -116,6 +116,7 @@
 <h1>🖥 服务器模式</h1>
 <p><b>启动：</b>运行命令：<code>python .\main.py server</code></p>
 <p><b>关闭：</b>按下 <code>Ctrl</code> + <code>C</code> 关闭服务器</p>
+<p>访问 <code>http://127.0.0.1:8000/docs</code>；你会看到自动生成的交互式 API 文档！</p>
 <p><b>请求接口：</b><code>/xhs/</code></p>
 <p><b>请求方法：</b><code>POST</code></p>
 <p><b>请求格式：</b><code>JSON</code></p>
@@ -224,7 +225,7 @@ async def example():
     chunk = 1024 * 1024 * 10  # 下载文件时，每次从服务器获取的数据块大小，单位：字节
     max_retry = 2  # 请求数据失败时，重试的最大次数，单位：秒，默认值：5
     record_data = False  # 是否保存作品数据至文件
-    image_format = "WEBP"  # 图文作品文件下载格式，支持：PNG、WEBP
+    image_format = "WEBP"  # 图文作品文件下载格式，支持：AUTO、PNG、WEBP、JPEG、HEIC
     folder_mode = False  # 是否将每个作品的文件储存至单独的文件夹
     image_download = True  # 图文作品文件下载开关
     video_download = True  # 视频作品文件下载开关
@@ -341,7 +342,7 @@ async def example():
 <tr>
 <td align="center">image_format</td>
 <td align="center">str</td>
-<td align="center">图文作品文件下载格式，支持：<code>PNG</code>、<code>WEBP</code><br><strong>该参数影响下载图片时所用的接口，并非固定图片格式！</strong></td>
+<td align="center">图文作品文件下载格式，支持：<code>AUTO</code>、<code>PNG</code>、<code>WEBP</code>、<code>JPEG</code>、<code>HEIC</code><br><strong>部分作品没有 <code>HEIC</code> 格式的文件，此时下载的文件可能为 <code>WEBP</code> 格式！</strong><br><strong>设置为 <code>AUTO</code> 时表示动态格式，实际格式取决于服务器响应数据！</strong></td>
 <td align="center">PNG</td>
 </tr>
 <tr>

README_EN.md

@@ -117,6 +117,7 @@
 <h1>🖥 Server Mode</h1>
 <p><b>Start:</b> Run the command: <code>python .\main.py server</code></p>
 <p><b>Stop:</b> Press <code>Ctrl</code> + <code>C</code> to stop the server</p>
+<p>Open <code>http://127.0.0.1:8000/docs</code>; you will see automatically generated interactive API documentation!</p>
 <p><b>Request endpoint:</b>
 <code>/xhs/</code></p>
 <p><b>Request method:</b>
@@ -228,7 +229,7 @@ async def example():
     chunk = 1024 * 1024 * 10  # 下载文件时，每次从服务器获取的数据块大小，单位：字节
     max_retry = 2  # 请求数据失败时，重试的最大次数，单位：秒，默认值：5
     record_data = False  # 是否保存作品数据至文件
-    image_format = "WEBP"  # 图文作品文件下载格式，支持：PNG、WEBP
+    image_format = "WEBP"  # 图文作品文件下载格式，支持：AUTO、PNG、WEBP、JPEG、HEIC
     folder_mode = False  # 是否将每个作品的文件储存至单独的文件夹
     image_download = True  # 图文作品文件下载开关
     video_download = True  # 视频作品文件下载开关
@@ -345,13 +346,13 @@ async def example():
 <tr>
 <td align="center">image_format</td>
 <td align="center">str</td>
-<td align="center">Download format for text and image works files, supported formats: <code>PNG</code>, <code>WEBP</code><br><strong>This parameter affects the API used when downloading images, not the fixed image format!</strong></td>
+<td align="center">Download format for image works files, supported: <code>AUTO</code>、<code>PNG</code>、<code>WEBP</code>、<code>JPEG</code>、<code>HEIC</code><br><strong>Some works do not have files in HEIC format, and the downloaded files may be in WEBP format</strong><br><strong>When set to<code>AUTO</code>, it represents dynamic format, and the actual format depends on the server's response data</strong></td>
 <td align="center">PNG</td>
 </tr>
 <tr>
 <td align="center">image_download</td>
 <td align="center">bool</td>
-<td align="center">Switch for downloading text and image works files</td>
+<td align="center">Switch for downloading image works files</td>
 <td align="center">true</td>
 </tr>
 <tr>

example.py

@@ -1,5 +1,7 @@
 from asyncio import run
 
+from rich import print
+
 from source import XHS
 
 
@@ -19,7 +21,7 @@ async def example():
     chunk = 1024 * 1024 * 10  # 下载文件时，每次从服务器获取的数据块大小，单位：字节
     max_retry = 2  # 请求数据失败时，重试的最大次数，单位：秒，默认值：5
     record_data = False  # 是否保存作品数据至文件
-    image_format = "WEBP"  # 图文作品文件下载格式，支持：PNG、WEBP
+    image_format = "WEBP"  # 图文作品文件下载格式，支持：AUTO、PNG、WEBP、JPEG、HEIC
     folder_mode = False  # 是否将每个作品的文件储存至单独的文件夹
     image_download = True  # 图文作品文件下载开关
     video_download = True  # 视频作品文件下载开关
@@ -59,11 +61,19 @@ async def example():
 
 async def test():
     url = ""
-    async with XHS() as xhs:
+    async with XHS(
+            download_record=False,
+            # image_format="PNG",
+            # image_format="WEBP",
+            # image_format="JPEG",
+            # image_format="HEIC",
+            # image_format="AVIF",
+            # image_format="AUTO",
+    ) as xhs:
         print(
             await xhs.extract(
                 url,
-                download=True,
+                # download=True,
             )
         )
 

source/TUI/setting.py

@@ -173,7 +173,7 @@ def compose(self) -> ComposeResult:
             Label(),
             Container(
                 Select.from_values(
-                    ("PNG", "WEBP"),
+                    ("AUTO", "PNG", "WEBP", "JPEG", "HEIC"),
                     value=self.data["image_format"].upper(),
                     allow_blank=False,
                     id="image_format",

source/application/app.py

@@ -34,6 +34,7 @@
     VERSION_MAJOR,
     VERSION_MINOR,
     VERSION_BETA,
+    __VERSION__
 )
 from source.module import logging
 from source.module import sleep_time
@@ -47,7 +48,7 @@
 __all__ = ["XHS"]
 
 
-def _data_cache(function):
+def data_cache(function):
     async def inner(
             self,
             data: dict,
@@ -179,7 +180,7 @@ async def __download_files(
             logging(log, _("提取作品文件下载地址失败"), ERROR)
         await self.save_data(container)
 
-    @_data_cache
+    @data_cache
     async def save_data(
             self,
             data: dict,
@@ -480,7 +481,7 @@ async def run_server(
         self.server = FastAPI(
             debug=self.VERSION_BETA,
             title="XHS-Downloader",
-            version=f"{self.VERSION_MAJOR}.{self.VERSION_MINOR}",
+            version=__VERSION__,
         )
         self.setup_routes()
         config = Config(

source/application/image.py

@@ -14,24 +14,24 @@ def get_image_link(cls, data: Namespace, format_: str) -> [list, list]:
             for i in images
         ]
         match format_:
-            case "png":
+            case "png" | "webp" | "jpeg" | "heic" | "avif":
                 return [
-                    Html.format_url(cls.__generate_png_link(i)) for i in token_list
+                    Html.format_url(cls.__generate_fixed_link(i, format_, )) for i in token_list
                 ], live_link
-            case "webp":
+            case "auto":
                 return [
-                    Html.format_url(cls.__generate_webp_link(i)) for i in token_list
+                    Html.format_url(cls.__generate_auto_link(i)) for i in token_list
                 ], live_link
             case _:
                 raise ValueError
 
     @staticmethod
-    def __generate_webp_link(token: str) -> str:
+    def __generate_auto_link(token: str) -> str:
         return f"https://sns-img-bd.xhscdn.com/{token}"
 
     @staticmethod
-    def __generate_png_link(token: str) -> str:
-        return f"https://ci.xiaohongshu.com/{token}?imageView2/format/png"
+    def __generate_fixed_link(token: str, format_: str, ) -> str:
+        return f"https://ci.xiaohongshu.com/{token}?imageView2/format/{format_}"
 
     @staticmethod
     def __extract_image_token(url: str) -> str:

source/module/__init__.py

@@ -29,6 +29,7 @@
     FILE_SIGNATURES,
     FILE_SIGNATURES_LENGTH,
     MAX_WORKERS,
+    __VERSION__,
 )
 from .tools import (
     retry,

source/module/manager.py

@@ -138,8 +138,8 @@ def __check_root_again(root: Path) -> bool | Path:
 
     @staticmethod
     def __check_image_format(image_format) -> str:
-        if image_format in {"png", "PNG", "webp", "WEBP"}:
-            return image_format.lower()
+        if (i := image_format.lower()) in {"auto", "png", "webp", "jpeg", "heic", "avif", }:
+            return i
         return "png"
 
     @staticmethod

source/module/static.py

@@ -3,7 +3,7 @@
 VERSION_MAJOR = 2
 VERSION_MINOR = 5
 VERSION_BETA = True
-__version__ = f"{VERSION_MAJOR}.{VERSION_MINOR}.{'beta' if VERSION_BETA else 'stable'}"
+__VERSION__ = f"{VERSION_MAJOR}.{VERSION_MINOR}.{'beta' if VERSION_BETA else 'stable'}"
 ROOT = Path(__file__).resolve().parent.parent.parent
 PROJECT = f"XHS-Downloader V{VERSION_MAJOR}.{VERSION_MINOR} {
 'Beta' if VERSION_BETA else 'Stable'
@@ -68,4 +68,4 @@
 MAX_WORKERS: int = 4
 
 if __name__ == "__main__":
-    print(__version__)
+    print(__VERSION__)

static/Release_Notes.md

@@ -1,6 +1,7 @@
 **项目更新内容：**
 
-1. 支持 SOCKS 代理
+1. 增加对 `JPEG` 和 `HEIC` 图片格式的支持
+2. 支持 `SOCKS` 代理
 
 *****