如何让类型检查器识别类与实例同名属性的不同动态类型

问题背景 #

现有如下Python代码，通过元类实现了类属性返回Column实例，实例属性返回对应数据值的逻辑，但类型检查器（如Pylance）无法区分两者的类型：

from typing import Any

class Column:
    def __init__(self, s: str) -> None:
        self.name = s

    def __repr__(self):
        return f'Column(name={self.name!r})'

class Meta(type):
    def __new__(cls, name: str, bases: tuple[type, ...], namespace: dict[str, Any]) -> type:
        annotations = namespace.get('__annotations__', {})
        namespace.update({k: Column(k) for k in annotations})
        return super().__new__(cls, name, bases, namespace)
        
class Base(metaclass=Meta):
    def __init__(self, data: dict[str, Any]) -> None:
        if self.__class__ == Base:
            raise RuntimeError
        self.__dict__ = data

# 示例
class Human(Base):
    name: str
    height: int

tom = Human({'name': 'Tom', 'height': 180})

print(Human.height)  # Column(name='height')
print(tom.height)    # 180

当前类型检查器会把Human.height和tom.height都视为注解声明的类型（如int），但实际类属性是Column类型，实例属性是注解类型。需要找到无需重复定义属性的方法，让类型检查器正确识别两者的类型。

解决方案 #

1. 利用Annotated分离类型信息（最优方案） #

通过Annotated标记实例属性的真实类型，同时让元类处理时保留类属性的Column类型逻辑，无需重复定义：

from typing import Any, Annotated, TypeVar, ClassVar
from typing_extensions import TypeAlias

T = TypeVar('T')
# 标记实例属性的真实类型
InstanceField = Annotated[T, "instance_field"]
# 类属性的类型别名
ColumnClassVar: TypeAlias = ClassVar[Column]

class Meta(type):
    def __new__(cls, name: str, bases: tuple[type, ...], namespace: dict[str, Any]) -> type:
        annotations = namespace.get('__annotations__', {})
        processed_annotations = {}
        column_attrs = {}
        for k, v in annotations.items():
            # 提取Annotated中的原始类型，同时生成Column类属性
            if hasattr(v, "__metadata__") and "instance_field" in v.__metadata__:
                processed_annotations[k] = v.__origin__
                column_attrs[k] = Column(k)
            else:
                processed_annotations[k] = v
        # 更新命名空间：类属性为Column，注解保留实例类型
        namespace.update(column_attrs)
        namespace['__annotations__'] = processed_annotations
        return super().__new__(cls, name, bases, namespace)

# 子类定义
class Human(Base):
    name: InstanceField[str]
    height: InstanceField[int]

此时类型检查器会准确识别：

• Human.name → ClassVar[Column]
• tom.name → str

2. 利用Protocol静态提示 #

定义协议类，通过__getattr__让类型检查器识别类属性和实例属性的不同类型，无需修改元类核心逻辑：

from typing import Protocol, ClassVar, Any

class BaseProtocol(Protocol):
    @classmethod
    def __getattr__(cls, name: str) -> Column: ...

class Base(metaclass=Meta, BaseProtocol):
    def __init__(self, data: dict[str, Any]) -> None:
        if self.__class__ == Base:
            raise RuntimeError
        self.__dict__ = data

    def __getattr__(self, name: str) -> Any:
        return self.__dict__[name]

# 子类定义
class Human(Base):
    name: str
    height: int

类型检查器会自动识别：

• Human.height → Column
• tom.height → int

3. 半自动补充类型注释（妥协方案） #

如果不想修改元类或使用额外工具，可以通过代码生成脚本自动补充类属性的ClassVar注释，避免手动重复编写：

class Human(Base):
    name: str
    height: int
    # 自动生成的类属性类型注释
    name: ClassVar[Column]
    height: ClassVar[Column]

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