Python类型提示Type Hints - 泛型Protocol与mypy完整指南

# 变量类型标注
name: str = "Alice"
age: int = 30
height: float = 1.75
is_active: bool = True

# 函数参数和返回值标注
def greet(name: str) -> str:
    """打招呼"""
    return f"Hello, {name}!"

# 多个参数
def calculate_total(price: float, quantity: int, discount: float = 0.0) -> float:
    """计算总价"""
    return price * quantity * (1 - discount)

# 无返回值的函数（返回None）
def log_message(message: str) -> None:
    """打印日志"""
    print(f"[LOG] {message}")

# Python 3.10+ 联合类型（使用 | 代替 Union）
def process_value(value: int | str) -> str:
    if isinstance(value, int):
        return f"整数: {value}"
    return f"字符串: {value}"

# Optional 类型（表示可以为None）
from typing import Optional

def find_user(user_id: int) -> Optional[str]:
    """查找用户，可能找不到返回None"""
    users = {1: "Alice", 2: "Bob"}
    return users.get(user_id)

# Any 类型（关闭类型检查）
from typing import Any

def handle_anything(data: Any) -> Any:
    """处理任意类型（不推荐滥用）"""
    return data

from typing import List, Dict, Set, Tuple, Sequence, Mapping

# Python 3.9+ 可以使用内置泛型（推荐）
# Python 3.8及以下需要从typing导入

# 列表
def sum_numbers(numbers: list[int]) -> int:
    return sum(numbers)

# 字典
def get_user_info(users: dict[str, int], name: str) -> int:
    return users.get(name, 0)

# 集合
def unique_items(items: list[str]) -> set[str]:
    return set(items)

# 元组（固定长度和类型）
def get_coordinates() -> tuple[float, float]:
    return (40.7128, -74.0060)

# 可变长度元组
def process_events(events: tuple[str, ...]) -> None:
    for event in events:
        print(event)

# Sequence 和 Mapping（更抽象的类型）
def first_element(seq: Sequence[int]) -> int:
    """接收任何序列类型（list、tuple等）"""
    return seq[0]

def get_value(mapping: Mapping[str, int], key: str) -> int:
    """接收任何映射类型（dict等）"""
    return mapping[key]

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:
        return self._items.pop()
    
    def peek(self) -> T:
        return self._items[-1]
    
    def is_empty(self) -> bool:
        return len(self._items) == 0

# 使用示例
int_stack: Stack[int] = Stack()
int_stack.push(42)
int_stack.push(100)
value: int = int_stack.pop()  # mypy知道这是int类型

str_stack: Stack[str] = Stack()
str_stack.push("hello")
word: str = str_stack.pop()  # mypy知道这是str类型

from typing import Protocol, runtime_checkable

class Serializable(Protocol):
    """可序列化协议"""
    def to_dict(self) -> dict: ...
    def from_dict(self, data: dict) -> None: ...

class User:
    """用户类 - 没有继承Serializable，但实现了其方法"""
    def __init__(self, name: str, age: int):
        self.name = name
        self.age = age
    
    def to_dict(self) -> dict:
        return {"name": self.name, "age": self.age}
    
    def from_dict(self, data: dict) -> None:
        self.name = data["name"]
        self.age = data["age"]

def save_to_database(obj: Serializable) -> None:
    """接收任何实现了Serializable协议的对象"""
    data = obj.to_dict()
    print(f"保存数据: {data}")

# User没有显式继承Serializable，但因为实现了to_dict和from_dict
# mypy会认为User符合Serializable协议
user = User("Alice", 30)
save_to_database(user)  # mypy检查通过

# 安装mypy
pip install mypy

# 检查单个文件
mypy my_script.py

# 检查整个目录
mypy src/

# 严格模式（推荐用于新项目）
mypy --strict src/

# 忽略特定错误
mypy --ignore-missing-imports src/

# 生成HTML报告
mypy --html-report mypy_report src/

# pyproject.toml配置
# [tool.mypy]
# python_version = "3.9"
# warn_return_any = true
# warn_unused_configs = true
# disallow_untyped_defs = true
# disallow_incomplete_defs = true
# check_untyped_defs = true
# no_implicit_optional = true
# warn_redundant_casts = true
# warn_unused_ignores = true

# mypy检查示例
def add(a: int, b: int) -> int:
    return a + b

# ✅ 正确调用
result = add(1, 2)  # mypy: OK

# ❌ mypy会报告错误
result = add(1, "2")
# error: Argument 2 to "add" has incompatible type "str"; expected "int"

result = add(1, 2, 3)
# error: Too many arguments for "add"

# 类型忽略（当mypy误报时）
from typing import cast
x: int = cast(int, some_dynamic_value)  # type: ignore[cast]