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()

在func_convert文档字符串的参数部分中，有没有标准的方法来记录__init__的预期签名？如果有什么不同，我使用的是numpy docstring样式（我认为）。

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)

Answer 2

如果要遵循numpy docstring样式，请参阅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的文档字符串，则可以按照您想要的任何方式对其进行描述。但是我强烈建议遵循@jfaccioni answer并使用类型提示。

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

2 个答案: