Python документирует тип возвращаемого объекта

Question

class Foo:
    def __init__(self, bar):
        self.bar = bar

    def get_new_foo(self, new_bar):
        return type(self)([self.bar, new_bar]) #How should it be documented?

Если get_new_foo вызывается из производного класса, то он возвращает экземпляр производного класса.Если несколько классов используют Foo в качестве базового класса, то get_new_foo вернет экземпляр производного класса, из которого он был вызван.

Я хочу задокументировать, какой тип объекта get_new_foo возвращает, и я не будуне понимаю, что / как документировать.Я не могу сказать Returns an instance of Foo, потому что так будет не всегда.

Answer 1

Лично меня бы это не беспокоило.Так как любой подкласс "is-a" Foo в любом случае, вы в худшем случае слегка вводите в заблуждение в выбранной вами формулировке.Если вы хотите быть педантично правильным, вы всегда можете развернуть его до «Возвращает экземпляр Foo (подкласс Foo при вызове на экземплярах дочернего класса)».

Answer 2

Вы можете предоставить подсказки типов в строке документации.

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

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