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

При написании строк документов на python мне интересно, должна ли строка документации содержать исключения, которые неявно возбуждаются, или она также должна содержать исключения, которые я вызываю явно.

Рассмотрим функцию

def inv(a):
    if a == 0:
        raise ZeroDivisionError
    else:
        return 1/a

Так что в строке документации под ключевым словом «Raises» я бы определенно поставил ZeroDivisionError. Однако, в зависимости от ввода, я также ожидаю TypeError. Не могли бы вы добавить это также в строку документации?

Из-за принципа EAFP (если я правильно понимаю) я не хочу проверять здесь типы, верно? Любой намек (в том числе на пример кода) приветствуется.


python-3.x python docstring raise
person Quickbeam2k1    schedule 21.10.2015    source источник

Ответы (2)


arrow_upward
6
arrow_downward

Это зависит от того, для чего (или для кого) вы пишете строку документации. Для автоматического преобразования в документацию по API мне нравятся строки документации в стиле Google, которые будет выглядеть так:

def inv(a):
    """Return the inverse of the argument.

    Arguments:
      a (int): The number to invert.

    Returns:
      float: The inverse of the argument.

    Raises:
      TypeError: If 1 cannot be divided by the argument.
      ZeroDivisionError: If the argument is zero.

    """
    return 1 / a

Здесь я включил все исключения, которые может вызвать функция. Обратите внимание, что нет необходимости явно raise ZeroDivisionError - это произойдет автоматически, если вы попытаетесь разделить на ноль.

Однако, если вы не создаете документацию из строки документации, я бы, вероятно, просто включил строку описания для такой простой функции:

def inv(a):
    """Return the inverse of the argument."""
    return 1 / a

Любой, кто его использует, вероятно, знает, что вы не можете инвертировать, например. струны.

Я не хочу проверять здесь типы, правильно?

Я бы не стал - если пользователь после прочтения вашей документации решит пройти, например. строку в функцию, которую они должны ожидать для получения TypeError, и нет никакого смысла тестировать тип аргумента, чтобы затем самостоятельно вызвать то же самое исключение, которое в любом случае было бы вызвано кодом (опять же, см. также ZeroDivisionError! ) То есть, если, например, float или complex числа должны быть недействительными, и в этом случае вам придется обрабатывать их вручную.

person jonrsharpe    schedule 21.10.2015
comment
Спасибо за оба ответа. Я также вижу, что ваш вариант более точно следует принципу EAFP, чем мой. Кроме того, имя функции предполагает, что может быть вставлена ​​матрица. Следовательно, если не указано, что функция принимает целочисленные аргументы (как предлагает amath), наличие TypeError с ее описанием лучше подчеркивает цель функции (на мой взгляд). - person Quickbeam2k1; 21.10.2015

arrow_upward
1
arrow_downward

Нет. Строка документации должна описывать ожидаемый ввод. Если бы это была моя функция, я бы включил что-то вроде этого в строку документации:

"""Return the inverse of an integer.  ZeroDivisionError is raised if zero is
passed to this function."""

Поэтому указано, что ввод должен быть целым числом. Указание, что функция может вызывать TypeError, просто чрезмерно усложняет строку документации.

person amath    schedule 21.10.2015