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

您可以在文档字符串中提供类型提示。

由于您是在一个类（该类将是其他类的超类）上编写文档的，因此您可以对返回的基本类型进行文档化。即使继承了基类后将返回的实际类型，结果仍将是该基本类型的实例，并且在此级别上，您无论如何都无法记录任何其他信息。

如果您觉得子类返回的内容需要更具体的文档，则只需在此处提供文档即可。