python - 是否有标准的文档字符串格式来显示采用函数的参数所需的签名？

Question

我的 __init__ 方法接受另一个名为 func_convert 的函数作为参数:

class Adc:
    """Reads data from ADC

    """
    def __init__(self, func_convert):
        """Setup the ADC

        Parameters
        ----------
        func_convert : [???]
            user-supplied conversion function
        """
        self._func_convert = func_convert

    def read(self):        
        data = 0 #some fake data
        return self._func_convert(data)

参数func_convert允许在实例化时提供一次自定义缩放函数，每次读取数据时都会调用该函数来转换数据。该函数必须接受单个 int 参数并返回单个 float。一个可能的例子是:

def adc_to_volts(value):
    return value * 3.0 / 2**16 - 1.5

adc = Adc(adc_to_volts)
volts = adc.read()

是否有一种标准方法可以在 __init__ 文档字符串的参数部分中记录 func_convert 的预期签名？如果它有区别，我正在使用 numpy 文档字符串样式(我认为)。

Answer 1

我不知道文档字符串是否存在这个标准 - 您当然可以用简单的句子解释该函数需要什么，但我假设您需要一种标准的、文档生成器友好的方法来执行此操作。

如果您不介意切换工具，可以使用类型提示和 typing module 中的 Callable 对象。 :

from typing import Callable

class Adc:
    """
    Reads data from ADC

    """
    def __init__(self, func_convert: Callable[[int], float]) -> None:
        self._func_convert = func_convert

    def read(self):        
        data = 0  # some fake data
        return self._func_convert(data)