python中类型标注的实现示例

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

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

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

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

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

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

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

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

from typing import NoReturn

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

Optional[str]
Union[str, None]
str | None          # Python 3.10+

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}"

name = find_user(1)
if name is None:
    print("没找到")
else:
    print(name)  # 这里才是确定的 str

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

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"}

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))

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

# 不用泛型：返回类型丢失了
def get_first(items):
    return items[0]

# 你无法知道返回的到底是什么类型

from typing import TypeVar

T = TypeVar('T')  # 定义一个类型变量

from typing import TypeVar, List

T = TypeVar('T')

def get_first_item(lst: List[T]) -> T:
    return lst[0]

# 调用时，类型自动推断
num = get_first_item([1, 2, 3])       # num 的类型是 int
text = get_first_item(['a', 'b', 'c']) # text 的类型是 str

from typing import TypeVar, Generic

T = TypeVar('T')

class Box(Generic[T]):
    def __init__(self, content: T):
        self.content = content

    def get(self) -> T:
        return self.content

# 使用
int_box = Box(42)          # Box[int]
str_box = Box("hello")     # Box[str]

# 以前
from typing import TypeVar, Generic
T = TypeVar('T')
class Box(Generic[T]):
    def get(self) -> T: ...

# 现在（Python 3.12+）
class Box[T]:
    def get(self) -> T: ...

# 函数也可以这样写
def get_first[T](lst: list[T]) -> T:
    return lst[0]

T = TypeVar('T')  # 可以是任何类型

S = TypeVar('S', bound=str)  # 必须是 str 或其子类

def print_capitalized(x: S) -> S:
    print(x.capitalize())
    return x

A = TypeVar('A', str, bytes)  # 只能是 str 或 bytes

def concatenate(x: A, y: A) -> A:
    return x + y

concatenate("hello", "world")  # OK，返回 str
concatenate(b"foo", b"bar")    # OK，返回 bytes
# concatenate("foo", b"bar")   # 类型检查报错，不能混用

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

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,
    }

from typing import TypedDict, NotRequired


class Product(TypedDict):
    id: int
    name: str
    description: NotRequired[str]  # 可选字段，可以不提供

# 两种写法都合法
p1: Product = {"id": 1, "name": "手机"}
p2: Product = {"id": 2, "name": "电脑", "description": "高性能笔记本"}

class Config(TypedDict, total=False):
    debug: bool
    retry_times: int
    timeout: float

# 所有字段都可以不提供
c: Config = {}