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

Question

我正在寻找一种标准的、轻量级的（最好是内置的）方法来处理“接口重复”的问题，其中相同的参数（带有注释、默认值和文档）在共享通用功能的多个函数中重复。有没有办法集中参数定义和文档而无需手动复制它们？ 这里用一个例子来说明这个问题。代码保持简短以避免冗长，是的，在这种特殊情况下，装饰器可以处理它。但是，请重点关注

签名元素和文档的重复

作为真正的问题，而不是功能的具体逻辑。 示例代码：

# Core function f
def f(a: str, b=1) -> str:
    """
    Repeats the string `a` `b` times.
    
    Args:
        a (str): The string to be repeated.
        b (int, optional): Number of repetitions. Defaults to 1.
    ...
    """
    return a * b

# Higher-level function g
def g(x, *, a: str, b=1) -> str:
    """
    Calls `f` to repeat `a`, appends `x` to the result.
    
    Args:
        x: Value to append to the repeated string.
        a (str): The string to be repeated.
        b (int, optional): Number of repetitions. Defaults to 1.
    
    ...
    """
    result = f(a, b)
    return result + str(x)

# Higher-level function h (different from g)
def h(y, *, a: str, b=2) -> int:
    """
    Calls `f` to repeat `a`, appends `y`, and returns the length of the result.
    
    Args:
        y: Value to append to the repeated string.
        a (str): The string to be repeated.
        b (int, optional): Number of repetitions. Defaults to 2.
    
    ...
    """
    result = f(a, b) + str(y)
    return len(result)

问题

在这种情况下，我发现自己在多个函数中重复参数定义（

a

、

b

）及其类型和默认值。同样，每个参数的文档在每个函数的文档字符串中重复。这导致：

视觉噪音
• ：重复会使代码变得混乱，使其更难以维护。
DRY 违规
• ：如果我需要更改 b 的默认值或更新文档，我必须在多个地方执行此操作。
维护更困难
• ：如果我忘记更新所有功能，一处的更改可能会导致不一致。
缓解方法

我考虑过的一些解决方案（例如，我们与我以前的团队一起开发的

i2.signatures

，以解决这个问题等等）包括：

使用装饰器
• 集中参数处理。例如，装饰器可以处理默认值并跨函数注入通用参数。
使用
• inspect

   将签名从一个函数动态复制到另一个函数，从而减少重复。

但是，这些方法仍然增加了复杂性，并且似乎并不是适合每种情况的理想解决方案。他们也没有完全解决重复文档的问题。

我在寻找什么

是否有一个

标准或轻量级解决方案

（最好是内置的）来解决Python中的这个接口重复问题？理想情况下，它将避免重复参数签名和文档字符串，同时保持代码尽可能简单和可读。 欢迎任何建议或最佳实践！

Answer 1

def h(y, *, a: str, b: int = 2) -> int:
    """
    Calls `f` to repeat `a`, appends `y`, and returns the length of the result.
    
    Args:
        y: Value to append to the repeated string.
        a: See :func:`f`.
        b: See :func:`f`.
    
    ...
    """

一些评论：

交叉链接还使用户更容易找到相关功能，这本身就是一个温和的好处。

• 我不喜欢自动编写任何文档的想法。无可否认，参数描述是一个相对良性的例子，但是当我阅读那些我可以看出不是手写的文档时，我就不再相信它们实际上是正确的。
• 在这种情况下，论点描述是如此简短，以至于我认为 DRY 的成本超过了好处。 所以我就写两遍。
• 不需要在文档字符串中包含参数类型，或者每个参数是否是可选的。所有这些信息都可以在签名本身中轻松获得。