wechat-article-parser 0.0.6__tar.gz → 0.0.7__tar.gz

{wechat_article_parser-0.0.6 → wechat_article_parser-0.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: wechat-article-parser
-Version: 0.0.6
+Version: 0.0.7
 Summary: WeChat MP article parser - extract metadata and content from WeChat public account articles
 License-Expression: MIT
 License-File: LICENSE
@@ -26,6 +26,10 @@ Description-Content-Type: text/markdown
 - 小红书风格图片轮播文章
 - 全屏布局短文本文章
 
+解析时优先读取页面全局的 `item_show_type`：`0` 对应图文、`5` 对应视频分享、
+`8` 对应图片轮播、`10` 对应文字消息，再通过 HTML 或脚本数据区分具体模板。
+类型字段缺失、值未知或对应分支未提取到正文时，会按原有 HTML 特征匹配顺序兜底。
+
 ## 安装
 
 ```bash
@@ -108,13 +112,42 @@ result = parse(
 | `article_title` | `str` | 文章标题 |
 | `article_cover_image` | `str` | 文章封面图链接 |
 | `article_description` | `str` | 文章摘要 |
-| `article_markdown` | `str` | 文章正文的 Markdown 内容 |
+| `article_markdown` | `str` | 文章正文的 Markdown 内容；视频分享没有文字附言时可为空 |
 | `article_publish_time` | `int` | 发布时间（Unix 时间戳） |
+| `article_display_type` | `ArticleDisplayType` | 文章展示类型：`article`、`video`、`image`、`text` 或 `unknown` |
 | `raw_html` | `str` | 原始 HTML 网页源代码（仅在 `include_raw_html=True` 时填充，否则为空字符串） |
 | `images` | `list[str]` | 文章中提取的所有图片链接 |
 | `is_valid` | `bool` | 关键字段是否全部解析成功（属性） |
 
-`is_valid` 为 `True` 的条件：`mp_id`、`mp_name`、`article_id`、`article_msg_id`、`article_idx`、`article_sn`、`article_title`、`article_markdown`、`article_publish_time` 均不为空/零。
+`is_valid` 为 `True` 的条件：`mp_id`、`mp_name`、`article_id`、`article_msg_id`、`article_idx`、`article_sn`、`article_title`、`article_publish_time` 均不为空/零，且 `article_markdown` 非空或 `article_display_type == "video"`。视频分享允许没有文字正文，仍须满足其他关键字段要求；有效性不表示已获取视频文件。
+
+### 判断文章展示类型
+
+`ArticleDisplayType` 是字符串枚举，既支持枚举比较，也支持语义字符串比较：
+
+| 枚举 | 字符串值 | 含义 |
+|---|---|---|
+| `ArticleDisplayType.ARTICLE` | `article` | 图文，包括转载式 |
+| `ArticleDisplayType.VIDEO` | `video` | 视频分享 |
+| `ArticleDisplayType.IMAGE` | `image` | 图片轮播 |
+| `ArticleDisplayType.TEXT` | `text` | 文字消息 |
+| `ArticleDisplayType.UNKNOWN` | `unknown` | 页面类型缺失或未支持 |
+
+```python
+from wechat_article_parser import parse, ArticleDisplayType
+
+result = parse("https://mp.weixin.qq.com/s/xxxxx")
+if result.article_display_type == ArticleDisplayType.VIDEO:
+    print("这是视频分享")
+
+if result.article_display_type == "video":
+    print("视频分享可以没有文字正文")
+
+print(result.article_display_type)  # 例如 video
+```
+
+`article_display_type` 是返回结果中的数据字段，包含在 `dataclasses.asdict(result)` 中，JSON 序列化时输出语义字符串。
+微信原始的 `item_show_type` 仅在解析器内部使用，不包含在返回结果中。
 
 ### 判断账号类型
 
@@ -168,7 +201,7 @@ except httpx.HTTPStatusError as e:
 
 ### 解析不完整
 
-部分文章类型可能无法提取所有字段（如某些文章没有封面图或摘要）。这种情况不会抛出异常，但 `result.is_valid` 会返回 `False`。建议在业务逻辑中检查：
+缺少标题、发布时间等关键字段，或非视频分享缺少正文时，解析结果的 `is_valid` 会返回 `False`。封面图、摘要等非必填字段为空不影响有效性。建议在业务逻辑中检查：
 
 ```python
 result = parse("https://mp.weixin.qq.com/s/xxxxx")

{wechat_article_parser-0.0.6 → wechat_article_parser-0.0.7}/README.md

@@ -11,6 +11,10 @@
 - 小红书风格图片轮播文章
 - 全屏布局短文本文章
 
+解析时优先读取页面全局的 `item_show_type`：`0` 对应图文、`5` 对应视频分享、
+`8` 对应图片轮播、`10` 对应文字消息，再通过 HTML 或脚本数据区分具体模板。
+类型字段缺失、值未知或对应分支未提取到正文时，会按原有 HTML 特征匹配顺序兜底。
+
 ## 安装
 
 ```bash
@@ -93,13 +97,42 @@ result = parse(
 | `article_title` | `str` | 文章标题 |
 | `article_cover_image` | `str` | 文章封面图链接 |
 | `article_description` | `str` | 文章摘要 |
-| `article_markdown` | `str` | 文章正文的 Markdown 内容 |
+| `article_markdown` | `str` | 文章正文的 Markdown 内容；视频分享没有文字附言时可为空 |
 | `article_publish_time` | `int` | 发布时间（Unix 时间戳） |
+| `article_display_type` | `ArticleDisplayType` | 文章展示类型：`article`、`video`、`image`、`text` 或 `unknown` |
 | `raw_html` | `str` | 原始 HTML 网页源代码（仅在 `include_raw_html=True` 时填充，否则为空字符串） |
 | `images` | `list[str]` | 文章中提取的所有图片链接 |
 | `is_valid` | `bool` | 关键字段是否全部解析成功（属性） |
 
-`is_valid` 为 `True` 的条件：`mp_id`、`mp_name`、`article_id`、`article_msg_id`、`article_idx`、`article_sn`、`article_title`、`article_markdown`、`article_publish_time` 均不为空/零。
+`is_valid` 为 `True` 的条件：`mp_id`、`mp_name`、`article_id`、`article_msg_id`、`article_idx`、`article_sn`、`article_title`、`article_publish_time` 均不为空/零，且 `article_markdown` 非空或 `article_display_type == "video"`。视频分享允许没有文字正文，仍须满足其他关键字段要求；有效性不表示已获取视频文件。
+
+### 判断文章展示类型
+
+`ArticleDisplayType` 是字符串枚举，既支持枚举比较，也支持语义字符串比较：
+
+| 枚举 | 字符串值 | 含义 |
+|---|---|---|
+| `ArticleDisplayType.ARTICLE` | `article` | 图文，包括转载式 |
+| `ArticleDisplayType.VIDEO` | `video` | 视频分享 |
+| `ArticleDisplayType.IMAGE` | `image` | 图片轮播 |
+| `ArticleDisplayType.TEXT` | `text` | 文字消息 |
+| `ArticleDisplayType.UNKNOWN` | `unknown` | 页面类型缺失或未支持 |
+
+```python
+from wechat_article_parser import parse, ArticleDisplayType
+
+result = parse("https://mp.weixin.qq.com/s/xxxxx")
+if result.article_display_type == ArticleDisplayType.VIDEO:
+    print("这是视频分享")
+
+if result.article_display_type == "video":
+    print("视频分享可以没有文字正文")
+
+print(result.article_display_type)  # 例如 video
+```
+
+`article_display_type` 是返回结果中的数据字段，包含在 `dataclasses.asdict(result)` 中，JSON 序列化时输出语义字符串。
+微信原始的 `item_show_type` 仅在解析器内部使用，不包含在返回结果中。
 
 ### 判断账号类型
 
@@ -153,7 +186,7 @@ except httpx.HTTPStatusError as e:
 
 ### 解析不完整
 
-部分文章类型可能无法提取所有字段（如某些文章没有封面图或摘要）。这种情况不会抛出异常，但 `result.is_valid` 会返回 `False`。建议在业务逻辑中检查：
+缺少标题、发布时间等关键字段，或非视频分享缺少正文时，解析结果的 `is_valid` 会返回 `False`。封面图、摘要等非必填字段为空不影响有效性。建议在业务逻辑中检查：
 
 ```python
 result = parse("https://mp.weixin.qq.com/s/xxxxx")

{wechat_article_parser-0.0.6 → wechat_article_parser-0.0.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wechat-article-parser"
-version = "0.0.6"
+version = "0.0.7"
 description = "WeChat MP article parser - extract metadata and content from WeChat public account articles"
 readme = "README.md"
 requires-python = ">=3.10"

wechat_article_parser-0.0.7/src/wechat_article_parser/__init__.py

@@ -0,0 +1,11 @@
+from .models import AccountType, ArticleDisplayType, ArticleResult, WeChatVerifyError
+from .parser import parse, parse_async
+
+__all__ = [
+    "parse",
+    "parse_async",
+    "ArticleResult",
+    "AccountType",
+    "ArticleDisplayType",
+    "WeChatVerifyError",
+]

{wechat_article_parser-0.0.6 → wechat_article_parser-0.0.7}/src/wechat_article_parser/models.py

@@ -22,6 +22,22 @@ class AccountType(str, Enum):
         return format(self.value, format_spec)
 
 
+class ArticleDisplayType(str, Enum):
+    """文章展示类型，支持枚举和语义字符串比较。"""
+
+    UNKNOWN = "unknown"
+    ARTICLE = "article"
+    VIDEO = "video"
+    IMAGE = "image"
+    TEXT = "text"
+
+    def __str__(self) -> str:
+        return self.value
+
+    def __format__(self, format_spec: str) -> str:
+        return format(self.value, format_spec)
+
+
 @dataclass
 class ArticleResult:
     """微信公众号文章的解析结果。"""
@@ -52,9 +68,12 @@ class ArticleResult:
     # 文章中提取的图片列表
     images: list[str] = field(default_factory=list)
 
+    # 对外返回语义展示类型，微信原始数值仅在解析器内部使用。
+    article_display_type: ArticleDisplayType = ArticleDisplayType.UNKNOWN
+
     @property
     def is_valid(self) -> bool:
-        """检查关键字段是否解析成功。"""
+        """检查关键字段是否解析成功；视频分享允许正文为空。"""
         return bool(
             self.mp_id
             and self.mp_name
@@ -63,6 +82,9 @@ class ArticleResult:
             and self.article_idx
             and self.article_sn
             and self.article_title
-            and self.article_markdown
+            and (
+                self.article_markdown
+                or self.article_display_type == ArticleDisplayType.VIDEO
+            )
             and self.article_publish_time
         )

{wechat_article_parser-0.0.6 → wechat_article_parser-0.0.7}/src/wechat_article_parser/parser.py

@@ -5,13 +5,15 @@ from __future__ import annotations
 import base64
 import html as html_module
 import re
+from collections import deque
+from dataclasses import replace
 from urllib.parse import unquote
 
 import httpx
 from bs4 import BeautifulSoup, Tag
 from markdownify import MarkdownConverter
 
-from .models import AccountType, ArticleResult, WeChatVerifyError
+from .models import AccountType, ArticleDisplayType, ArticleResult, WeChatVerifyError
 
 _USER_AGENT = (
     "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
@@ -20,6 +22,13 @@ _USER_AGENT = (
 )
 _TIMEOUT = 15
 
+# 将字符串和注释作为整体，避免其中的括号干扰图片数组的层级判断。
+_JS_DATA_TOKEN_RE = re.compile(
+    r"(?P<string>'(?:\\[\s\S]|[^'\\])*'|\"(?:\\[\s\S]|[^\"\\])*\"|`(?:\\[\s\S]|[^`\\])*`)"
+    r"|(?P<comment>//[^\r\n]*|/\*[\s\S]*?\*/)"
+    r"|[a-zA-Z_$][\w$]*|\d+(?:\.\d*)?(?:[eE][+-]?\d+)?|[^\s]"
+)
+
 
 # ---------------------------------------------------------------------------
 # Markdown 转换器
@@ -95,18 +104,59 @@ def _service_type_to_account_type(value: str) -> AccountType:
 
 
 def _extract_picture_cdn_urls(script_text: str) -> list[str]:
-    """从 picture_page_info_list 中只提取正文图片的 cdn_url，排除 watermark_info 和 share_cover 中的。"""
+    """读取图片数组条目的直接 cdn_url，排除数组外和嵌套对象中的地址。
+
+    支持 window.picture_page_info_list = [...] 和 cgiDataNew 中的同名属性。
+    页面数据是含表达式的 JS 对象字面量，因此只跟踪结构，不执行脚本。
+    """
+    if "picture_page_info_list" not in script_text:
+        return []
+
     urls: list[str] = []
     seen: set[str] = set()
-    for m in re.finditer(r"(watermark_info|share_cover)?\s*(?::\s*\{[^}]*?)?\bcdn_url:\s*'([^']*)'", script_text):
-        prefix = m.group(1)
-        url = m.group(2)
-        if prefix or not url:
+    stack: list[str] = []
+    array_urls: list[str] = []
+    previous = before_previous = ""
+    for match in _JS_DATA_TOKEN_RE.finditer(script_text):
+        if match.lastgroup == "comment":
             continue
-        normalized = _normalize_image_url(url)
-        if normalized not in seen:
-            seen.add(normalized)
-            urls.append(normalized)
+        token = match.group()
+        is_string = match.lastgroup == "string"
+
+        if not stack:
+            if (
+                token == "["
+                and previous in (":", "=")
+                and before_previous == "picture_page_info_list"
+            ):
+                stack.append(token)
+        elif token in ("[", "{"):
+            stack.append(token)
+        elif token in ("]", "}"):
+            if stack[-1] != {"]": "[", "}": "{"}[token]:
+                stack.clear()
+                array_urls.clear()
+            else:
+                stack.pop()
+                if not stack:
+                    # 只提交完整数组，保留图片顺序并去重。
+                    for url in array_urls:
+                        if url not in seen:
+                            seen.add(url)
+                            urls.append(url)
+                    array_urls.clear()
+        elif (
+            stack == ["[", "{"]
+            and before_previous == "cdn_url"
+            and previous == ":"
+            and is_string
+            and token[0] in ("'", '"')
+        ):
+            url = _decode_text(token[1:-1])
+            if url:
+                array_urls.append(_normalize_image_url(url))
+
+        before_previous, previous = previous, token[1:-1] if is_string else token
     return urls
 
 
@@ -138,6 +188,38 @@ def _extract_meta(soup: BeautifulSoup, result: ArticleResult) -> None:
             setattr(result, attr, value)
 
 
+def _extract_item_show_type(scripts: list[Tag]) -> int | None:
+    """只读取当前文章的全局类型赋值；0 是有效类型，缺失时返回 None。"""
+    for script in scripts:
+        if "item_show_type" not in script.text:
+            continue
+        history: deque[str] = deque(maxlen=5)
+        brace_depth = 0
+        for match in _JS_DATA_TOKEN_RE.finditer(script.text):
+            if match.lastgroup == "comment":
+                continue
+            token = match.group()
+            previous = tuple(history)
+            is_global_var = (
+                brace_depth == 0
+                and previous[-3:] == ("var", "item_show_type", "=")
+            )
+            is_window_assignment = (
+                previous[-4:] == ("window", ".", "item_show_type", "=")
+                and (len(previous) < 5 or previous[-5] != ".")
+            )
+            if is_global_var or is_window_assignment:
+                value = token[1:-1] if token.startswith(("'", '"')) else token
+                if re.fullmatch(r"[0-9]+", value):
+                    return int(value)
+            if token == "{":
+                brace_depth += 1
+            elif token == "}":
+                brace_depth -= 1
+            history.append(token)
+    return None
+
+
 def _extract_account_type(script_text: str, result: ArticleResult) -> None:
     """从 new_service_type 中提取账号类型：0/1 → 订阅号，2 → 服务号。"""
     if result.mp_account_type:
@@ -345,25 +427,30 @@ def _extract_plain_text_content(soup: BeautifulSoup, result: ArticleResult) -> N
 
 def _extract_swiper_content(soup: BeautifulSoup, result: ArticleResult) -> None:
     """从小红书风格的图片轮播文章中提取内容。"""
+    images: list[str] = []
+    seen: set[str] = set()
+    description = ""
     for script in soup.find_all("script", attrs={"type": "text/javascript"}):
-        if "window.picture_page_info_list =" not in script.text:
-            continue
-
-        result.images = _extract_picture_cdn_urls(script.text)
-
-        html_parts = [f'<img src="{img}" /><br>' for img in result.images]
+        # 图片数据和 window.desc 可能位于不同的 script，分别收集。
+        for url in _extract_picture_cdn_urls(script.text):
+            if url not in seen:
+                seen.add(url)
+                images.append(url)
 
         m = re.search(r'window.desc = "([^"]+)"', script.text)
         if m:
-            text = _decode_text(m.group(1), preserve_newlines=True)
-            html_parts.append(f"<p>{text}</p>")
+            description = _decode_text(m.group(1), preserve_newlines=True)
 
-        if html_parts:
-            result.article_markdown = _to_markdown_plain("".join(html_parts))
+    result.images = images
+    html_parts = [f'<img src="{img}" /><br>' for img in images]
+    if description:
+        html_parts.append(f"<p>{description}</p>")
+    if html_parts:
+        result.article_markdown = _to_markdown_plain("".join(html_parts))
 
 
 def _extract_fullscreen_content(soup: BeautifulSoup, result: ArticleResult) -> None:
-    """从全屏布局文章中提取内容（appmsg_type 10002）。
+    """从全屏布局文字消息中提取内容。
 
     此类文章的文本存储在 text_page_info.content 中，通过 JsDecode() 编码；
     图片存储在 picture_page_info_list 的 cdn_url 字段中。
@@ -402,6 +489,67 @@ def _extract_fullscreen_content(soup: BeautifulSoup, result: ArticleResult) -> N
 # 主解析流程
 # ---------------------------------------------------------------------------
 
+# 顺序与原有 HTML 判断流程一致，用于未知类型及提取失败时的兜底。
+_CONTENT_SELECTORS = {
+    "rich_text": "div.rich_media_content",
+    "repost": "div.original_page",
+    "plain_text": "p#js_text_desc",
+    "video": "div#js_common_share_desc_wrap",
+    "swiper": "div.share_media_swiper_content",
+    "fullscreen": "div#js_fullscreen_layout_padding",
+}
+_ITEM_SHOW_TYPE_BRANCHES = {
+    0: ("rich_text", "repost"),
+    5: ("video",),
+    8: ("swiper",),
+    10: ("plain_text", "fullscreen"),
+}
+_ARTICLE_DISPLAY_TYPES = {
+    0: ArticleDisplayType.ARTICLE,
+    5: ArticleDisplayType.VIDEO,
+    8: ArticleDisplayType.IMAGE,
+    10: ArticleDisplayType.TEXT,
+}
+
+
+def _try_content_branch(
+    branch: str,
+    soup: BeautifulSoup,
+    scripts: list[Tag],
+    result: ArticleResult,
+    *,
+    require_html: bool,
+) -> ArticleResult | None:
+    content = soup.select_one(_CONTENT_SELECTORS[branch])
+    rich_text_template = branch in ("rich_text", "repost")
+    if content is None and (require_html or rich_text_template):
+        return None
+
+    # 失败分支的图片、元数据和标题处理不能污染后续分支。
+    candidate = replace(result, images=result.images.copy())
+    extract_meta = _extract_rich_text_meta if rich_text_template else _extract_swiper_meta
+    for script in scripts:
+        extract_meta(script.text, candidate)
+
+    if branch == "rich_text":
+        _extract_rich_media_content(content, candidate)
+    elif branch == "repost":
+        _extract_repost_content(content, candidate)
+    elif branch in ("plain_text", "video"):
+        _extract_plain_text_content(soup, candidate)
+    elif branch == "swiper":
+        _extract_swiper_content(soup, candidate)
+    elif branch == "fullscreen":
+        _extract_fullscreen_content(soup, candidate)
+
+    if not candidate.article_markdown.strip():
+        return None
+    if branch in ("plain_text", "fullscreen") and len(candidate.article_title) > 50:
+        short = candidate.article_title.split("。")[0]
+        candidate.article_title = short if len(short) <= 50 else candidate.article_title[:30]
+    return candidate
+
+
 def _parse_html(url: str, html: str) -> ArticleResult:
     """将原始 HTML 解析为 ArticleResult。"""
     # 检测微信验证码/人机验证页面
@@ -420,59 +568,26 @@ def _parse_html(url: str, html: str) -> ArticleResult:
 
     scripts = soup.find_all("script", attrs={"type": "text/javascript"})
 
-    # 尝试解析标准富文本文章
-    content = soup.find("div", class_="rich_media_content")
-    if content:
-        for s in scripts:
-            _extract_rich_text_meta(s.text, result)
-        _extract_rich_media_content(content, result)
-        return result
-
-    # 尝试解析转载式文章
-    content = soup.find("div", class_="original_page")
-    if content:
-        for s in scripts:
-            _extract_rich_text_meta(s.text, result)
-        _extract_repost_content(content, result)
-        return result
-
-    # 尝试解析纯文本文章
-    content = soup.find("p", id="js_text_desc")
-    if content:
-        for s in scripts:
-            _extract_swiper_meta(s.text, result)
-        _extract_plain_text_content(soup, result)
-        if result.article_title and len(result.article_title) > 50:
-            short = result.article_title.split("。")[0]
-            result.article_title = short if len(short) <= 50 else result.article_title[:30]
-        return result
-
-    # 尝试解析视频分享类文章
-    content = soup.find("div", id="js_common_share_desc_wrap")
-    if content:
-        for s in scripts:
-            _extract_swiper_meta(s.text, result)
-        _extract_plain_text_content(soup, result)
-        return result
-
-    # 尝试解析小红书风格图片轮播文章
-    content = soup.find("div", class_="share_media_swiper_content")
-    if content:
-        for s in scripts:
-            _extract_swiper_meta(s.text, result)
-        _extract_swiper_content(soup, result)
-        return result
-
-    # 尝试解析全屏布局文章（如短文本帖子，appmsg_type 10002）
-    content = soup.find("div", id="js_fullscreen_layout_padding")
-    if content:
-        for s in scripts:
-            _extract_swiper_meta(s.text, result)
-        _extract_fullscreen_content(soup, result)
-        if result.article_title and len(result.article_title) > 50:
-            short = result.article_title.split("。")[0]
-            result.article_title = short if len(short) <= 50 else result.article_title[:30]
-        return result
+    item_show_type = _extract_item_show_type(scripts)
+    result.article_display_type = _ARTICLE_DISPLAY_TYPES.get(
+        item_show_type, ArticleDisplayType.UNKNOWN,
+    )
+    preferred = _ITEM_SHOW_TYPE_BRANCHES.get(item_show_type, ())
+    attempted: set[str] = set()
+    for branch in (*preferred, *_CONTENT_SELECTORS):
+        if branch in attempted:
+            continue
+        attempted.add(branch)
+        # 已知类型先用对应的 DOM 或脚本数据细分模板；失败后按原有 HTML 顺序兜底。
+        candidate = _try_content_branch(
+            branch,
+            soup,
+            scripts,
+            result,
+            require_html=branch not in preferred,
+        )
+        if candidate is not None:
+            return candidate
 
     # 兜底：尽可能提取元数据
     for s in scripts:

wechat_article_parser-0.0.7/tests/test_models.py

@@ -0,0 +1,89 @@
+"""按展示类型检查解析结果的有效性。"""
+
+from dataclasses import asdict, replace
+import json
+
+import pytest
+
+from wechat_article_parser import ArticleDisplayType, ArticleResult
+
+
+_COMPLETE = ArticleResult(
+    mp_id=123,
+    mp_name="测试公众号",
+    article_id="ncPoZnxKdvDRLM_s4DBgmA",
+    article_msg_id=456,
+    article_idx=1,
+    article_sn="signature",
+    article_title="测试文章",
+    article_publish_time=1788860293,
+)
+
+
+@pytest.mark.parametrize("display_type", list(ArticleDisplayType))
+@pytest.mark.parametrize("markdown", ["", "正文"])
+def test_only_video_can_be_valid_without_markdown(
+    display_type: ArticleDisplayType, markdown: str,
+) -> None:
+    result = replace(
+        _COMPLETE, article_display_type=display_type, article_markdown=markdown,
+    )
+
+    assert result.is_valid is (bool(markdown) or display_type == ArticleDisplayType.VIDEO)
+
+
+@pytest.mark.parametrize(
+    ("field_name", "empty_value"),
+    [
+        ("mp_id", 0),
+        ("mp_name", ""),
+        ("article_id", ""),
+        ("article_msg_id", 0),
+        ("article_idx", 0),
+        ("article_sn", ""),
+        ("article_title", ""),
+        ("article_publish_time", 0),
+    ],
+)
+@pytest.mark.parametrize("markdown", ["", "视频附言"])
+def test_video_still_requires_all_key_metadata(
+    field_name: str, empty_value: str | int, markdown: str,
+) -> None:
+    result = replace(
+        _COMPLETE,
+        article_display_type=ArticleDisplayType.VIDEO,
+        article_markdown=markdown,
+        **{field_name: empty_value},
+    )
+
+    assert not result.is_valid
+
+
+@pytest.mark.parametrize(
+    "expected",
+    [
+        "article",
+        "video",
+        "image",
+        "text",
+        "unknown",
+    ],
+)
+def test_display_type_has_semantic_string_values(expected: str) -> None:
+    result = ArticleResult(article_display_type=ArticleDisplayType(expected))
+
+    assert result.article_display_type is ArticleDisplayType(expected)
+    assert result.article_display_type == expected
+    assert str(result.article_display_type) == expected
+    assert f"{result.article_display_type:>10}" == f"{expected:>10}"
+    assert json.dumps(result.article_display_type) == json.dumps(expected)
+    serialized = json.loads(json.dumps(asdict(result)))
+    assert serialized["article_display_type"] == expected
+    assert "item_show_type" not in serialized
+    assert not hasattr(result, "item_show_type")
+
+
+def test_default_display_type_is_unknown() -> None:
+    result = ArticleResult()
+    assert result.article_display_type is ArticleDisplayType.UNKNOWN
+    assert not result.is_valid

{wechat_article_parser-0.0.6 → wechat_article_parser-0.0.7}/tests/test_parser.py

@@ -15,6 +15,7 @@ TEST_URLS = [
     "https://mp.weixin.qq.com/s/h8E6riExCaH2Znmnprj-WQ",
     "https://mp.weixin.qq.com/s/ySQdtsRlRmAl_skdc5HQ-A",
     "https://mp.weixin.qq.com/s/MnkArbYQNp3tF29gujMUnQ",
+    "https://mp.weixin.qq.com/s/ncPoZnxKdvDRLM_s4DBgmA",
 ]
 
 
@@ -62,6 +63,7 @@ def _assert_result(result: ArticleResult, url: str) -> None:
     print(f"文章idx:      {result.article_idx}")
     print(f"文章签名:     {result.article_sn}")
     print(f"文章标题:     {result.article_title}")
+    print(f"展示类型:     {result.article_display_type}")
     print(
         f"封面图:       {result.article_cover_image[:80]}..."
         if result.article_cover_image
@@ -85,7 +87,8 @@ def _assert_result(result: ArticleResult, url: str) -> None:
     assert result.article_idx > 0, "article_idx should be positive"
     assert result.article_sn, "article_sn should not be empty"
     assert result.article_title, "article_title should not be empty"
-    assert result.article_markdown, "article_markdown should not be empty"
+    if result.article_display_type != "video":
+        assert result.article_markdown, "article_markdown should not be empty for non-video articles"
     assert result.article_publish_time > 0, "article_publish_time should be positive"
     assert result.is_valid
 
@@ -110,6 +113,7 @@ def test_fetch_all(url: str, proxy: str | None) -> None:
     print(f"文章idx:      {result.article_idx}")
     print(f"文章签名:     {result.article_sn}")
     print(f"文章标题:     {result.article_title}")
+    print(f"展示类型:     {result.article_display_type}")
     print(f"封面图:       {result.article_cover_image}")
     print(f"文章摘要:     {result.article_description}")
     print(f"发布时间:     {result.article_publish_time}")

wechat_article_parser-0.0.7/tests/test_swiper_content.py

@@ -0,0 +1,150 @@
+"""使用精简页面离线回归轮播图片的提取和 Markdown 输出。"""
+
+import pytest
+
+from wechat_article_parser.parser import _parse_html
+
+
+_URL = "https://mp.weixin.qq.com/s/0Wz3JeMbtWBL5iWJgYPS_Q"
+_EXPECTED_IMAGES = [
+    "https://mmbiz.qpic.cn/mmbiz_png/second/640",
+    "https://mmbiz.qpic.cn/mmbiz_png/first/640",
+]
+_PICTURES = r"""[
+  {
+    note: '含括号 ] } 和转义引号 \' 的字符串',
+    watermark_info: {
+      position: {x: 1},
+      cdn_url: 'https://mmbiz.qpic.cn/mmbiz_png/watermark/0'
+    },
+    cdn_url: 'https://mmbiz.qpic.cn/mmbiz_png/second/0?wx_fmt=png',
+    share_cover: {
+      crop_info: {x: 0},
+      cdn_url: 'https://mmbiz.qpic.cn/mmbiz_png/share-cover/0'
+    },
+    live_photo: {format_info: [{cdn_url: 'https://example.com/live-photo'}]}
+  },
+  {"cdn_url": "https://mmbiz.qpic.cn/mmbiz_png/first/0?wx_fmt=png"},
+  {cdn_url: 'https://mmbiz.qpic.cn/mmbiz_png/second/640'},
+  {cdn_url: ''}
+]"""
+_DESCRIPTION = r'window.desc = "第一行\x0a第二行";'
+_REFERENCE = """
+window.picture_page_info_list =
+  ((window.cgiDataNew && window.cgiDataNew.picture_page_info_list) || []).slice(0, 20);
+"""
+
+
+def _html(*scripts: str, fullscreen: bool = False) -> str:
+    content = (
+        '<div id="js_fullscreen_layout_padding"></div>'
+        if fullscreen
+        else '<div class="share_media_swiper_content"></div>'
+    )
+    return content + "".join(
+        f'<script type="text/javascript">{script}</script>' for script in scripts
+    )
+
+
+@pytest.mark.parametrize("layout", ["inline", "data_first", "description_first"])
+def test_swiper_collects_body_images_across_scripts(layout: str) -> None:
+    data = (
+        "window.cgiDataNew = {"
+        "cdn_url: 'https://mmbiz.qpic.cn/mmbiz_png/outside-before/0',"
+        f"picture_page_info_list: {_PICTURES},"
+        "other: {cdn_url: 'https://mmbiz.qpic.cn/mmbiz_png/outside-after/0'}"
+        "};"
+    )
+    reference = _REFERENCE + _DESCRIPTION
+    if layout == "inline":
+        scripts = [f"window.picture_page_info_list = {_PICTURES};" + _DESCRIPTION]
+    elif layout == "data_first":
+        scripts = [data, reference]
+    else:
+        scripts = [reference, data]
+
+    result = _parse_html(_URL, _html(*scripts))
+
+    assert result.images == _EXPECTED_IMAGES
+    assert result.article_markdown.count("![") == 2
+    assert result.article_markdown.index(_EXPECTED_IMAGES[0]) < result.article_markdown.index(_EXPECTED_IMAGES[1])
+    assert "第一行  \n第二行" in result.article_markdown
+    assert "outside" not in result.article_markdown
+    assert "watermark" not in result.article_markdown
+    assert "share-cover" not in result.article_markdown
+    assert "live-photo" not in result.article_markdown
+
+
+def test_swiper_later_empty_lists_do_not_erase_images() -> None:
+    result = _parse_html(
+        _URL,
+        _html(
+            f"window.picture_page_info_list = {_PICTURES};" + _DESCRIPTION,
+            "window.picture_page_info_list = [];",
+            _REFERENCE,
+        ),
+    )
+
+    assert result.images == _EXPECTED_IMAGES
+    assert result.article_markdown.count("![") == 2
+    assert "第一行  \n第二行" in result.article_markdown
+
+
+def test_swiper_ignores_list_text_in_strings_and_comments() -> None:
+    decoy = "picture_page_info_list: [{cdn_url: 'https://example.com/decoy'}]"
+    result = _parse_html(
+        _URL,
+        _html(
+            f'var example = "{decoy}";\n'
+            f"// {decoy}\n"
+            f"/* {decoy} */\n"
+            f"var template = `{decoy}`;\n",
+            f"window.cgiDataNew = {{'picture_page_info_list': {_PICTURES}}};",
+            _REFERENCE + _DESCRIPTION,
+        ),
+    )
+
+    assert result.images == _EXPECTED_IMAGES
+    assert "decoy" not in result.article_markdown
+
+
+def test_swiper_image_only_content() -> None:
+    result = _parse_html(
+        _URL,
+        _html(f"window.cgiDataNew = {{picture_page_info_list: {_PICTURES}}};", _REFERENCE),
+    )
+
+    assert result.images == _EXPECTED_IMAGES
+    assert result.article_markdown.count("![") == 2
+
+
+def test_swiper_text_only_content() -> None:
+    result = _parse_html(
+        _URL,
+        _html(
+            "window.cgiDataNew = {picture_page_info_list: [], cdn_url: 'https://example.com/cover'};",
+            _REFERENCE,
+            _DESCRIPTION,
+        ),
+    )
+
+    assert result.images == []
+    assert result.article_markdown == "第一行  \n第二行"
+
+
+def test_fullscreen_shared_image_extractor_keeps_body_images() -> None:
+    result = _parse_html(
+        _URL,
+        _html(
+            "window.cgiDataNew = {"
+            "cdn_url: 'https://example.com/cover',"
+            f"picture_page_info_list: {_PICTURES},"
+            "text_page_info: {content: JsDecode('全屏正文')}"
+            "};",
+            fullscreen=True,
+        ),
+    )
+
+    assert result.images == _EXPECTED_IMAGES
+    assert result.article_markdown.count("![") == 2
+    assert "全屏正文" in result.article_markdown

wechat_article_parser-0.0.7/tests/test_type_routing.py

@@ -0,0 +1,241 @@
+"""类型字段优先分发、模板细分及 HTML 兜底的离线回归测试。"""
+
+import pytest
+from bs4 import BeautifulSoup
+
+from wechat_article_parser import ArticleDisplayType, parser
+
+
+_URL = "https://mp.weixin.qq.com/s/0Wz3JeMbtWBL5iWJgYPS_Q"
+_RICH_TEXT = '<div class="rich_media_content"><p>富文本正文</p></div>'
+_REPOST = """
+<div class="original_page">
+  <p id="js_share_notice"><script>notice.innerHTML = "转载附言";</script></p>
+  <span id="js_share_source" data-url="https://example.com/original"></span>
+</div>
+"""
+_PLAIN_DATA = """
+var TextContentNoEncode = '';
+var ContentNoEncode = window.a_value_which_never_exists || '文字正文';
+"""
+_SWIPER_DATA = """
+window.cgiDataNew = {
+  picture_page_info_list: [{cdn_url: 'https://mmbiz.qpic.cn/mmbiz_png/body/0'}]
+};
+window.desc = "轮播正文";
+"""
+_FULLSCREEN_DATA = """
+window.cgiDataNew = {
+  picture_page_info_list: [],
+  text_page_info: {content: JsDecode('全屏正文')}
+};
+"""
+
+
+def _html(body: str = "", script: str = "", title: str = "原标题") -> str:
+    return (
+        f'<meta property="og:title" content="{title}">'
+        f"{body}<script type=\"text/javascript\">{script}</script>"
+    )
+
+
+@pytest.mark.parametrize(
+    ("script", "expected"),
+    [
+        ('var item_show_type = "0";', 0),
+        ("window.item_show_type = '8' || '';", 8),
+        ("window.item_show_type = 10;", 10),
+        ("var /* 注释 */ item_show_type = 5;", 5),
+        ("(function() { window.item_show_type = '10'; })();", 10),
+        ("window.item_show_type = '999';", 999),
+        ("window.item_show_type = '';", None),
+        ("window.item_show_type = 'unknown';", None),
+        ("window.item_show_type = null;", None),
+        ("window.item_show_type = -1;", None),
+        ("window.item_show_type = 8.5;", None),
+        ("window.item_show_type = 8e2;", None),
+        ("window.item_show_type == 8;", None),
+        ("var real_item_show_type = '8';", None),
+        ("", None),
+    ],
+)
+def test_read_current_article_type(script: str, expected: int | None) -> None:
+    soup = BeautifulSoup(_html(script=script), "html.parser")
+
+    assert parser._extract_item_show_type(soup.find_all("script")) == expected
+
+
+@pytest.mark.parametrize("current_assignment", ["", "window.item_show_type = '8';"])
+def test_ignore_type_in_references_strings_comments_and_local_variables(
+    current_assignment: str,
+) -> None:
+    decoys = """
+    var reference = {item_show_type: 5};
+    var example = "var item_show_type = '5';";
+    var url = 'https://example.com/?item_show_type=5';
+    var template = `
+      window.item_show_type = '5';
+    `;
+    // window.item_show_type = '5';
+    /* var item_show_type = '5'; */
+    function report() { var item_show_type = '5'; }
+    report.window.item_show_type = '5';
+    window.real_item_show_type = '5';
+    """
+    soup = BeautifulSoup(_html(script=decoys + current_assignment), "html.parser")
+
+    expected = 8 if current_assignment else None
+    assert parser._extract_item_show_type(soup.find_all("script")) == expected
+
+
+@pytest.mark.parametrize(
+    ("body", "expected"),
+    [
+        (_RICH_TEXT + _REPOST, "富文本正文"),
+        (_REPOST, "转载附言"),
+        ('<div class="rich_media_content"></div>' + _REPOST, "转载附言"),
+    ],
+)
+def test_type_zero_uses_html_to_distinguish_rich_text_and_repost(
+    body: str, expected: str,
+) -> None:
+    result = parser._parse_html(_URL, _html(body, 'var item_show_type = "0";'))
+
+    assert result.article_display_type is ArticleDisplayType.ARTICLE
+    assert expected in result.article_markdown
+    if expected == "转载附言":
+        assert "[查看原文](https://example.com/original)" in result.article_markdown
+    else:
+        assert "转载附言" not in result.article_markdown
+
+
+@pytest.mark.parametrize(
+    ("item_type", "data", "expected", "display_type"),
+    [
+        (5, _PLAIN_DATA, "文字正文", ArticleDisplayType.VIDEO),
+        (8, _SWIPER_DATA, "轮播正文", ArticleDisplayType.IMAGE),
+        (10, _PLAIN_DATA, "文字正文", ArticleDisplayType.TEXT),
+        (10, _FULLSCREEN_DATA, "全屏正文", ArticleDisplayType.TEXT),
+    ],
+)
+def test_known_type_takes_priority_over_other_html_templates(
+    item_type: int, data: str, expected: str, display_type: ArticleDisplayType,
+) -> None:
+    # 即使存在富文本壳，已知类型仍先读取对应脚本数据；无需专用容器。
+    result = parser._parse_html(
+        _URL,
+        _html(_RICH_TEXT, f"window.item_show_type = '{item_type}';" + data),
+    )
+
+    assert expected in result.article_markdown
+    assert "富文本正文" not in result.article_markdown
+    assert result.article_display_type is display_type
+    assert not hasattr(result, "item_show_type")
+    if item_type == 8:
+        assert result.images == ["https://mmbiz.qpic.cn/mmbiz_png/body/640"]
+
+
+@pytest.mark.parametrize(
+    "declaration",
+    ["", "window.item_show_type = '999';", "window.item_show_type = 'invalid';"],
+)
+def test_missing_unknown_or_invalid_type_falls_back_to_html(declaration: str) -> None:
+    result = parser._parse_html(_URL, _html(_RICH_TEXT, declaration))
+
+    assert result.article_markdown == "富文本正文"
+    assert result.article_display_type is ArticleDisplayType.UNKNOWN
+
+
+@pytest.mark.parametrize("item_type", [5, 8, 10])
+def test_known_type_without_matching_data_falls_back_to_html(item_type: int) -> None:
+    result = parser._parse_html(
+        _URL,
+        _html(_RICH_TEXT, f"window.item_show_type = '{item_type}';"),
+    )
+
+    assert result.article_markdown == "富文本正文"
+
+
+def test_type_zero_without_matching_html_falls_back_to_other_templates() -> None:
+    result = parser._parse_html(
+        _URL,
+        _html(
+            '<div class="share_media_swiper_content"></div>',
+            "window.item_show_type = '0';" + _SWIPER_DATA,
+        ),
+    )
+
+    assert "轮播正文" in result.article_markdown
+    assert len(result.images) == 1
+
+
+def test_failed_branch_does_not_pollute_fallback_result(monkeypatch) -> None:
+    def fail_swiper(soup, result):
+        result.article_title = "错误标题"
+        result.mp_name = "错误账号"
+        result.images.append("https://example.com/wrong-image")
+        result.article_markdown = "  \n"
+
+    monkeypatch.setattr(parser, "_extract_swiper_content", fail_swiper)
+    result = parser._parse_html(
+        _URL,
+        _html(_RICH_TEXT, "window.item_show_type = '8';"),
+    )
+
+    assert result.article_title == "原标题"
+    assert result.mp_name == ""
+    assert result.images == []
+    assert result.article_markdown == "富文本正文"
+
+
+def test_unrecognized_content_still_returns_metadata() -> None:
+    result = parser._parse_html(
+        _URL,
+        _html(script='window.item_show_type = "999"; window.alias = "account";'),
+    )
+
+    assert result.article_title == "原标题"
+    assert result.mp_alias == "account"
+    assert result.article_display_type is ArticleDisplayType.UNKNOWN
+    assert result.article_markdown == ""
+    assert not result.is_valid
+
+
+@pytest.mark.parametrize(
+    ("declaration", "expected_type"),
+    [
+        ("", ArticleDisplayType.UNKNOWN),
+        ("window.item_show_type = '5';", ArticleDisplayType.VIDEO),
+    ],
+)
+def test_video_without_description_keeps_type_and_metadata(
+    declaration: str, expected_type: ArticleDisplayType,
+) -> None:
+    metadata = """
+    window.__initCgiDataConfig = function(d) {
+      return {
+        biz: d.biz ? d.biz : 'MQ==',
+        nick_name: d.nick_name ? d.nick_name : '测试公众号',
+        mid: d.mid ? d.mid : '123',
+        idx: d.idx ? d.idx : '1',
+        sn: d.sn ? d.sn : 'signature',
+        create_time: d.create_time ? d.create_time : '1788860293'
+      };
+    };
+    var TextContentNoEncode = window.a_value_which_never_exists || '';
+    var ContentNoEncode = window.a_value_which_never_exists || '';
+    """
+    result = parser._parse_html(
+        _URL,
+        _html(
+            '<div id="js_common_share_desc_wrap" style="display: none"></div>'
+            '<div id="js_fullscreen_layout_padding"></div>',
+            declaration + metadata,
+        ),
+    )
+
+    assert result.article_display_type is expected_type
+    assert result.mp_id == 1
+    assert result.mp_name == "测试公众号"
+    assert result.article_markdown == ""
+    assert result.is_valid is (expected_type == ArticleDisplayType.VIDEO)

wechat_article_parser-0.0.6/src/wechat_article_parser/__init__.py

@@ -1,4 +0,0 @@
-from .models import AccountType, ArticleResult, WeChatVerifyError
-from .parser import parse, parse_async
-
-__all__ = ["parse", "parse_async", "ArticleResult", "AccountType", "WeChatVerifyError"]