wechat-article-parser 0.0.14__tar.gz → 0.0.15__tar.gz

{wechat_article_parser-0.0.14 → wechat_article_parser-0.0.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: wechat-article-parser
-Version: 0.0.14
+Version: 0.0.15
 Summary: WeChat MP article parser - extract metadata and content from WeChat public account articles
 License-Expression: MIT
 License-File: LICENSE
@@ -109,6 +109,17 @@ result = parse(
 )
 ```
 
+### 长链接
+
+同步和异步接口均支持短链接 `/s/<22位文章ID>` 和长链接 `/s?__biz=...&mid=...&idx=...&sn=...&chksm=...`。
+根据原始输入 URL 识别链接类型：协议须为 HTTP/HTTPS，域名须为 `mp.weixin.qq.com`。
+长链接路径须为 `/s`，且 `__biz`、`mid`、`idx`、`sn`、`chksm` 五个查询参数必须都存在且有值，
+空字符串或纯空白不算有效值；重复参数中的每个值也须非空白。额外查询参数和片段不影响识别。
+未满足识别条件时，`article_url_type` 为 `unknown`，仍尝试解析页面，不额外抛出链接校验异常。
+
+长链接返回的 `article_id` 为空，其他字段继续从页面提取。
+只有识别为 `long` 时，`is_valid` 才允许缺少 `article_id`。
+
 ## 返回结构
 
 `parse` 和 `parse_async` 均返回 `ArticleResult` 数据类，包含以下字段：
@@ -123,7 +134,8 @@ result = parse(
 | `mp_image` | `str` | 公众号头像链接 |
 | `mp_description` | `str` | 公众号简介 |
 | `mp_account_type` | `AccountType` | 账号类型：`AccountType.SUBSCRIPTION`（订阅号）/ `AccountType.SERVICE`（服务号）/ `AccountType.UNKNOWN`（未识别） |
-| `article_id` | `str` | 文章 ID |
+| `article_id` | `str` | 短链接中的文章 ID；长链接为空字符串 |
+| `article_url_type` | `ArticleURLType` | 输入链接类型：`short`、`long` 或 `unknown`（默认）；可从包顶层导入枚举，支持字符串比较和 JSON 序列化 |
 | `article_msg_id` | `int` | 文章所在的群发消息 ID |
 | `article_idx` | `int` | 群发图文中的位置（从 1 开始） |
 | `article_sn` | `str` | 文章签名（防伪校验） |
@@ -139,7 +151,9 @@ result = parse(
 | `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_publish_time` 均不为空/零，且 `article_markdown` 非空或 `article_display_type in ("video", "audio")`。视频和音频分享允许没有文字正文，仍须满足其他关键字段要求；有效性不表示已获取视频或音频文件。
+`is_valid` 为 `True` 的条件：`mp_id`、`mp_name`、`article_msg_id`、`article_idx`、`article_sn`、`article_title`、`article_publish_time` 均不为空/零，且 `article_markdown` 非空或 `article_display_type in ("video", "audio")`。
+此外，`article_url_type == "long"` 时允许 `article_id` 为空；短链接和未识别链接仍要求 `article_id` 非空。
+视频和音频分享允许没有文字正文，仍须满足其他关键字段要求；有效性不表示已获取视频或音频文件。
 
 付费受限页面返回提示且关键元数据完整时，`is_valid` 也为 `True`，这不表示已获取付费正文。
 

{wechat_article_parser-0.0.14 → wechat_article_parser-0.0.15}/README.md

@@ -94,6 +94,17 @@ result = parse(
 )
 ```
 
+### 长链接
+
+同步和异步接口均支持短链接 `/s/<22位文章ID>` 和长链接 `/s?__biz=...&mid=...&idx=...&sn=...&chksm=...`。
+根据原始输入 URL 识别链接类型：协议须为 HTTP/HTTPS，域名须为 `mp.weixin.qq.com`。
+长链接路径须为 `/s`，且 `__biz`、`mid`、`idx`、`sn`、`chksm` 五个查询参数必须都存在且有值，
+空字符串或纯空白不算有效值；重复参数中的每个值也须非空白。额外查询参数和片段不影响识别。
+未满足识别条件时，`article_url_type` 为 `unknown`，仍尝试解析页面，不额外抛出链接校验异常。
+
+长链接返回的 `article_id` 为空，其他字段继续从页面提取。
+只有识别为 `long` 时，`is_valid` 才允许缺少 `article_id`。
+
 ## 返回结构
 
 `parse` 和 `parse_async` 均返回 `ArticleResult` 数据类，包含以下字段：
@@ -108,7 +119,8 @@ result = parse(
 | `mp_image` | `str` | 公众号头像链接 |
 | `mp_description` | `str` | 公众号简介 |
 | `mp_account_type` | `AccountType` | 账号类型：`AccountType.SUBSCRIPTION`（订阅号）/ `AccountType.SERVICE`（服务号）/ `AccountType.UNKNOWN`（未识别） |
-| `article_id` | `str` | 文章 ID |
+| `article_id` | `str` | 短链接中的文章 ID；长链接为空字符串 |
+| `article_url_type` | `ArticleURLType` | 输入链接类型：`short`、`long` 或 `unknown`（默认）；可从包顶层导入枚举，支持字符串比较和 JSON 序列化 |
 | `article_msg_id` | `int` | 文章所在的群发消息 ID |
 | `article_idx` | `int` | 群发图文中的位置（从 1 开始） |
 | `article_sn` | `str` | 文章签名（防伪校验） |
@@ -124,7 +136,9 @@ result = parse(
 | `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_publish_time` 均不为空/零，且 `article_markdown` 非空或 `article_display_type in ("video", "audio")`。视频和音频分享允许没有文字正文，仍须满足其他关键字段要求；有效性不表示已获取视频或音频文件。
+`is_valid` 为 `True` 的条件：`mp_id`、`mp_name`、`article_msg_id`、`article_idx`、`article_sn`、`article_title`、`article_publish_time` 均不为空/零，且 `article_markdown` 非空或 `article_display_type in ("video", "audio")`。
+此外，`article_url_type == "long"` 时允许 `article_id` 为空；短链接和未识别链接仍要求 `article_id` 非空。
+视频和音频分享允许没有文字正文，仍须满足其他关键字段要求；有效性不表示已获取视频或音频文件。
 
 付费受限页面返回提示且关键元数据完整时，`is_valid` 也为 `True`，这不表示已获取付费正文。
 

{wechat_article_parser-0.0.14 → wechat_article_parser-0.0.15}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wechat-article-parser"
-version = "0.0.14"
+version = "0.0.15"
 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.14 → wechat_article_parser-0.0.15}/src/wechat_article_parser/__init__.py

@@ -1,4 +1,4 @@
-from .models import AccountType, ArticleDisplayType, ArticleResult, WeChatVerifyError
+from .models import AccountType, ArticleDisplayType, ArticleResult, ArticleURLType, WeChatVerifyError
 from .parser import parse, parse_async
 
 __all__ = [
@@ -7,5 +7,6 @@ __all__ = [
     "ArticleResult",
     "AccountType",
     "ArticleDisplayType",
+    "ArticleURLType",
     "WeChatVerifyError",
 ]

{wechat_article_parser-0.0.14 → wechat_article_parser-0.0.15}/src/wechat_article_parser/models.py

@@ -22,6 +22,20 @@ class AccountType(str, Enum):
         return format(self.value, format_spec)
 
 
+class ArticleURLType(str, Enum):
+    """输入链接类型；仅通过长链接校验时才允许缺少文章 ID。"""
+
+    UNKNOWN = "unknown"
+    SHORT = "short"
+    LONG = "long"
+
+    def __str__(self) -> str:
+        return self.value
+
+    def __format__(self, format_spec: str) -> str:
+        return format(self.value, format_spec)
+
+
 class ArticleDisplayType(str, Enum):
     """文章展示类型，支持枚举和语义字符串比较。"""
 
@@ -79,13 +93,16 @@ class ArticleResult:
     # 页面是否包含当前文章的付费标记；不表示是否已获取付费全文。
     article_is_paid: bool = False
 
+    # 根据原始输入 URL 识别，不根据 article_id 是否为空反推。
+    article_url_type: ArticleURLType = ArticleURLType.UNKNOWN
+
     @property
     def is_valid(self) -> bool:
         """检查关键字段是否解析成功；视频和音频分享允许正文为空。"""
         return bool(
             self.mp_id
             and self.mp_name
-            and self.article_id
+            and (self.article_id or self.article_url_type == ArticleURLType.LONG)
             and self.article_msg_id
             and self.article_idx
             and self.article_sn

{wechat_article_parser-0.0.14 → wechat_article_parser-0.0.15}/src/wechat_article_parser/parser.py

@@ -7,13 +7,13 @@ import html as html_module
 import re
 from collections import deque
 from dataclasses import replace
-from urllib.parse import unquote
+from urllib.parse import parse_qs, unquote, urlsplit
 
 import httpx
 from bs4 import BeautifulSoup, Tag
 from markdownify import MarkdownConverter
 
-from .models import AccountType, ArticleDisplayType, ArticleResult, WeChatVerifyError
+from .models import AccountType, ArticleDisplayType, ArticleResult, ArticleURLType, WeChatVerifyError
 
 _USER_AGENT = (
     "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
@@ -216,10 +216,33 @@ def _extract_picture_cdn_urls(script_text: str) -> list[str]:
 # 内部提取函数
 # ---------------------------------------------------------------------------
 
+def _extract_article_url_type(url: str) -> ArticleURLType:
+    """识别输入链接；长链接的五个必需参数均须存在且非空白。"""
+    try:
+        parts = urlsplit(url)
+    except ValueError:
+        return ArticleURLType.UNKNOWN
+    if (
+        parts.scheme not in ("http", "https")
+        or parts.hostname != "mp.weixin.qq.com"
+        or parts.username is not None
+        or parts.password is not None
+    ):
+        return ArticleURLType.UNKNOWN
+    if re.fullmatch(r"/s/[A-Za-z0-9_-]{22}", parts.path):
+        return ArticleURLType.SHORT
+    if parts.path == "/s":
+        params = parse_qs(parts.query, keep_blank_values=True)
+        required = ("__biz", "mid", "idx", "sn", "chksm")
+        # 保留空值，重复参数中出现空值也不能放行。
+        if all(key in params and all(value.strip() for value in params[key]) for key in required):
+            return ArticleURLType.LONG
+    return ArticleURLType.UNKNOWN
+
+
 def _extract_article_id(url: str) -> str:
-    parts = url.split("/")
-    if len(parts) == 5 and len(parts[4]) == 22:
-        return parts[4]
+    if _extract_article_url_type(url) == ArticleURLType.SHORT:
+        return urlsplit(url).path.rsplit("/", 1)[1]
     return ""
 
 
@@ -839,6 +862,7 @@ def _parse_html(url: str, html: str) -> ArticleResult:
     result = ArticleResult()
     soup = BeautifulSoup(html, "html.parser")
 
+    result.article_url_type = _extract_article_url_type(url)
     result.article_id = _extract_article_id(url)
     _extract_meta(soup, result)
 

wechat_article_parser-0.0.15/tests/test_article_urls.py

@@ -0,0 +1,148 @@
+"""长短链接识别及有效性判断的离线回归测试。"""
+
+from dataclasses import replace
+from urllib.parse import urlencode
+
+import httpx
+import pytest
+
+from wechat_article_parser import ArticleURLType, parser
+
+
+_SHORT_URL = "https://mp.weixin.qq.com/s/ncPoZnxKdvDRLM_s4DBgmA"
+_PARAMS = {
+    "__biz": "MjY2NzgwMjU0MA==",
+    "mid": "2650331950",
+    "idx": "3",
+    "sn": "59630a9449c484f555c71978ee521cd8",
+    "chksm": "ae4b5d1c0343c5bf3af413da074abb54a3d56268937ba1825fa518c6ba4b1c96c34675d15d9e",
+}
+_LONG_URL = "https://mp.weixin.qq.com/s?" + urlencode(_PARAMS)
+_HTML = """
+<meta property="og:title" content="长链接测试文章">
+<div class="rich_media_content"><p>正文</p></div>
+<script type="text/javascript">
+var item_show_type = "0";
+var hd_head_img = "https://example.com/avatar";
+var nickname = htmlDecode("测试公众号");
+var oriCreateTime = '1791884914';
+window.__allowLoadResFromMp = true;
+var biz = "MjY2NzgwMjU0MA==";
+var mid = "2650331950";
+var idx = "3";
+var sn = "59630a9449c484f555c71978ee521cd8";
+</script>
+"""
+
+
+@pytest.mark.parametrize("scheme", ["http", "https"])
+@pytest.mark.parametrize("suffix", ["", "&scene=21#wechat_redirect"])
+def test_long_url_parses_without_article_id(scheme: str, suffix: str) -> None:
+    result = parser._parse_html(_LONG_URL.replace("https:", scheme + ":") + suffix, _HTML)
+
+    assert result.article_url_type is ArticleURLType.LONG
+    assert result.article_id == ""
+    assert result.mp_id == 2667802540
+    assert result.article_msg_id == 2650331950
+    assert result.article_idx == 3
+    assert result.article_sn == _PARAMS["sn"]
+    assert result.article_markdown == "正文"
+    assert result.is_valid
+
+
+@pytest.mark.parametrize("key", _PARAMS)
+@pytest.mark.parametrize("value", [None, "", " \t\n"])
+def test_long_url_requires_each_parameter_with_value(key: str, value: str | None) -> None:
+    params = _PARAMS.copy()
+    if value is None:
+        del params[key]
+    else:
+        params[key] = value
+    result = parser._parse_html("https://mp.weixin.qq.com/s?" + urlencode(params), _HTML)
+
+    assert result.article_url_type is ArticleURLType.UNKNOWN
+    assert result.article_id == ""
+    assert not result.is_valid
+
+
+@pytest.mark.parametrize("key", _PARAMS)
+def test_duplicate_blank_parameter_does_not_pass_validation(key: str) -> None:
+    result = parser._parse_html(_LONG_URL + "&" + key + "=", _HTML)
+    assert result.article_url_type is ArticleURLType.UNKNOWN
+    assert not result.is_valid
+
+
+@pytest.mark.parametrize(
+    "base",
+    [
+        "https://example.com/s",
+        "https://mp.weixin.qq.com.example.com/s",
+        "https://mp.weixin.qq.com@evil.example/s",
+        "https://user@mp.weixin.qq.com/s",
+        "ftp://mp.weixin.qq.com/s",
+        "//mp.weixin.qq.com/s",
+        "https://mp.weixin.qq.com/s/",
+        "https://mp.weixin.qq.com/other",
+        "https://[invalid/s",
+    ],
+)
+def test_unrecognized_url_cannot_skip_article_id(base: str) -> None:
+    result = parser._parse_html(base + "?" + urlencode(_PARAMS), _HTML)
+    assert result.article_url_type is ArticleURLType.UNKNOWN
+    assert not result.is_valid
+
+
+def test_required_parameters_in_fragment_do_not_count() -> None:
+    result = parser._parse_html("https://mp.weixin.qq.com/s#" + urlencode(_PARAMS), _HTML)
+    assert result.article_url_type is ArticleURLType.UNKNOWN
+    assert not result.is_valid
+
+
+@pytest.mark.parametrize("suffix", ["", "?scene=21#wechat_redirect", "?" + urlencode(_PARAMS)])
+def test_short_url_still_requires_article_id(suffix: str) -> None:
+    result = parser._parse_html(_SHORT_URL + suffix, _HTML)
+    assert result.article_url_type is ArticleURLType.SHORT
+    assert result.article_id == "ncPoZnxKdvDRLM_s4DBgmA"
+    assert result.is_valid
+    assert not replace(result, article_id="").is_valid
+
+
+def test_query_parameters_do_not_replace_missing_page_metadata() -> None:
+    result = parser._parse_html(_LONG_URL, '<div class="rich_media_content">正文</div>')
+    assert result.article_url_type is ArticleURLType.LONG
+    assert not result.is_valid
+
+
+@pytest.fixture
+def mock_article_http(monkeypatch):
+    # 重定向到短链接后仍根据原始输入链接识别类型。
+    def respond(request):
+        if request.url.path == "/s":
+            return httpx.Response(302, headers={"Location": _SHORT_URL})
+        return httpx.Response(200, text=_HTML)
+
+    transport = httpx.MockTransport(respond)
+    client, async_client = httpx.Client, httpx.AsyncClient
+    monkeypatch.setattr(
+        parser.httpx, "Client", lambda **kwargs: client(transport=transport, **kwargs),
+    )
+    monkeypatch.setattr(
+        parser.httpx, "AsyncClient", lambda **kwargs: async_client(transport=transport, **kwargs),
+    )
+
+
+def test_sync_public_entry_accepts_long_url(mock_article_http) -> None:
+    result = parser.parse(_LONG_URL, include_raw_html=True)
+    assert result.article_url_type is ArticleURLType.LONG
+    assert result.article_id == ""
+    assert result.is_valid
+    assert result.raw_html == _HTML
+
+
+@pytest.mark.asyncio
+async def test_async_public_entry_accepts_long_url(mock_article_http) -> None:
+    result = await parser.parse_async(_LONG_URL, include_raw_html=True)
+    assert result.article_url_type is ArticleURLType.LONG
+    assert result.article_id == ""
+    assert result.is_valid
+    assert result.raw_html == _HTML

{wechat_article_parser-0.0.14 → wechat_article_parser-0.0.15}/tests/test_models.py

@@ -5,7 +5,7 @@ import json
 
 import pytest
 
-from wechat_article_parser import ArticleDisplayType, ArticleResult
+from wechat_article_parser import ArticleDisplayType, ArticleResult, ArticleURLType
 
 
 _COMPLETE = ArticleResult(
@@ -98,3 +98,46 @@ def test_paid_field_serializes_as_boolean(is_paid: bool) -> None:
     result = ArticleResult(article_is_paid=is_paid)
     assert json.loads(json.dumps(asdict(result)))["article_is_paid"] is is_paid
     assert ArticleResult().article_is_paid is False
+
+
+@pytest.mark.parametrize("url_type", list(ArticleURLType))
+@pytest.mark.parametrize("display_type", list(ArticleDisplayType))
+@pytest.mark.parametrize("markdown", ["", "正文"])
+def test_only_long_url_can_omit_article_id(
+    url_type: ArticleURLType, display_type: ArticleDisplayType, markdown: str,
+) -> None:
+    result = replace(
+        _COMPLETE, article_id="", article_url_type=url_type,
+        article_display_type=display_type, article_markdown=markdown,
+    )
+    assert result.is_valid is (
+        url_type == ArticleURLType.LONG
+        and (bool(markdown) or display_type in (ArticleDisplayType.VIDEO, ArticleDisplayType.AUDIO))
+    )
+
+
+@pytest.mark.parametrize(
+    ("field_name", "empty_value"),
+    [
+        ("mp_id", 0), ("mp_name", ""), ("article_msg_id", 0),
+        ("article_idx", 0), ("article_sn", ""), ("article_title", ""),
+        ("article_publish_time", 0),
+    ],
+)
+def test_long_url_still_requires_other_key_metadata(
+    field_name: str, empty_value: str | int,
+) -> None:
+    result = replace(
+        _COMPLETE, article_id="", article_url_type=ArticleURLType.LONG,
+        article_markdown="正文", **{field_name: empty_value},
+    )
+    assert not result.is_valid
+
+
+@pytest.mark.parametrize("url_type", list(ArticleURLType))
+def test_url_type_serializes_as_semantic_string(url_type: ArticleURLType) -> None:
+    result = ArticleResult(article_url_type=url_type)
+    assert str(url_type) == url_type.value
+    assert f"{url_type:>10}" == f"{url_type.value:>10}"
+    assert json.loads(json.dumps(asdict(result)))["article_url_type"] == url_type.value
+    assert ArticleResult().article_url_type is ArticleURLType.UNKNOWN

{wechat_article_parser-0.0.14 → wechat_article_parser-0.0.15}/tests/test_parser.py

@@ -80,6 +80,7 @@ def _assert_result(result: ArticleResult, url: str) -> None:
         else "公众号简介:   (empty)"
     )
     print(f"文章ID:       {result.article_id}")
+    print(f"链接类型:     {result.article_url_type}")
     print(f"群发消息ID:   {result.article_msg_id}")
     print(f"文章idx:      {result.article_idx}")
     print(f"文章签名:     {result.article_sn}")
@@ -134,6 +135,7 @@ def test_fetch_all(url: str, proxy: str | None) -> None:
     print(f"公众号图片:   {result.mp_image}")
     print(f"公众号简介:   {result.mp_description}")
     print(f"文章ID:       {result.article_id}")
+    print(f"链接类型:     {result.article_url_type}")
     print(f"群发消息ID:   {result.article_msg_id}")
     print(f"文章idx:      {result.article_idx}")
     print(f"文章签名:     {result.article_sn}")