Python类型注解与文档字符串继承的最佳实践：子类签名识别问题

当子类通过*args, **kwargs继承父类__init__方法时，编辑器无法识别签名匹配，进而无法展示父类的文档提示。以下是几种实用的解决方案：

1. 显式重写父类签名（推荐） #

直接在子类__init__中写出父类的完整参数列表，再添加子类特有的参数。这种方式能让编辑器直接识别签名，同时保持代码可读性。

示例代码：

from typing import Callable, Literal
import torch.nn as nn

class ResidualLinBlock(LinBlock):
    def __init__(
            self,
            inp_features: int,
            out_features: int,
            activation: Callable[[], "nn.Module"] = None,
            normalizer: Callable[[int], "nn.Module"] = None,
            n: int = 1,
            p: float = 0,
            activation_every_n: bool = False,
            normalizer_every_n: bool = True,
            sample_type: Literal["mono", "bi"] = "mono",
            # 子类特有的参数
            residual_dropout: float = 0.1,
            **extras,
    ):
        """
        带残差连接的线性块
        :param residual_dropout: 残差连接的Dropout概率
        :inherit-doc: 其余参数见父类LinBlock
        """
        super().__init__(
            inp_features=inp_features,
            out_features=out_features,
            activation=activation,
            normalizer=normalizer,
            n=n,
            p=p,
            activation_every_n=activation_every_n,
            normalizer_every_n=normalizer_every_n,
            sample_type=sample_type,
            **extras,
        )
        # 子类专属逻辑
        self.residual_dropout = nn.Dropout(residual_dropout)
        ...

• 优点：编辑器完全支持，参数逻辑清晰，可读性强；
• 缺点：父类签名变更时需要同步修改子类。

2. 使用override装饰器标记重写 #

Python 3.12+原生支持override装饰器（低版本可使用typing_extensions.override），它能告知编辑器当前方法是重写父类的，部分编辑器会因此加载父类的文档提示。

示例代码：

from typing_extensions import override  # Python<3.12版本使用
# from typing import override  # Python3.12+版本使用

class ResidualLinBlock(LinBlock):
    @override
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        # 子类专属逻辑
        ...

• 优点：无需重复签名，父类变更时子类无需同步修改；
• 缺点：依赖编辑器对override装饰器的支持，部分编辑器可能无法完全展示父类文档。

3. 手动继承父类文档字符串 #

在子类__init__的文档字符串中明确引用父类文档，或使用编辑器支持的文档继承标记（如PyCharm支持的:inherit-doc:）。

示例代码：

class ResidualLinBlock(LinBlock):
    def __init__(self, *args, **kwargs):
        """
        带残差连接的线性块
        :inherit-doc: LinBlock.__init__
        :param kwargs: 父类LinBlock的所有参数
        """
        super().__init__(*args, **kwargs)
        # 子类专属逻辑
        ...

• 优点：无需重复签名，文档提示设置灵活；
• 缺点：依赖编辑器对文档标记的支持，不同编辑器兼容性不一。

4. 动态生成签名（适合库开发） #

利用inspect模块获取父类签名，动态设置子类方法的签名。这种方式适合大型库开发，可避免手动维护签名同步。

示例代码：

import inspect
from functools import wraps

def inherit_signature(parent_cls):
    def decorator(func):
        parent_sig = inspect.signature(parent_cls.__init__)
        @wraps(func)
        def wrapper(*args, **kwargs):
            return func(*args, **kwargs)
        wrapper.__signature__ = parent_sig
        return wrapper
    return decorator

class ResidualLinBlock(LinBlock):
    @inherit_signature(LinBlock)
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        # 子类专属逻辑
        ...

• 优点：自动同步父类签名，无需手动维护；
• 缺点：实现复杂，对新手不友好，部分编辑器可能无法识别动态生成的签名。

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