1573 lines
56 KiB
Python
1573 lines
56 KiB
Python
"""从包源码树中静态提取 API 数据。
|
||
|
||
本模块只做「静态解析」：读源码文本 + ast 解析，不 import 被解析的包。
|
||
因此不需要安装 numpy / torch / transformers 等重依赖，
|
||
也不会触发包内 statistics_of_guan_package() 的联网行为。
|
||
|
||
提取的内容全部来自源码本身，**不假设任何固定的包名、目录名、模块名或函数名**，
|
||
这样即使源码结构或内容大幅变动，网站仍然能自动识别并生成：
|
||
|
||
* 包目录自动发现（支持 src/ 布局、任意包名、嵌套子包）
|
||
* 模块名 / 模块头注释（形如 "# Module: basic_functions"），缺失时回退到模块名
|
||
* 每个函数的签名、参数与默认值、装饰器、返回类型
|
||
* 函数说明：优先取定义正上方紧邻的注释块，其次取 docstring
|
||
* 分节注释（形如 "# --- 某某某 ---"）
|
||
* 类及其方法、基类
|
||
* 函数体内对包内其它函数的调用（用于生成交叉参考）
|
||
* 弃用标记（函数体中出现 'deprecated' 提示，或 @deprecated 装饰器）
|
||
* 字面量形式的数据表（函数返回的，或模块级定义的 dict / list）
|
||
* 包的导出关系：__init__.py 中的 import * / 显式导入 / __all__
|
||
* 解析失败的文件不会中断构建，只会被记录为错误
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
import ast
|
||
import configparser
|
||
import json
|
||
import re
|
||
import tomllib
|
||
import warnings
|
||
from dataclasses import dataclass, field
|
||
from pathlib import Path
|
||
from typing import Any
|
||
|
||
# "# --- 标题 ---" 形式的分节注释
|
||
SECTION_RE = re.compile(r"^#\s*-{3,}\s*(.*?)\s*-{3,}\s*$")
|
||
|
||
# 模块头注释 "# Module: xxx"
|
||
MODULE_HEADER_RE = re.compile(r"^#\s*Module:\s*(.+?)\s*$")
|
||
|
||
# 弃用相关的关键字（装饰器名、警告文字等）
|
||
DEPRECATED_RE = re.compile(r"deprecat", re.IGNORECASE)
|
||
|
||
|
||
def _parse(text: str, filename: str) -> ast.Module:
|
||
"""解析源码，屏蔽被解析文件自身的 SyntaxWarning 等噪音。"""
|
||
with warnings.catch_warnings():
|
||
warnings.simplefilter("ignore")
|
||
return ast.parse(text, filename=filename)
|
||
|
||
|
||
# --------------------------------------------------------------------------
|
||
# 数据结构
|
||
# --------------------------------------------------------------------------
|
||
|
||
|
||
@dataclass
|
||
class Param:
|
||
"""函数的一个参数。"""
|
||
|
||
name: str
|
||
default: str | None = None # 默认值的源码文本，None 表示无默认值
|
||
annotation: str | None = None
|
||
kind: str = "positional" # positional / vararg / keyword_only / kwarg
|
||
|
||
@property
|
||
def required(self) -> bool:
|
||
"""是否必须传参（*args / **kwargs 不算）。"""
|
||
return (
|
||
self.default is None
|
||
and self.kind in ("positional", "keyword_only")
|
||
)
|
||
|
||
|
||
@dataclass
|
||
class Function:
|
||
"""一个函数（或方法）。"""
|
||
|
||
name: str
|
||
module: str
|
||
signature: str
|
||
params: list[Param] = field(default_factory=list)
|
||
description: str = ""
|
||
docstring: str = ""
|
||
decorators: list[str] = field(default_factory=list)
|
||
lineno: int = 0
|
||
end_lineno: int = 0
|
||
source: str = ""
|
||
section: str = ""
|
||
deprecated: bool = False
|
||
deprecated_note: str = ""
|
||
calls: list[str] = field(default_factory=list) # 该函数调用到的包内函数
|
||
returns: str | None = None
|
||
is_async: bool = False
|
||
exported: bool = True # 是否出现在包命名空间中
|
||
owner: str = "" # 所属类（方法才有）
|
||
|
||
@property
|
||
def anchor(self) -> str:
|
||
return f"{self.module}.{self.name}"
|
||
|
||
@property
|
||
def required_params(self) -> list[Param]:
|
||
return [p for p in self.params if p.required]
|
||
|
||
|
||
@dataclass
|
||
class Class:
|
||
"""一个类。"""
|
||
|
||
name: str
|
||
module: str
|
||
description: str = ""
|
||
docstring: str = ""
|
||
bases: list[str] = field(default_factory=list)
|
||
methods: list[Function] = field(default_factory=list)
|
||
attributes: list[str] = field(default_factory=list)
|
||
lineno: int = 0
|
||
exported: bool = True
|
||
|
||
|
||
@dataclass
|
||
class DataTable:
|
||
"""源码中以字面量形式定义的数据表。"""
|
||
|
||
name: str
|
||
module: str
|
||
kind: str # dict / list
|
||
description: str = ""
|
||
entries: list[tuple[str, str]] = field(default_factory=list) # (键, 值的源码文本)
|
||
lineno: int = 0
|
||
origin: str = "function" # function（函数返回）/ module（模块级常量）
|
||
|
||
|
||
@dataclass
|
||
class Module:
|
||
"""一个 Python 模块。"""
|
||
|
||
name: str
|
||
file: str
|
||
path: str = "" # 相对包根目录的路径
|
||
source_path: str = "" # 磁盘上的绝对路径
|
||
title: str = ""
|
||
description: str = ""
|
||
functions: list[Function] = field(default_factory=list)
|
||
classes: list[Class] = field(default_factory=list)
|
||
data: list[DataTable] = field(default_factory=list)
|
||
line_count: int = 0
|
||
is_package: bool = False # 该文件所在目录是一个包（有 __init__.py）
|
||
is_init: bool = False # 该文件本身是不是 __init__.py
|
||
is_entry: bool = False # 是否是包入口 __init__.py
|
||
error: str = "" # 解析失败时的错误信息
|
||
|
||
@property
|
||
def anchor(self) -> str:
|
||
return self.name
|
||
|
||
|
||
@dataclass
|
||
class PackageInfo:
|
||
"""包的基本信息，来自 pyproject.toml / setup.cfg / __init__.py。"""
|
||
|
||
name: str = ""
|
||
import_name: str = "" # 导入时使用的名字（包目录名）
|
||
version: str = ""
|
||
description: str = ""
|
||
summary: str = ""
|
||
requires_python: str = ""
|
||
url: str = ""
|
||
urls: dict[str, str] = field(default_factory=dict)
|
||
author: str = ""
|
||
author_email: str = ""
|
||
license: str = ""
|
||
classifiers: list[str] = field(default_factory=list)
|
||
|
||
|
||
# --------------------------------------------------------------------------
|
||
# 文本小工具
|
||
# --------------------------------------------------------------------------
|
||
|
||
|
||
def _read_text(path: Path) -> tuple[str, str]:
|
||
"""读源码文本，返回 (文本, 编码)。对编码问题尽量宽容。"""
|
||
raw = path.read_bytes()
|
||
for encoding in ("utf-8-sig", "utf-8", "gbk", "latin-1"):
|
||
try:
|
||
return raw.decode(encoding), encoding
|
||
except UnicodeDecodeError:
|
||
continue
|
||
return raw.decode("utf-8", errors="replace"), "utf-8"
|
||
|
||
|
||
def _first_paragraph(text: str) -> str:
|
||
"""取文本的第一段，压成一行。"""
|
||
text = (text or "").strip()
|
||
if not text:
|
||
return ""
|
||
parts = re.split(r"\n\s*\n", text, maxsplit=1)
|
||
return " ".join(line.strip() for line in parts[0].splitlines() if line.strip())
|
||
|
||
|
||
def _is_dunder(name: str) -> bool:
|
||
"""是否是 __xxx__ 形式的内部名字。"""
|
||
return len(name) > 4 and name.startswith("__") and name.endswith("__")
|
||
|
||
|
||
def _definition_start(node: ast.AST) -> int:
|
||
"""定义真正开始的行号：装饰器之上的那一行。
|
||
|
||
带装饰器时 ast 的 lineno 指向 def 那一行，
|
||
上方的注释块会被装饰器隔开，取说明文字时要以装饰器为起点。
|
||
"""
|
||
start = getattr(node, "lineno", 0)
|
||
for decorator in getattr(node, "decorator_list", []) or []:
|
||
start = min(start, decorator.lineno)
|
||
return start
|
||
|
||
|
||
def _comment_block_above(lines: list[str], lineno: int) -> str:
|
||
"""取函数/类定义正上方紧邻的注释块（自下而上收集连续的 # 注释行）。"""
|
||
collected: list[str] = []
|
||
index = lineno - 2 # lineno 为 1-based，转换成上一行的 0-based 下标
|
||
while index >= 0:
|
||
stripped = lines[index].strip()
|
||
if stripped.startswith("#"):
|
||
collected.append(stripped.lstrip("#").strip())
|
||
index -= 1
|
||
else:
|
||
break
|
||
collected.reverse()
|
||
return " ".join(part for part in collected if part)
|
||
|
||
|
||
def _docstring_of(node: ast.AST) -> str:
|
||
"""取节点 docstring（没有则为空串）。"""
|
||
try:
|
||
return ast.get_docstring(node) or ""
|
||
except TypeError:
|
||
return ""
|
||
|
||
|
||
# --------------------------------------------------------------------------
|
||
# 签名与参数
|
||
# --------------------------------------------------------------------------
|
||
|
||
|
||
def _format_params(args: ast.arguments) -> list[Param]:
|
||
"""把 ast.arguments 转成参数列表。"""
|
||
params: list[Param] = []
|
||
positional = list(args.posonlyargs) + list(args.args)
|
||
defaults: list[ast.expr | None] = [None] * (
|
||
len(positional) - len(args.defaults)
|
||
) + list(args.defaults)
|
||
for arg, default in zip(positional, defaults):
|
||
params.append(
|
||
Param(
|
||
name=arg.arg,
|
||
default=ast.unparse(default) if default is not None else None,
|
||
annotation=ast.unparse(arg.annotation) if arg.annotation else None,
|
||
kind="positional",
|
||
)
|
||
)
|
||
if args.vararg:
|
||
params.append(
|
||
Param(
|
||
name="*" + args.vararg.arg,
|
||
annotation=ast.unparse(args.vararg.annotation)
|
||
if args.vararg.annotation
|
||
else None,
|
||
kind="vararg",
|
||
)
|
||
)
|
||
for arg, default in zip(args.kwonlyargs, args.kw_defaults):
|
||
params.append(
|
||
Param(
|
||
name=arg.arg,
|
||
default=ast.unparse(default) if default is not None else None,
|
||
annotation=ast.unparse(arg.annotation) if arg.annotation else None,
|
||
kind="keyword_only",
|
||
)
|
||
)
|
||
if args.kwarg:
|
||
params.append(
|
||
Param(
|
||
name="**" + args.kwarg.arg,
|
||
annotation=ast.unparse(args.kwarg.annotation)
|
||
if args.kwarg.annotation
|
||
else None,
|
||
kind="kwarg",
|
||
)
|
||
)
|
||
return params
|
||
|
||
|
||
def _format_signature(
|
||
name: str, args: ast.arguments, returns: ast.expr | None = None
|
||
) -> str:
|
||
"""还原出可读的函数签名文本。
|
||
|
||
优先用 ast.unparse 直接还原参数表（能正确处理仅位置参数分隔符 "/"、
|
||
关键字限定、注解与默认值），失败时退回手工拼接。
|
||
"""
|
||
try:
|
||
text = ast.unparse(args)
|
||
except Exception: # pragma: no cover - ast.unparse 极少失败
|
||
text = _format_params_text(args)
|
||
signature = f"{name}({text})"
|
||
if returns is not None:
|
||
try:
|
||
signature += " -> " + ast.unparse(returns)
|
||
except Exception: # pragma: no cover
|
||
pass
|
||
return signature
|
||
|
||
|
||
def _format_params_text(args: ast.arguments) -> str:
|
||
"""手工拼接参数列表（ast.unparse 不可用时的退路）。"""
|
||
parts: list[str] = []
|
||
positional = list(args.posonlyargs) + list(args.args)
|
||
defaults: list[ast.expr | None] = [None] * (
|
||
len(positional) - len(args.defaults)
|
||
) + list(args.defaults)
|
||
for arg, default in zip(positional, defaults):
|
||
text = arg.arg
|
||
if arg.annotation is not None:
|
||
text += ": " + ast.unparse(arg.annotation)
|
||
if default is not None:
|
||
text += "=" + ast.unparse(default)
|
||
parts.append(text)
|
||
if args.vararg:
|
||
text = "*" + args.vararg.arg
|
||
if args.vararg.annotation is not None:
|
||
text += ": " + ast.unparse(args.vararg.annotation)
|
||
parts.append(text)
|
||
for arg, default in zip(args.kwonlyargs, args.kw_defaults):
|
||
text = arg.arg
|
||
if arg.annotation is not None:
|
||
text += ": " + ast.unparse(arg.annotation)
|
||
if default is not None:
|
||
text += "=" + ast.unparse(default)
|
||
parts.append(text)
|
||
if args.kwarg:
|
||
text = "**" + args.kwarg.arg
|
||
if args.kwarg.annotation is not None:
|
||
text += ": " + ast.unparse(args.kwarg.annotation)
|
||
parts.append(text)
|
||
return ", ".join(parts)
|
||
|
||
|
||
# --------------------------------------------------------------------------
|
||
# 弃用、调用、数据表
|
||
# --------------------------------------------------------------------------
|
||
|
||
|
||
def _deprecation(node: ast.AST) -> tuple[bool, str]:
|
||
"""判断是否已弃用，返回 (是否弃用, 说明文字)。
|
||
|
||
识别几种写法：
|
||
* 装饰器名里含 deprecated，例如 @deprecated
|
||
* 函数体里的字符串含 deprecated，例如提示信息
|
||
* 出现 DeprecationWarning / PendingDeprecationWarning，
|
||
无论是直接写名字还是写成 warnings.DeprecationWarning
|
||
"""
|
||
note = ""
|
||
for decorator in getattr(node, "decorator_list", []) or []:
|
||
text = ast.unparse(decorator)
|
||
if DEPRECATED_RE.search(text):
|
||
return True, text
|
||
for child in ast.walk(node):
|
||
if isinstance(child, ast.Constant) and isinstance(child.value, str):
|
||
if DEPRECATED_RE.search(child.value):
|
||
note = child.value.strip()
|
||
break
|
||
elif isinstance(child, ast.Name) and DEPRECATED_RE.search(child.id):
|
||
if "Warning" in child.id:
|
||
return True, note or child.id
|
||
elif isinstance(child, ast.Attribute) and DEPRECATED_RE.search(child.attr):
|
||
if "Warning" in child.attr:
|
||
return True, note or child.attr
|
||
return False, note
|
||
|
||
|
||
def _package_aliases(tree: ast.Module, names: set[str]) -> set[str]:
|
||
"""找出源码里指向本包的别名，例如 import guan / import guan as g。"""
|
||
aliases: set[str] = set()
|
||
for node in ast.walk(tree):
|
||
if isinstance(node, ast.Import):
|
||
for alias in node.names:
|
||
root = alias.name.split(".")[0]
|
||
if root in names:
|
||
aliases.add(alias.asname or alias.name)
|
||
elif isinstance(node, ast.ImportFrom):
|
||
root = (node.module or "").split(".")[0]
|
||
if root in names:
|
||
for alias in node.names:
|
||
aliases.add(alias.asname or alias.name)
|
||
return aliases
|
||
|
||
|
||
def _iter_calls(node: ast.AST):
|
||
"""遍历节点里的调用，但不下钻到嵌套的函数 / 类 / lambda 内部。
|
||
|
||
嵌套函数体内的调用属于嵌套函数，不该算到外层函数头上。
|
||
"""
|
||
for child in ast.iter_child_nodes(node):
|
||
if isinstance(
|
||
child,
|
||
(ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Lambda),
|
||
):
|
||
continue
|
||
if isinstance(child, ast.Call):
|
||
yield child
|
||
yield from _iter_calls(child)
|
||
|
||
|
||
def _package_calls(
|
||
node: ast.AST,
|
||
aliases: set[str],
|
||
direct_names: set[str] | None = None,
|
||
shadowed: set[str] | None = None,
|
||
) -> list[str]:
|
||
"""收集函数体内出现的包内函数调用（去重且保持顺序）。
|
||
|
||
两种形式都算：
|
||
* 别名调用：``guan.foo()`` / ``core.foo()``，别名须在 aliases 里
|
||
* 直接调用：``from .core import foo`` 之后的 ``foo()``，
|
||
名字须在 direct_names 里，且没有被本模块的同名定义遮蔽
|
||
"""
|
||
found: list[str] = []
|
||
direct_names = direct_names or set()
|
||
shadowed = shadowed or set()
|
||
for child in _iter_calls(node):
|
||
func = child.func
|
||
name = ""
|
||
if (
|
||
isinstance(func, ast.Attribute)
|
||
and isinstance(func.value, ast.Name)
|
||
and func.value.id in aliases
|
||
):
|
||
name = func.attr
|
||
elif (
|
||
isinstance(func, ast.Name)
|
||
and func.id in direct_names
|
||
and func.id not in shadowed
|
||
):
|
||
name = func.id
|
||
if name and name not in found:
|
||
found.append(name)
|
||
return found
|
||
|
||
|
||
def _literal_value(node: ast.AST) -> Any:
|
||
"""尝试把 AST 节点求值成 Python 字面量，失败则返回 None。"""
|
||
try:
|
||
return ast.literal_eval(node)
|
||
except (ValueError, SyntaxError, TypeError, MemoryError, RecursionError):
|
||
return None
|
||
|
||
|
||
def _format_value(value: Any) -> str:
|
||
"""把字面量转成适合网页展示的文本。"""
|
||
if isinstance(value, bool):
|
||
return "True" if value else "False"
|
||
if value is None:
|
||
return "None"
|
||
if isinstance(value, float):
|
||
return repr(value)
|
||
if isinstance(value, str):
|
||
return value
|
||
if isinstance(value, (dict, list, tuple)):
|
||
try:
|
||
return json.dumps(value, ensure_ascii=False, default=str)
|
||
except (TypeError, ValueError):
|
||
return repr(value)
|
||
return str(value)
|
||
|
||
|
||
def _table_entries(value: Any) -> list[tuple[str, str]]:
|
||
"""把 dict / list 字面量转成 (键, 值) 列表。"""
|
||
if isinstance(value, dict):
|
||
return [(str(k), _format_value(v)) for k, v in value.items()]
|
||
if isinstance(value, (list, tuple)):
|
||
return [(str(i), _format_value(v)) for i, v in enumerate(value)]
|
||
return []
|
||
|
||
|
||
def _collect_data_tables(node: ast.FunctionDef, module_name: str) -> list[DataTable]:
|
||
"""从一个函数里提取以字面量形式写死的数据表。
|
||
|
||
覆盖常见的几种写法：
|
||
* 直接 return 一个 dict / list 字面量
|
||
* 先建一个容器变量，再逐项 constants['x'] = ... 赋值，最后 return 该变量
|
||
* 用 container.update({...}) 追加
|
||
* return 一个元组，其中的元素是 dict / list
|
||
"""
|
||
tables: list[DataTable] = []
|
||
variables: dict[str, Any] = {}
|
||
|
||
for statement in node.body:
|
||
if isinstance(statement, ast.Assign) and len(statement.targets) == 1:
|
||
target = statement.targets[0]
|
||
value = _literal_value(statement.value)
|
||
if isinstance(target, ast.Name) and value is not None:
|
||
variables[target.id] = value
|
||
elif isinstance(target, ast.Subscript) and isinstance(target.value, ast.Name):
|
||
container = variables.get(target.value.id)
|
||
key = _literal_value(target.slice)
|
||
item = _literal_value(statement.value)
|
||
if isinstance(container, dict) and key is not None and item is not None:
|
||
container[key] = item
|
||
elif isinstance(statement, ast.AugAssign) and isinstance(statement.target, ast.Name):
|
||
container = variables.get(statement.target.id)
|
||
item = _literal_value(statement.value)
|
||
if isinstance(container, list) and isinstance(item, list):
|
||
container.extend(item)
|
||
variables[statement.target.id] = container
|
||
elif isinstance(statement, ast.Expr) and isinstance(statement.value, ast.Call):
|
||
call = statement.value
|
||
if (
|
||
isinstance(call.func, ast.Attribute)
|
||
and isinstance(call.func.value, ast.Name)
|
||
and call.args
|
||
):
|
||
container = variables.get(call.func.value.id)
|
||
patch = _literal_value(call.args[0])
|
||
if call.func.attr == "update" and isinstance(container, dict):
|
||
if isinstance(patch, dict):
|
||
container.update(patch)
|
||
elif call.func.attr == "append" and isinstance(container, list):
|
||
if patch is not None:
|
||
container.append(patch)
|
||
elif call.func.attr == "extend" and isinstance(container, list):
|
||
if isinstance(patch, (list, tuple)):
|
||
container.extend(patch)
|
||
elif isinstance(statement, ast.Return) and statement.value is not None:
|
||
value = _literal_value(statement.value)
|
||
if value is None and isinstance(statement.value, ast.Name):
|
||
value = variables.get(statement.value.id)
|
||
candidates: list[Any] = []
|
||
if isinstance(value, (list, tuple)):
|
||
candidates = [v for v in value if isinstance(v, (dict, list, tuple))]
|
||
elif value is not None:
|
||
candidates = [value]
|
||
for candidate in candidates:
|
||
if not isinstance(candidate, (dict, list, tuple)) or not candidate:
|
||
continue
|
||
kind = "dict" if isinstance(candidate, dict) else "list"
|
||
entries = _table_entries(candidate)
|
||
if entries:
|
||
tables.append(
|
||
DataTable(
|
||
name=node.name,
|
||
module=module_name,
|
||
kind=kind,
|
||
entries=entries,
|
||
lineno=node.lineno,
|
||
origin="function",
|
||
)
|
||
)
|
||
|
||
return tables
|
||
|
||
|
||
def _collect_module_tables(tree: ast.Module, module_name: str) -> list[DataTable]:
|
||
"""提取模块级以字面量定义的数据表（常量表）。"""
|
||
tables: list[DataTable] = []
|
||
for statement in tree.body:
|
||
if isinstance(statement, ast.Assign) and len(statement.targets) == 1:
|
||
target = statement.targets[0]
|
||
value_node = statement.value
|
||
elif isinstance(statement, ast.AnnAssign) and statement.value is not None:
|
||
target = statement.target
|
||
value_node = statement.value
|
||
else:
|
||
continue
|
||
if not isinstance(target, ast.Name):
|
||
continue
|
||
if _is_dunder(target.id):
|
||
continue # __all__ / __version__ 之类的内部名字不算数据表
|
||
value = _literal_value(value_node)
|
||
if not isinstance(value, (dict, list)) or not value:
|
||
continue
|
||
kind = "dict" if isinstance(value, dict) else "list"
|
||
tables.append(
|
||
DataTable(
|
||
name=target.id,
|
||
module=module_name,
|
||
kind=kind,
|
||
entries=_table_entries(value),
|
||
lineno=statement.lineno,
|
||
origin="module",
|
||
)
|
||
)
|
||
return tables
|
||
|
||
|
||
# --------------------------------------------------------------------------
|
||
# 模块解析
|
||
# --------------------------------------------------------------------------
|
||
|
||
|
||
def _find_sections(lines: list[str]) -> list[tuple[int, str]]:
|
||
"""找出所有分节注释，返回 (行号, 标题)。"""
|
||
sections: list[tuple[int, str]] = []
|
||
for number, line in enumerate(lines, start=1):
|
||
match = SECTION_RE.match(line.strip())
|
||
if match:
|
||
sections.append((number, match.group(1)))
|
||
return sections
|
||
|
||
|
||
def _module_all(tree: ast.Module) -> set[str] | None:
|
||
"""取模块级的 __all__（没有则返回 None）。"""
|
||
for node in tree.body:
|
||
if isinstance(node, ast.Assign):
|
||
for target in node.targets:
|
||
if isinstance(target, ast.Name) and target.id == "__all__":
|
||
value = _literal_value(node.value)
|
||
if isinstance(value, (list, tuple, set)):
|
||
return {str(item) for item in value}
|
||
elif isinstance(node, ast.AnnAssign):
|
||
if isinstance(node.target, ast.Name) and node.target.id == "__all__":
|
||
value = _literal_value(node.value) if node.value else None
|
||
if isinstance(value, (list, tuple, set)):
|
||
return {str(item) for item in value}
|
||
return None
|
||
|
||
|
||
def parse_module(path: Path, module_name: str, relative_path: str = "") -> Module:
|
||
"""解析单个模块文件。
|
||
|
||
解析失败不会抛出异常，而是在返回的 Module 上记录 error，
|
||
以免一个文件的语法问题导致整个网站构建失败。
|
||
"""
|
||
module = Module(
|
||
name=module_name,
|
||
file=path.name,
|
||
path=relative_path or path.name,
|
||
source_path=str(path),
|
||
)
|
||
try:
|
||
text, _ = _read_text(path)
|
||
except OSError as exc:
|
||
module.error = f"无法读取文件：{exc}"
|
||
return module
|
||
|
||
module.line_count = len(text.splitlines())
|
||
try:
|
||
tree = _parse(text, str(path))
|
||
except SyntaxError as exc:
|
||
module.error = f"语法错误：第 {exc.lineno} 行 {exc.msg}"
|
||
return module
|
||
|
||
lines = text.splitlines()
|
||
|
||
for line in lines:
|
||
header = MODULE_HEADER_RE.match(line.strip())
|
||
if header:
|
||
module.title = header.group(1)
|
||
break
|
||
|
||
module.description = _first_paragraph(_docstring_of(tree))
|
||
if not module.title:
|
||
module.title = module_name
|
||
|
||
sections = _find_sections(lines)
|
||
aliases = _package_aliases(tree, {module_name.split(".")[0]}) | {module_name}
|
||
|
||
def section_for(lineno: int) -> str:
|
||
current = ""
|
||
for number, title in sections:
|
||
if number < lineno:
|
||
current = title
|
||
else:
|
||
break
|
||
return current
|
||
|
||
def describe(node: ast.AST) -> str:
|
||
"""函数说明：注释块优先，其次 docstring。
|
||
|
||
注释块从装饰器往上找，这样「@装饰器」不会把说明文字挡掉。
|
||
"""
|
||
comment = _comment_block_above(lines, _definition_start(node))
|
||
if comment:
|
||
return comment
|
||
return _first_paragraph(_docstring_of(node))
|
||
|
||
def build_function(
|
||
node: ast.FunctionDef | ast.AsyncFunctionDef, owner: str = ""
|
||
) -> Function:
|
||
end = node.end_lineno or node.lineno
|
||
# 装饰器在 def 之上，源码片段要从装饰器开始
|
||
start = _definition_start(node)
|
||
source = "\n".join(lines[start - 1 : end])
|
||
deprecated, note = _deprecation(node)
|
||
docstring = _docstring_of(node)
|
||
return Function(
|
||
name=node.name,
|
||
module=module_name,
|
||
signature=_format_signature(node.name, node.args, node.returns),
|
||
params=_format_params(node.args),
|
||
description=describe(node),
|
||
docstring=docstring,
|
||
decorators=[ast.unparse(d) for d in node.decorator_list],
|
||
lineno=node.lineno,
|
||
end_lineno=end,
|
||
source=source,
|
||
section=section_for(node.lineno),
|
||
deprecated=deprecated,
|
||
deprecated_note=note,
|
||
calls=_package_calls(node, aliases),
|
||
returns=ast.unparse(node.returns) if node.returns else None,
|
||
is_async=isinstance(node, ast.AsyncFunctionDef),
|
||
owner=owner,
|
||
)
|
||
|
||
for node in tree.body:
|
||
if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
|
||
module.functions.append(build_function(node))
|
||
module.data.extend(_collect_data_tables(node, module_name))
|
||
elif isinstance(node, ast.ClassDef):
|
||
klass = Class(
|
||
name=node.name,
|
||
module=module_name,
|
||
description=describe(node),
|
||
docstring=_docstring_of(node),
|
||
bases=[ast.unparse(base) for base in node.bases],
|
||
lineno=node.lineno,
|
||
)
|
||
for item in node.body:
|
||
if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
|
||
klass.methods.append(build_function(item, owner=node.name))
|
||
elif isinstance(item, ast.Assign) and len(item.targets) == 1:
|
||
if isinstance(item.targets[0], ast.Name):
|
||
klass.attributes.append(item.targets[0].id)
|
||
module.classes.append(klass)
|
||
|
||
module.data.extend(_collect_module_tables(tree, module_name))
|
||
|
||
# 让数据表带上说明文字
|
||
for table in module.data:
|
||
if table.origin == "function":
|
||
for function in module.functions:
|
||
if function.name == table.name:
|
||
table.description = function.description
|
||
break
|
||
|
||
return module
|
||
|
||
|
||
# --------------------------------------------------------------------------
|
||
# 包解析
|
||
# --------------------------------------------------------------------------
|
||
|
||
|
||
def module_name_for(path: Path, package_root: Path) -> str:
|
||
"""由文件路径推出模块名（相对包根目录，支持子包）。"""
|
||
relative = path.relative_to(package_root)
|
||
parts = list(relative.parts)
|
||
if parts[-1] == "__init__.py":
|
||
parts = parts[:-1]
|
||
else:
|
||
parts[-1] = parts[-1].removesuffix(".py")
|
||
return ".".join(parts)
|
||
|
||
|
||
def _is_build_dir(path: Path) -> bool:
|
||
"""判断目录是不是网站构建脚本所在目录（那不是被发布的包）。"""
|
||
return (path / "build_site.py").is_file() or (path / "extract.py").is_file()
|
||
|
||
|
||
def discover_package_dir(search_roots: list[Path]) -> Path | None:
|
||
"""在候选目录里找出包目录（含 __init__.py 的那一层）。
|
||
|
||
依次检查每个候选根目录下的子目录；若根目录本身就是包，也算命中。
|
||
这样仓库把源码放在 PyPI/src、src 或根目录都能被认出来。
|
||
"""
|
||
for root in search_roots:
|
||
root = Path(root)
|
||
if not root.is_dir() or _is_build_dir(root):
|
||
continue
|
||
if (root / "__init__.py").is_file():
|
||
return root
|
||
candidates = [
|
||
child
|
||
for child in sorted(root.iterdir())
|
||
if child.is_dir()
|
||
and not child.name.startswith((".", "_"))
|
||
and not _is_build_dir(child)
|
||
and (child / "__init__.py").is_file()
|
||
]
|
||
if len(candidates) == 1:
|
||
return candidates[0]
|
||
if candidates:
|
||
# 多个候选时，优先挑模块文件最多的那个
|
||
return max(candidates, key=lambda d: len(list(d.rglob("*.py"))))
|
||
# 退一步：支持没有 __init__.py 的命名空间包（PEP 420）
|
||
for root in search_roots:
|
||
root = Path(root)
|
||
if not root.is_dir() or _is_build_dir(root):
|
||
continue
|
||
loose = [
|
||
child
|
||
for child in sorted(root.iterdir())
|
||
if child.is_dir()
|
||
and not child.name.startswith((".", "_"))
|
||
and not _is_build_dir(child)
|
||
and any(child.glob("*.py"))
|
||
]
|
||
if loose:
|
||
return max(loose, key=lambda d: len(list(d.rglob("*.py"))))
|
||
return None
|
||
|
||
|
||
def _import_order(entry_module: Module) -> list[str]:
|
||
"""从包入口 __init__.py 解析导入顺序（from .xxx import * 等）。"""
|
||
order: list[str] = []
|
||
path = Path(entry_module.source_path or entry_module.path)
|
||
try:
|
||
text, _ = _read_text(path)
|
||
tree = _parse(text, str(path))
|
||
except (OSError, SyntaxError):
|
||
return order
|
||
for node in tree.body:
|
||
if isinstance(node, ast.ImportFrom) and node.level and node.module:
|
||
order.append(node.module)
|
||
elif isinstance(node, ast.ImportFrom) and node.level and node.names:
|
||
for alias in node.names:
|
||
order.append(alias.name)
|
||
return order
|
||
|
||
|
||
_TREE_CACHE: dict[str, ast.Module | None] = {}
|
||
|
||
|
||
def _tree_of(module: Module) -> ast.Module | None:
|
||
"""取模块的 AST（带缓存，解析失败返回 None）。"""
|
||
path = Path(module.source_path or module.path)
|
||
key = str(path)
|
||
if key in _TREE_CACHE:
|
||
return _TREE_CACHE[key]
|
||
tree: ast.Module | None = None
|
||
try:
|
||
text, _ = _read_text(path)
|
||
tree = _parse(text, str(path))
|
||
except (OSError, SyntaxError):
|
||
tree = None
|
||
_TREE_CACHE[key] = tree
|
||
return tree
|
||
|
||
|
||
def _package_context(module: Module) -> list[str]:
|
||
"""模块在包内的相对位置（用于解析 from .xxx import）。"""
|
||
if module.is_entry:
|
||
return []
|
||
if module.is_init:
|
||
return module.name.split(".")
|
||
parts = module.name.split(".")
|
||
return parts[:-1]
|
||
|
||
|
||
def _resolve_relative(module: Module, level: int, name: str) -> str:
|
||
"""把 `from .xxx import y` 里的 xxx 解析成包内的完整模块名。"""
|
||
context = _package_context(module)
|
||
if level > 1:
|
||
context = context[: max(0, len(context) - (level - 1))]
|
||
if name:
|
||
context = context + name.split(".")
|
||
return ".".join(context)
|
||
|
||
|
||
def _public_names(
|
||
module_name: str,
|
||
by_name: dict[str, Module],
|
||
stack: tuple[str, ...] = (),
|
||
) -> set[str]:
|
||
"""一个模块通过 `from .x import *` 会带出哪些名字。
|
||
|
||
除了本模块定义的函数与类，还包括它自己再导入的名字
|
||
（比如子包的 __init__.py 里 `from .extra import *`），
|
||
这样包入口 `from .sub import *` 也能把子包里的函数带出来。
|
||
"""
|
||
module = by_name.get(module_name)
|
||
if module is None or module_name in stack:
|
||
return set()
|
||
tree = _tree_of(module)
|
||
if tree is None:
|
||
return set()
|
||
|
||
explicit = _module_all(tree)
|
||
if explicit is not None:
|
||
return set(explicit)
|
||
|
||
names: set[str] = set()
|
||
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.ImportFrom):
|
||
if node.level:
|
||
if node.module:
|
||
target = _resolve_relative(module, node.level, node.module)
|
||
names |= _public_names(target, by_name, stack + (module_name,))
|
||
else:
|
||
# from . import mod：带出子模块本身
|
||
for alias in node.names:
|
||
if alias.name != "*":
|
||
names.add(alias.asname or alias.name)
|
||
elif node.module:
|
||
for alias in node.names:
|
||
if alias.name != "*":
|
||
names.add(alias.asname or alias.name)
|
||
elif isinstance(node, ast.Import):
|
||
for alias in node.names:
|
||
names.add(alias.asname or alias.name.split(".")[0])
|
||
return names
|
||
|
||
|
||
def _module_constants(module: Module) -> set[str]:
|
||
"""模块顶层定义的常量名（大写或普通赋值）。"""
|
||
tree = _tree_of(module)
|
||
if tree is None:
|
||
return set()
|
||
names: set[str] = set()
|
||
for node in tree.body:
|
||
if isinstance(node, ast.Assign):
|
||
for target in node.targets:
|
||
if isinstance(target, ast.Name):
|
||
names.add(target.id)
|
||
elif isinstance(node, ast.AnnAssign):
|
||
if isinstance(node.target, ast.Name):
|
||
names.add(node.target.id)
|
||
return names
|
||
|
||
|
||
def _definition_index(modules: list[Module]) -> dict[str, str]:
|
||
"""名字 → 真正定义它的模块。
|
||
|
||
同名时以先出现的模块为准；跨子包转发时也能指对真正定义的地方。
|
||
"""
|
||
index: dict[str, str] = {}
|
||
for module in modules:
|
||
for function in module.functions:
|
||
index.setdefault(function.name, module.name)
|
||
for klass in module.classes:
|
||
index.setdefault(klass.name, module.name)
|
||
return index
|
||
|
||
|
||
def compute_exports(
|
||
package_root: Path, modules: list[Module]
|
||
) -> tuple[dict[str, str], set[str]]:
|
||
"""计算包命名空间里可见的名字。
|
||
|
||
返回 (名字 → 定义所在模块, 包级显式 __all__)。
|
||
解析 __init__.py 里的几种导入写法：
|
||
* from .mod import * → 整个模块的公开名字
|
||
* from .mod import name → 单个名字
|
||
* from .mod import name as x→ 别名
|
||
* from . import mod → 子模块本身
|
||
|
||
只有包内真正定义出来的名字才算导出，第三方库（numpy、os 之类）
|
||
即使在 __init__.py 里被 import，也不会出现在导出表里。
|
||
"""
|
||
exports: dict[str, str] = {}
|
||
explicit_all: set[str] = set()
|
||
|
||
by_name = {module.name: module for module in modules}
|
||
entry = next((m for m in modules if m.is_entry), None)
|
||
if entry is None:
|
||
return exports, explicit_all
|
||
|
||
tree = _tree_of(entry)
|
||
if tree is None:
|
||
return exports, explicit_all
|
||
|
||
# 包里真正定义出来的名字（排除 import 进来的第三方名字，如 numpy）
|
||
owners = _definition_index(modules)
|
||
defined_names: set[str] = set(owners)
|
||
for module in modules:
|
||
defined_names.update(_module_constants(module))
|
||
|
||
def owner_of(name: str) -> str:
|
||
return owners.get(name, entry.name)
|
||
|
||
def is_public(name: str) -> bool:
|
||
"""下划线开头的名字不算公开 API。"""
|
||
return bool(name) and not name.startswith("_")
|
||
|
||
for node in tree.body:
|
||
if isinstance(node, ast.Assign):
|
||
for target in node.targets:
|
||
if isinstance(target, ast.Name) and target.id == "__all__":
|
||
value = _literal_value(node.value)
|
||
if isinstance(value, (list, tuple, set)):
|
||
explicit_all = {str(item) for item in value}
|
||
elif isinstance(node, ast.ImportFrom):
|
||
source = node.module or ""
|
||
if node.level and not source:
|
||
# from . import mod：把子模块本身挂到包命名空间上
|
||
for alias in node.names:
|
||
if alias.name == "*":
|
||
continue
|
||
target = _resolve_relative(entry, node.level, alias.name)
|
||
if target in by_name:
|
||
exports.setdefault(alias.asname or alias.name, target)
|
||
elif node.level and source:
|
||
source = _resolve_relative(entry, node.level, source)
|
||
if source not in by_name:
|
||
continue
|
||
for alias in node.names:
|
||
if alias.name == "*":
|
||
for name in _public_names(source, by_name):
|
||
if name in defined_names and is_public(name):
|
||
exports.setdefault(name, owner_of(name))
|
||
elif is_public(alias.asname or alias.name):
|
||
exports.setdefault(
|
||
alias.asname or alias.name, owner_of(alias.name)
|
||
)
|
||
elif source:
|
||
# from 包名 import xxx：只认包内真正定义过的名字
|
||
for alias in node.names:
|
||
if alias.name == "*":
|
||
continue
|
||
if alias.name in defined_names and is_public(alias.asname or alias.name):
|
||
exports.setdefault(
|
||
alias.asname or alias.name, owner_of(alias.name)
|
||
)
|
||
elif isinstance(node, ast.Import):
|
||
# 直接 import 进来的多半是第三方库，只有包内定义的名字才算导出
|
||
for alias in node.names:
|
||
name = alias.asname or alias.name.split(".")[0]
|
||
if alias.name.count(".") == 0 and name in defined_names and is_public(name):
|
||
exports.setdefault(name, owner_of(name))
|
||
|
||
# 入口自身定义的函数、类与常量总是可见
|
||
for function in entry.functions:
|
||
if is_public(function.name):
|
||
exports.setdefault(function.name, entry.name)
|
||
for klass in entry.classes:
|
||
if is_public(klass.name):
|
||
exports.setdefault(klass.name, entry.name)
|
||
for name in _module_constants(entry):
|
||
if is_public(name):
|
||
exports.setdefault(name, entry.name)
|
||
|
||
# 注意：__all__ 只影响 `from 包 import *`，
|
||
# 不影响 `包.名字` 的访问，所以这里不据此裁剪导出表。
|
||
return exports, explicit_all
|
||
|
||
|
||
def parse_modules(source_dir: Path) -> list[Module]:
|
||
"""解析包目录下的所有模块（只做语法解析，不涉及导出关系）。
|
||
|
||
递归处理子包；包入口 __init__.py 也作为一个模块返回（is_entry=True）。
|
||
顺序按 __init__.py 中的导入顺序排列，其余模块按名字追加。
|
||
"""
|
||
package_root = Path(source_dir)
|
||
modules: list[Module] = []
|
||
|
||
files = [
|
||
p
|
||
for p in sorted(package_root.rglob("*.py"))
|
||
if "__pycache__" not in p.parts and p.name != "setup.py"
|
||
]
|
||
for path in files:
|
||
relative = path.relative_to(package_root)
|
||
name = module_name_for(path, package_root)
|
||
if not name:
|
||
# 包入口 __init__.py：模块名就是包名
|
||
name = package_root.name
|
||
module = parse_module(path, name, relative.as_posix())
|
||
module.is_init = path.name == "__init__.py"
|
||
module.is_entry = module.is_init and path.parent == package_root
|
||
module.is_package = (path.parent / "__init__.py").is_file()
|
||
if module.is_entry:
|
||
module.title = module.title or package_root.name
|
||
modules.append(module)
|
||
|
||
# 排序：按 __init__.py 的导入顺序
|
||
entry = next((m for m in modules if m.is_entry), None)
|
||
order: list[str] = []
|
||
if entry is not None:
|
||
order = _import_order(entry)
|
||
rank = {name: index for index, name in enumerate(order)}
|
||
|
||
def sort_key(module: Module) -> tuple:
|
||
if module.is_entry:
|
||
return (1, 0, module.name)
|
||
return (0, rank.get(module.name, len(rank)), module.name)
|
||
|
||
modules.sort(key=sort_key)
|
||
return modules
|
||
|
||
|
||
def apply_exports(modules: list[Module], exports: dict[str, str]) -> None:
|
||
"""按导出表标记每个函数 / 类是否出现在包命名空间里。"""
|
||
for module in modules:
|
||
for function in module.functions:
|
||
function.exported = function.name in exports
|
||
for klass in module.classes:
|
||
klass.exported = klass.name in exports
|
||
|
||
|
||
def _direct_package_names(module: Module, by_name: dict[str, Module]) -> set[str]:
|
||
"""本模块用 `from .xxx import y` 直接引进来的包内名字。
|
||
|
||
这些名字在函数体里是以裸名字调用的（``y()``），
|
||
只靠「包名.xxx」的形式是找不到它们的。
|
||
"""
|
||
tree = _tree_of(module)
|
||
if tree is None:
|
||
return set()
|
||
names: set[str] = set()
|
||
for node in ast.walk(tree):
|
||
if not isinstance(node, ast.ImportFrom) or not node.level:
|
||
continue
|
||
for alias in node.names:
|
||
if alias.name == "*":
|
||
continue
|
||
name = alias.asname or alias.name
|
||
if name in by_name:
|
||
continue # 这是子模块本身，不是函数
|
||
names.add(name)
|
||
return names
|
||
|
||
|
||
def resolve_calls(
|
||
modules: list[Module],
|
||
package_root: Path,
|
||
package_aliases: set[str] | None = None,
|
||
) -> None:
|
||
"""算出每个函数调用到的包内函数（用于生成交叉参考）。"""
|
||
package_root = Path(package_root)
|
||
by_name = {module.name: module for module in modules}
|
||
|
||
# 包内的调用（交叉参考）应使用整个包的别名集合：
|
||
# 包名本身、模块名、以及源码里显式写下的别名。
|
||
all_aliases: set[str] = {package_root.name}
|
||
all_aliases |= {m.name for m in modules}
|
||
all_aliases |= {m.name.split(".")[0] for m in modules}
|
||
if package_aliases:
|
||
all_aliases |= package_aliases
|
||
for module in modules:
|
||
all_aliases |= _explicit_aliases(module)
|
||
|
||
for module in modules:
|
||
tree = _tree_of(module)
|
||
if tree is None:
|
||
continue
|
||
direct = _direct_package_names(module, by_name)
|
||
# 本模块自己定义的名字会遮住直接引入的同名函数
|
||
shadowed = {f.name for f in module.functions}
|
||
shadowed |= {c.name for c in module.classes}
|
||
calls_by_function: dict[tuple[str, int], list[str]] = {}
|
||
for node in ast.walk(tree):
|
||
if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
|
||
calls_by_function[(node.name, node.lineno)] = _package_calls(
|
||
node, all_aliases, direct, shadowed
|
||
)
|
||
for function in module.functions:
|
||
function.calls = calls_by_function.get(
|
||
(function.name, function.lineno), function.calls
|
||
)
|
||
|
||
|
||
def parse_package(
|
||
source_dir: Path, package_aliases: set[str] | None = None
|
||
) -> list[Module]:
|
||
"""解析整个包目录，返回模块列表。
|
||
|
||
解析、导出关系、交叉参考三步都做完了。
|
||
"""
|
||
package_root = Path(source_dir)
|
||
modules = parse_modules(package_root)
|
||
exports, _ = compute_exports(package_root, modules)
|
||
apply_exports(modules, exports)
|
||
resolve_calls(modules, package_root, package_aliases)
|
||
return modules
|
||
|
||
|
||
def _explicit_aliases(module: Module) -> set[str]:
|
||
"""源码里指向包内模块的别名。
|
||
|
||
只认相对导入（``from .core import foo as f``、``from . import core as c``），
|
||
第三方库的别名（``import numpy as np``）不算，
|
||
否则 ``np.array(...)`` 会被误认成对包内 ``array`` 的调用。
|
||
"""
|
||
tree = _tree_of(module)
|
||
if tree is None:
|
||
return set()
|
||
aliases: set[str] = set()
|
||
for node in ast.walk(tree):
|
||
if isinstance(node, ast.ImportFrom) and node.level:
|
||
for alias in node.names:
|
||
if alias.asname:
|
||
aliases.add(alias.asname)
|
||
return aliases
|
||
|
||
|
||
# --------------------------------------------------------------------------
|
||
# 包元信息
|
||
# --------------------------------------------------------------------------
|
||
|
||
|
||
def _read_pyproject(path: Path) -> dict[str, Any]:
|
||
if not path.exists():
|
||
return {}
|
||
try:
|
||
text, _ = _read_text(path)
|
||
return tomllib.loads(text)
|
||
except (OSError, ValueError, tomllib.TOMLDecodeError):
|
||
return {}
|
||
|
||
|
||
def _read_setup_cfg(path: Path) -> dict[str, dict[str, str]]:
|
||
if not path.exists():
|
||
return {}
|
||
parser = configparser.ConfigParser()
|
||
try:
|
||
text, _ = _read_text(path)
|
||
parser.read_string(text)
|
||
except (OSError, ValueError, configparser.Error):
|
||
return {}
|
||
return {section: dict(parser[section]) for section in parser.sections()}
|
||
|
||
|
||
def _version_from_init(path: Path) -> str:
|
||
"""从 __init__.py 里找 __version__ = "..."。"""
|
||
if not path.exists():
|
||
return ""
|
||
try:
|
||
text, _ = _read_text(path)
|
||
tree = _parse(text, str(path))
|
||
except (OSError, SyntaxError):
|
||
return ""
|
||
for node in tree.body:
|
||
if isinstance(node, ast.Assign):
|
||
for target in node.targets:
|
||
if isinstance(target, ast.Name) and target.id == "__version__":
|
||
value = _literal_value(node.value)
|
||
if isinstance(value, str):
|
||
return value
|
||
return ""
|
||
|
||
|
||
def _module_attr_value(path: Path, attr: str) -> str:
|
||
"""在模块里找某个赋值（``attr = "..."``）的字面量值。"""
|
||
try:
|
||
text, _ = _read_text(path)
|
||
tree = _parse(text, str(path))
|
||
except (OSError, SyntaxError):
|
||
return ""
|
||
for node in tree.body:
|
||
value = None
|
||
if isinstance(node, ast.Assign):
|
||
for target in node.targets:
|
||
if isinstance(target, ast.Name) and target.id == attr:
|
||
value = _literal_value(node.value)
|
||
elif isinstance(node, ast.AnnAssign):
|
||
if (
|
||
isinstance(node.target, ast.Name)
|
||
and node.target.id == attr
|
||
and node.value is not None
|
||
):
|
||
value = _literal_value(node.value)
|
||
if isinstance(value, str):
|
||
return value
|
||
return ""
|
||
|
||
|
||
def _attr_value(package_dir: Path | None, spec: str) -> str:
|
||
"""解析 ``attr: 包名.__version__``，静态读出那个值。
|
||
|
||
不 import 被解析的包，只按路径找文件读字面量。
|
||
"""
|
||
if not package_dir:
|
||
return ""
|
||
spec = spec.strip()
|
||
if "." not in spec:
|
||
return ""
|
||
module_part, _, attr = spec.rpartition(".")
|
||
parts = module_part.split(".")
|
||
candidates = []
|
||
if module_part == package_dir.name:
|
||
# 指的就是包自己
|
||
candidates.append(package_dir / "__init__.py")
|
||
candidates.append(package_dir.joinpath(*parts).with_suffix(".py"))
|
||
candidates.append(package_dir.joinpath(*parts, "__init__.py"))
|
||
for path in candidates:
|
||
if path.is_file():
|
||
value = _module_attr_value(path, attr)
|
||
if value:
|
||
return value
|
||
return ""
|
||
|
||
|
||
def _resolve_version_directive(
|
||
value: str, package_dir: Path | None, base_dir: Path | None
|
||
) -> str:
|
||
"""把 ``attr:`` / ``file:`` 形式的版本号写法解析成真正的值。
|
||
|
||
setup.cfg 里常写 ``version = attr: pkg.__version__``，
|
||
直接显示出来会很难看，这里静态地把它读出来。
|
||
"""
|
||
value = value.strip()
|
||
if value.startswith("attr:"):
|
||
return _attr_value(package_dir, value[5:]) or value
|
||
if value.startswith("file:"):
|
||
name = value[5:].strip()
|
||
if base_dir:
|
||
path = Path(base_dir) / name
|
||
if path.is_file():
|
||
try:
|
||
text, _ = _read_text(path)
|
||
except OSError:
|
||
return value
|
||
first = text.strip().splitlines()[0].strip() if text.strip() else ""
|
||
if first:
|
||
return first
|
||
return value
|
||
|
||
|
||
def parse_package_info(
|
||
pyproject: Path,
|
||
setup_cfg: Path | None = None,
|
||
init_file: Path | None = None,
|
||
package_dir: Path | None = None,
|
||
import_name: str = "",
|
||
) -> PackageInfo:
|
||
"""读取包信息。
|
||
|
||
同时兼容三种来源：PEP 621 的 [project] 表、setuptools 的 [metadata] 表、
|
||
以及 setup.cfg。本仓库的元数据写在 setup.cfg 的 [metadata] 段里。
|
||
"""
|
||
sources: list[dict[str, Any]] = []
|
||
|
||
data = _read_pyproject(Path(pyproject))
|
||
project = data.get("project")
|
||
if isinstance(project, dict):
|
||
sources.append(project)
|
||
metadata = data.get("metadata")
|
||
if isinstance(metadata, dict):
|
||
sources.append(metadata)
|
||
|
||
cfg = _read_setup_cfg(Path(setup_cfg)) if setup_cfg else {}
|
||
for section in ("metadata", "options"):
|
||
if section in cfg:
|
||
sources.append(cfg[section])
|
||
|
||
def pick(*keys: str, default: str = "") -> str:
|
||
for source in sources:
|
||
for key in keys:
|
||
value = source.get(key)
|
||
if isinstance(value, str) and value:
|
||
return value
|
||
return default
|
||
|
||
urls: dict[str, str] = {}
|
||
for source in sources:
|
||
raw = source.get("project_urls") or source.get("urls")
|
||
if not raw:
|
||
continue
|
||
if isinstance(raw, dict): # pyproject 的 [project.urls] 表
|
||
for key, value in raw.items():
|
||
if isinstance(value, str):
|
||
urls.setdefault(str(key), value)
|
||
continue
|
||
raw = str(raw)
|
||
if raw.strip().startswith("{"):
|
||
try:
|
||
urls = {str(k): str(v) for k, v in json.loads(raw).items()}
|
||
break
|
||
except (ValueError, TypeError):
|
||
continue
|
||
for line in raw.splitlines():
|
||
if "=" in line:
|
||
key, _, value = line.partition("=")
|
||
urls.setdefault(key.strip(), value.strip())
|
||
|
||
classifiers: list[str] = []
|
||
for source in sources:
|
||
value = source.get("classifiers")
|
||
if isinstance(value, list):
|
||
classifiers = [str(item) for item in value]
|
||
break
|
||
if isinstance(value, str) and value.strip():
|
||
classifiers = [line.strip() for line in value.splitlines() if line.strip()]
|
||
break
|
||
|
||
author = pick("author", "maintainer")
|
||
author_email = pick("author_email", "maintainer_email")
|
||
if not author or not author_email:
|
||
# PEP 621 的 authors / maintainers 是 [{name, email}, ...] 列表
|
||
for source in sources:
|
||
for key in ("authors", "maintainers"):
|
||
people = source.get(key)
|
||
if not isinstance(people, list):
|
||
continue
|
||
for person in people:
|
||
if not isinstance(person, dict):
|
||
continue
|
||
if not author and person.get("name"):
|
||
author = str(person["name"])
|
||
if not author_email and person.get("email"):
|
||
author_email = str(person["email"])
|
||
|
||
license_text = pick("license")
|
||
if not license_text:
|
||
for source in sources:
|
||
value = source.get("license")
|
||
if isinstance(value, dict):
|
||
license_text = str(value.get("text") or value.get("file") or "")
|
||
if license_text:
|
||
break
|
||
|
||
version = pick("version")
|
||
if version:
|
||
base_dir = Path(setup_cfg).parent if setup_cfg else None
|
||
version = _resolve_version_directive(version, package_dir, base_dir)
|
||
if not version and init_file is not None:
|
||
version = _version_from_init(Path(init_file))
|
||
|
||
name = pick("name")
|
||
if not name and package_dir is not None:
|
||
name = Path(package_dir).name
|
||
if not import_name and package_dir is not None:
|
||
import_name = Path(package_dir).name
|
||
|
||
description = pick("description", "summary")
|
||
if description.startswith("file:"):
|
||
# 描述指向一个文件时（比如 `description = file: README.md`），
|
||
# 取那个文件的第一段文字，而不是把 "file: ..." 摆在网站上
|
||
base_dir = Path(setup_cfg).parent if setup_cfg else None
|
||
if base_dir:
|
||
path = base_dir / description[5:].strip()
|
||
if path.is_file():
|
||
try:
|
||
text, _ = _read_text(path)
|
||
except OSError:
|
||
text = ""
|
||
description = _first_paragraph(text) or description
|
||
|
||
return PackageInfo(
|
||
name=name,
|
||
import_name=import_name or name,
|
||
version=version,
|
||
description=description,
|
||
summary=pick("summary"),
|
||
requires_python=pick("requires-python", "requires_python", "python_requires"),
|
||
url=pick("url", "home-page", "homepage"),
|
||
urls=urls,
|
||
author=author,
|
||
author_email=author_email,
|
||
license=license_text,
|
||
classifiers=classifiers,
|
||
)
|
||
|
||
|
||
# --------------------------------------------------------------------------
|
||
# 序列化
|
||
# --------------------------------------------------------------------------
|
||
|
||
|
||
def _function_to_dict(function: Function) -> dict[str, Any]:
|
||
"""把函数（或方法）序列化成统一的字典结构。"""
|
||
return {
|
||
"name": function.name,
|
||
"signature": function.signature,
|
||
"description": function.description,
|
||
"docstring": function.docstring,
|
||
"decorators": function.decorators,
|
||
"lineno": function.lineno,
|
||
"end_lineno": function.end_lineno,
|
||
"section": function.section,
|
||
"deprecated": function.deprecated,
|
||
"deprecated_note": function.deprecated_note,
|
||
"calls": function.calls,
|
||
"returns": function.returns,
|
||
"is_async": function.is_async,
|
||
"exported": function.exported,
|
||
"owner": function.owner,
|
||
"params": [
|
||
{
|
||
"name": p.name,
|
||
"default": p.default,
|
||
"annotation": p.annotation,
|
||
"kind": p.kind,
|
||
"required": p.required,
|
||
}
|
||
for p in function.params
|
||
],
|
||
"source": function.source,
|
||
}
|
||
|
||
|
||
def to_dict(
|
||
modules: list[Module],
|
||
info: PackageInfo,
|
||
exports: dict[str, str] | None = None,
|
||
) -> dict[str, Any]:
|
||
"""整理成可直接序列化为 JSON 的结构。"""
|
||
exported_names = set(exports or {})
|
||
return {
|
||
"package": {
|
||
"name": info.name,
|
||
"import_name": info.import_name or info.name,
|
||
"version": info.version,
|
||
"description": info.description,
|
||
"summary": info.summary,
|
||
"requires_python": info.requires_python,
|
||
"url": info.url,
|
||
"urls": info.urls,
|
||
"author": info.author,
|
||
"author_email": info.author_email,
|
||
"license": info.license,
|
||
"classifiers": info.classifiers,
|
||
},
|
||
"stats": {
|
||
"modules": len(modules),
|
||
"functions": sum(len(m.functions) for m in modules),
|
||
"classes": sum(len(m.classes) for m in modules),
|
||
"lines": sum(m.line_count for m in modules),
|
||
"data_tables": sum(len(m.data) for m in modules),
|
||
"exported_functions": sum(
|
||
1
|
||
for m in modules
|
||
for f in m.functions
|
||
if f.exported or f.name in exported_names
|
||
),
|
||
},
|
||
"exports": dict(sorted((exports or {}).items())),
|
||
"modules": [
|
||
{
|
||
"name": m.name,
|
||
"file": m.file,
|
||
"path": m.path,
|
||
"title": m.title,
|
||
"description": m.description,
|
||
"line_count": m.line_count,
|
||
"is_package": m.is_package,
|
||
"is_entry": m.is_entry,
|
||
"error": m.error,
|
||
"data": [
|
||
{
|
||
"name": d.name,
|
||
"kind": d.kind,
|
||
"description": d.description,
|
||
"lineno": d.lineno,
|
||
"origin": d.origin,
|
||
"entries": [{"key": k, "value": v} for k, v in d.entries],
|
||
}
|
||
for d in m.data
|
||
],
|
||
"classes": [
|
||
{
|
||
"name": c.name,
|
||
"description": c.description,
|
||
"docstring": c.docstring,
|
||
"bases": c.bases,
|
||
"lineno": c.lineno,
|
||
"exported": c.exported,
|
||
"attributes": list(c.attributes),
|
||
"methods": [_function_to_dict(f) for f in c.methods],
|
||
}
|
||
for c in m.classes
|
||
],
|
||
"functions": [_function_to_dict(f) for f in m.functions],
|
||
}
|
||
for m in modules
|
||
],
|
||
}
|