如何避免Python函数签名与文档字符串中的接口重复？

我正在寻找一种标准、轻量（最好是内置）的方法来解决接口重复问题——即多个共享通用功能的函数重复使用相同的参数（包含注解、默认值和文档）。能否无需手动重复，集中定义这些参数的定义和文档？

以下示例可说明该问题。代码尽量简短简洁以避免冗余，当然在这个特定场景下可以用装饰器处理，但请聚焦于签名元素与文档的重复这一核心问题，而非函数的具体逻辑。

示例代码 #

# 核心函数 f
def f(a: str, b=1) -> str:
    """
    将字符串`a`重复`b`次。
    
    Args:
        a (str): 待重复的字符串。
        b (int, optional): 重复次数，默认值为1。
    ...
    """
    return a * b

# 高阶函数 g
def g(x, *, a: str, b=1) -> str:
    """
    调用`f`重复`a`，并将`x`追加到结果后。
    
    Args:
        x: 追加到重复字符串后的内容。
        a (str): 待重复的字符串。
        b (int, optional): 重复次数，默认值为1。
    
    ...
    """
    result = f(a, b)
    return result + str(x)

# 高阶函数 h（与g不同）
def h(y, *, a: str, b=2) -> int:
    """
    调用`f`重复`a`，追加`y`后返回结果的长度。
    
    Args:
        y: 追加到重复字符串后的内容。
        a (str): 待重复的字符串。
        b (int, optional): 重复次数，默认值为2。
    
    ...
    """
    result = f(a, b) + str(y)
    return len(result)

问题所在 #

在此场景中，我需要在多个函数中重复定义参数a、b及其类型和默认值，同时每个参数的文档也会在各函数的文档字符串中重复。这会导致：

• 视觉冗余：重复内容使代码杂乱，增加维护难度。
• 违反DRY原则：若需修改b的默认值或更新文档，必须在多处进行修改。
• 维护难度提升：若忘记更新所有函数，一处修改会导致不一致问题。

已考虑的缓解方案 #

我曾考虑过一些解决方案，包括：

• 使用装饰器集中处理参数，例如通过装饰器处理默认值并向多个函数注入通用参数。
• 使用inspect模块动态复制一个函数的签名到另一个函数，减少重复。

但这些方法仍会增加复杂度，并非适用于所有场景的理想方案，且无法完全解决文档重复的问题。

需求 #

是否存在一种标准或轻量的解决方案（最好是内置的）来解决Python中的这一接口重复问题？理想情况下，它能避免参数签名和文档字符串的重复，同时保持代码简洁可读。

欢迎任何建议或最佳实践！

解决方案推荐 #

1. 文档模板+typing.Protocol（Python 3.8+）

用字符串模板复用参数文档，配合Protocol明确通用参数的类型约束，属于轻量内置方案：

from typing import Protocol

class HasRepeatParams(Protocol):
    """包含重复参数的接口规范"""
    a: str
    b: int = 1

# 通用参数文档模板
REPEAT_PARAMS_DOC = """
    a (str): 待重复的字符串。
    b (int, optional): 重复次数，默认值为{default_b}。
"""

def f(a: str, b=1) -> str:
    """
    将字符串`a`重复`b`次。
    
    Args:
        {repeat_params}
    ...
    """.format(repeat_params=REPEAT_PARAMS_DOC.format(default_b=1))
    return a * b

def g(x, *, a: str, b=1) -> str:
    """
    调用`f`重复`a`，并将`x`追加到结果后。
    
    Args:
        x: 追加到重复字符串后的内容。
        {repeat_params}
    ...
    """.format(repeat_params=REPEAT_PARAMS_DOC.format(default_b=1))
    result = f(a, b)
    return result + str(x)

def h(y, *, a: str, b=2) -> int:
    """
    调用`f`重复`a`，追加`y`后返回结果的长度。
    
    Args:
        y: 追加到重复字符串后的内容。
        {repeat_params}
    ...
    """.format(repeat_params=REPEAT_PARAMS_DOC.format(default_b=2))
    result = f(a, b) + str(y)
    return len(result)

2. dataclasses封装通用参数（Python 3.7+）

将重复参数封装为数据类，彻底消除签名重复，文档只需引用数据类说明：

from dataclasses import dataclass

@dataclass
class RepeatParams:
    """重复操作的参数配置"""
    a: str  # 待重复的字符串
    b: int = 1  # 重复次数，默认值为1

def f(params: RepeatParams) -> str:
    """将字符串`params.a`重复`params.b`次。
    
    Args:
        params (RepeatParams): 重复操作的参数配置。
    ...
    """
    return params.a * params.b

def g(x, params: RepeatParams) -> str:
    """调用`f`重复`params.a`，并将`x`追加到结果后。
    
    Args:
        x: 追加到重复字符串后的内容。
        params (RepeatParams): 重复操作的参数配置。
    ...
    """
    result = f(params)
    return result + str(x)

def h(y, params: RepeatParams = RepeatParams("", b=2)) -> int:
    """调用`f`重复`params.a`，追加`y`后返回结果的长度。
    
    Args:
        y: 追加到重复字符串后的内容。
        params (RepeatParams, optional): 重复操作的参数配置，默认b=2。
    ...
    """
    result = f(params) + str(y)
    return len(result)

3. functools.partial简化逻辑复用（内置）

如果通用参数默认值无需频繁调整，可先用partial绑定核心函数逻辑，配合文档模板减少重复：

from functools import partial

# 复用f的核心逻辑
g_base = partial(f)
def g(x, *, a: str, b=1) -> str:
    """
    调用`f`重复`a`，并将`x`追加到结果后。
    
    Args:
        x: 追加到重复字符串后的内容。
        {repeat_params}
    ...
    """.format(repeat_params=REPEAT_PARAMS_DOC.format(default_b=1))
    result = g_base(a, b)
    return result + str(x)

最佳实践总结 #

• 追求最小改动：优先用文档模板+类型注解，配合Protocol明确约束；
• 彻底解决重复：数据类封装是最优解，统一参数定义与文档维护；
• 复杂场景备选：装饰器/inspect方案适合特殊需求，但内置方案已覆盖多数常规场景，更易维护。

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