Merge pull request #7050 from DDSRem-Dev/codex-comment-migration

docs: 统一全项目中文注释和结构化契约说明

tests/test_nexus_php_parser.py

@@ -1,3 +1,7 @@
+"""
+验证NexusPHP 页面结构与种子字段兼容。
+"""
+
 # -*- coding: utf-8 -*-
 from pathlib import Path
 from urllib.parse import parse_qs, urlsplit
@@ -22,7 +26,9 @@ def _build_parser() -> NexusPhpSiteUserInfo:
 
 
 def test_nexus_php_depthstudio_traffic_falls_back_to_details():
-    """首页解析失败后从详情表格补齐流量，不依赖卡片类名或实际流量。"""
+    """
+    首页解析失败后从详情表格补齐流量，不依赖卡片类名或实际流量。
+    """
     html_text = (Path(__file__).parent / "fixtures" / "depthstudio_userdetails.html").read_text(encoding="utf-8")
     html = etree.HTML(html_text)
     homepage = etree.tostring(html.xpath("//div")[0], encoding="unicode")
@@ -42,7 +48,9 @@ def test_nexus_php_depthstudio_traffic_falls_back_to_details():
 
 
 def test_nexus_php_detail_traffic_preserves_nonzero_values():
-    """详情兜底不能覆盖已有的非零流量和分享率。"""
+    """
+    详情兜底不能覆盖已有的非零流量和分享率。
+    """
     parser = _build_parser()
     parser._parse_user_base_info(
         "<html><body>上传量: 1 GB 下载量: 2 GB 分享率: 0.5</body></html>"
@@ -67,7 +75,9 @@ def test_nexus_php_detail_traffic_preserves_nonzero_values():
 def test_nexus_php_detail_traffic_fills_zero_fields(
     homepage, expected_upload, expected_download, expected_ratio
 ):
-    """零值字段允许从详情补读，分享率优先取详情表格的显示值。"""
+    """
+    零值字段允许从详情补读，分享率优先取详情表格的显示值。
+    """
     parser = _build_parser()
     parser._parse_user_base_info(f"<html><body>{homepage}</body></html>")
     detail = (Path(__file__).parent / "fixtures" / "depthstudio_userdetails.html").read_text(encoding="utf-8")
@@ -80,7 +90,9 @@ def test_nexus_php_detail_traffic_fills_zero_fields(
 
 
 def test_nexus_php_zero_ratio_uses_final_traffic_without_displayed_ratio():
-    """详情未显示分享率时，按补读后的上传/下载量重新计算零分享率。"""
+    """
+    详情未显示分享率时，按补读后的上传/下载量重新计算零分享率。
+    """
     parser = _build_parser()
     parser._parse_user_base_info("<html><body>上传量: 0 B 下载量: 0 B 分享率: 0</body></html>")
 
@@ -107,7 +119,9 @@ def test_nexus_php_zero_ratio_uses_final_traffic_without_displayed_ratio():
     ('<tr><td>上传量</td><td>未知</td></tr><tr><td>下载量</td><td>未知</td></tr>', 0, 0, 0.0),
 ])
 def test_nexus_php_detail_traffic_table(table, expected_upload, expected_download, expected_ratio):
-    """按表格字段识别流量，支持嵌套单位和分列布局，并排除实际流量。"""
+    """
+    按表格字段识别流量，支持嵌套单位和分列布局，并排除实际流量。
+    """
     parser = _build_parser()
     parser._parse_user_base_info("<html><body></body></html>")
 
@@ -124,7 +138,9 @@ def test_nexus_php_detail_traffic_table(table, expected_upload, expected_downloa
     ("0 B", "", 0.0),
 ])
 def test_nexus_php_legacy_traffic(download, ratio_text, expected_ratio):
