Python：函数注解

函数注解（Function Annotations）是 Python 3 引入的一项语法特性。它允许在函数的参数和返回值中添加类型提示或说明信息，以增强代码的可读性、可维护性和开发效率。

Python 是动态类型语言，函数注解不会改变运行时行为，仅提供元信息，供 IDE、静态检查器、文档工具或运行时反射使用。

一、基本语法

函数参数与返回值的注解语法：

def 函数名(参数名: 注解) -> 返回值注解:
    函数体

示例：

def greet(name: str, age: int = 18) -> str:
    return f"{name} is {age} years old."

name: str 表示参数 name 应该是字符串。

age: int = 18 表示参数 age 应该是整数，默认值为 18。

-> str 表示函数的返回值应该是字符串。

注解不局限于类型，还可以是任意表达式或对象：

def add(a: '数字类型', b: int = 0) -> '返回整数':
    return a + b

提示：

注解中的字符串、对象仅作为元信息标签，本身不会被解释器执行类型检查。

注解信息会存储在函数的 __annotations__ 属性中：

print(greet.__annotations__)
# {'name': 

 , 'return': 

 } 

二、常见类型提示（typing 模块）

为了更精确地提示复杂类型，推荐使用 模块。

1、基本类型

用于标注参数或返回值为常见的内置数据类型。比如，str表示字符串，int表示整数。

def repeat(s: str, times: int = 2) -> str:
    return s * times

2、容器类型

用于标注容器及其内部元素的类型：

from typing import List, Dict, Tuple, Set

def total(scores: List[int]) -> int:     # 列表，元素是 int
    return sum(scores)

def phone_book() -> Dict[str, str]:      # 字典，键和值均是 str
    return {"Alice": "1234", "Bob": "5678"}

def split_pair() -> Tuple[int, int]:     # 固定长度的元组
    return (1, 2)

提示：

Python 3.9+ 支持原生类型提示（无需从 typing 导入）：

def func(data: list[int]) -> dict[str, int]:
    return {str(i): i for i in data}

3、Optional（可选类型）

用于表示一个值可能为某类型，也可能是 None。

from typing import Optional

def find(key: str) -> Optional[int]:
    return None

Python 3.10 可用 | 表示二选一。

def find(key: str) -> int | None:
    return None

4、Union（联合类型）

用于表示值可能属于多种类型之一。

from typing import Union

def stringify(data: Union[str, int, float]) -> str:
    return str(data)

Python 3.10 可用 | 表示多选一：

def stringify(data: str | int | float) -> str:
    return str(data)

提示：

Optional[T] 是 Union[T, None] 的简写。

5、Any（任意类型）

表示可以是任意类型，适合需要最大灵活性的场景。

from typing import Any

def log_all(*args: Any, **kwargs: Any) -> None:
    print(args, kwargs)

6、Callable（可调用对象）

用于表示参数或返回值是函数、方法、lambda 等可调用对象。

from typing import Callable

def apply(f: Callable[[int, int], int], x: int, y: int) -> int:
    return f(x, y)

print(apply(lambda a, b: a + b, 3, 4))

Callable 的格式为：Callable[[参数类型...], 返回类型]

7、Literal（字面量类型）

用于限制值必须是固定的字面量之一，常用于配置值、枚举场景。

from typing import Literal

def get_status(code: int) -> Literal["ok", "error"]:
    return "ok" if code == 0 else "error"

8、TypeVar（泛型类型）

用于编写泛型函数或类，保持参数和返回值类型一致。

from typing import TypeVar

T = TypeVar("T")

def identity(x: T) -> T:
    return x

泛型使函数/类更通用，适用于多种类型。

9、其他常用提示

Self

（Python 3.11+）用于类方法，表示返回当前类实例，更直观：

from typing import Self

class Person:
    def set_name(self, name: str) -> Self:
        self.name = name
        return self

Annotated

（Python 3.9+）在类型提示中附加额外元信息（例如校验规则、文档说明）：

from typing import Annotated

def scale(x: Annotated[float, "must be positive"]) -> float:
    return x * 2

Self 让类方法返回值更清晰，Annotated 让类型提示更有语义性。

三、应用场景

1、静态类型检查

使用工具如 进行代码静态分析，提前发现类型错误。

安装与使用：

pip install mypy
mypy your_script.py

示例：

def add(a: int, b: int) -> int:
    return a + b

add("1", "2")  # ⚠ mypy 报错，但 Python 仍能运行

2、IDE 自动补全与提示

PyCharm、VSCode 等编辑器会根据注解提供智能提示。

3、代码文档生成

如 、 会利用注解生成更清晰的 API 文档。

4、运行时验证（配合第三方库）

如 、 实现运行时类型检查。

from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int

u = User(name="Alice", age="18")  # 自动转为 int
print(u)

小结

函数注解在 Python 中并不是“强制类型”的工具，而是一种增强代码语义的说明机制。在大型项目中，合理地使用函数注解配合工具链，可以有效提高代码质量、可读性和开发效率。

“点赞有美意，赞赏是鼓励”