Python含__new__或metaclass时，__init__文档字符串编写及效果记录问询

一、__init__的文档字符串该描述哪个参数？ #

PEP257要求构造函数文档写在__init__里，但核心原则是文档要服务于类的使用者，所以必须优先描述用户调用MyClass(*args1, **kwargs1)时传入的参数——这才是使用者需要知道的调用方式。

如果__new__或元类在中间修改了参数（比如做了参数转换、过滤），可以在__init__的文档里补充说明内部的参数处理逻辑，但不能让内部实现的参数混淆了对外的调用规范。举个简单的例子：

def __init__(self, processed_data):
    """初始化MyClass实例。
    
    调用方式提示：用户无需直接传入processed_data，请使用`MyClass(raw_data)`的形式，
    raw_data会被__new__自动转换为processed_data后传入。
    
    参数:
        processed_data (dict): 由__new__处理后的结构化数据（内部参数，用户无需关注）
    """
    self.data = processed_data

二、__new__和元类的作用该如何记录？ #

1. __new__的文档记录

__new__作为实例创建的前置逻辑，其自身的文档字符串要清晰说明它的作用：比如是否修改了入参、是否做了实例缓存（单例）、是否限制了实例创建数量等。同时，在类的文档字符串里可以提一句__new__有特殊处理，引导用户查看__new__的详细文档。

2. 元类的文档记录

• 元类本身的文档字符串要详细描述它的功能：比如是否修改了类的属性生成逻辑、是否添加了类方法、是否做了参数校验等。
• 使用该元类的类，要在自己的文档字符串里说明元类带来的特殊行为，让使用者知道这个类的特性来自元类，而不是普通类的逻辑。比如：

class MyMeta(type):
    """自定义元类：自动为类添加`version`类属性。"""
    def __new__(cls, name, bases, attrs):
        attrs['version'] = '1.0'
        return super().__new__(cls, name, bases, attrs)

class MyClass(metaclass=MyMeta):
    """使用MyMeta元类的类，自动拥有`version`类属性。"""
    pass

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