-    """保留传统页面解析、分享率计算及零下载量行为。"""
+    """
+    保留传统页面解析、分享率计算及零下载量行为。
+    """
     parser = _build_parser()
 
     parser._parse_user_traffic_info(
@@ -209,7 +225,9 @@ def test_nexus_php_pttime_homepage_parses_bonus_and_user_level():
 
 
 def test_nexus_php_pttime_marker_requires_common_level_for_current_user():
-    """UID 标记缺少通用等级或属于其他用户时，不应解析站点专用等级。"""
+    """
+    UID 标记缺少通用等级或属于其他用户时，不应解析站点专用等级。
+    """
     parse_marker = NexusPhpSiteUserInfo._parse_user_level_marker
 
     assert parse_marker("[UID=67537][(初中)]", "67537") is None
@@ -425,7 +443,9 @@ def test_nexus_php_seeding_list_replaces_profile_fallback_without_double_countin
 
 
 def test_custom_seeding_endpoints_and_pterclub_navigation_headers():
-    """已确认的定制站点直接使用真实入口，猫站请求头不影响其他站点。"""
+    """
+    已确认的定制站点直接使用真实入口，猫站请求头不影响其他站点。
+    """
     endpoints = {
         "pterclub.net": "getusertorrentlist.php?userid=123&type=seeding",
         "pterclub.com": "getusertorrentlist.php?userid=123&type=seeding",
@@ -449,7 +469,9 @@ def test_custom_seeding_endpoints_and_pterclub_navigation_headers():
 
 
 def test_keepfrds_unmarked_columns_preserve_profile_count(monkeypatch):
-    """朋友列表含做种时长，汇总数量与可见明细不一致时保留汇总和真实明细体积。"""
+    """
+    朋友列表含做种时长，汇总数量与可见明细不一致时保留汇总和真实明细体积。
+    """
     parser = _build_parser()
     parser._site_domain = "keepfrds.com"
     parser._parse_site_page('<a href="userdetails.php?id=123">user</a>')
@@ -466,7 +488,9 @@ def test_keepfrds_unmarked_columns_preserve_profile_count(monkeypatch):
 
 
 def test_pterclub_profile_size_overrides_partial_paginated_list(monkeypatch):
-    """猫站汇总体积优先于分页明细累加，翻页继续沿用导航头且不重复汇总。"""
+    """
+    猫站汇总体积优先于分页明细累加，翻页继续沿用导航头且不重复汇总。
+    """
     parser = _build_parser()
     parser._site_domain = "pterclub.net"
     parser._parse_site_page('<a href="userdetails.php?id=123">user</a>')
@@ -477,7 +501,9 @@ def test_pterclub_profile_size_overrides_partial_paginated_list(monkeypatch):
     calls = []
 
     def get_page(**kwargs):
-        """回放分页内容并记录请求参数。"""
+        """
+        回放分页内容并记录请求参数。
+        """
         calls.append(kwargs)
         if len(calls) == 1:
             return page + '<a href="getusertorrentlist.php?page=1">下一页</a>'
@@ -494,14 +520,18 @@ def test_pterclub_profile_size_overrides_partial_paginated_list(monkeypatch):
 
 
 def test_putao_summary_only_does_not_follow_global_torrent_list(monkeypatch):
-    """葡萄只取明确做种计数，不推算体积或扫描全站列表。"""
+    """
+    葡萄只取明确做种计数，不推算体积或扫描全站列表。
+    """
     parser = _build_parser()
     parser._site_domain = "pt.sjtu.edu.cn"
     parser._parse_site_page('<a href="userdetails.php?id=123">user</a>')
     calls = []
 
     def get_page(**kwargs):
-        """回放葡萄异步汇总响应。"""
+        """
+        回放葡萄异步汇总响应。
+        """
         calls.append(kwargs)
         return '<div>当前做种 21 完成种子数 2 未完成种子数 138</div>'
 
@@ -515,7 +545,9 @@ def test_putao_summary_only_does_not_follow_global_torrent_list(monkeypatch):
 
 
 def test_nexus_empty_seeding_response_logs_warning(monkeypatch):
-    """接口失败为空时应提示可诊断警告，并保留详情页汇总。"""
+    """
+    接口失败为空时应提示可诊断警告，并保留详情页汇总。
+    """
     parser = _build_parser()
     parser.userid = "123"
     parser.seeding = 7
@@ -530,7 +562,9 @@ def test_nexus_empty_seeding_response_logs_warning(monkeypatch):
 
 
 def test_pterclub_headers_reach_http_transport_and_failures_are_visible(monkeypatch):
-    """导航头实际传递给统一 HTTP 客户端，404/403 警告不暴露 Cookie 或用户标识。"""
+    """
+    导航头实际传递给统一 HTTP 客户端，404/403 警告不暴露 Cookie 或用户标识。
+    """
     from types import SimpleNamespace
 
     parser = _build_parser()
@@ -539,7 +573,9 @@ def test_pterclub_headers_reach_http_transport_and_failures_are_visible(monkeypa
     calls, warnings = [], []
 
     def get_response(**kwargs):
-        """回放 HTTP 失败响应，验证传输层参数。"""
+        """
+        回放 HTTP 失败响应，验证传输层参数。
+        """
         calls.append(kwargs)
         return SimpleNamespace(status_code=404, text="File not found.")