Python中处理仅TYPE_CHECKING下声明的类型提示的正确方法

在Python中遇到像Flask的WSGIEnvironment这类仅在typing.TYPE_CHECKING为真时才存在的类型时，有两种简洁实用的解决方法，完全不需要重复声明typeshed里已有的类型定义：

方法一：条件导入+字符串注解/延迟注解 #

利用TYPE_CHECKING在运行时为False的特性，把类型导入放在条件块里，同时用字符串形式的类型注解（或Python 3.7+的延迟注解）避免运行时的名称查找错误：

from typing import TYPE_CHECKING

# 仅类型检查时执行导入，运行时跳过
if TYPE_CHECKING:
    from flask import WSGIEnvironment

# Python 3.6及以上可用：字符串形式的类型注解
def handle_request(environ: "WSGIEnvironment") -> None:
    pass

# Python 3.7+更简洁的写法：开启延迟注解
# 只需在文件顶部添加：
# from __future__ import annotations
# 之后直接写：
# def handle_request(environ: WSGIEnvironment) -> None:
#     pass

这种方式下，mypy等类型检查器会正常识别WSGIEnvironment类型，而Python运行时不会执行条件块内的导入，也不会解析字符串形式的注解，完全不会触发报错。

方法二：使用运行时存在的等效标准类型 #

像WSGIEnvironment这类框架定义的类型，本质是遵循标准规范的通用类型，你可以直接用标准库中运行时存在的等效类型替代：

# Python 3.9+可用，wsgiref.types里的WSGIEnvironment是标准定义
from wsgiref.types import WSGIEnvironment

def handle_request(environ: WSGIEnvironment) -> None:
    pass

# 针对Python 3.8及更早版本，用基础泛型类型注解
from typing import Mapping, Any

def handle_request(environ: Mapping[str, Any]) -> None:
    pass

这种方法不需要依赖框架的类型定义，既满足类型检查的需求，运行时也不会有任何问题。

关于是否需要重新声明typeshed类型 #

完全不需要。typeshed的类型定义已经被mypy等工具识别，上面两种方法已经能完美复用这些定义，重复声明只会增加维护成本。

内容的提问来源于stack exchange，提问作者Alek