parsehub 2.3.12__tar.gz → 2.3.13__tar.gz

{parsehub-2.3.12/src/parsehub.egg-info → parsehub-2.3.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: parsehub
-Version: 2.3.12
+Version: 2.3.13
 Summary: 轻量、异步、开箱即用的社交媒体聚合解析库
 Author-email: 梓澪 <zilingmio@gmail.com>
 License: MIT
@@ -22,7 +22,7 @@ Requires-Dist: pydub>=0.25.1
 Requires-Dist: python-dotenv>=1.0.1
 Requires-Dist: tenacity>=8.5.0
 Requires-Dist: urlextract>=1.9.0
-Requires-Dist: yt-dlp[default]>=2026.8.18.122307.dev0
+Requires-Dist: yt-dlp[default]>=2026.10.10.233141.dev0
 Requires-Dist: lxml>=5.3.0
 Requires-Dist: pydantic>=1.10.19
 Requires-Dist: markdownify>=1.1.0

{parsehub-2.3.12 → parsehub-2.3.13}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "parsehub"
-version = "2.3.12"
+version = "2.3.13"
 description = "轻量、异步、开箱即用的社交媒体聚合解析库"
 readme = "README.md"
 requires-python = ">=3.12.0"
@@ -25,7 +25,7 @@ dependencies = [
     "python-dotenv>=1.0.1",
     "tenacity>=8.5.0",
     "urlextract>=1.9.0",
-    "yt-dlp[default]>=2026.8.18.122307.dev0",
+    "yt-dlp[default]>=2026.10.10.233141.dev0",
     "lxml>=5.3.0",
     "pydantic>=1.10.19",
     "markdownify>=1.1.0",

{parsehub-2.3.12 → parsehub-2.3.13}/src/parsehub/errors.py

@@ -76,6 +76,21 @@ class DownloadError(ParseHubError):
     """下载错误"""
 
     MSG = __doc__
+    status_code: int | None = None
+
+    def __init__(self, msg: str = "", *, status_code: int | None = None, cookie: "SecretCookie | None" = None):
+        super().__init__(msg, cookie=cookie)
+        self.status_code = status_code
+
+
+class DownloadFallbackError(DownloadError):
+    """所有下载地址均失败"""
+
+    MSG = __doc__
+
+    def __init__(self, attempts: list[FallbackAttempt]):
+        self.attempts = attempts
+        Exception.__init__(self, f"{self.MSG}:\n{format_attempts(attempts)}")
 
 
 class DeleteError(ParseHubError):

{parsehub-2.3.12 → parsehub-2.3.13}/src/parsehub/parsers/base/base.py

@@ -2,13 +2,11 @@ import importlib
 import pkgutil
 import re
 from abc import ABC, abstractmethod
-from collections.abc import Awaitable, Callable
-from dataclasses import dataclass
-from typing import Any, Generic, TypeVar
+from collections.abc import Callable
+from typing import Any, TypeVar
 from urllib.parse import parse_qs, urlencode, urlparse
 
 import httpx
-from loguru import logger
 
 from ... import parsers
 from ...errors import ParseHubError
@@ -21,18 +19,12 @@ from ...types import (
     ParseError,
 )
 from ...types.platform import Platform
+from ...utils.fallback import FallbackStage, run_fallback
 from ...utils.helpers import UA, SecretCookie, match_url
 
 T = TypeVar("T")
 
 
-@dataclass(frozen=True)
-class FallbackStage(Generic[T]):  # noqa: UP046
-    name: str
-    func: Callable[[], Awaitable[T]]
-    cookie: bool = False
-
-
 def _attach_cookie(e: Exception, cookie: SecretCookie) -> Exception:
     if isinstance(e, (ContentUnavailableError, FallbackError)):
         return e
@@ -118,30 +110,20 @@ class BaseParser(ABC):
         *stages: FallbackStage[T],
         stop: Callable[[Exception], bool] = is_content_unavailable,
     ) -> T:
-        attempts: list[FallbackAttempt] = []
-        for stage in stages:
-            try:
-                result = await stage.func()
-            except Exception as e:
-                logger.opt(exception=e).debug(f"{self.__platform__} {stage.name} 解析失败")
-                should_stop = stop(e)
-                err = _attach_cookie(e, self.cookie if stage.cookie else SecretCookie())
-                if should_stop:
-                    if err is e:
-                        raise
-                    raise err from e
-                attempts.append(FallbackAttempt(stage.name, err, stage.cookie))
-            else:
-                self._fallback_attempts.extend(attempts)
-                return result
-
-        if len(attempts) == 1:
-            raise attempts[0].error
-        last_error = attempts[-1].error
-        error_type = (
-            ContentUnavailableFallbackError if isinstance(last_error, ContentUnavailableError) else FallbackError
+        def exhausted(attempts: list[FallbackAttempt]) -> FallbackError:
+            if isinstance(attempts[-1].error, ContentUnavailableError):
+                return ContentUnavailableFallbackError(attempts)
+            return FallbackError(attempts)
+
+        result, attempts = await run_fallback(
+            stages,
+            stop=stop,
+            wrap=lambda e, stage: _attach_cookie(e, self.cookie if stage.cookie else SecretCookie()),
+            exhausted=exhausted,
+            label=f"{self.__platform__} 解析",
         )
-        raise error_type(attempts) from last_error
+        self._fallback_attempts.extend(attempts)
+        return result
 
     @abstractmethod
     async def _do_parse(self, raw_url: str) -> AnyParseResult:

{parsehub-2.3.12 → parsehub-2.3.13}/src/parsehub/parsers/base/ytdlp.py

@@ -499,7 +499,7 @@ class YtVideoParseResult(VideoParseResult):
 
         v = [p for p in output_dir_path.glob(f"{self.name}.*") if p.is_file()]
         if not v:
-            raise DownloadError("下载失败: 未找到下载后的视频文件")
+            raise DownloadError("未找到下载后的视频文件")
 
         if callback:
             await callback(100, 100, "bytes", *callback_args, **callback_kwargs)
@@ -540,7 +540,7 @@ class YtVideoParseResult(VideoParseResult):
                 callback_kwargs=callback_kwargs,
             )
         except Exception as e:
-            raise DownloadError(f"下载失败: {str(e)}") from e
+            raise DownloadError(str(e)) from e
 
 
 @dataclass

{parsehub-2.3.12 → parsehub-2.3.13}/src/parsehub/parsers/parser/douyin.py

@@ -116,15 +116,12 @@ def remove_video_watermark(url: str) -> str:
     return url.replace("playwm", "play")
 
 
-def _p_play_addr(video_data: dict) -> tuple[str | None, int, int]:
+def _p_play_addr(video_data: dict) -> tuple[list[str], int, int]:
     play_addr = video_data["play_addr"]
-    url_list = play_addr["url_list"]
-    if not url_list:
-        return None, 0, 0
-    return url_list[0], play_addr.get("width", 0), play_addr.get("height", 0)
+    return play_addr["url_list"], play_addr.get("width", 0), play_addr.get("height", 0)
 
 
-def _p_bit_rates(video_data: dict, filter_bytevc1: bool = False) -> tuple[str, int, int]:
+def _p_bit_rates(video_data: dict, filter_bytevc1: bool = False) -> tuple[list[str], int, int]:
     bit_rates: list = video_data.get("bit_rate", [])
     if filter_bytevc1:
         bit_rates = list(filter(lambda i: i.get("is_bytevc1", 0) == 0, bit_rates))
@@ -139,20 +136,19 @@ def _p_bit_rates(video_data: dict, filter_bytevc1: bool = False) -> tuple[str, i
     best_quality = bit_rates[0]
 
     play_addr = best_quality.get("play_addr", {})
-    url_list = play_addr.get("url_list", [])
-    return url_list[0], play_addr.get("width", 0), play_addr.get("height", 0)
+    return play_addr.get("url_list", []), play_addr.get("width", 0), play_addr.get("height", 0)
 
 
 def parse_video_info(video_data: dict) -> dict:
     is_app = video_data.get("is_bytevc1", None) is not None  # 只有 app 接口带 is_bytevc1 参数
     if is_app:
-        u, w, h = _p_play_addr(video_data)
-        if not u:
-            u, w, h = _p_bit_rates(video_data, True)
+        urls, w, h = _p_play_addr(video_data)
+        if not urls:
+            urls, w, h = _p_bit_rates(video_data, True)
     else:
-        u, w, h = _p_bit_rates(video_data)
+        urls, w, h = _p_bit_rates(video_data)
 
-    video_url = remove_video_watermark(u)
+    video_url, *backup_urls = dict.fromkeys(remove_video_watermark(u) for u in urls)
 
     cover = video_data.get("cover", {})
     thumb_url_list = cover.get("url_list", [])
@@ -160,6 +156,7 @@ def parse_video_info(video_data: dict) -> dict:
 
     return {
         "video_url": video_url,
+        "backup_urls": backup_urls,
         "thumb_url": thumb_url,
         "duration": video_data.get("duration", 0),
         "width": w,
@@ -288,6 +285,7 @@ class DouyinApiResult:
             type=DouyinMediaType.VIDEO,
             video=VideoRef(
                 url=video_info["video_url"],
+                backup_urls=video_info["backup_urls"],
                 thumb_url=video_info["thumb_url"],
                 width=video_info["width"],
                 height=video_info["height"],

{parsehub-2.3.12 → parsehub-2.3.13}/src/parsehub/types/__init__.py

@@ -2,6 +2,7 @@ from ..errors import (
     ContentUnavailableError,
     ContentUnavailableFallbackError,
     DownloadError,
+    DownloadFallbackError,
     FallbackAttempt,
     FallbackError,
     ParseError,
@@ -23,6 +24,7 @@ from .result import (
 
 __all__ = [
     "DownloadError",
+    "DownloadFallbackError",
     "ParseError",
     "ContentUnavailableError",
     "FallbackAttempt",

{parsehub-2.3.12 → parsehub-2.3.13}/src/parsehub/types/media_ref.py

@@ -1,4 +1,4 @@
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 
 
 @dataclass(kw_only=True)
@@ -10,6 +10,7 @@ class MediaRef:
         thumb_url: 缩略图 URL
         width: 宽度
         height: 高度
+        backup_urls: 备用下载链接, 与 url 是同一个文件, url 下载失败时按顺序尝试
     """
 
     url: str
@@ -17,6 +18,7 @@ class MediaRef:
     thumb_url: str | None = None
     width: int = 0
     height: int = 0
+    backup_urls: list[str] = field(default_factory=list)
 
 
 @dataclass(kw_only=True)

{parsehub-2.3.12 → parsehub-2.3.13}/src/parsehub/types/result.py

@@ -7,6 +7,7 @@ from collections.abc import Sequence
 from dataclasses import asdict
 from pathlib import Path
 from typing import Any, ClassVar
+from urllib.parse import urlparse
 
 import aiofiles
 from bs4 import BeautifulSoup
@@ -14,8 +15,9 @@ from markdown import markdown as md_to_html
 from slugify import slugify
 
 from ..config import GlobalConfig
-from ..errors import DeleteError, DownloadError, FallbackAttempt
+from ..errors import DeleteError, DownloadError, DownloadFallbackError, FallbackAttempt
 from ..utils.downloader import download
+from ..utils.fallback import FallbackStage, run_fallback
 from ..utils.helpers import run_sync
 from .callback import ProgressCallback
 from .media_file import AniFile, AnyMediaFile, ImageFile, LivePhotoFile, VideoFile
@@ -80,6 +82,10 @@ class ParseResult(ABC):  # noqa: B024
             "media": media,
         }
 
+    def _download_stop(self, e: Exception) -> bool:
+        """下载失败时是否不再尝试后面的备用链接, 平台可覆盖"""
+        return False
+
     async def _do_download(
         self,
         *,
@@ -109,6 +115,7 @@ class ParseResult(ABC):  # noqa: B024
         media_list = list(self.media) if isinstance(self.media, Sequence) else [self.media]
         is_single = not isinstance(self.media, Sequence)
         concurrency = max(1, concurrency)
+        fallback_errors: list[FallbackAttempt] = []
 
         async def _download_media(
             media: AnyMediaRef,
@@ -117,19 +124,30 @@ class ParseResult(ABC):  # noqa: B024
             progress_args: tuple = (),
             progress_kwargs: dict | None = None,
         ) -> AnyMediaFile:
-            try:
-                f = await download(
-                    media.url,
-                    output_dir.joinpath(f"{stem}.{media.ext}"),
-                    headers=headers,
-                    proxy=proxy,
-                    progress=progress,
-                    progress_args=progress_args,
-                    progress_kwargs=progress_kwargs,
-                    connections=connections,
+            def _stage(i: int, url: str) -> FallbackStage[str]:
+                return FallbackStage(
+                    f"#{i + 1} {urlparse(url).hostname}",
+                    lambda: download(
+                        url,
+                        output_dir.joinpath(f"{stem}.{media.ext}"),
+                        headers=headers,
+                        proxy=proxy,
+                        progress=progress,
+                        progress_args=progress_args,
+                        progress_kwargs=progress_kwargs,
+                        connections=connections,
+                    ),
                 )
-            except Exception as e:
-                raise DownloadError(f"下载失败: {e}") from e
+
+            urls = list(dict.fromkeys([media.url, *media.backup_urls]))
+            f, attempts = await run_fallback(
+                [_stage(i, url) for i, url in enumerate(urls)],
+                stop=self._download_stop,
+                wrap=lambda e, _: e if isinstance(e, DownloadError) else DownloadError(f"{type(e).__name__}: {e}"),
+                exhausted=DownloadFallbackError,
+                label=f"{self.platform.display_name if self.platform else ''} 下载",
+            )
+            fallback_errors.extend(attempts)
 
             mf: AnyMediaFile
             match media:
@@ -150,8 +168,12 @@ class ParseResult(ABC):  # noqa: B024
                                 proxy=proxy,
                                 connections=connections,
                             )
+                        except DownloadError as e:
+                            raise DownloadError(
+                                f"LivePhoto 视频{e.message.removeprefix(DownloadError.MSG)}", status_code=e.status_code
+                            ) from e
                         except Exception as e:
-                            raise DownloadError(f"LivePhoto 视频下载失败: {e}") from e
+                            raise DownloadError(f"LivePhoto 视频: {type(e).__name__}: {e}") from e
                         else:
                             mf.video_path = vf
 
@@ -182,7 +204,7 @@ class ParseResult(ABC):  # noqa: B024
             except DownloadError:
                 shutil.rmtree(output_dir, ignore_errors=True)
                 raise
-            return DownloadResult(mf, output_dir)
+            return DownloadResult(mf, output_dir, fallback_errors)
 
         n = len(media_list)
         results: list[AnyMediaFile | None] = [None] * n
@@ -210,7 +232,7 @@ class ParseResult(ABC):  # noqa: B024
             raise
 
         result_list = [media for media in results if media is not None]
-        return DownloadResult(result_list, output_dir)
+        return DownloadResult(result_list, output_dir, fallback_errors)
 
     async def download(
         self,
@@ -413,14 +435,21 @@ class RichTextParseResult(ParseResult):
 
 
 class DownloadResult:
-    def __init__(self, media: AnyMediaFile | Sequence[AnyMediaFile], output_dir: str | Path):
+    def __init__(
+        self,
+        media: AnyMediaFile | Sequence[AnyMediaFile],
+        output_dir: str | Path,
+        fallback_errors: list[FallbackAttempt] | None = None,
+    ):
         """
         下载结果
         :param media: 本地媒体路径
         :param output_dir: 输出目录
+        :param fallback_errors: 下载成功前失败的链接
         """
         self.media = media
         self.output_dir = Path(output_dir).resolve()
+        self.fallback_errors = fallback_errors or []
 
     def delete(self) -> None:
         try:

{parsehub-2.3.12 → parsehub-2.3.13}/src/parsehub/utils/downloader.py

@@ -96,7 +96,9 @@ class SegmentDownloader:
             except httpx.HTTPStatusError as e:
                 last_error = e
                 if attempt == self.max_retries or not _is_retryable_status(e.response.status_code):
-                    raise DownloadError(f"HTTP错误: {e.response.status_code}") from e
+                    raise DownloadError(
+                        f"HTTP错误: {e.response.status_code}", status_code=e.response.status_code
+                    ) from e
             except (httpx.TimeoutException, httpx.NetworkError, httpx.RemoteProtocolError, httpx.ReadError) as e:
                 last_error = e
                 if attempt == self.max_retries:
@@ -104,7 +106,7 @@ class SegmentDownloader:
             except Exception as e:
                 last_error = e
                 if attempt == self.max_retries:
-                    raise DownloadError(f"下载失败: {e}") from e
+                    raise DownloadError(f"{type(e).__name__}: {e}" if str(e) else type(e).__name__) from e
 
             await asyncio.sleep(2**attempt)
 
@@ -273,7 +275,9 @@ class SegmentDownloader:
                         raise FallbackToSingle
                     response.raise_for_status()
                     if response.status_code != 206:
-                        raise DownloadError(f"分片下载失败: HTTP {response.status_code}")
+                        raise DownloadError(
+                            f"分片下载失败: HTTP {response.status_code}", status_code=response.status_code
+                        )
                     if _has_non_identity_encoding(response.headers.get("Content-Encoding")):
                         raise FallbackToSingle
                     self._validate_part_response(part, response.headers, total_size)
@@ -293,7 +297,9 @@ class SegmentDownloader:
                 raise
             except httpx.HTTPStatusError as e:
                 if attempt == self.max_retries or not _is_retryable_status(e.response.status_code):
-                    raise DownloadError(f"分片下载失败: HTTP {e.response.status_code}") from e
+                    raise DownloadError(
+                        f"分片下载失败: HTTP {e.response.status_code}", status_code=e.response.status_code
+                    ) from e
             except (httpx.TimeoutException, httpx.NetworkError, httpx.RemoteProtocolError, httpx.ReadError) as e:
                 if attempt == self.max_retries:
                     raise DownloadError(f"分片网络错误: {e}") from e

parsehub-2.3.13/src/parsehub/utils/fallback.py

@@ -0,0 +1,51 @@
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+from loguru import logger
+
+from ..errors import FallbackAttempt
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class FallbackStage(Generic[T]):  # noqa: UP046
+    name: str
+    func: Callable[[], Awaitable[T]]
+    cookie: bool = False
+
+
+async def run_fallback(  # noqa: UP047
+    stages: tuple[FallbackStage[T], ...] | list[FallbackStage[T]],
+    *,
+    stop: Callable[[Exception], bool],
+    wrap: Callable[[Exception, FallbackStage[T]], Exception],
+    exhausted: Callable[[list[FallbackAttempt]], Exception],
+    label: str = "",
+) -> tuple[T, list[FallbackAttempt]]:
+    """依次尝试各层, 返回首个成功的结果和之前失败的记录
+
+    :param stop: 返回 True 则中止回退, 直接抛出该层错误
+    :param wrap: 包装各层的原始错误
+    :param exhausted: 多层全部失败时构造的错误, 只试了一层则透传该层错误
+    :param label: 日志前缀
+    """
+    attempts: list[FallbackAttempt] = []
+    for stage in stages:
+        try:
+            result = await stage.func()
+        except Exception as e:
+            logger.opt(exception=e).debug(f"{label} {stage.name} 失败")
+            err = wrap(e, stage)
+            if stop(e):
+                if err is e:
+                    raise
+                raise err from e
+            attempts.append(FallbackAttempt(stage.name, err, stage.cookie))
+        else:
+            return result, attempts
+
+    if len(attempts) == 1:
+        raise attempts[0].error
+    raise exhausted(attempts) from attempts[-1].error

{parsehub-2.3.12 → parsehub-2.3.13/src/parsehub.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: parsehub
-Version: 2.3.12
+Version: 2.3.13
 Summary: 轻量、异步、开箱即用的社交媒体聚合解析库
 Author-email: 梓澪 <zilingmio@gmail.com>
 License: MIT
@@ -22,7 +22,7 @@ Requires-Dist: pydub>=0.25.1
 Requires-Dist: python-dotenv>=1.0.1
 Requires-Dist: tenacity>=8.5.0
 Requires-Dist: urlextract>=1.9.0
-Requires-Dist: yt-dlp[default]>=2026.8.18.122307.dev0
+Requires-Dist: yt-dlp[default]>=2026.10.10.233141.dev0
 Requires-Dist: lxml>=5.3.0
 Requires-Dist: pydantic>=1.10.19
 Requires-Dist: markdownify>=1.1.0

{parsehub-2.3.12 → parsehub-2.3.13}/src/parsehub.egg-info/SOURCES.txt

@@ -73,6 +73,7 @@ src/parsehub/types/platform.py
 src/parsehub/types/post.py
 src/parsehub/types/result.py
 src/parsehub/utils/downloader.py
+src/parsehub/utils/fallback.py
 src/parsehub/utils/helpers.py
 src/parsehub/utils/media_info.py
 test/test_cli.py

{parsehub-2.3.12 → parsehub-2.3.13}/src/parsehub.egg-info/requires.txt

@@ -5,7 +5,7 @@ pydub>=0.25.1
 python-dotenv>=1.0.1
 tenacity>=8.5.0
 urlextract>=1.9.0
-yt-dlp[default]>=2026.8.18.122307.dev0
+yt-dlp[default]>=2026.10.10.233141.dev0
 lxml>=5.3.0
 pydantic>=1.10.19
 markdownify>=1.1.0

{parsehub-2.3.12 → parsehub-2.3.13}/test/test_core_offline.py

@@ -188,6 +188,7 @@ class TestParseResultToDict(unittest.TestCase):
                     "thumb_url": "https://cdn.example/thumb.jpg",
                     "width": 1920,
                     "height": 1080,
+                    "backup_urls": [],
                     "duration": 90,
                 },
             },
@@ -209,6 +210,7 @@ class TestParseResultToDict(unittest.TestCase):
                     "thumb_url": None,
                     "width": 100,
                     "height": 0,
+                    "backup_urls": [],
                 },
                 {
                     "url": "https://cdn.example/two.jpg",
@@ -216,6 +218,7 @@ class TestParseResultToDict(unittest.TestCase):
                     "thumb_url": None,
                     "width": 0,
                     "height": 0,
+                    "backup_urls": [],
                 },
             ],
         )