如何访问函数注释

简介

Python 中的函数注释提供了一种强大的方式，可向函数参数和返回值添加类型提示和元数据。本教程探讨了访问和利用函数注释的技术，帮助开发者提高其 Python 项目中的代码可读性、类型安全性和文档质量。

函数注释简介

什么是函数注释？

Python 中的函数注释提供了一种向函数参数和返回值添加元数据的方式。自 Python 3 引入后，它们允许开发者在不影响函数运行时行为的情况下，将任意信息附加到函数签名上。

基本语法

def greet(name: str, age: int) -> str:
    return f"Hello, {name}! You are {age} years old."

在这个例子中，name: str 表示 name 参数预期为字符串类型，age: int 表示整数类型，而 -> str 指定返回类型为字符串。

关键特性

用例

函数注释在以下方面特别有用：

• 类型提示
• 文档说明
• 静态类型检查
• 生成文档
• 提供额外的元数据

复杂注释示例

def calculate_area(
    length: float,
    width: float,
    unit: str = "square meters"
) -> dict[str, float]:
    area = length * width
    return {
        "value": area,
        "unit": unit
    }

注释存储

注释存储在函数的 __annotations__ 属性中：

def sample_function(x: int, y: str) -> bool:
    pass

print(sample_function.__annotations__)
## 输出: {'x': <class 'int'>, 'y': <class'str'>,'return': <class 'bool'>}

函数注释的工作流程

graph TD
    A[函数定义] --> B[添加注释]
    B --> C[存储在 __annotations__ 中]
    C --> D[可选的类型检查]
    D --> E[运行时执行]

LabEx Pro 提示

在使用函数注释时，LabEx 建议使用 mypy 等工具进行静态类型检查，以充分发挥注释的潜力。

局限性

• 注释在运行时不强制进行类型检查
• 它们纯粹是提供信息的
• 性能开销极小

通过理解函数注释，Python 开发者可以编写更具自我文档性和类型感知的代码。

获取注释数据

访问函数注释

可以使用 __annotations__ 属性来获取函数注释，该属性提供了一个包含函数所有注释的字典。

基本检索方法

访问参数注释

def calculate_area(length: float, width: float) -> float:
    return length * width

## 获取参数注释
print(calculate_area.__annotations__)
## 输出: {'length': <class 'float'>, 'width': <class 'float'>,'return': <class 'float'>}

详细的注释提取

遍历注释

def user_profile(name: str, age: int, active: bool = True) -> dict:
    return {"name": name, "age": age, "active": active}

## 遍历注释
for param, annotation in user_profile.__annotations__.items():
    print(f"{param}: {annotation}")

注释检索技术

使用 inspect 模块进行高级检索

import inspect

def complex_function(x: "int > 0", y: list[int]) -> str:
    return f"Processing {x} items from {y}"

## 获取详细的注释信息
signature = inspect.signature(complex_function)
for param_name, param in signature.parameters.items():
    print(f"Parameter: {param_name}")
    print(f"Annotation: {param.annotation}")

注释检索的工作流程

graph TD
    A[带有注释的函数] --> B[访问 __annotations__]
    B --> C{检索方法}
    C --> |直接访问| D[简单字典]
    C --> |inspect 模块| E[详细签名]
    C --> |类型提示| F[解析后的引用]

处理复杂注释

使用 typing 模块

from typing import get_type_hints

def process_data(items: list[int], threshold: float = 0.5) -> list[int]:
    return [item for item in items if item > threshold]

## 获取类型提示
type_hints = get_type_hints(process_data)
print(type_hints)

LabEx Pro 提示

在处理注释时，LabEx 建议使用 typing 模块进行更强大的类型处理和前向引用解析。

常见陷阱

• 注释不是类型检查
• 运行时类型转换不是自动的
• 前向引用需要谨慎处理

实际示例

class DataProcessor:
    def transform(self, data: list[str],
                  converter: callable = str.upper) -> list[str]:
        return [converter(item) for item in data]

## 获取类方法注释
processor = DataProcessor()
print(processor.transform.__annotations__)

通过掌握这些注释检索技术，开发者可以更深入地了解函数类型提示和元数据。

高级注释技术

自定义类型注释

创建复杂类型提示

from typing import Union, List, Dict, Callable

def process_data(
    data: Union[List[int], List[str]],
    transformer: Callable[[str], int] = int
) -> Dict[str, int]:
    return {str(item): transformer(item) for item in data}

注释验证

运行时类型检查

def validate_annotations(func):
    def wrapper(*args, **kwargs):
        signature = inspect.signature(func)
        bound_arguments = signature.bind(*args, **kwargs)

        for name, value in bound_arguments.arguments.items():
            annotation = signature.parameters[name].annotation
            if annotation is not inspect.Parameter.empty:
                if not isinstance(value, annotation):
                    raise TypeError(f"{name} 必须是 {annotation} 类型")

        return func(*args, **kwargs)
    return wrapper

@validate_annotations
def create_user(name: str, age: int) -> dict:
    return {"name": name, "age": age}

高级注释策略

使用注释进行元编程

from typing import TypeVar, Generic

T = TypeVar('T')

class Repository(Generic[T]):
    def __init__(self, items: List[T]):
        self._items = items

    def filter(self, predicate: Callable[[T], bool]) -> List[T]:
        return [item for item in self._items if predicate(item)]

注释工作流程

graph TD
    A[函数定义] --> B[添加复杂注释]
    B --> C{注释处理}
    C --> |类型检查| D[验证输入/输出]
    C --> |元编程| E[生成动态行为]
    C --> |文档| F[生成元数据]

前向引用

from __future__ import annotations
from typing import List

class TreeNode:
    def __init__(self, value, children: List[TreeNode] = None):
        self.value = value
        self.children = children or []

LabEx Pro 提示

在实现高级注释时，LabEx 建议使用 typing.Protocol 创建灵活的结构化类型接口。

基于装饰器的注释处理

def type_checked(func):
    def wrapper(*args, **kwargs):
        annotations = func.__annotations__

        ## 检查参数类型
        for param, value in zip(func.__code__.co_varnames, args):
            if param in annotations:
                expected_type = annotations[param]
                if not isinstance(value, expected_type):
                    raise TypeError(f"{param} 必须是 {expected_type} 类型")

        result = func(*args, **kwargs)

        ## 检查返回类型
        if'return' in annotations:
            return_type = annotations['return']
            if not isinstance(result, return_type):
                raise TypeError(f"返回值必须是 {return_type} 类型")

        return result
    return wrapper

@type_checked
def multiply(x: int, y: int) -> int:
    return x * y

性能考虑

• 注释处理增加的运行时开销极小
• 使用静态类型检查器进行编译时验证
• 在类型安全和性能之间取得平衡

复杂注释模式

from typing import Literal, TypedDict

class UserConfig(TypedDict):
    username: str
    role: Literal['admin', 'user', 'guest']
    permissions: List[str]

def configure_user(config: UserConfig) -> None:
    ## 用户配置逻辑
    pass

通过掌握这些高级注释技术，开发者可以创建更健壮、自我文档化且类型安全的 Python 代码。

总结

通过掌握 Python 中的函数注释，开发者可以提高代码质量、改进类型检查，并创建更具自我文档性的代码。本教程涵盖的技术展示了如何检索、分析和利用注释数据来编写更健壮且易于维护的 Python 应用程序。