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

Question

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

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

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

Answer 1

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

Answer 2

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

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