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

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 参数和 return 单个 float。一个可能的例子是：

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

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

是否有一种标准的方法来记录 func_convert 文档字符串的参数部分中预期的 func_convert 签名？如果它有所作为，我正在使用 numpy docstring 样式（我认为）。

Answer 1

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

如果您不介意切换工具，可以使用类型提示和 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)

Answer 2

如果你想遵循 numpy 文档字符串风格，有一些来自 numpy 的例子展示了如何描述函数参数：

1)

apply_along_axis(func1d, axis, arr, *args, **kwargs)
    ...

    Parameters
    ----------
    func1d : function (M,) -> (Nj...)
        This function should accept 1-D arrays. It is applied to 1-D
        slices of `arr` along the specified axis.

2)

apply_over_axes(func, a, axes)
    ...

    Parameters
    ----------
    func : function
        This function must take two arguments, `func(a, axis)`.

3)

set_string_function(f, repr=True)
    ...

    Parameters
    ----------
    f : function or None
        Function to be used to pretty print arrays. The function should expect
        a single array argument and return a string of the representation of
        the array. If None, the function is reset to the default NumPy function
        to print arrays.

TLDR：它们是手动描述的，没有任何特殊的语法或指南。如果你的目标是创建类似于 numpy 的文档字符串，你可以用任何你想要的方式描述它们。但我强烈建议遵循并使用类型提示。

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

Is there a standard docstring format to show what signature is expected for an argument that takes a function?

python

docstring