如何为含派生类内部类的Python代码添加类型提示支持静态分析

要在保持代码简洁的同时让静态分析工具正确识别data属性的类型，可通过绑定子类的TypeVar结合泛型类实现，同时可选添加轻量运行时验证避免类型不匹配。

1. 核心实现：泛型类+自动类型推导 #

定义绑定到Base子类的TypeVar，让静态分析工具自动推导子类的Data类型，无需手动指定泛型参数：

from typing import TypeVar, Generic

# 限制TypeVar只能是Base的子类，确保能引用子类的Data类
T = TypeVar('T', bound='Base')

class Base(Generic[T]):
    # 注解Data为子类的Data类类型
    Data: type[T.Data]

    def __init__(self):
        # self.data的类型自动关联子类的Data实例
        self.data: T.Data = self.Data()

2. 派生类使用示例 #

派生类只需定义内部Data类即可，静态分析工具会自动识别data的具体类型：

class Derived(Base):
    class Data:
        attr: str = None

obj = Derived()
reveal_type(obj.data)  # 静态分析返回：Derived.Data
reveal_type(obj.data.attr)  # 静态分析返回：str
obj.data.attr = 7  # 触发静态错误（int无法赋值给str类型）
obj.data.other = 7  # 触发静态错误（不存在other属性）

3. 可选运行时验证（兼容抽象基类） #

如果需要确保运行时Data类与类型注解一致，可在Base的__init_subclass__中添加验证逻辑，同时兼容未定义Data的抽象派生类：

from abc import ABC, abstractmethod

class Base(Generic[T], ABC):
    Data: type[T.Data]

    def __init_subclass__(cls, **kwargs):
        super().__init_subclass__(**kwargs)
        # 仅对非抽象子类验证Data类是否存在
        if not getattr(cls, '__abstractmethods__', set()):
            if not hasattr(cls, 'Data'):
                raise TypeError(f"子类 {cls.__name__} 必须定义内部Data类")

    @abstractmethod
    def some_abstract_method(self):
        pass

# 抽象派生类无需定义Data（不会触发验证）
class AbstractDerived(Base):
    pass

# 非抽象派生类必须定义Data
class ConcreteDerived(Base):
    class Data:
        attr: str = None

方案优势 #

• 遵循DRY原则：派生类无需重复指定泛型参数，静态分析自动推导类型关联
• 完善的静态分析支持：mypy、pyright等工具可正确识别data的具体类型，拦截属性赋值、访问错误
• 灵活兼容：支持抽象基类，仅对非抽象子类强制验证Data类存在

简洁替代方案（Python 3.11+） #

若不需要泛型的扩展性，可直接使用PEP 673的Self类型（部分静态分析工具对Self.Data的支持需验证）：

from typing import Self

class Base:
    Data: type[Self.Data]

    def __init__(self):
        self.data: Self.Data = self.Data()

class Derived(Base):
    class Data:
        attr: str = None

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