__doc__ 是只读字符串，仅在类定义时由 docstring 设置，不可动态修改；推荐用 __init_subclass__ 自动生成文档，或预处理插值式 docstring，但 sphinx 等工具仅识别静态内容。
类的 __doc__ 属性不是装饰器，它只是个字符串
Python 类的 __doc__ 是一个只读属性，直接赋值或运行时修改不会生效——它只在类定义时由第一个字符串字面量（即 docstring）自动设置。很多人误以为可以像 @property 那样动态生成文档，但实际不能：__doc__ 不支持 descriptor 协议，也不能用 setattr(cls, '__doc__', ...) 覆盖（CPython 中会静默失败，PyPy 可能报错）。
真正可控的方式只有两种：写死 docstring，或在类定义后手动替换（需用 cls.__dict__['__doc__'] 绕过只读限制，但有兼容风险）。
- 推荐做法：把自描述逻辑封装进函数，再让 docstring 调用它，比如
"""{get_class_summary(MyClass)}"""—— 但这需要预处理，标准 Python 不支持插值式 docstring - 可行替代：用
__init_subclass__或元类在类创建后注入__doc__，但要注意help()和 IDE 文档提示可能不识别运行时注入的内容 - 注意：Sphinx、pydoc 等工具只读取静态字符串，动态生成的
__doc__在生成 API 文档时会被忽略
用 __init_subclass__ 实现基础自描述类
如果想让子类自动带上有字段说明的文档，可以用 __init_subclass__ 提前扫描 __annotations__ 并拼接 docstring。这种方式不破坏静态可读性，且 help() 能正常显示。
class AutoDoc:
def __init_subclass__(cls, **kwargs):
super().__init_subclass__(**kwargs)
if cls.__doc__ is None or "Auto-generated" not in cls.__doc__:
fields = []
for name, typ in cls.__annotations__.items():
typ_name = getattr(typ, '__name__', str(typ))
fields.append(f" {name}: {typ_name}")
if fields:
cls.__doc__ = f"{cls.__name__} (auto-generated)\n\nAttributes:\n" + "\n".join(fields)
class User(AutoDoc):
name: str
age: int
执行 help(User) 就能看到字段说明。但要注意：
- 仅对带类型注解的变量生效；普通实例变量（如
self.x = 1）无法被扫描到 - 若子类自己写了 docstring，这个逻辑默认跳过，避免覆盖人工说明
- 继承链中多个
__init_subclass__可能冲突，建议只在一个基类里实现
用元类控制 __doc__ 的生成时机
元类比 __init_subclass__ 更底层，能确保 docstring 在类对象完全构建前就就位，适合更复杂的场景（比如结合 dataclass 或配置字段）。但代价是调试困难、IDE 支持弱、且容易和第三方库（如 Pydantic）的元类冲突。
关键点在于：必须在 __new__ 中构造类对象后立即重写 __doc__，而不是在 __init__ 里——后者太晚，__doc__ 已被冻结。
- 不要用
type.__new__后直接cls.__doc__ = ...，某些 Python 版本会忽略 - 稳妥做法是用
namespace参数预先计算 docstring，再传给super().__new__ - 如果类用了
@dataclass，元类必须放在 dataclass 之前（即定义顺序靠前），否则 dataclass 会覆盖元类行为
为什么不用 __repr__ 或 __str__ 替代？
有人试图在 __repr__ 里塞文档内容，期望调用 help() 时显示——这行不通。help() 查的是 __doc__，不是 __repr__。而 __repr__ 是实例方法，__doc__ 是类属性，两者作用域和用途完全不同。
混淆它们会导致两个典型问题：
- 在 REPL 中输入类名（如
User）看到的是__repr__输出，但help(User)仍是空或默认字符串 - 写单元测试校验文档时，误用
assert 'name' in repr(User)，结果测试通过但真实文档缺失 - 类型检查器（mypy/pyright）只读取
__doc__做参数提示，__repr__对 IDE 无意义
自描述的核心目标是让文档可被工具消费，不是让人眼阅读——所以必须守住 __doc__ 这条线，其他都是旁路。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
