Python如何实现含父类参数的类参数文档化与自动补全？

一、使用typing.ParamSpec + Concatenate（Python 3.10+） #

这是官方推荐的类型提示方案，能让子类自动继承父类的参数定义，同时保留子类新增参数，IDE可以完美识别并提供自动补全。

先导入依赖的类型工具：

from typing import ParamSpec, Concatenate, TypeVar

P = ParamSpec('P')
T = TypeVar('T', bound='Car')

父类定义：

class Car:
    def __init__(self, model: str, color: str, type: str, *args, **kwargs):
        self.model = model
        self.color = color
        self.type = type

子类定义：

class SportsCar(Car):
    def __init__(self, *args: Concatenate[str, P.args], horse_power: int, **kwargs: P.kwargs):
        """
        Args:
            model: 车型
            color: 颜色
            type: 车辆类型
            horse_power: 马力
        """
        super().__init__(*args, **kwargs)
        self.horse_power = horse_power

实例化SportsCar时，IDE会自动提示父类的model、color、type以及子类的horse_power参数，无需重复编写父类参数列表。

二、使用dataclasses（Python 3.7+） #

如果不需要自定义复杂的__init__逻辑，dataclasses是最简洁的选择，它天生支持字段继承，自动生成__init__方法，IDE补全和文档展示都很友好。

代码示例：

from dataclasses import dataclass

@dataclass
class Car:
    model: str
    color: str
    type: str

@dataclass
class SportsCar(Car):
    horse_power: int

SportsCar会自动继承Car的所有字段，实例化时直接传入model、color、type、horse_power即可，无需手动编写任何__init__代码。

三、手动复用父类参数（兼容旧版本Python） #

对于Python 3.9及以下版本，可以把父类的参数名定义为常量，在子类中通过字典推导提取参数，减少重复代码：

class Car:
    INIT_PARAMS = ('model', 'color', 'type')
    def __init__(self, model: str, color: str, type: str, *args, **kwargs):
        self.model = model
        self.color = color
        self.type = type

class SportsCar(Car):
    def __init__(self, horse_power: int, **kwargs):
        """
        Args:
            horse_power: 马力
            model: 车型
            color: 颜色
            type: 车辆类型
        """
        parent_params = {k: v for k, v in kwargs.items() if k in Car.INIT_PARAMS}
        super().__init__(**parent_params)
        self.horse_power = horse_power

这种方式虽然IDE补全时父类参数会显示在**kwargs中，但避免了重复编写参数列表，适合无法升级Python版本的场景。

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