Python类型提示：返回值标注父类时返回子类报错问题排查

共涉及三个结构简单的代码文件：

• schema.py（模式定义文件）

from pydantic import BaseModel


class BaseSchema(BaseModel):
    user_type: UserTypeEnum
    configuration_type: ConfigurationTypeEnum


class UserDataSchema(BaseSchema):
    user_type: UserTypeEnum.NORMAL
    configuration_type: ConfigurationTypeEnum.NORMAL

    user_name: str
    user_age: int

• class_file.py（类定义文件）

class AnotherServiceClass(BaseClient):

    @property
    def client_name(self):
        return 'another_service_class'

    def get_call(self, schema_identifier_param: str) -> BaseSchema:
        url = 'some/url/constructed'
        return self.get(url)

• caller_function.py（业务调用文件）

def get_data_from_another_service(
    user_name: str,
    schema_identifier_param: str
) -> UserDataSchema:
    another_service_instance = AnotherServiceClass(
        user_name=user_name
    )
    return another_service_instance.get_call(schema_identifier_param)

AnotherServiceClass.get_call是通用方法，可返回任意继承自BaseSchema的子类实例，因此原代码将其返回类型标注为BaseSchema。业务方法get_data_from_another_service可根据传入的schema_identifier_param确定本次调用必然返回UserDataSchema实例，因此标注返回类型为UserDataSchema。
运行类型检查时报错：get_call返回类型为BaseSchema，与业务方法声明的UserDataSchema返回类型不匹配。此前尝试将get_call返回类型标注为Type[BaseSchema]仍无法解决问题。

1. 静态类型检查器无法感知运行时的参数逻辑：虽然开发者知道传入特定schema_identifier_param会返回UserDataSchema，但类型检查器只能看到get_call的静态返回声明是BaseSchema，它无法确认返回值一定对应BaseSchema的哪个子类，直接返回窄化的子类类型不符合静态校验规则。
2. 之前尝试的Type[BaseSchema]标注本身是错误的：Type[X]代表返回值是类对象本身，而不是类的实例，和方法实际返回模型实例的逻辑完全不符，自然无法解决问题。

方案1：泛型标注（最规范，推荐） #

通过给通用类绑定上界为BaseSchema的泛型参数，让调用方可以在实例化时指定具体的返回模型类型，类型检查器可自动推导对应返回值类型。
修改class_file.py：

from typing import Generic, TypeVar
# 定义泛型，上界限定为BaseSchema的子类
SchemaT = TypeVar("SchemaT", bound=BaseSchema)

class AnotherServiceClass(BaseClient, Generic[SchemaT]):
    @property
    def client_name(self):
        return 'another_service_class'

    def get_call(self, schema_identifier_param: str) -> SchemaT:
        url = 'some/url/constructed'
        return self.get(url)

修改caller_function.py，实例化类时指定泛型参数：

def get_data_from_another_service(
    user_name: str,
    schema_identifier_param: str
) -> UserDataSchema:
    # 实例化时明确指定本次调用返回的Schema类型
    another_service_instance = AnotherServiceClass[UserDataSchema](
        user_name=user_name
    )
    return another_service_instance.get_call(schema_identifier_param)

方案2：类型断言（改动最小） #

如果不想调整通用类的标注，可以在调用位置用typing.cast告知类型检查器返回值的实际类型，该方法仅做静态类型提示，运行时不会增加额外开销。
仅需修改caller_function.py：

from typing import cast

def get_data_from_another_service(
    user_name: str,
    schema_identifier_param: str
) -> UserDataSchema:
    another_service_instance = AnotherServiceClass(
        user_name=user_name
    )
    raw_resp = another_service_instance.get_call(schema_identifier_param)
    return cast(UserDataSchema, raw_resp)

方案3：忽略类型检查（应急使用，不推荐） #

如果确定逻辑100%正确，也可以在报错行加类型忽略注释跳过校验，但会丢失这一行的类型保护，非应急场景不建议使用：

def get_data_from_another_service(
    user_name: str,
    schema_identifier_param: str
) -> UserDataSchema:
    another_service_instance = AnotherServiceClass(
        user_name=user_name
    )
    return another_service_instance.get_call(schema_identifier_param)  # type: ignore[return-value]

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