【Python】typing_extensions库：增强Python类型注解的支持功能详解

typing_extensions 是一个 Python 库，提供对 Python 类型注解的扩展支持，包含在较新 Python 版本中引入的类型功能（如 Literal、TypedDict、Protocol），并将其回溯到旧版本。它是 typing 标准库的补充，广泛用于需要高级类型注解的场景，如静态类型检查（使用 mypy、pyright）、IDE 类型提示和现代 Python 项目。

以下是对 typing_extensions 库的详细介绍，包括其功能、用法和实际应用，基于最新信息（截至 2025）。

1. typing_extensions 库的作用

2. 安装与环境要求

pip install typing-extensions

import typing_extensions
print(typing_extensions.__version__)  # 示例输出: 4.12.2

注意：

3. 核心功能与用法

typing_extensions 扩展了 typing 模块，提供了多种高级类型和工具。以下是主要功能和示例。

3.1 Literal

表示变量只能取特定字面值。

from typing_extensions import Literal

def set_mode(mode: Literal["on", "off"]) -> None:
    print(f"Mode set to {mode}")

set_mode("on")  # 正确
# set_mode("standby")  # mypy 报错: Argument 1 to "set_mode" has incompatible type "str"; expected "Literal['on', 'off']"

说明：

3.2 TypedDict

定义字典的键值类型，支持必需/可选字段。

from typing_extensions import TypedDict, Required, NotRequired

class Movie(TypedDict):
    title: str
    year: NotRequired[int]  # 可选字段
    rating: Required[float]  # 必需字段

movie: Movie = {"title": "Inception", "rating": 8.8}
# movie = {"title": "Inception"}  # mypy 报错: Missing key "rating"

说明：

3.3 Protocol

定义结构化类型（鸭子类型），支持隐式接口。

from typing_extensions import Protocol

class HasName(Protocol):
    def get_name(self) -> str:
        ...

class Person:
    def get_name(self) -> str:
        return "Alice"

class Robot:
    def get_name(self) -> str:
        return "R2-D2"

def greet(entity: HasName) -> None:
    print(f"Hello, {entity.get_name()}!")

greet(Person())  # 正确
greet(Robot())   # 正确

说明：

3.4 Annotated

附加元数据到类型注解。

from typing_extensions import Annotated

def process_data(data: Annotated[str, "Sensitive"]) -> None:
    print(f"Processing: {data}")

process_data("secret")

说明：

3.5 Self

表示当前类的类型，适合方法返回自身实例。

from typing_extensions import Self

class Node:
    def __init__(self, value: int) -> None:
        self.value = value
        self.next: Node | None = None

    def add_next(self, value: int) -> Self:
        self.next = Node(value)
        return self

node = Node(1).add_next(2)
print(node.next.value)  # 输出: 2

说明：

3.6 TypeGuard

缩小类型范围，优化条件分支。

from typing_extensions import TypeGuard

def is_string_list(value: list) -> TypeGuard[list[str]]:
    return all(isinstance(x, str) for x in value)

def process_list(data: list) -> None:
    if is_string_list(data):
        print(data[0].upper())  # mypy 知道 data 是 list[str]
    else:
        print("Not a string list")

process_list(["hello", "world"])  # 输出: HELLO

说明：

3.7 override 和 deprecated

标记方法重写或废弃（实验性）。

from typing_extensions import override, deprecated

class Base:
    def process(self) -> None:
        print("Base process")

class Derived(Base):
    @override
    def process(self) -> None:
        print("Derived process")

@deprecated("Use new_function instead")
def old_function() -> None:
    print("Old function")

Derived().process()  # 输出: Derived process
old_function()      # mypy 警告: Call to deprecated function

说明：

3.8 TypeAliasType

定义类型别名（Python 3.12+）。

from typing_extensions import TypeAliasType

MyList = TypeAliasType("MyList", list[int])
x: MyList = [1, 2, 3]
# x = [1, "2"]  # mypy 报错: Incompatible type

说明：

4. 性能与特点

5. 实际应用场景

示例（FastAPI 集成）：

from fastapi import FastAPI
from typing_extensions import TypedDict, Literal
from pydantic import BaseModel
from loguru import logger

app = FastAPI()

# 定义 TypedDict
class User(TypedDict):
    id: int
    role: Literal["admin", "user"]

# Pydantic 模型
class UserResponse(BaseModel):
    id: int
    role: Literal["admin", "user"]

# 模拟数据库
users: list[User] = [{"id": 1, "role": "admin"}, {"id": 2, "role": "user"}]

@app.get("/users/{user_id}", response_model=UserResponse)
async def get_user(user_id: int):
    for user in users:
        if user["id"] == user_id:
            logger.info(f"Found user: {user}")
            return user
    logger.error(f"User {user_id} not found")
    raise HTTPException(status_code=404, detail="User not found")

说明：

6. 与静态类型检查工具集成

pip install mypy
mypy script.py

npm install -g pyright
pyright script.py

# pyproject.toml
[tool.mypy]
plugins = ["typing_extensions"]
strict = true

7. 注意事项

8. 综合示例

以下是一个综合示例，结合 typing_extensions、FastAPI 和 loguru，展示多种类型注解：

from fastapi import FastAPI, Depends
from typing_extensions import TypedDict, Literal, Protocol, Self, TypeGuard, override
from pydantic import BaseModel
from loguru import logger
import httpx

# 配置日志
logger.add("app.log", rotation="1 MB", level="INFO")

# Protocol 定义接口
class ApiClient(Protocol):
    def fetch_data(self, endpoint: str) -> dict:
        ...

# TypedDict 定义数据结构
class UserData(TypedDict):
    id: int
    role: Literal["admin", "user"]

# Pydantic 模型
class UserResponse(BaseModel):
    id: int
    role: Literal["admin", "user"]

# 实现 ApiClient
class HttpClient:
    def __init__(self, base_url: str) -> None:
        self.client = httpx.AsyncClient(base_url=base_url)

    @override
    async def fetch_data(self, endpoint: str) -> dict:
        response = await self.client.get(endpoint)
        response.raise_for_status()
        return response.json()

# 类型检查函数
def is_user_data(data: dict) -> TypeGuard[UserData]:
    return "id" in data and "role" in data and data["role"] in ("admin", "user")

# FastAPI 应用
app = FastAPI()

async def get_client() -> ApiClient:
    return HttpClient("https://api.example.com")

@app.get("/users/{user_id}", response_model=UserResponse)
async def get_user(user_id: int, client: ApiClient = Depends(get_client)):
    try:
        data = await client.fetch_data(f"/users/{user_id}")
        if is_user_data(data):
            logger.info(f"User data: {data}")
            return data
        logger.error(f"Invalid user data: {data}")
        raise HTTPException(status_code=422, detail="Invalid user data")
    except httpx.HTTPStatusError as e:
        logger.error(f"API error: {e}")
        raise HTTPException(status_code=e.response.status_code, detail=str(e))

说明：

运行：

uvicorn main:app --reload

类型检查：

mypy main.py

9. 资源与文档

作者：彬彬侠