Как в python docstring задать несколько типов получаемых аргументов или возвращаемых значений
столкнулся с такой проблемой: при написании docstring не могу задать несколько типов значений. Например допустим может в качестве аргумента прийти строка, или список строк. Пытаюсь следующие варианты: :param str, list arg: *info about argument*, и :param Union[str, list] arg: *info about argument*, и :type arg: list, str, и :type arg: Union[list, str], аналогичные варианты в return, но все равно при наведении курсора на функцию всплывающая подсказка в PyCharm говорит, что тип аргумента или возвращаемого значения Any. И статический анализатор перестает ругаться, если в функцию начинаешь пихать например int. Что я упускаю?
Ответы (1 шт):
Что я упускаю?
То, что перечисление нескольких типов в type прописывается через or, а не через запятую:
Multiple types in a type field will be linked automatically if separated by the word “or”.
Источник в документации Sphinx: Info field lists.
Пример:
import random
def f(x, y):
"""
:param x: ...
:type x: str or list
:param int or None y: ...
:rtype: int or str
"""
if random.choice((True, False)):
return 42
return "spam"
Тип x прописан через поле type, тип y задан инлайн. PyCharm должен корректно распознать сигнатуру f как def f(x: Union[str, list], y: Optional[int]) -> Union[int, str].
Хотя, конечно, прописать аннотации или инлайн или через стабы, как предложил @insolor, решение куда лучше тем, что это стандарт языка, в то время как типы в докстрингах, по идее, должны использоваться только для генерации красивой документации (кажется, с некоторых пор Sphinx умеет вытаскивать типы и из аннотаций тоже, так что типы в докстрингах утрачивают свою актуальность).