Python类型标注-JXin的博客

为什么需要类型标注

# 问题：参数类型不明确
def add(a, b):
    return a + b

# 调用者不知道应该传什么类型
add(1, 2)        # 3
add("1", "2")    # "12"  —— 这也是合法的，但可能不是预期行为
add([1], [2])    # [1, 2]  —— 同样合法

# 没有类型提示，难以在编码时发现错误

1
2
3
4
5
6
7
8
9
10

基础类型标注

变量类型标注

# 声明变量的类型
name: str = "Alice"
age: int = 25
pi: float = 3.14
is_active: bool = True

# 没有初始值
value: int
value = 10

# Python 是动态语言，类型标注不会强制约束
x: int = "hello"  # 不会报错，但类型检查工具会提示

1
2
3
4
5
6
7
8
9
10
11
12

函数类型标注

def greet(name: str, age: int) -> str:
    """函数参数和返回值的类型标注"""
    return f"{name} 今年 {age} 岁"

# 调用
greet("Alice", 25)        # 正确
greet("Alice", "25")      # 运行不会报错，但类型检查会警告

1
2
3
4
5
6
7

from typing import NoReturn

def exit_program() -> NoReturn:
    """表示函数永远不会正常返回"""
    import sys
    sys.exit(1)

1
2
3
4
5
6

常用复合类型

Optional 和 Union

from typing import Optional, Union

# Optional：值可以是某个类型，也可以是 None
def find_user(user_id: int) -> Optional[str]:
    """返回用户名，找不到时返回 None"""
    if user_id <= 0:
        return None
    return f"User_{user_id}"

# Union：值可以是多种类型之一
def parse_value(value: str) -> Union[int, float, str]:
    """尝试将字符串转换为数字，失败则返回原字符串"""
    try:
        if "." in value:
            return float(value)
        return int(value)
    except ValueError:
        return value

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

容器类型

from typing import List, Dict, Tuple, Set

# 列表：元素类型
scores: List[int] = [85, 90, 78]
names: List[str] = ["Alice", "Bob", "Charlie"]


# 字典：键类型, 值类型
student_scores: Dict[str, int] = {
    "Alice": 85,
    "Bob": 90,
}

# 元组：固定长度，每个位置类型可不同
point: Tuple[int, int] = (10, 20)
person: Tuple[str, int, bool] = ("Alice", 25, True)

# 集合：元素类型
tags: Set[str] = {"python", "typing", "type-hints"}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Any 和类型别名

from typing import Any, TypeAlias

# Any：任意类型，相当于没有类型约束
def log_data(data: Any) -> None:
    print(f"数据: {data}")

# 类型别名，让复杂类型更易读
Vector: TypeAlias = List[float]
Matrix: TypeAlias = List[List[float]]

def dot_product(v1: Vector, v2: Vector) -> float:
    """计算两个向量的点积"""
    return sum(a * b for a, b in zip(v1, v2))

1
2
3
4
5
6
7
8
9
10
11
12
13

类与自定义类型

from typing import Self

class Point:
    def __init__(self, x: float, y: float) -> None:
        self.x = x
        self.y = y

    def move(self, dx: float, dy: float) -> Self:
        """返回移动后的新点"""
        return Point(self.x + dx, self.y + dy)

    def distance_to(self, other: "Point") -> float:
        """计算到另一个点的距离"""
        return ((self.x - other.x) ** 2 + (self.y - other.y) ** 2) ** 0.5

# 使用
p1 = Point(0, 0)
p2 = Point(3, 4)
print(p1.distance_to(p2))  # 5.0

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

泛型

from typing import TypeVar, Generic

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:
        if not self._items:
            raise IndexError("栈为空")
        return self._items.pop()

    def peek(self) -> T | None:
        if not self._items:
            return None
        return self._items[-1]

# 使用
int_stack: Stack[int] = Stack()
int_stack.push(1)
int_stack.push(2)
print(int_stack.pop())  # 2

