有关要返回的对象类型的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?

If get_new_foo gets called from a derived class, then it would return an instance of the derived class. If multiple classes use Foo as base class, then get_new_foo will return an instance of the derived class it was called from.

I want to document what type of object get_new_foo returns, and I don't understand what/how to document it. I can't say Returns an instance of Foo because this will not be the case always.

Answer 1

Personally, I wouldn't be overly concerned about this. Since any subclass "is-a" Foo anyway, you're at worst mildly misleading in your chosen wording. If you want to be pedantically correct, you can always expand it to "Returns an instance of Foo (a Foo subclass when called on child class instances)".

Answer 2

You can provide type hints in the docstring.

Since you're writing the documentation on a class that would be the super-class for other classes, it makes sense that you document the base type it returns. Even if the actual type that will be returned once the base class is inherited, the results will still be instances of the base type and at this level, you cannot document anything beyond that anyway.

If you feel sub-classes need more specific documentation for whatever they return, you can simply provide the documentation there.