当前位置：首页 > news >正文

Python类型推导协议

news 2026/5/30 20:55:48

===============================================================================
Python 类型推导与协议 (Protocol & TypeGuard)
===============================================================================
深入 Python 的类型系统：Protocol 实现结构子类型（鸭子类型），
TypeGuard 自定义类型收窄，@runtime_checkable 运行时检查，
以及协变/逆变、类型桩文件等高级主题。
===============================================================================

from typing import (
Protocol, TypeVar, runtime_checkable,
TypeGuard, assert_type, reveal_type,
Iterator, Iterable, overload
)
from typing import TYPE_CHECKING

T = TypeVar("T")

# ===================================================================
# 第一部分：Protocol 结构子类型
# ===================================================================

# -------------------------------------------------------------------
# 1. 基本 Protocol：定义行为接口而非类层次
# -------------------------------------------------------------------
class 可打印(Protocol):
"""任何具有 .to_str() 方法的对象都自动满足此协议"""
def to_str(self) -> str: ...

class 用户:
def __init__(self, name: str):
self.name = name
def to_str(self) -> str:
return f"用户: {self.name}"

class 商品:
def __init__(self, title: str, price: float):
self.title = title
self.price = price
def to_str(self) -> str:
return f"{self.title} (¥{self.price})"

def 格式化输出(对象: 可打印) -> None:
"""接受任何满足可打印协议的对象"""
print(f"格式化: {对象.to_str()}")

格式化输出(用户("张三")) # → 格式化: 用户: 张三
格式化输出(商品("Python教程", 39.9)) # → 格式化: Python教程 (¥39.9)

# -------------------------------------------------------------------
# 2. 多方法协议：定义完整接口
# -------------------------------------------------------------------
class 可迭代集合(Iterable[T], Protocol[T]):
"""协议可以继承其他协议或类型"""
def __len__(self) -> int: ...
def __iter__(self) -> Iterator[T]: ...

def 获取大小(集合: 可迭代集合) -> int:
return len(集合)

print(f"列表大小: {获取大小([1, 2, 3])}") # → 3
print(f"集合大小: {获取大小({1, 2, 3, 4})}") # → 4

# -------------------------------------------------------------------
# 3. @runtime_checkable：运行时协议检查
# -------------------------------------------------------------------
@runtime_checkable
class 可序列化(Protocol):
def 序列化(self) -> bytes: ...
def 反序列化(self, 数据: bytes) -> None: ...

class JSON文档:
def 序列化(self) -> bytes:
return b'{"key": "value"}'
def 反序列化(self, 数据: bytes) -> None:
print(f"反序列化: {数据}")

class XML文档:
def 序列化(self) -> bytes:
return b"value"
def 反序列化(self, 数据: bytes) -> None:
print(f"解析 XML: {数据}")

def 保存文档(文档: 可序列化) -> None:
if isinstance(文档, 可序列化):
数据 = 文档.序列化()
print(f"保存 {len(数据)} 字节")
else:
raise TypeError("对象不可序列化")

保存文档(JSON文档()) # → 保存 16 字节

# ===================================================================
# 第二部分：TypeGuard 类型守卫
# ===================================================================

# -------------------------------------------------------------------
# 4. TypeGuard：自定义类型收窄
# -------------------------------------------------------------------
def 是字符串列表(值: list[object]) -> TypeGuard[list[str]]:
"""TypeGuard 让类型检查器知道：如果返回 True，参数就是 list[str]"""
return all(isinstance(x, str) for x in 值)

def 是整数列表(值: list[object]) -> TypeGuard[list[int]]:
return all(isinstance(x, int) for x in 值)

def 处理混合列表(列表: list[object]) -> None:
if 是字符串列表(列表):
print(f"字符串列表: {', '.join(列表)}")
elif 是整数列表(列表):
总和 = sum(列表)
print(f"整数列表, 总和: {总和}")
else:
print(f"混合类型列表: {列表}")

处理混合列表(["a", "b", "c"]) # → 字符串列表: a, b, c
处理混合列表([1, 2, 3, 4, 5]) # → 整数列表, 总和: 15
处理混合列表([1, "two", 3]) # → 混合类型列表