str_stack: Stack[str] = Stack()
str_stack.push("hello")
# str_stack.push(123)  # 类型检查会警告

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

Callable 和回调函数

from typing import Callable

def execute_callback(
    callback: Callable[[int, int], int],
    a: int,
    b: int
) -> int:
    """执行回调函数"""
    return callback(a, b)

# 使用
result = execute_callback(lambda x, y: x + y, 3, 5)
print(result)  # 8

1
2
3
4
5
6
7
8
9
10
11
12
13

应用场景

1. API 接口定义

from typing import TypedDict

class UserResponse(TypedDict):
    """API 返回的用户数据结构"""
    id: int
    name: str
    email: str
    is_active: bool

def get_user(user_id: int) -> UserResponse:
    return {
        "id": user_id,
        "name": "Alice",
        "email": "alice@example.com",
        "is_active": True,
    }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

2. 配合 IDE 获得智能提示

类型标注让 IDE 可以提供：

自动补全
参数提示
类型错误高亮

class Database:
    def connect(self, host: str, port: int = 5432) -> "Connection":
        ...

    def query(self, sql: str) -> list[dict[str, Any]]:
        ...

db = Database()
conn = db.connect("localhost")  # IDE 会提示 port 参数

1
2
3
4
5
6
7
8
9

忽略类型检查

有时某些代码难以标注或不需要检查，可以使用 # type: ignore 忽略：

# 忽略整行的类型检查
data = some_dynamic_library.load()  # type: ignore

# 有具体错误码时，可以指定忽略特定错误
x: int = "hello"  # type: ignore[assignment]

1
2
3
4
5

注意： 应该尽量少用，只在必要时使用

作业

一、为函数添加类型标注

为以下函数添加合适的类型标注：

def calculate_bmi(weight, height):
    """计算 BMI 指数"""
    if height <= 0:
        raise ValueError("身高必须大于0")
    return weight / (height ** 2)

def get_grade(score):
    """根据分数返回等级"""
    if score >= 90:
        return "A"
    elif score >= 80:
        return "B"
    elif score >= 70:
        return "C"
    elif score >= 60:
        return "D"
    else:
        return "F"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

二、实现泛型缓存

from typing import TypeVar, Generic, Optional

K = TypeVar("K")
V = TypeVar("V")

class Cache(Generic[K, V]):
    """泛型缓存类"""
    
    def __init__(self) -> None:
        # 你的代码
        pass
    
    def set(self, key: K, value: V) -> None:
        """设置缓存"""
        # 你的代码
        pass
    
    def get(self, key: K) -> Optional[V]:
        """获取缓存，不存在返回 None"""
        # 你的代码
        pass
    
    def clear(self) -> None:
        """清空缓存"""
        # 你的代码
        pass

# 测试
cache: Cache[str, int] = Cache()
cache.set("a", 1)
cache.set("b", 2)
print(cache.get("a"))   # 1
print(cache.get("c"))   # None
cache.clear()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

三、定义配置类

使用 TypedDict 定义应用配置结构：

from typing import TypedDict, Optional

class DatabaseConfig(TypedDict):
    """数据库配置"""
    # 你的代码：包含 host(str), port(int), username(str), password(str), database(str)

class AppConfig(TypedDict):
    """应用配置"""
    # 你的代码：包含 app_name(str), debug(bool), db(DatabaseConfig)

def load_config() -> AppConfig:
    """加载默认配置"""
    return {
        "app_name": "MyApp",
        "debug": False,
        "db": {
            "host": "localhost",
            "port": 5432,
            "username": "admin",
            "password": "secret",
            "database": "mydb",
        }
    }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

四、思考题

下面代码的类型标注是否正确？如果不正确，如何修改？

from typing import List, Dict

def process_data(items: List) -> Dict:
    """处理数据项"""
    result = {}
    for item in items:
        result[item["id"]] = item["value"]
    return result

def find_max(a: int, b: int) -> int | None:
    """返回较大的数"""
    if a == b:
        return None
    return a if a > b else b

