繼承父類docstring作爲__doc__屬性

Question

有一個關於Inherit docstrings in Python class inheritance的問題，但其中的答案處理方法docstrings。

我的問題是如何繼承父類的文檔字符串作爲__doc__屬性。用例是Django rest framework基於您的視圖類的文檔字符串在您的API的html版本中生成很好的文檔。但是，在沒有docstring的類中繼承基類（帶有docstring）時，API不會顯示文檔字符串。

它可能是非常好的，獅身人面像和其他工具做正確的事情，併爲我處理文檔字符串繼承，但django休息框架看看（空）.__doc__屬性。

class ParentWithDocstring(object): 
    """Parent docstring""" 
    pass 


class SubClassWithoutDoctring(ParentWithDocstring): 
    pass 


parent = ParentWithDocstring() 
print parent.__doc__ # Prints "Parent docstring". 
subclass = SubClassWithoutDoctring() 
print subclass.__doc__ # Prints "None" 

我已經試過類似super(SubClassWithoutDocstring, self).__doc__，但也只拿到了我None。

Answer 1

由於無法分配新__doc__文檔字符串類（在CPython的至少），你將不得不使用元類：

import inspect 

def inheritdocstring(name, bases, attrs): 
    if not '__doc__' in attrs: 
     # create a temporary 'parent' to (greatly) simplify the MRO search 
     temp = type('temporaryclass', bases, {}) 
     for cls in inspect.getmro(temp): 
      if cls.__doc__ is not None: 
       attrs['__doc__'] = cls.__doc__ 
       break 

    return type(name, bases, attrs) 

是的，我們通過一個額外的箍或兩跳，但上面的元類將找到正確的__doc__，然而令你費解的是你的繼承圖。

用法：

>>> class ParentWithDocstring(object): 
...  """Parent docstring""" 
... 
>>> class SubClassWithoutDocstring(ParentWithDocstring): 
...  __metaclass__ = inheritdocstring 
... 
>>> SubClassWithoutDocstring.__doc__ 
'Parent docstring' 

另一種方法是設置__doc__在__init__，作爲一個實例變量：

def __init__(self): 
    try: 
     self.__doc__ = next(cls.__doc__ for cls in inspect.getmro(type(self)) if cls.__doc__ is not None) 
    except StopIteration: 
     pass 

然後至少您的實例具有一個文檔字符串：

>>> class SubClassWithoutDocstring(ParentWithDocstring): 
...  def __init__(self): 
...   try: 
...    self.__doc__ = next(cls.__doc__ for cls in inspect.getmro(type(self)) if cls.__doc__ is not None) 
...   except StopIteration: 
...    pass 
... 
>>> SubClassWithoutDocstring().__doc__ 
'Parent docstring' 

從Python 3.3開始（它修復了issue 12773），你可以最後只設置自定義類的__doc__屬性，這樣，那麼你可以使用一個類裝飾器：

import inspect 

def inheritdocstring(cls): 
    for base in inspect.getmro(cls): 
     if base.__doc__ is not None: 
      cls.__doc__ = base.__doc__ 
      break 
    return cls 

然後可以這樣應用：

>>> @inheritdocstring 
... class SubClassWithoutDocstring(ParentWithDocstring): 
...  pass 
... 
>>> SubClassWithoutDocstring.__doc__ 
'Parent docstring' 

Answer 2

在你能這種特殊情況下通過重寫.get_name()方法，還可以覆蓋REST框架如何確定用於端點的名稱。

如果你確實採用了這種方法，你可能會發現自己想要爲你的視圖定義一組基類，並且使用一個簡單的mixin類來覆蓋所有基本視圖的方法。

例如：

class GetNameMixin(object): 
    def get_name(self): 
     # Your docstring-or-ancestor-docstring code here 

class ListAPIView(GetNameMixin, generics.ListAPIView): 
    pass 

class RetrieveAPIView(GetNameMixin, generics.RetrieveAPIView): 
    pass 

還要注意get_name方法被認爲是私有的，並有可能在未來的某個時刻改變，所以你需要升級時密切關注的發行說明，對於那裏的任何改變。

Answer 3

最簡單的方法是將其指定爲一個類變量：

class ParentWithDocstring(object): 
    """Parent docstring""" 
    pass 

class SubClassWithoutDoctring(ParentWithDocstring): 
    __doc__ = ParentWithDocstring.__doc__ 

parent = ParentWithDocstring() 
print parent.__doc__ # Prints "Parent docstring". 
subclass = SubClassWithoutDoctring() 
assert subclass.__doc__ == parent.__doc__ 

它的手冊，遺憾的是，但簡單。順便說一句，而字符串格式化不起作用通常的方式，它用同樣的方法：

class A(object): 
    _validTypes = (str, int) 
    __doc__ = """A accepts the following types: %s""" % str(_validTypes) 

A accepts the following types: (<type 'str'>, <type 'int'>) 

Answer 4

你也可以做到這一點使用@property

class ParentWithDocstring(object): 
    """Parent docstring""" 
    pass 

class SubClassWithoutDocstring(ParentWithDocstring): 
    @property 
    def __doc__(self): 
     return None 

class SubClassWithCustomDocstring(ParentWithDocstring): 
    def __init__(self, docstring, *args, **kwargs): 
     super(SubClassWithCustomDocstring, self).__init__(*args, **kwargs) 
     self.docstring = docstring 
    @property 
    def __doc__(self): 
     return self.docstring 

>>> parent = ParentWithDocstring() 
>>> print parent.__doc__ # Prints "Parent docstring". 
Parent docstring 
>>> subclass = SubClassWithoutDocstring() 
>>> print subclass.__doc__ # Prints "None" 
None 
>>> subclass = SubClassWithCustomDocstring('foobar') 
>>> print subclass.__doc__ # Prints "foobar" 
foobar 

你甚至可以覆蓋文檔字符串。

class SubClassOverwriteDocstring(ParentWithDocstring): 
    """Original docstring""" 
    def __init__(self, docstring, *args, **kwargs): 
     super(SubClassOverwriteDocstring, self).__init__(*args, **kwargs) 
     self.docstring = docstring 
    @property 
    def __doc__(self): 
     return self.docstring 

>>> subclass = SubClassOverwriteDocstring('new docstring') 
>>> print subclass.__doc__ # Prints "new docstring" 
new docstring 

一個警告，屬性不能被其他類繼承明顯，你必須在你要覆蓋文檔字符串每個類添加屬性。

class SubClassBrokenDocstring(SubClassOverwriteDocstring): 
    """Broken docstring""" 
    def __init__(self, docstring, *args, **kwargs): 
     super(SubClassBrokenDocstring, self).__init__(docstring, *args, **kwargs) 

>>> subclass = SubClassBrokenDocstring("doesn't work") 
>>> print subclass.__doc__ # Prints "Broken docstring" 
Broken docstring 

無賴！但絕對比元類更容易！