Как документировать тип утки?

Question

У меня раздувается документация, так как всякий раз, когда я сталкиваюсь со сложным типом утки, мне нужен какой-то способ сказать «этот тип утки», но вместо этого я попадаю в бесконечный цикл «ваша функция требует этого ввода, но не документирует это ", а затем документирует это.Это приводит к раздутой, повторяющейся документации, такой как:

def Foo(arg):
    """
    Args:
      arg: An object that supports X functionality, and Y functionality,
        and can be passed to Z other functionality.
    """
    # Insert code here.

def Bar(arg):
    """
    Args:
      arg: An object that supports X functionality, and Y functionality,
        and can be passed to Z other functionality.
    """
    # Insert code here.

и так далее, и так далее, для Baz, Qux и других функций.Мне нужен какой-то более короткий способ написания «arg - это (тип объекта)».

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

Я чувствую, что C ++ имеет ту же проблему с шаблонными типами.У Haskell это будет, но для документирования можно использовать определение класса типа.(Примечание: классы на Haskell! = Классы на Java / C ++ / Python / и т. Д.) (Примечание: на самом деле я не программирую на Haskell, так что извините, если это дурацкий пример.)

Должен ли я пойтитрадиционный OO-маршрут, и просто напишите базовый класс и скажите «что-нибудь подобное этому базовому классу» в документах?В коде не будет принудительно производного от базового класса (поскольку не требуется, чтобы объект был получен из него), и базовый класс не добавляет никакого значения, кроме как для документирования свойств интерфейса, по существу.

С другой стороны, я программирую на Python и пытаюсь программировать на языке языка.(Как это обычно бывает больно.) Базовые классы хороши для наследования функциональности, но когда ваш базовый класс полностью абстрактен, кажется, что он не добавляет значения на языке с уткой.

---

РЕДАКТИРОВАТЬ : К ответам: я знаю, что такое утка (это должно быть видно из поста).Где я документирую это вопрос, особенно?когда не существует класса для прикрепления документации.

Answer 1

Идея типизации утки заключается в том, что вы документируете, что вы ожидаете утку, и что другие объекты могут притворяться уткой.

Нигде в документации ни один API не указывает, что он принимает объект StringIO. Вместо этого мы в большинстве случаев ожидаем файлоподобный объект.

Также, по большей части, стандартная библиотека пытается избежать именования конкретных методов, требующих типа утки. Это оставляет реализацию открытой для изменений. Например, API random.sample можно было бы определить в терминах итераций или последовательностей.

Если вы хотите быть более конкретным, вы можете использовать абстрактные базовые классы . Некоторые из них уже включены в модуль коллекций (например, Iterable, Hashable и Sized) или модуль чисел (Rational, Integral и т. Д.). Не трудно смоделировать после того, как они вас запишут. Затем в документации просто указывается, какие ABC требуются (т. Е. x - это Размер Итерируемый и y - это Integral ).

Answer 2

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

Полагаю, вы могли бы заимствовать концепцию, не привлекая при себе багаж строгой типизации: просто определите и задокументируйте абстрактный класс Foo, а затем скажите, что ваш метод ожидает "Foo или Foo -подобный" объект». Вам даже не нужно заставлять любой другой класс на самом деле наследовать от Foo, если вы не хотите; люди, читающие документацию, все равно будут знать, куда идти, чтобы узнать, что ожидается от Foo -подобного объекта.

Answer 3

Смысл утиной типизации в том, что понятие «тип» становится абстрактной интуитивной идеей, а не чем-то, что формально является частью языка.Это делает набор текста гораздо более гибким и гибким, чем в языках, где проверка типов является частью языка.

Для использования утиной типизации требуется, чтобы программа не знала, какой «тип» выИспользуете, но это другие программисты делают.Поэтому, если у вас есть целое семейство классов / функций / и т. Д., Которые работают с объектами определенного «типа», и этот тип не может быть описан в нескольких словах, просто добавьте раздел в комментариях или строку документации (или дажевнешний файл .txt), описывающий ваш тип и называющий его.Тогда вы можете просто обратиться к этому имени везде.