Python类型注解举例超详细指南_Python

python 类型注解详细指南

类型注解(type annotations)是 python 3.5+ 引入的一项重要特性，它允许开发者显式地声明变量、函数参数和返回值的类型。

1.基础类型注解

python 内置的基本类型可以直接用于注解：

# 变量注解
name: str = "alice"
age: int = 30
price: float = 19.99
is_active: bool = true

# 函数参数和返回值注解
def greet(name: str) -> str:
    return f"hello, {name}"

2.复合类型注解

对于更复杂的类型，可以使用 typing 模块中的工具：

from typing import list, dict, tuple, set, optional

# 列表
numbers: list[int] = [1, 2, 3]

# 字典
person: dict[str, str] = {"name": "alice", "email": "alice@example.com"}

# 元组 (固定长度和类型)
point: tuple[float, float] = (3.14, 2.71)

# 集合
unique_numbers: set[int] = {1, 2, 3}

# 可选类型 (表示可能是none)
middle_name: optional[str] = none

3.函数类型注解

函数可以详细注解参数和返回值类型：

from typing import callable

# 基本函数注解
def add(a: int, b: int) -> int:
    return a + b

# 带默认值的参数
def greet(name: str, greeting: str = "hello") -> str:
    return f"{greeting}, {name}"

# 函数作为参数
def apply_func(func: callable[[int, int], int], x: int, y: int) -> int:
    return func(x, y)

4.特殊类型

typing 模块提供了许多特殊类型：

from typing import any, union, noreturn

# any - 任意类型
def log(message: any) -> none:
    print(message)

# union - 多个可能的类型
def square(number: union[int, float]) -> union[int, float]:
    return number ** 2

# noreturn - 函数不会正常返回
def fail() -> noreturn:
    raise exception("something went wrong")

5.类型别名

可以为复杂类型创建别名提高可读性：

from typing import list, tuple

# 简单别名
userid = int

# 复杂别名
point = tuple[float, float]
vector = list[float]

def normalize(vector: vector) -> vector:
    length = sum(x**2 for x in vector) ** 0.5
    return [x/length for x in vector]

6.泛型

使用泛型创建可重用的类型模板：

from typing import typevar, generic, list

t = typevar('t')  # 声明类型变量

class stack(generic[t]):
    def __init__(self) -> none:
        self.items: list[t] = []
    
    def push(self, item: t) -> none:
        self.items.append(item)
    
    def pop(self) -> t:
        return self.items.pop()

# 使用
int_stack = stack[int]()
int_stack.push(1)

7.类型变量

类型变量允许约束可能的类型：

from typing import typevar, union

# 无约束的类型变量
t = typevar('t')

# 约束的类型变量
number = typevar('number', int, float, complex)

def double(x: number) -> number:
    return x * 2

8.自定义类型

可以创建自定义类型：

from typing import newtype, typeddict

# 新类型
userid = newtype('userid', int)

def get_user_name(user_id: userid) -> str:
    return f"user_{user_id}"

# 类型化字典 (python 3.8+)
class person(typeddict):
    name: str
    age: int
    email: optional[str]

person: person = {"name": "alice", "age": 30}

9.类型检查工具

常用的类型检查工具：

mypy: 最流行的静态类型检查器
pyright: microsoft 开发的类型检查器
pytype: google 开发的类型检查器

安装 mypy:

pip install mypy

运行类型检查:

mypy your_script.py

10.注意事项

渐进式类型化：可以逐步添加类型注解，不需要一次性完成
优先注解公共api：优先注解模块接口、函数参数和返回值
使用严格模式：在 mypy 中使用 --strict 标志获取最严格的检查
保持一致性：整个项目中保持一致的注解风格
文档与类型互补：类型注解不能完全替代文档，重要行为仍需文档说明
避免过度使用any：尽量使用具体类型，any 会失去类型检查的好处
利用类型推断：简单的局部变量可以省略类型注解

总结

在python中使用类型注解（type annotations）虽然看起来与python的动态类型特性相悖，但实际上这是python社区近年来积极推广的实践，具有重要的实际意义。python 的类型注解系统提供了强大的工具来增强代码的可读性和可维护性，同时通过静态类型检查可以在开发早期发现潜在的错误。随着 python 类型系统的不断演进，类型注解正成为大型 python 项目的标准实践，具有以下优势：

（1）代码可读性与文档化

显式契约：类型注解明确声明了参数和返回值的预期类型，使函数接口的语义一目了然。例如 def get_user(id: int) -> user 比未注解的版本更清晰。
替代部分注释：减少对参数类型的文字描述（如 # x should be an integer），直接通过语法表达意图。

（2）静态类型检查

工具支持：配合静态类型检查工具（如 mypy, pyright, pycharm内置检查），可以在代码运行前捕获类型相关的错误。例如：
```
func(x="hello")  # 静态检查会报错：expected 'int', got 'str'
```
提前发现错误：避免运行时因类型错误导致的 attributeerror 或 typeerror，尤其适合大型项目。

（3）ide智能支持