Python使用property的正确方式：封装后VS Code不显示docstring如何解决

问题根因 #

VS Code 搭载的 Pylance 静态类型检查器仅识别代码静态结构，你当前通过运行时动态生成property对象的写法，虽然显式传入了doc参数，但静态分析阶段无法读取动态生成对象的文档字符串与类型签名，因此无法正常显示悬停提示。

可行解决方案 #

方案1：改用泛型描述符实现（最优，同时兼容类型检查与文档提示） #

将原返回property的静态方法替换为泛型描述符类，Pylance 对描述符的静态识别支持度极高，原有调用逻辑无需修改即可生效：

from typing import Generic, TypeVar, Optional

T = TypeVar('T')

class BaseProp(Generic[T]):
    def __init__(self, name: str, doc: str, field_type: type[T]):
        self.name = name
        self.__doc__ = doc
        self.field_type = field_type

    def __get__(self, instance: 'Base', owner: type) -> Optional[T]:
        if instance is None:
            return self
        return getattr(instance, f"_{self.name}", None)

    def __set__(self, instance: 'Base', value: T) -> None:
        instance._set(self.name, value)

class Prop:
    @staticmethod
    def int_prop(name: str, doc: str) -> BaseProp[int]:
        return BaseProp(name, doc, int)

该方案下不仅文档可以正常显示，属性的类型检查也会正常生效，赋值类型错误时 Pylance 会主动提示。

方案2：补全静态标注（改动最小，兼容原有实现） #

如果不想调整现有封装逻辑，只需要给int_prop方法添加明确的泛型返回标注，同时手动补全property对象的注解字段即可解决大部分场景的文档识别问题：

from typing import Optional, Property

class Prop:
    @staticmethod
    def int_prop(name: str, doc: str) -> Property[Optional[int], int]:
        # Property泛型参数依次为get返回类型、set接收类型
        def fget(self: Base) -> Optional[int]:
            return getattr(self, "_" + name, None)
        
        def fset(self: Base, value: int) -> None:
            self._set(name, value)
        
        prop = property(fget, fset, doc=doc)
        # 手动补充注解强制静态检查器识别
        prop.__doc__ = doc
        prop.__annotations__ = {
            "fget": fget.__annotations__,
            "fset": fset.__annotations__
        }
        return prop

方案3：类装饰器批量生成（适合属性量极大的场景） #

如果你的类中需要定义数十个同类属性，可以用类装饰器批量生成，同时主动给类补充属性注解，静态检查器也可以正常识别：

def add_properties(props: dict[str, tuple[type, str]]):
    def wrapper(cls):
        for field_name, (field_type, doc) in props.items():
            def fget(self, n=field_name):
                return getattr(self, f"_{n}", None)
            def fset(self, value, n=field_name):
                self._set(n, value)
            setattr(cls, field_name, property(fget, fset, doc=doc))
            # 给类补充属性注解
            cls.__annotations__[field_name] = Optional[field_type]
        return cls
    return wrapper

# 使用示例
@add_properties({
    "prop": (int, "属性文档"),
    "name": (str, "名称字段")
})
class Child(Base):
    # 无需单独定义属性
    pass

优化建议 #

你当前的封装思路是合理的，在属性占比极高的项目中可以大幅减少样板代码，上述方案均不需要修改业务层的调用逻辑，即可解决文档显示问题。

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