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

Question

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

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

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

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

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

Answer 1

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

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

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

Answer 2

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

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 номера должны быть недопустимыми вводами, и в этом случае вам придется обрабатывать их вручную.