按「数据类型」合并同类查询接口:一个数据类型 = 一个方法,跨市场自动选路。 - 28 个统一接口(get_universe/get_quotes/get_bars/get_indicators/get_ticks/ get_minutes/get_f10/get_file/get_boards/get_board_of/get_snapshot 等), 标的统一字符串写法(sz000001 / hk00700 / usAAPL / cffex:IFL0); 同名旧方法不再兼容 (market, code) 元组。 - 旧 51 个按通道/市场分裂的接口:33 个保留为 deprecated 别名(1.0 移除), 18 个同名升级为统一接口。公开方法共 63 个。 - 新增库层标的解析 pytdxdata.symbols;数据模型追加 symbol/name/fields 兜底字段。 - 修复:分页器连接泄漏、日期区间 K线返回 0 条(偏移方向探测)、池子全冷却死等。 - 文档/README/SKILL/llms.txt 全量同步;新增 docs/refactor-audit.md 审查报告。 - 测试 127 个用例全绿(含 tests/test_all_interfaces.py 全 63 方法回归)。
186 lines
6.3 KiB
Python
186 lines
6.3 KiB
Python
#!/usr/bin/env python3
|
|
"""文档漂移检查。
|
|
|
|
确保 `api.py` 里 `TdxData` 的公开方法与手写文档保持一致,双向检查:
|
|
|
|
1. **漏写**:代码里有、文档里没提到的方法
|
|
2. **过时**:文档里提到、代码里已不存在的方法
|
|
|
|
`docs/api/tdxdata.md` 由 mkdocstrings 自动生成,不在检查范围内(它不可能漂移)。
|
|
本脚本只管那些**手写**的接口清单,分两档:
|
|
|
|
- `MUST_LIST_ALL`:必须列全所有公开方法(漏写也报错)
|
|
- `MUST_NOT_BE_STALE`:入口 / 教程 / 精选清单,只要求「不提到已删除的方法」
|
|
|
|
用法::
|
|
|
|
.venv/Scripts/python.exe scripts/check_docs.py # Windows
|
|
.venv/bin/python scripts/check_docs.py # Linux / macOS
|
|
|
|
退出码 0 = 一致,1 = 存在漂移。
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
import ast
|
|
import re
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
ROOT = Path(__file__).resolve().parent.parent
|
|
API_FILE = ROOT / "src" / "pytdxdata" / "api.py"
|
|
PKG_DIR = ROOT / "src" / "pytdxdata"
|
|
|
|
# 必须**列全**所有公开方法的文档(漏写 = 漂移)
|
|
MUST_LIST_ALL = [
|
|
ROOT / "docs" / "API_REFERENCE.md",
|
|
]
|
|
|
|
# 只需**不提到已删除的方法**的文档:
|
|
# 这些是入口 / 教程 / 精选清单 / 接口总览(只列推荐的统一接口,旧方法不强制列出),
|
|
# 但绝不能引用已不存在的方法
|
|
MUST_NOT_BE_STALE = [
|
|
ROOT / "SKILL.md",
|
|
ROOT / "README.md",
|
|
ROOT / "docs" / "llms.txt",
|
|
ROOT / "docs" / "index.md",
|
|
ROOT / "docs" / "getting-started.md",
|
|
ROOT / "docs" / "cookbook.md",
|
|
ROOT / "docs" / "faq.md",
|
|
ROOT / "docs" / "cli.md",
|
|
ROOT / "docs" / "ai.md",
|
|
ROOT / "docs" / "api" / "index.md",
|
|
ROOT / "docs" / "refactor-audit.md",
|
|
]
|
|
|
|
|
|
def collect_api_methods(path: Path) -> tuple[set[str], set[str]]:
|
|
"""返回 (全部公开方法, 非 async 的公开方法)。"""
|
|
tree = ast.parse(path.read_text(encoding="utf-8"))
|
|
all_names: set[str] = set()
|
|
sync_names: set[str] = set()
|
|
|
|
for node in ast.walk(tree):
|
|
if isinstance(node, ast.ClassDef) and node.name == "TdxData":
|
|
for item in node.body:
|
|
if not isinstance(item, ast.FunctionDef | ast.AsyncFunctionDef):
|
|
continue
|
|
if item.name.startswith("_"):
|
|
continue
|
|
all_names.add(item.name)
|
|
if not isinstance(item, ast.AsyncFunctionDef):
|
|
sync_names.add(item.name)
|
|
return all_names, sync_names
|
|
|
|
|
|
def mentioned_in(text: str, name: str) -> bool:
|
|
"""文档中是否提到该方法(`get_kline` 不会误匹配 `get_kline_batch`)。"""
|
|
return re.search(rf"(?<![\w]){re.escape(name)}(?![\w])", text) is not None
|
|
|
|
|
|
def collect_doc_references(text: str) -> set[str]:
|
|
"""抽取文档中以反引号标注的疑似方法名。
|
|
|
|
同时覆盖两种写法:`` `get_kline` `` 与 `` `get_kline(market, code, ...)` ``。
|
|
"""
|
|
return set(
|
|
re.findall(r"`((?:get|download)_[a-z0-9_]+)\s*(?:\([^`()]*\))?`", text)
|
|
)
|
|
|
|
|
|
def collect_package_symbols() -> set[str]:
|
|
"""收集包内所有模块级公开函数 / 类名,以及 ``__all__`` 导出的名字。
|
|
|
|
文档里会合法地引用 `config.get_standard_hosts` 这类**模块级**函数,
|
|
不把它们纳入白名单就会被误判成「引用了已删除的方法」。
|
|
"""
|
|
names: set[str] = set()
|
|
for path in PKG_DIR.rglob("*.py"):
|
|
try:
|
|
tree = ast.parse(path.read_text(encoding="utf-8"))
|
|
except SyntaxError: # pragma: no cover - 语法错误交给 CI 的测试去抓
|
|
continue
|
|
for node in tree.body:
|
|
if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef):
|
|
if not node.name.startswith("_"):
|
|
names.add(node.name)
|
|
elif isinstance(node, ast.Assign):
|
|
for target in node.targets:
|
|
if isinstance(target, ast.Name) and target.id == "__all__":
|
|
try:
|
|
names.update(str(x) for x in ast.literal_eval(node.value))
|
|
except (ValueError, TypeError):
|
|
pass
|
|
return names
|
|
|
|
|
|
def main() -> int:
|
|
if not API_FILE.exists():
|
|
print(f"[FAIL] 找不到 {API_FILE}")
|
|
return 1
|
|
|
|
methods, sync_methods = collect_api_methods(API_FILE)
|
|
|
|
if "--list" in sys.argv:
|
|
for name in sorted(methods):
|
|
print(name)
|
|
return 0
|
|
|
|
print(f"api.py: TdxData 公开方法 {len(methods)} 个(含 start/close 生命周期)")
|
|
|
|
# 「已删除」判定要排除包内其它公开符号(config 的模块级函数等),否则误报
|
|
known = methods | collect_package_symbols()
|
|
|
|
problems: list[str] = []
|
|
|
|
if sync_methods:
|
|
problems.append(
|
|
"以下公开方法不是 async(本库约定全部公开方法为 async): "
|
|
+ ", ".join(sorted(sync_methods))
|
|
)
|
|
|
|
for doc in MUST_LIST_ALL:
|
|
if not doc.exists():
|
|
problems.append(f"缺少文档文件: {doc.relative_to(ROOT)}")
|
|
continue
|
|
|
|
text = doc.read_text(encoding="utf-8")
|
|
rel = doc.relative_to(ROOT).as_posix()
|
|
|
|
missing = sorted(n for n in methods if not mentioned_in(text, n))
|
|
if missing:
|
|
problems.append(
|
|
f"{rel} 漏写 {len(missing)} 个方法: " + ", ".join(missing)
|
|
)
|
|
|
|
stale = sorted(n for n in collect_doc_references(text) if n not in known)
|
|
if stale:
|
|
problems.append(f"{rel} 提到已不存在的方法: " + ", ".join(stale))
|
|
|
|
if not missing and not stale:
|
|
print(f" [OK] {rel}")
|
|
|
|
for doc in MUST_NOT_BE_STALE:
|
|
if not doc.exists():
|
|
continue
|
|
|
|
rel = doc.relative_to(ROOT).as_posix()
|
|
text = doc.read_text(encoding="utf-8")
|
|
stale = sorted(n for n in collect_doc_references(text) if n not in known)
|
|
if stale:
|
|
problems.append(f"{rel} 提到已不存在的方法: " + ", ".join(stale))
|
|
else:
|
|
print(f" [OK] {rel}(无过时引用)")
|
|
|
|
if problems:
|
|
print("\n[FAIL] 文档漂移:")
|
|
for p in problems:
|
|
print(" - " + p)
|
|
return 1
|
|
|
|
print("\n[OK] 文档与代码一致")
|
|
return 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
sys.exit(main())
|