# -------------------------------------------------------------------
# 5. TypeGuard 在类方法中的使用
# -------------------------------------------------------------------
class 数据处理器:
@staticmethod
def 是有效记录(数据: dict[str, object]) -> TypeGuard[dict[str, str | int]]:
return (
"id" in 数据 and isinstance(数据["id"], int)
and "name" in 数据 and isinstance(数据["name"], str)
)
@classmethod
def 处理(cls, 数据: dict[str, object]) -> None:
if cls.是有效记录(数据):
print(f"处理记录: id={数据['id']}, name={数据['name']}")
else:
print("无效记录")

数据处理器.处理({"id": 1, "name": "张三"})

# ===================================================================
# 第三部分：类型推断辅助工具
# ===================================================================

# -------------------------------------------------------------------
# 6. assert_type 和 reveal_type
# -------------------------------------------------------------------
def 类型检查辅助():
值1: int = 42
# reveal_type(值1) # mypy 显示: Revealed type is 'builtins.str'
print(f"类型检查辅助工具: assert_type / reveal_type")

类型检查辅助()

# -------------------------------------------------------------------
# 7. 类型桩文件 (.pyi)
# -------------------------------------------------------------------
def 桩文件示例():
"""
类型桩文件 (.pyi) 为纯 Python 项目提供类型信息：
- 放在与 .py 文件同目录下，文件名相同，扩展名为 .pyi
- 只包含类型签名，不含实现
"""
print("类型桩文件 (.pyi) 为已有模块添加类型信息")
print("优点：不改动源码即可添加类型")

桩文件示例()

# ===================================================================
# 第四部分：协变与逆变在 Protocol 中的应用
# ===================================================================

# -------------------------------------------------------------------
# 8. Protocol 中的协变与逆变
# -------------------------------------------------------------------
T_co = TypeVar("T_co", covariant=True)
T_con = TypeVar("T_con", contravariant=True)

class 生产者(Protocol[T_co]):
"""协变协议：只产生（返回）值"""
def 获取(self) -> T_co: ...

class 消费者(Protocol[T_con]):
"""逆变协议：只消费（接收）值"""
def 放入(self, 值: T_con) -> None: ...

class Int生产者:
def 获取(self) -> int:
return 42

def 使用生产者(p: 生产者[float]) -> None:
print(f"生产值: {p.获取()}")

使用生产者(Int生产者()) # 协变允许

class Float消费者:
def 放入(self, 值: float) -> None:
print(f"消费浮点: {值}")

def 需要int消费者(c: 消费者[int]) -> None:
c.放入(100)

需要int消费者(Float消费者()) # 逆变允许

# ===================================================================
# 第五部分：综合应用示例
# ===================================================================

# -------------------------------------------------------------------
# 9. 完整的 Protocol 实战：仓库模式
# -------------------------------------------------------------------
T实体 = TypeVar("T实体")

class 仓库(Protocol[T实体]):
def 按ID获取(self, id: int) -> T实体 | None: ...
def 保存(self, 实体: T实体) -> None: ...
def 删除(self, id: int) -> bool: ...

@runtime_checkable
class 可验证(Protocol):
def 验证(self) -> bool: ...

class 用户仓库:
def __init__(self):
self._数据: dict[int, str] = {}
def 按ID获取(self, id: int) -> str | None:
return self._数据.get(id)
def 保存(self, 实体: str) -> None:
id = hash(实体) % 10000
self._数据[id] = 实体
def 删除(self, id: int) -> bool:
return self._数据.pop(id, None) is not None
def 验证(self) -> bool:
return len(self._数据) < 1000

def 执行仓库操作(仓库对象: 仓库[str]) -> None:
仓库对象.保存("测试数据")
if isinstance(仓库对象, 可验证):
print(f"验证通过: {仓库对象.验证()}")

u = 用户仓库()
执行仓库操作(u)

# ===================================================================
# 总结
# ===================================================================
# Python 类型推导与协议核心概念：
#
# Protocol:
# - 结构子类型：根据对象的方法签名判断类型（鸭子类型）
# - @runtime_checkable: 支持 isinstance() 运行时检查
# - 可继承其他协议/类型组合接口
#
# TypeGuard:
# - 自定义类型收窄函数
# - 类型检查器根据返回值收窄类型
#
# 辅助工具:
# - assert_type: 运行时断言类型（开发调试）
# - reveal_type: 让类型检查器显示推断类型
# - .pyi 桩文件: 为已有模块添加类型信息
#
# 协变/逆变:
# - 协变 (covariant): 生产者/只读容器
# - 逆变 (contravariant): 消费者/只写容器
# - 不变 (invariant): 读写兼备的容器