Должна ли Docstring содержать оператор Raises, если ошибка обрабатывается в коде

Предположим, у меня есть простая функция. Например:

def if_a_float(string):
   try:
       float(string)
   except ValueError:
       return False
   else:
       return True

Должен ли я включать оператор Raises: ValueError в свою строку документации или мне следует избегать его, поскольку ошибка уже была обработана в коде? Это делается для любой ошибки (пойманной/непойманной)? Я понимаю, что это, вероятно, зависит от стиля, поэтому, допустим, я использую Стиль Google Docstring (хотя, думаю, это не имеет большого значения)


python docstring
person Alex.Kh    schedule 30.10.2019    source источник

Ответы (2)


arrow_upward
2
arrow_downward

Вы должны документировать явные исключения, а также те, которые могут иметь отношение к интерфейсу, в соответствии с Руководство по стилю Google (тот же документ, который вы упоминаете сами).

Этот код не вызывает исключение явно (нет raise), и вам не нужно упоминать, что вы его перехватываете. На самом деле, этот код не может даже случайно поднять его (вы улавливаете единственную строку, которая может), и поэтому было бы неправильно документировать, что if_a_float() поднимал ValueError.

person norok2    schedule 30.10.2019
comment
Спасибо, я просто хотел быть на 100% уверенным в этом. - person Alex.Kh; 31.10.2019

arrow_upward
2
arrow_downward

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

person Barmar    schedule 30.10.2019