numpydoc: документирование параметра типа утки

Question

В соответствии с соглашением, приведенным в руководстве к документации numpy/scipy, параметры функции должны быть задокументированы следующим образом:

def foo(x):
    """" This function does nothing

    Parameters
    ----------
    x : type
       Description of parameter `x`.
    """"
    pass

Это просто, если тип - это отдельный тип, такой как int или str.

Теперь я хочу, чтобы параметр был экземпляром BaseClass или любым объектом, который предоставляет тот же интерфейс (например, класс, производный от BaseClass). Существует ли соглашение о том, как кратко задокументировать, что параметр x должен предоставлять определенный интерфейс (путем деривации или утки)?

Answer 1

Описанный вами подход в значительной степени стандартный.

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