1
2
3
4
5
6
7
8
9
10
11
12
13
14

作业答案

一、为函数添加类型标注

def calculate_bmi(weight: float, height: float) -> float:
    """计算 BMI 指数"""
    if height <= 0:
        raise ValueError("身高必须大于0")
    return weight / (height**2)

def get_grade(score: int) -> str:
    """根据分数返回等级"""
    if score >= 90:
        return "A"
    elif score >= 80:
        return "B"
    elif score >= 70:
        return "C"
    elif score >= 60:
        return "D"
    else:
        return "F"

# 测试
print(calculate_bmi(70, 1.75))  # 22.857...
print(get_grade(85))  # B
print(get_grade(59))  # F

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

二、实现泛型缓存

from typing import TypeVar, Generic, Optional, Dict

K = TypeVar("K")
V = TypeVar("V")

class Cache(Generic[K, V]):
    """泛型缓存类"""
    
    def __init__(self) -> None:
        self._data: Dict[K, V] = {}
    
    def set(self, key: K, value: V) -> None:
        """设置缓存"""
        self._data[key] = value
    
    def get(self, key: K) -> Optional[V]:
        """获取缓存，不存在返回 None"""
        return self._data.get(key)
    
    def clear(self) -> None:
        """清空缓存"""
        self._data.clear()

# 测试
cache: Cache[str, int] = Cache()
cache.set("a", 1)
cache.set("b", 2)
print(cache.get("a"))   # 1
print(cache.get("c"))   # None
cache.clear()
print(cache.get("a"))   # None

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

三、定义配置类

from typing import TypedDict

class DatabaseConfig(TypedDict):
    """数据库配置"""
    host: str
    port: int
    username: str
    password: str
    database: str

class AppConfig(TypedDict):
    """应用配置"""
    app_name: str
    debug: bool
    db: DatabaseConfig

def load_config() -> AppConfig:
    """加载默认配置"""
    return {
        "app_name": "MyApp",
        "debug": False,
        "db": {
            "host": "localhost",
            "port": 5432,
            "username": "admin",
            "password": "secret",
            "database": "mydb",
        }
    }

# 测试
config = load_config()
print(config["app_name"])           # MyApp
print(config["db"]["host"])         # localhost
print(config["db"]["port"])         # 5432

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

四、思考题

from typing import List, Dict, Any, Optional


# 原代码的问题：
# 1. List 和 Dict 没有指定泛型参数，不够具体
# 2. 应该明确 items 是包含 id 和 value 的字典列表
# 3. 返回值应该指定键和值的类型


def process_data(items: List[Dict[str, Any]]) -> Dict[Any, Any]:
    """处理数据项"""
    result: Dict[Any, Any] = {}
    for item in items:
        result[item["id"]] = item["value"]
    return result


# 更好的写法：使用 TypedDict 或更具体的类型
# from typing import TypedDict
# class DataItem(TypedDict):
#     id: int
#     value: str
# def process_data(items: List[DataItem]) -> Dict[int, str]:


def find_max(a: int, b: int) -> Optional[int]:
    """返回较大的数"""
    if a == b:
        return None
    return a if a > b else b


# 测试
print(process_data([{"id": 1, "value": "a"}, {"id": 2, "value": "b"}]))
print(find_max(3, 5))   # 5
print(find_max(3, 3))   # None

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

Python类型标注

为什么需要类型标注

基础类型标注

变量类型标注

函数类型标注

常用复合类型

Optional 和 Union

容器类型

Any 和 类型别名

类与自定义类型

泛型

Callable 和 回调函数

应用场景

1. API 接口定义

2. 配合 IDE 获得智能提示

忽略类型检查

作业

一、为函数添加类型标注

二、实现泛型缓存

三、定义配置类

四、思考题

作业答案

一、为函数添加类型标注

二、实现泛型缓存

三、定义配置类

四、思考题

Any 和类型别名

Callable 和回调函数