Python 类型注解（Type Hints）常用示例

适用于 Python 3.9+。若使用 Python < 3.9，请参考 typing 模块替代写法。

1. 基本类型

name: str = "Alice"
age: int = 25
height: float = 1.75
is_student: bool = True

2. 列表（List）

# Python 3.9+
scores: list[int] = [90, 85, 92]

# Python < 3.9
from typing import List
scores: List[int] = [90, 85, 92]

3. 字典（Dict）

# Python 3.9+
student_grades: dict[str, float] = {"math": 92.5, "english": 88.0}

# Python < 3.9
from typing import Dict
student_grades: Dict[str, float] = {"math": 92.5, "english": 88.0}

4. 元组（Tuple）

# 固定结构
point: tuple[float, float] = (1.0, 2.5)

# 任意长度（同类型）
rgb: tuple[int, ...] = (255, 128, 0)

5. 集合（Set）

# Python 3.9+
unique_ids: set[int] = {1, 2, 3}

6. 函数：参数与返回值

def greet(name: str) -> str:
    return f"Hello, {name}!"

def average(numbers: list[float]) -> float:
    return sum(numbers) / len(numbers)

7. 可选类型（Optional）

from typing import Optional

def get_middle_name(full_name: str) -> Optional[str]:
    parts = full_name.split()
    return parts[1] if len(parts) > 2 else None

等价于 Union[str, None]

8. 联合类型（Union）

# Python 3.10+
def parse_value(value: int | str) -> str:
    return str(value)

# Python < 3.10
from typing import Union
def parse_value(value: Union[int, str]) -> str:
    return str(value)

9. 自定义类作为类型

class Person:
    def __init__(self, name: str, age: int):
        self.name = name
        self.age = age

def introduce(person: Person) -> str:
    return f"{person.name} is {person.age} years old."

10. 泛型（TypeVar） 模板

from typing import TypeVar

T = TypeVar('T')

def first(items: list[T]) -> T:
    return items[0]

# 使用
numbers = [1, 2, 3]
first_num: int = first(numbers)

11. 字面量类型（Literal）

from typing import Literal

def set_theme(mode: Literal["light", "dark"]) -> None:
    print(f"Theme set to {mode}")

传入 "blue" 会被 mypy 报错。

12. 嵌套复杂结构

# 学生成绩：姓名 → 科目 → 分数
grades: dict[str, dict[str, float]] = {
    "Alice": {"math": 95.0, "science": 88.5},
    "Bob": {"math": 82.0, "science": 91.0}
}