Существует ли стандартный формат строки документа, показывающий, какая подпись ожидается для аргумента, который принимает функцию? - PullRequest
Новая
       27

Существует ли стандартный формат строки документа, показывающий, какая подпись ожидается для аргумента, который принимает функцию?

1 голос
/ 30 мая 2019

Мой __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__?Если это что-то меняет, я использую стиль обалденной строки документации (я думаю).

Ответы [ 2 ]

1 голос
/ 30 мая 2019

Я не знаю, существует ли этот стандарт для строк документации - вы, конечно, можете объяснить, что нужно этой функции, в простых предложениях, но я предполагаю, что вам нужен стандартный, удобный для документации способ сделать это.

Если вы не против переключения инструментов, это возможно с помощью подсказок типа и объекта 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)
0 голосов
/ 30 мая 2019

Если вы хотите следовать стилю numy 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 и использовать подсказки типа.

...