在Python中继承方法的文档字符串

Question

我有一个带有文档字符串的OO层次结构，它需要与代码本身一样多的维护。例如，

class Swallow(object):
    def airspeed(self):
        """Returns the airspeed (unladen)"""
        raise NotImplementedError

class AfricanSwallow(Swallow):
    def airspeed(self):
        # whatever

现在，问题在于AfricanSwallow.airspeed它不继承超类方法的文档字符串。我知道我可以使用模板方法模式保留文档字符串，即

class Swallow(object):
    def airspeed(self):
        """Returns the airspeed (unladen)"""
        return self._ask_arthur()

并_ask_arthur在每个子类中实现。但是，我想知道是否还有另一种方法来继承文档字符串，也许是我还没有发现的装饰器？

Answer 1

以类装饰器风格编写一个函数来为您执行复制。在Python2.5中，您可以在创建类后直接应用它。在更高版本中，您可以使用@decorator表示法。

这是如何做到的第一步：

import types

def fix_docs(cls):
    for name, func in vars(cls).items():
        if isinstance(func, types.FunctionType) and not func.__doc__:
            print func, 'needs doc'
            for parent in cls.__bases__:
                parfunc = getattr(parent, name, None)
                if parfunc and getattr(parfunc, '__doc__', None):
                    func.__doc__ = parfunc.__doc__
                    break
    return cls


class Animal(object):
    def walk(self):
        'Walk like a duck'

class Dog(Animal):
    def walk(self):
        pass

Dog = fix_docs(Dog)
print Dog.walk.__doc__

在较新的Python版本中，最后一部分更加简单美观：

@fix_docs
class Dog(Animal):
    def walk(self):
        pass

这是一项Pythonic技术，与标准库中现有工具的设计完全匹配。例如，
functools.total_ordering

类装饰器向类添加缺少的丰富比较方法。再举一个例子，
functools.wraps

装饰器将元数据从一个函数复制到另一个函数。