Python函数怎样用函数注解实现简单的接口文档 Python函数注解接口文档化的方法​

typing

Annotated

Annotated

Annotated

from typing import Annotated, get_type_hints

def process_user_data(
    user_id: Annotated[int, "用户的唯一标识符，必须是正整数"],
    user_name: Annotated[str, "用户的名称，字符串类型，不能为空"],
    is_active: Annotated[bool, "用户是否处于活跃状态，布尔值"] = True
) -> Annotated[dict, "处理后的用户数据字典，包含id、name和status"]:
    """
    根据提供的用户ID、名称和活跃状态，处理并返回用户数据。
    这是一个示例函数，用于演示注解的使用。
    """
    if not isinstance(user_id, int) or user_id <= 0:
        raise ValueError("用户ID必须是正整数。")
    if not user_name:
        raise ValueError("用户名称不能为空。")

    # 实际的业务逻辑
    processed_data = {
        "id": user_id,
        "name": user_name.strip(),
        "status": "active" if is_active else "inactive"
    }
    return processed_data

# 如何提取这些注解信息
# 使用 get_type_hints 函数，并设置 include_extras=True 来获取 Annotated 中的元数据
annotations_info = get_type_hints(process_user_data, include_extras=True)

print("--- 函数注解提取结果 ---")
for param_name, annotation_type in annotations_info.items():
    if hasattr(annotation_type, '__metadata__') and annotation_type.__metadata__:
        # 如果是 Annotated 类型，__origin__ 是原始类型，__metadata__ 是附加的元数据
        original_type = annotation_type.__origin__.__name__ if hasattr(annotation_type.__origin__, '__name__') else str(annotation_type.__origin__)
        description = annotation_type.__metadata__[0] # 假设描述是第一个元数据
        print(f"参数/返回: {param_name}")
        print(f"  类型: {original_type}")
        print(f"  描述: {description}")
    else:
        # 普通的类型注解
        print(f"参数/返回: {param_name}")
        print(f"  类型: {annotation_type.__name__ if hasattr(annotation_type, '__name__') else str(annotation_type)}")
        print(f"  描述: 无额外描述")
print("------------------------")

Annotated

get_type_hints

include_extras=True

__annotations__

typing.Annotated

__annotations__

typing.get_type_hints()

from typing import Annotated, get_type_hints

def calculate_average(
    numbers: Annotated[list[float], "待计算平均值的浮点数列表，不能为空"],
    weights: Annotated[list[float] | None, "可选的权重列表，与numbers长度一致，不提供则视为等权"] = None
) -> Annotated[float, "计算出的加权平均值，如果列表为空则返回0.0"]:
    """
    计算一个浮点数列表的加权平均值。
    """
    if not numbers:
        return 0.0
    if weights and len(numbers) != len(weights):
        raise ValueError("权重列表的长度必须与数值列表一致。")

    total_sum = sum(n * w for n, w in zip(numbers, weights)) if weights else sum(numbers)
    total_weight = sum(weights) if weights else len(numbers)
    return total_sum / total_weight if total_weight != 0 else 0.0

def extract_annotation_docs(func):
    """
    提取函数的所有注解信息，包括 Annotated 中的描述。
    返回一个字典，键为参数/返回名，值为包含类型和描述的字典。
    """
    docs = {}
    # 使用 get_type_hints 确保解析 Annotated 类型
    hints = get_type_hints(func, include_extras=True)

    for name, hint in hints.items():
        param_info = {"type": None, "description": "无描述"}
        if hasattr(hint, '__metadata__') and hint.__metadata__:
            # 是 Annotated 类型
            param_info["type"] = str(hint.__origin__) # 原始类型
            param_info["description"] = hint.__metadata__[0] # 第一个元数据作为描述
        else:
            # 普通类型注解
            param_info["type"] = str(hint)
        docs[name] = param_info
    return docs

# 提取并打印文档信息
extracted_docs = extract_annotation_docs(calculate_average)
print("\n--- 自动化提取的文档信息 ---")
for name, info in extracted_docs.items():
    print(f"名称: {name}")
    print(f"  类型: {info['type']}")
    print(f"  描述: {info['description']}")
print("--------------------------")

# 你可以进一步将 extracted_docs 字典转换为 Markdown、HTML 或其他格式
# 例如，生成一个简单的 Markdown 表格：
markdown_table = ["| 参数/返回 | 类型 | 描述 |", "|---|---|---|"]
for name, info in extracted_docs.items():
    markdown_table.append(f"| {name} | `{info['type']}` | {info['description']} |")

print("\n--- 生成的 Markdown 表格 ---")
print("\n".join(markdown_table))
print("--------------------------")

extract_annotation_docs